feat(theme): add Theme (#741)

* feat(theme): add Theme

* fix(theme): fix broken type test

* docs(theme): add examples

* docs(theme): add description, update carbon theme link [ci skip]

* docs: pre-wrap type code snippet [ci skip]

COMPONENT_INDEX.md

@@ -1,6 +1,6 @@
 # Component Index
 
-> 171 components exported from carbon-components-svelte@0.39.0.
+> 172 components exported from carbon-components-svelte@0.39.0.
 
 ## Components
 
@@ -153,6 +153,7 @@
 - [`TextAreaSkeleton`](#textareaskeleton)
 - [`TextInput`](#textinput)
 - [`TextInputSkeleton`](#textinputskeleton)
+- [`Theme`](#theme)
 - [`Tile`](#tile)
 - [`TileGroup`](#tilegroup)
 - [`TimePicker`](#timepicker)
@@ -4201,6 +4202,38 @@ None.
 | mouseenter | forwarded | --     |
 | mouseleave | forwarded | --     |
 
+## `Theme`
+
+### Types
+
+```ts
+export type CarbonTheme = "white" | "g10" | "g80" | "g90" | "g100";
+```
+
+### Props
+
+| Prop name  | Kind             | Reactive | Type                                                                                                           | Default value                                                                                                 | Description                                                                                                               |
+| :--------- | :--------------- | :------- | :------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| theme      | <code>let</code> | Yes      | <code>CarbonTheme</code>                                                                                       | <code>"white"</code>                                                                                          | Set the current Carbon theme                                                                                              |
+| tokens     | <code>let</code> | No       | <code>{ [token: string]: any; }</code>                                                                         | <code>{}</code>                                                                                               | Customize a theme with your own tokens<br />https://carbondesignsystem.com/guidelines/themes/overview#customizing-a-theme |
+| persist    | <code>let</code> | No       | <code>boolean</code>                                                                                           | <code>false</code>                                                                                            | Set to `true` to persist the theme using window.localStorage                                                              |
+| persistKey | <code>let</code> | No       | <code>string</code>                                                                                            | <code>"theme"</code>                                                                                          | Specify the local storage key                                                                                             |
+| render     | <code>let</code> | No       | <code>"toggle" &#124; "select"</code>                                                                          | --                                                                                                            | Render a toggle or select dropdown to control the theme                                                                   |
+| toggle     | <code>let</code> | No       | <code>import("../Toggle/Toggle").ToggleProps & { themes?: [labelA: CarbonTheme, labelB: CarbonTheme]; }</code> | <code>{ themes: ["white", "g100"], labelA: "", labelB: "", labelText: "Dark mode", hideLabel: false, }</code> | Override the default toggle props                                                                                         |
+| select     | <code>let</code> | No       | <code>import("../Select/Select").SelectProps & { themes?: CarbonTheme[]; }</code>                              | <code>{ themes: themeKeys, labelText: "Themes", hideLabel: false, }</code>                                    | Override the default select props                                                                                         |
+
+### Slots
+
+| Slot name | Default | Props                                 | Fallback |
+| :-------- | :------ | :------------------------------------ | :------- |
+| --        | Yes     | <code>{ theme: CarbonTheme; } </code> | --       |
+
+### Events
+
+| Event name | Type       | Detail                               |
+| :--------- | :--------- | :----------------------------------- |
+| update     | dispatched | <code>{ theme: CarbonTheme; }</code> |
+
 ## `Tile`
 
 ### Props

docs/src/COMPONENT_API.json

@@ -1,5 +1,5 @@
 {
-  "total": 171,
+  "total": 172,
   "components": [
     {
       "moduleName": "Accordion",
@@ -11573,6 +11573,109 @@
       "typedefs": [],
       "rest_props": { "type": "Element", "name": "div" }
     },
+    {
+      "moduleName": "Theme",
+      "filePath": "src/Theme/Theme.svelte",
+      "props": [
+        {
+          "name": "theme",
+          "kind": "let",
+          "description": "Set the current Carbon theme",
+          "type": "CarbonTheme",
+          "value": "\"white\"",
+          "isFunction": false,
+          "isFunctionDeclaration": false,
+          "constant": false,
+          "reactive": true
+        },
+        {
+          "name": "tokens",
+          "kind": "let",
+          "description": "Customize a theme with your own tokens\nhttps://carbondesignsystem.com/guidelines/themes/overview#customizing-a-theme",
+          "type": "{ [token: string]: any; }",
+          "value": "{}",
+          "isFunction": false,
+          "isFunctionDeclaration": false,
+          "constant": false,
+          "reactive": false
+        },
+        {
+          "name": "persist",
+          "kind": "let",
+          "description": "Set to `true` to persist the theme using window.localStorage",
+          "type": "boolean",
+          "value": "false",
+          "isFunction": false,
+          "isFunctionDeclaration": false,
+          "constant": false,
+          "reactive": false
+        },
+        {
+          "name": "persistKey",
+          "kind": "let",
+          "description": "Specify the local storage key",
+          "type": "string",
+          "value": "\"theme\"",
+          "isFunction": false,
+          "isFunctionDeclaration": false,
+          "constant": false,
+          "reactive": false
+        },
+        {
+          "name": "render",
+          "kind": "let",
+          "description": "Render a toggle or select dropdown to control the theme",
+          "type": "\"toggle\" | \"select\"",
+          "isFunction": false,
+          "isFunctionDeclaration": false,
+          "constant": false,
+          "reactive": false
+        },
+        {
+          "name": "toggle",
+          "kind": "let",
+          "description": "Override the default toggle props",
+          "type": "import(\"../Toggle/Toggle\").ToggleProps & { themes?: [labelA: CarbonTheme, labelB: CarbonTheme]; }",
+          "value": "{     themes: [\"white\", \"g100\"],     labelA: \"\",     labelB: \"\",     labelText: \"Dark mode\",     hideLabel: false,   }",
+          "isFunction": false,
+          "isFunctionDeclaration": false,
+          "constant": false,
+          "reactive": false
+        },
+        {
+          "name": "select",
+          "kind": "let",
+          "description": "Override the default select props",
+          "type": "import(\"../Select/Select\").SelectProps & { themes?: CarbonTheme[]; }",
+          "value": "{     themes: themeKeys,     labelText: \"Themes\",     hideLabel: false,   }",
+          "isFunction": false,
+          "isFunctionDeclaration": false,
+          "constant": false,
+          "reactive": false
+        }
+      ],
+      "slots": [
+        {
+          "name": "__default__",
+          "default": true,
+          "slot_props": "{ theme: CarbonTheme; }"
+        }
+      ],
+      "events": [
+        {
+          "type": "dispatched",
+          "name": "update",
+          "detail": "{ theme: CarbonTheme; }"
+        }
+      ],
+      "typedefs": [
+        {
+          "type": "\"white\" | \"g10\" | \"g80\" | \"g90\" | \"g100\"",
+          "name": "CarbonTheme",
+          "ts": "type CarbonTheme = \"white\" | \"g10\" | \"g80\" | \"g90\" | \"g100\""
+        }
+      ]
+    },
     {
       "moduleName": "Tile",
       "filePath": "src/Tile/Tile.svelte",

docs/src/components/ComponentApi.svelte

@@ -221,4 +221,8 @@
   code {
     word-break: break-word;
   }
+
+  :global(.cell .bx--snippet--inline code, .bx--snippet--single pre) {
+    white-space: pre-wrap !important;
+  }
 </style>

docs/src/pages/_layout.svelte

@@ -20,7 +20,7 @@
   import Footer from "../components/Footer.svelte";
 
   const deprecated = ["ToggleSmall", "Icon"];
-  const new_components = ["Breakpoint", "RecursiveList", "TreeView"];
+  const new_components = ["Theme"];
 
   let isOpen = false;
   let isSideNavOpen = true;
@@ -269,6 +269,6 @@
   }
 
   .bx--side-nav__submenu[aria-expanded="true"] + .bx--side-nav__menu {
-    max-height: 132rem;
+    max-height: 144rem;
   }
 </style>

docs/src/pages/components/Theme.svx

@@ -0,0 +1,46 @@
+<script>
+  import { Theme } from "carbon-components-svelte";
+  import Preview from "../../components/Preview.svelte";
+</script>
+
+This utility component dynamically updates the Carbon theme on the client-side using CSS variables.
+
+### Default
+
+<FileSource src="/framed/Theme/Theme" />
+
+### Persist locally
+
+Set `persist` to `true` to persist the theme locally using the [Window.localStorage API](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage).
+
+<FileSource src="/framed/Theme/ThemePersist" />
+
+### Custom theme
+
+Define keys and values in the `tokens` prop that override default Carbon theme tokens. Refer to the [Carbon website](https://carbondesignsystem.com/guidelines/themes/overview#customizing-a-theme) for guidance on customizing a theme using token values.
+
+<FileSource src="/framed/Theme/ThemeTokens" />
+
+### Theme toggle
+
+Set `render` to `"toggle"` to render a toggle switch to control the theme.
+
+<FileSource src="/framed/Theme/ThemeToggle" />
+
+### Theme toggle (custom)
+
+Customize the toggle using the `toggle` prop.
+
+<FileSource src="/framed/Theme/ThemeToggleCustom" />
+
+### Theme select
+
+Set `render` to `"select"` to render a select dropdown to control the theme.
+
+<FileSource src="/framed/Theme/ThemeSelect" />
+
+### Theme select (custom)
+
+Customize the select using the `select` prop.
+
+<FileSource src="/framed/Theme/ThemeSelectCustom" />

docs/src/pages/framed/Theme/Theme.svelte

@@ -0,0 +1,17 @@
+<script>
+  import {
+    Theme,
+    RadioButtonGroup,
+    RadioButton,
+  } from "carbon-components-svelte";
+
+  let theme = "g90";
+</script>
+
+<Theme bind:theme />
+
+<RadioButtonGroup legendText="Carbon theme" bind:selected="{theme}">
+  {#each ["white", "g10", "g80", "g90", "g100"] as value}
+    <RadioButton labelText="{value}" value="{value}" />
+  {/each}
+</RadioButtonGroup>

docs/src/pages/framed/Theme/ThemePersist.svelte

@@ -0,0 +1,17 @@
+<script>
+  import {
+    Theme,
+    RadioButtonGroup,
+    RadioButton,
+  } from "carbon-components-svelte";
+
+  let theme = "g90";
+</script>
+
+<Theme bind:theme persist persistKey="__carbon-theme" />
+
+<RadioButtonGroup legendText="Carbon theme" bind:selected="{theme}">
+  {#each ["white", "g10", "g80", "g90", "g100"] as value}
+    <RadioButton labelText="{value}" value="{value}" />
+  {/each}
+</RadioButtonGroup>

docs/src/pages/framed/Theme/ThemeSelect.svelte

@@ -0,0 +1,5 @@
+<script>
+  import { Theme } from "carbon-components-svelte";
+</script>
+
+<Theme render="select" />

docs/src/pages/framed/Theme/ThemeSelectCustom.svelte

@@ -0,0 +1,12 @@
+<script>
+  import { Theme } from "carbon-components-svelte";
+</script>
+
+<Theme
+  render="select"
+  select="{{
+    themes: ['white', 'g90', 'g100'],
+    labelText: 'Select a theme',
+    inline: true,
+  }}"
+/>

docs/src/pages/framed/Theme/ThemeToggle.svelte

@@ -0,0 +1,5 @@
+<script>
+  import { Theme } from "carbon-components-svelte";
+</script>
+
+<Theme render="toggle" />

docs/src/pages/framed/Theme/ThemeToggleCustom.svelte

@@ -0,0 +1,14 @@
+<script>
+  import { Theme } from "carbon-components-svelte";
+</script>
+
+<Theme
+  render="toggle"
+  toggle="{{
+    themes: ['g10', 'g80'],
+    labelA: 'Enable dark mode',
+    labelB: 'Enable dark mode',
+    hideLabel: true,
+    size: 'sm',
+  }}"
+/>

docs/src/pages/framed/Theme/ThemeTokens.svelte

@@ -0,0 +1,14 @@
+<script>
+  import { Theme, Button } from "carbon-components-svelte";
+</script>
+
+<Theme
+  theme="g90"
+  tokens="{{
+    'interactive-01': '#d02670',
+    'hover-primary': '#ee5396',
+    'active-primary': '#9f1853',
+  }}"
+/>
+
+<Button>Primary button</Button>

src/Theme/Theme.svelte

@@ -0,0 +1,118 @@
+<script>
+  /**
+   * Dynamic, client-side theming using CSS variables
+   * Only works with `carbon-components-svelte/css/all.css`
+   */
+
+  /**
+   * @typedef {"white" | "g10" | "g80" | "g90" | "g100"} CarbonTheme
+   * @event {{ theme: CarbonTheme; }} update
+   * @slot {{ theme: CarbonTheme; }}
+   */
+
+  /**
+   * Set the current Carbon theme
+   * @type {CarbonTheme}
+   */
+  export let theme = "white";
+
+  /**
+   * Customize a theme with your own tokens
+   * https://carbondesignsystem.com/guidelines/themes/overview#customizing-a-theme
+   * @type {{ [token: string]: any; }}
+   */
+  export let tokens = {};
+
+  /** Set to `true` to persist the theme using window.localStorage */
+  export let persist = false;
+
+  /** Specify the local storage key */
+  export let persistKey = "theme";
+
+  /**
+   * Render a toggle or select dropdown to control the theme
+   * @type {"toggle" | "select"}
+   */
+  export let render = undefined;
+
+  /**
+   * Override the default toggle props
+   * @type {import("../Toggle/Toggle").ToggleProps & { themes?: [labelA: CarbonTheme, labelB: CarbonTheme]; }}
+   */
+  export let toggle = {
+    themes: ["white", "g100"],
+    labelA: "",
+    labelB: "",
+    labelText: "Dark mode",
+    hideLabel: false,
+  };
+
+  /** @type {Record<CarbonTheme, string>} */
+  const themes = {
+    white: "White",
+    g10: "Gray 10",
+    g80: "Gray 80",
+    g90: "Gray 90",
+    g100: "Gray 100",
+  };
+
+  /** @type {CarbonTheme} */
+  const themeKeys = Object.keys(themes);
+
+  /**
+   * Override the default select props
+   * @type {import("../Select/Select").SelectProps & { themes?: CarbonTheme[]; }}
+   */
+  export let select = {
+    themes: themeKeys,
+    labelText: "Themes",
+    hideLabel: false,
+  };
+
+  import { createEventDispatcher } from "svelte";
+  import Toggle from "../Toggle/Toggle.svelte";
+  import Select from "../Select/Select.svelte";
+  import SelectItem from "../Select/SelectItem.svelte";
+  import LocalStorage from "../LocalStorage/LocalStorage.svelte";
+
+  const dispatch = createEventDispatcher();
+
+  $: if (typeof window !== "undefined") {
+    Object.entries(tokens).forEach(([token, value]) => {
+      document.documentElement.style.setProperty(`--cds-${token}`, value);
+    });
+
+    if (theme in themes) {
+      document.documentElement.setAttribute("theme", theme);
+      dispatch("update", { theme });
+    } else {
+      console.warn(
+        `[Theme.svelte] invalid theme "${theme}". Value must be one of: ${JSON.stringify(
+          Object.keys(themes)
+        )}`
+      );
+    }
+  }
+</script>
+
+{#if persist}
+  <LocalStorage bind:value="{theme}" key="{persistKey}" />
+{/if}
+
+{#if render === "toggle"}
+  <Toggle
+    {...toggle}
+    toggled="{theme === toggle.themes[1]}"
+    on:toggle="{({ detail }) => {
+      theme = detail.toggled ? toggle.themes[1] : toggle.themes[0];
+    }}"
+  />
+{:else if render === "select"}
+  <Select {...select} bind:selected="{theme}">
+    {#each select.themes as theme (theme)}
+      <SelectItem value="{theme}" text="{themes[theme]}" />
+    {/each}
+  </Select>
+{/if}
+
+<slot theme="{theme}" />

src/Theme/index.js

@@ -0,0 +1 @@
+export { default as Theme } from "./Theme.svelte";

src/index.js

@@ -113,6 +113,7 @@ export { Tabs, Tab, TabContent, TabsSkeleton } from "./Tabs";
 export { Tag, TagSkeleton } from "./Tag";
 export { TextArea, TextAreaSkeleton } from "./TextArea";
 export { TextInput, TextInputSkeleton, PasswordInput } from "./TextInput";
+export { Theme } from "./Theme";
 export {
   Tile,
   ClickableTile,

tests/Theme.test.svelte

@@ -0,0 +1,24 @@
+<script lang="ts">
+  import { Theme } from "../types";
+  import { CarbonTheme } from "../types/Theme/Theme";
+
+  let theme: CarbonTheme = "g10";
+</script>
+
+<Theme
+  bind:theme
+  persist
+  persistKey="carbon-theme"
+  on:update="{(e) => console.log(e.detail.theme)}"
+  tokens="{{ 'button-primary': 'violet' }}"
+  render="toggle"
+  toggle="{{
+    themes: ['g10', 'g90'],
+    labelA: '',
+    labelB: '',
+  }}"
+  select="{{
+    themes: ['g10', 'g90'],
+    labelText: '',
+  }}"
+/>

types/Theme/Theme.d.ts

@@ -0,0 +1,56 @@
+/// <reference types="svelte" />
+import { SvelteComponentTyped } from "svelte";
+
+export type CarbonTheme = "white" | "g10" | "g80" | "g90" | "g100";
+
+export interface ThemeProps {
+  /**
+   * Set the current Carbon theme
+   * @default "white"
+   */
+  theme?: CarbonTheme;
+
+  /**
+   * Customize a theme with your own tokens
+   * https://carbondesignsystem.com/guidelines/themes/overview#customizing-a-theme
+   * @default {}
+   */
+  tokens?: { [token: string]: any };
+
+  /**
+   * Set to `true` to persist the theme using window.localStorage
+   * @default false
+   */
+  persist?: boolean;
+
+  /**
+   * Specify the local storage key
+   * @default "theme"
+   */
+  persistKey?: string;
+
+  /**
+   * Render a toggle or select dropdown to control the theme
+   */
+  render?: "toggle" | "select";
+
+  /**
+   * Override the default toggle props
+   * @default { themes: ["white", "g100"], labelA: "", labelB: "", labelText: "Dark mode", hideLabel: false, }
+   */
+  toggle?: import("../Toggle/Toggle").ToggleProps & {
+    themes?: [labelA: CarbonTheme, labelB: CarbonTheme];
+  };
+
+  /**
+   * Override the default select props
+   * @default { themes: themeKeys, labelText: "Themes", hideLabel: false, }
+   */
+  select?: import("../Select/Select").SelectProps & { themes?: CarbonTheme[] };
+}
+
+export default class Theme extends SvelteComponentTyped<
+  ThemeProps,
+  { update: CustomEvent<{ theme: CarbonTheme }> },
+  { default: { theme: CarbonTheme } }
+> {}

types/index.d.ts

@@ -129,6 +129,7 @@ export { default as TextAreaSkeleton } from "./TextArea/TextAreaSkeleton";
 export { default as TextInput } from "./TextInput/TextInput";
 export { default as TextInputSkeleton } from "./TextInput/TextInputSkeleton";
 export { default as PasswordInput } from "./TextInput/PasswordInput";
+export { default as Theme } from "./Theme/Theme";
 export { default as Tile } from "./Tile/Tile";
 export { default as ClickableTile } from "./Tile/ClickableTile";
 export { default as ExpandableTile } from "./Tile/ExpandableTile";