@pure-ds/storybook 0.5.30 → 0.5.31

package/.storybook/preview.js

@@ -1,5 +1,5 @@
 import { addons } from '@storybook/preview-api';
-import { SELECT_STORY } from '@storybook/core-events';
+import { SELECT_STORY, UPDATE_GLOBALS } from '@storybook/core-events';
 import React from 'react';
 import { Title, Subtitle, Description as DocsDescription, Controls } from '@storybook/blocks';
 import { PDS } from '@pds-src/js/pds.js';
@@ -121,6 +121,61 @@ PDS.addEventListener('pds:ready', (event) => {
  */
 // Track current view mode globally for other code to check
 let currentViewMode = 'story';
+let toolbarTheme = null;
+
+const setToolbarThemeValue = (value) => {
+  if (!value) return;
+  toolbarTheme = value;
+};
+
+const emitThemeGlobals = (value) => {
+  if (!value || value === toolbarTheme) return;
+
+  const channel = addons?.getChannel?.();
+  if (!channel) return;
+
+  toolbarTheme = value;
+  channel.emit(UPDATE_GLOBALS, {
+    globals: { theme: value }
+  });
+};
+
+const initThemeSync = (() => {
+  let initialized = false;
+  return () => {
+    if (initialized || typeof window === 'undefined') return;
+    initialized = true;
+
+    PDS.addEventListener('pds:theme:changed', (event) => {
+      emitThemeGlobals(event?.detail?.theme ?? PDS.theme);
+    });
+
+    const watchDomTheme = () => {
+      const targets = [document.body, document.documentElement].filter(Boolean);
+      if (!targets.length) return;
+
+      const syncFromDom = () => {
+        const nextTheme = document.body?.getAttribute('data-theme')
+          || document.documentElement?.getAttribute('data-theme');
+        emitThemeGlobals(nextTheme);
+      };
+
+      const observer = new MutationObserver(syncFromDom);
+      targets.forEach((target) => {
+        observer.observe(target, { attributes: true, attributeFilter: ['data-theme'] });
+      });
+      syncFromDom();
+    };
+
+    if (!document.body && document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', watchDomTheme, { once: true });
+    } else {
+      watchDomTheme();
+    }
+  };
+})();
+
+initThemeSync();
 
 const withPDS = (story, context) => {
   currentViewMode = context.viewMode;
@@ -318,6 +373,9 @@ const withGlobalsHandler = (story, context) => {
     document.body.setAttribute('data-theme', globals.theme);
     PDS.theme = globals.theme;
   }
+  if (globals?.theme) {
+    setToolbarThemeValue(globals.theme);
+  }
   
   return story();
 };
@@ -1452,6 +1510,7 @@ if (typeof window !== 'undefined') {
         PDS.theme = globals.theme;
         
         console.log('✅ Theme applied:', globals.theme);
+        setToolbarThemeValue(globals.theme);
       }
       
       if (globals?.preset) {

package/dist/pds-reference.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-01-22T15:56:09.074Z",
+  "generatedAt": "2026-01-23T07:20:42.584Z",
   "sources": {
     "customElements": "custom-elements.json",
     "ontology": "src\\js\\pds-core\\pds-ontology.js",
@@ -1928,6 +1928,90 @@
       ],
       "notes": []
     },
+    "pds-theme": {
+      "tag": "pds-theme",
+      "className": "PdsTheme",
+      "displayName": "Pds Theme",
+      "storyTitle": "Components/Pds Theme",
+      "category": "Components",
+      "description": null,
+      "docsDescription": null,
+      "pdsTags": [
+        "appearance",
+        "autodocs",
+        "pds-theme",
+        "switcher",
+        "theme",
+        "toggle"
+      ],
+      "ontology": null,
+      "stories": [],
+      "sourceModule": "public/assets/pds/components/pds-theme.js",
+      "superclass": "HTMLElement",
+      "attributes": [
+        {
+          "name": "label",
+          "description": null,
+          "type": null,
+          "default": null,
+          "fieldName": null
+        }
+      ],
+      "properties": [
+        {
+          "name": "label",
+          "attribute": "label",
+          "description": "Gets the legend/aria-label text to display.",
+          "type": null,
+          "default": null,
+          "reflects": false,
+          "privacy": "public"
+        }
+      ],
+      "methods": [
+        {
+          "name": "attributeChangedCallback",
+          "description": null,
+          "parameters": [
+            {
+              "name": "name",
+              "type": "any",
+              "description": null,
+              "optional": false
+            },
+            {
+              "name": "oldValue",
+              "type": "any",
+              "description": null,
+              "optional": false
+            },
+            {
+              "name": "newValue",
+              "type": "any",
+              "description": null,
+              "optional": false
+            }
+          ],
+          "return": "void"
+        },
+        {
+          "name": "connectedCallback",
+          "description": null,
+          "parameters": [],
+          "return": "void"
+        },
+        {
+          "name": "disconnectedCallback",
+          "description": null,
+          "parameters": [],
+          "return": "void"
+        }
+      ],
+      "events": [],
+      "slots": [],
+      "cssParts": [],
+      "notes": []
+    },
     "pds-toaster": {
       "tag": "pds-toaster",
       "className": "AppToaster",
@@ -4949,6 +5033,33 @@
         "packages\\pds-storybook\\stories\\components\\PdsTabstrip.stories.js"
       ]
     },
+    "pds-theme": {
+      "slug": "pds-theme",
+      "storyTitle": "Components/Pds Theme",
+      "category": "Components",
+      "name": "Pds Theme",
+      "description": null,
+      "tags": [
+        "appearance",
+        "autodocs",
+        "pds-theme",
+        "switcher",
+        "theme",
+        "toggle"
+      ],
+      "pdsParameters": {
+        "tags": [
+          "theme",
+          "appearance",
+          "toggle",
+          "pds-theme"
+        ]
+      },
+      "stories": [],
+      "files": [
+        "packages\\pds-storybook\\stories\\components\\PdsTheme\\PdsTheme.stories.js"
+      ]
+    },
     "pds-toaster": {
       "slug": "pds-toaster",
       "storyTitle": "Components/Pds Toaster",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pure-ds/storybook",
-  "version": "0.5.30",
+  "version": "0.5.31",
   "description": "Storybook showcase for Pure Design System with live configuration",
   "type": "module",
   "private": false,
@@ -38,7 +38,7 @@
     "pds:build-icons": "pds-build-icons"
   },
   "peerDependencies": {
-    "@pure-ds/core": "^0.5.30"
+    "@pure-ds/core": "^0.5.31"
   },
   "dependencies": {
     "@custom-elements-manifest/analyzer": "^0.11.0",

package/public/assets/pds/components/pds-theme.js

@@ -0,0 +1,170 @@
+/**
+ * `<pds-theme>` exposes a zero-config theme toggle that updates `PDS.theme` and
+ * keeps its UI in sync with programmatic theme changes.
+ *
+ * @element pds-theme
+ * @attr {string} label - Optional legend text (defaults to "Theme").
+ */
+const THEME_OPTIONS = [
+  { value: "system", label: "System", icon: "moon-stars" },
+  { value: "light", label: "Light", icon: "sun" },
+  { value: "dark", label: "Dark", icon: "moon" },
+];
+
+const DEFAULT_LABEL = "Theme";
+const LAYERS = ["tokens", "primitives", "components", "utilities"];
+
+class PdsTheme extends HTMLElement {
+  static get observedAttributes() {
+    return ["label"];
+  }
+
+  #observer;
+  #listening = false;
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: "open" });
+  }
+
+  connectedCallback() {
+    if (!this.shadowRoot.hasChildNodes()) {
+      void this.#setup();
+    } else {
+      this.#attachObserver();
+      this.#syncLegend();
+      this.#syncCheckedState();
+    }
+  }
+
+  disconnectedCallback() {
+    this.#teardownObserver();
+  }
+
+  attributeChangedCallback(name, oldValue, newValue) {
+    if (oldValue === newValue) return;
+    if (name === "label") {
+      this.#syncLegend();
+    }
+  }
+
+  /**
+   * Gets the legend/aria-label text to display.
+   * @returns {string}
+   */
+  get label() {
+    return this.getAttribute("label")?.trim() || DEFAULT_LABEL;
+  }
+
+  set label(value) {
+    if (value == null || value === "") {
+      this.removeAttribute("label");
+    } else {
+      this.setAttribute("label", value);
+    }
+  }
+
+  async #setup() {
+    const componentStyles = PDS.createStylesheet(`
+      :host {
+        display: block;
+      }
+
+      label span {
+        display: inline-flex;
+        gap: var(--spacing-xs, 0.35rem);
+        align-items: center;
+      }
+    `);
+
+    await PDS.adoptLayers(this.shadowRoot, LAYERS, [componentStyles]);
+
+    this.shadowRoot.innerHTML = this.#template();
+
+    if (!this.#listening) {
+      this.shadowRoot.addEventListener("change", this.#handleChange);
+      this.#listening = true;
+    }
+
+    this.#attachObserver();
+    this.#syncLegend();
+    this.#syncCheckedState();
+  }
+
+  #template() {
+    const optionsMarkup = THEME_OPTIONS.map(
+      (option) => /*html*/`
+        <label part="option">
+          <input type="radio" name="theme" value="${option.value}" />
+          <span>
+            <pds-icon icon="${option.icon}" size="sm"></pds-icon>
+            ${option.label}
+          </span>
+        </label>`,
+    ).join("");
+
+    return /*html*/`
+      <form part="form">
+        <fieldset part="fieldset" role="radiogroup" aria-label="${DEFAULT_LABEL}" class="buttons">
+          <legend part="legend">${DEFAULT_LABEL}</legend>
+          ${optionsMarkup}
+        </fieldset>
+      </form>`;
+  }
+
+  #handleChange = (event) => {
+    const target = event.target;
+    if (!(target instanceof HTMLInputElement) || target.name !== "theme") {
+      return;
+    }
+
+    const { value } = target;
+    if (!THEME_OPTIONS.some((option) => option.value === value)) {
+      return;
+    }
+
+    if (PDS.theme !== value) {
+      PDS.theme = value;
+    }
+
+  };
+
+  #attachObserver() {
+    if (this.#observer) return;
+
+    this.#observer = new MutationObserver(() => {
+      this.#syncCheckedState();
+    });
+
+    this.#observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ["data-theme"],
+    });
+  }
+
+  #teardownObserver() {
+    if (!this.#observer) return;
+    this.#observer.disconnect();
+    this.#observer = undefined;
+  }
+
+  #syncLegend() {
+    const legend = this.shadowRoot.querySelector("legend");
+    const fieldset = this.shadowRoot.querySelector("fieldset");
+    if (legend) legend.textContent = this.label;
+    if (fieldset) fieldset.setAttribute("aria-label", this.label);
+  }
+
+  #syncCheckedState() {
+    const currentTheme = PDS.theme || "system";
+    this.shadowRoot
+      .querySelectorAll('input[type="radio"]')
+      .forEach((radio) => {
+        radio.checked = radio.value === currentTheme;
+      });
+  }
+}
+
+if (!customElements.get("pds-theme")) {
+  customElements.define("pds-theme", PdsTheme);
+}

package/public/assets/pds/vscode-custom-data.json

@@ -775,6 +775,16 @@
         }
       ]
     },
+    {
+      "name": "pds-theme",
+      "description": "PdsTheme component",
+      "attributes": [
+        {
+          "name": "label",
+          "description": ""
+        }
+      ]
+    },
     {
       "name": "pds-toaster",
       "description": "AppToaster component"

package/stories/components/PdsTheme/PdsTheme.stories.js

@@ -0,0 +1,68 @@
+import { html } from 'lit';
+import { createComponentDocsPage } from '../../reference/reference-docs.js';
+
+const componentDescription = `The \`<pds-theme>\` component lets users switch between **system**, **light**, and **dark** modes.
+It updates \`PDS.theme\`, stays in sync with programmatic changes, and emits \`pds:theme:changed\` so bootstrap code can react (for example, to show a toast).
+
+---
+
+## Quick Reference
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| \`label\` | string | \`"Theme"\` | Custom legend + aria-label |
+
+Listen for global theme updates with \`PDS.addEventListener('pds:theme:changed', handler)\` when other UI needs to respond.
+`;
+
+const docsParameters = {
+  description: {
+    component: componentDescription
+  },
+  page: createComponentDocsPage('pds-theme')
+};
+
+const renderThemeToggle = (args) => html`
+  <pds-theme
+    label=${args.label || ''}
+  ></pds-theme>
+`;
+
+export default {
+  title: 'Components/Pds Theme',
+  tags: ['autodocs', 'theme', 'appearance', 'pds-theme', 'switcher'],
+  parameters: {
+    pds: {
+      tags: ['theme', 'appearance', 'toggle', 'pds-theme']
+    },
+    docs: docsParameters
+  },
+  argTypes: {
+    label: {
+      control: 'text',
+      description: 'Legend + aria-label text'
+    }
+  }
+};
+
+export const Playground = {
+  name: 'Interactive Playground',
+  args: {
+    label: 'Theme'
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use the controls to adjust the component label.'
+      }
+    }
+  },
+  render: (args) => html`
+    <div class="stack-md">
+      <p class="text-muted">The toggle updates <code>PDS.theme</code> so the rest of your UI stays in sync.</p>
+      ${renderThemeToggle(args)}
+    </div>
+  `
+};
+
+

package/stories/getting-started.md

@@ -21,7 +21,6 @@ What you get (key files):
 - `pds.config.js` — your design system config
 - `src/js/app.js` — bootstraps PDS and mounts the app
 - `public/assets/my/my-home.js` — your first web component
-- `public/assets/my/my-theme.js` — simple dark/light mode switcher
 - `public/index.html` — app shell
 
 **Next edits:**