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]

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>