@adia-ai/web-modules 0.4.1 → 0.4.3

package/theme/theme-panel/theme-panel.test.js

@@ -0,0 +1,274 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import '../../../web-components/core/element.js';
+// Stub primitives that theme-panel composes — they don't need to render
+// anything visible for these behavior tests; we just need them to register
+// so customElements.define() inside theme-panel sees its DOM children as
+// known elements (otherwise happy-dom treats them as HTMLUnknownElement,
+// which is fine for our assertions).
+import './theme-panel.js';
+
+const tick = () => new Promise((r) => queueMicrotask(r));
+
+function mount(html) {
+  const wrap = document.createElement('div');
+  wrap.innerHTML = html;
+  document.body.appendChild(wrap);
+  return wrap.firstElementChild;
+}
+
+// happy-dom doesn't implement matchMedia; stub a non-dark default.
+let mqlListeners = [];
+function installMatchMedia({ dark = false } = {}) {
+  globalThis.matchMedia = (query) => ({
+    matches: query.includes('dark') ? dark : false,
+    media: query,
+    addEventListener: (_evt, fn) => { mqlListeners.push(fn); },
+    removeEventListener: (_evt, fn) => {
+      mqlListeners = mqlListeners.filter((f) => f !== fn);
+    },
+    addListener: (fn) => { mqlListeners.push(fn); },
+    removeListener: (fn) => {
+      mqlListeners = mqlListeners.filter((f) => f !== fn);
+    },
+  });
+}
+
+// happy-dom's requestAnimationFrame is sync via setTimeout; force it
+// synchronous so #onThemeClick's slider sync runs in the test's tick().
+beforeEach(() => {
+  document.body.innerHTML = '';
+  try { localStorage.clear(); } catch {}
+  mqlListeners = [];
+  installMatchMedia({ dark: false });
+  // Synchronous rAF for deterministic tests
+  globalThis.requestAnimationFrame = (cb) => { cb(); return 0; };
+});
+
+afterEach(() => {
+  // Always clean any html-level inline state so tests don't leak
+  document.documentElement.removeAttribute('data-theme');
+  document.documentElement.style.removeProperty('--a-density');
+  document.documentElement.style.removeProperty('--a-radius-k');
+  document.documentElement.style.removeProperty('color-scheme');
+});
+
+describe('theme-panel', () => {
+  it('registers theme-panel as a custom element', () => {
+    expect(customElements.get('theme-panel')).toBeDefined();
+  });
+
+  it('stamps internal DOM on connect (themes row)', async () => {
+    const tp = mount('<theme-panel></theme-panel>');
+    await tick();
+    const themes = tp.querySelector('[part="themes"]');
+    expect(themes).toBeTruthy();
+    // 8 default themes
+    expect(themes.querySelectorAll('button-ui').length).toBe(8);
+  });
+
+  it('renders only minimum surface by default (no sliders, presets, scheme)', async () => {
+    const tp = mount('<theme-panel></theme-panel>');
+    await tick();
+    expect(tp.querySelector('[part="presets"]')).toBeNull();
+    expect(tp.querySelector('[part="scheme"]')).toBeNull();
+    expect(tp.querySelector('slider-ui')).toBeNull();
+  });
+
+  it('[parametric] adds density + radius sliders', async () => {
+    const tp = mount('<theme-panel parametric></theme-panel>');
+    await tick();
+    expect(tp.querySelector('slider-ui[part="density"]')).toBeTruthy();
+    expect(tp.querySelector('slider-ui[part="radius"]')).toBeTruthy();
+  });
+
+  it('[presets] adds the preset row (compact/default/spacious)', async () => {
+    const tp = mount('<theme-panel presets></theme-panel>');
+    await tick();
+    const presets = tp.querySelector('[part="presets"]');
+    expect(presets).toBeTruthy();
+    const buttons = [...presets.querySelectorAll('button-ui')];
+    expect(buttons.map((b) => b.getAttribute('data-preset'))).toEqual(['compact', 'default', 'spacious']);
+  });
+
+  it('[scheme-toggle] adds the segmented scheme picker', async () => {
+    const tp = mount('<theme-panel scheme-toggle></theme-panel>');
+    await tick();
+    expect(tp.querySelector('[part="scheme"] segmented-ui')).toBeTruthy();
+  });
+
+  it('theme button click sets [data-theme] on the target (defaults to <html>)', async () => {
+    const tp = mount('<theme-panel></theme-panel>');
+    await tick();
+    const oceanBtn = tp.querySelector('button-ui[data-theme-slug="ocean"]');
+    oceanBtn.dispatchEvent(new Event('click', { bubbles: true }));
+    await tick();
+    expect(document.documentElement.getAttribute('data-theme')).toBe('ocean');
+    expect(tp.getAttribute('active-theme')).toBe('ocean');
+  });
+
+  it('theme button click for "default" clears [data-theme]', async () => {
+    document.documentElement.setAttribute('data-theme', 'ocean');
+    const tp = mount('<theme-panel></theme-panel>');
+    await tick();
+    const defaultBtn = tp.querySelector('button-ui[data-theme-slug="default"]');
+    defaultBtn.dispatchEvent(new Event('click', { bubbles: true }));
+    await tick();
+    expect(document.documentElement.hasAttribute('data-theme')).toBe(false);
+    expect(tp.getAttribute('active-theme')).toBe('');
+  });
+
+  it('fires theme-change event with source: "theme" on theme click', async () => {
+    const tp = mount('<theme-panel></theme-panel>');
+    await tick();
+    const onChange = vi.fn();
+    tp.addEventListener('theme-change', onChange);
+    tp.querySelector('button-ui[data-theme-slug="forest"]').dispatchEvent(new Event('click', { bubbles: true }));
+    await tick();
+    expect(onChange).toHaveBeenCalled();
+    const detail = onChange.mock.calls[0][0].detail;
+    expect(detail.theme).toBe('forest');
+    expect(detail.source).toBe('theme');
+  });
+
+  it('sliders write --a-density / --a-radius-k on target', async () => {
+    const tp = mount('<theme-panel parametric></theme-panel>');
+    await tick();
+    const density = tp.querySelector('slider-ui[part="density"]');
+    density.value = '1.2';
+    density.dispatchEvent(new Event('input', { bubbles: true }));
+    await tick();
+    expect(document.documentElement.style.getPropertyValue('--a-density')).toBe('1.2');
+
+    const radius = tp.querySelector('slider-ui[part="radius"]');
+    radius.value = '0.6';
+    radius.dispatchEvent(new Event('input', { bubbles: true }));
+    await tick();
+    expect(document.documentElement.style.getPropertyValue('--a-radius-k')).toBe('0.6');
+  });
+
+  it('preset "compact" applies (0.85, 0.75)', async () => {
+    const tp = mount('<theme-panel parametric presets></theme-panel>');
+    await tick();
+    const compact = tp.querySelector('button-ui[data-preset="compact"]');
+    compact.dispatchEvent(new Event('click', { bubbles: true }));
+    await tick();
+    expect(document.documentElement.style.getPropertyValue('--a-density')).toBe('0.85');
+    expect(document.documentElement.style.getPropertyValue('--a-radius-k')).toBe('0.75');
+  });
+
+  it('preset "spacious" applies (1.15, 1.25)', async () => {
+    const tp = mount('<theme-panel parametric presets></theme-panel>');
+    await tick();
+    const spacious = tp.querySelector('button-ui[data-preset="spacious"]');
+    spacious.dispatchEvent(new Event('click', { bubbles: true }));
+    await tick();
+    expect(document.documentElement.style.getPropertyValue('--a-density')).toBe('1.15');
+    expect(document.documentElement.style.getPropertyValue('--a-radius-k')).toBe('1.25');
+  });
+
+  it('preset "default" (Reset) clears [data-theme]', async () => {
+    document.documentElement.setAttribute('data-theme', 'ocean');
+    const tp = mount('<theme-panel parametric presets></theme-panel>');
+    await tick();
+    const reset = tp.querySelector('button-ui[data-preset="default"]');
+    reset.dispatchEvent(new Event('click', { bubbles: true }));
+    await tick();
+    expect(document.documentElement.hasAttribute('data-theme')).toBe(false);
+  });
+
+  it('[persist] writes localStorage keys on theme click', async () => {
+    const tp = mount('<theme-panel persist></theme-panel>');
+    await tick();
+    tp.querySelector('button-ui[data-theme-slug="ocean"]').dispatchEvent(new Event('click', { bubbles: true }));
+    await tick();
+    expect(localStorage.getItem('adia-theme-theme')).toBe('ocean');
+  });
+
+  it('absence of [persist] does NOT write localStorage', async () => {
+    const tp = mount('<theme-panel></theme-panel>');
+    await tick();
+    tp.querySelector('button-ui[data-theme-slug="ocean"]').dispatchEvent(new Event('click', { bubbles: true }));
+    await tick();
+    expect(localStorage.getItem('adia-theme-theme')).toBeNull();
+  });
+
+  it('reset() clears all state and emits source: "reset"', async () => {
+    document.documentElement.setAttribute('data-theme', 'ocean');
+    document.documentElement.style.setProperty('--a-density', '1.2');
+    const tp = mount('<theme-panel parametric persist></theme-panel>');
+    await tick();
+    const onChange = vi.fn();
+    tp.addEventListener('theme-change', onChange);
+    tp.reset();
+    await tick();
+    expect(document.documentElement.hasAttribute('data-theme')).toBe(false);
+    expect(document.documentElement.style.getPropertyValue('--a-density')).toBe('');
+    expect(onChange).toHaveBeenCalled();
+    expect(onChange.mock.calls[0][0].detail.source).toBe('reset');
+  });
+
+  it('[storage-prefix] override changes LS key namespace', async () => {
+    const tp = mount('<theme-panel persist storage-prefix="my-app-"></theme-panel>');
+    await tick();
+    tp.querySelector('button-ui[data-theme-slug="ocean"]').dispatchEvent(new Event('click', { bubbles: true }));
+    await tick();
+    expect(localStorage.getItem('my-app-theme')).toBe('ocean');
+    expect(localStorage.getItem('adia-theme-theme')).toBeNull();
+  });
+
+  it('apply({theme}) is equivalent to a theme click and emits source: "programmatic"', async () => {
+    const tp = mount('<theme-panel></theme-panel>');
+    await tick();
+    const onChange = vi.fn();
+    tp.addEventListener('theme-change', onChange);
+    tp.apply({ theme: 'slate' });
+    await tick();
+    expect(document.documentElement.getAttribute('data-theme')).toBe('slate');
+    expect(onChange.mock.calls[0][0].detail.source).toBe('programmatic');
+  });
+
+  it('PCM listener attaches when scheme="auto" and no persisted scheme', async () => {
+    const tp = mount('<theme-panel scheme-toggle></theme-panel>');
+    await tick();
+    // mqlListeners is populated by our matchMedia stub on addEventListener('change', ...)
+    expect(mqlListeners.length).toBeGreaterThan(0);
+    expect(tp.getAttribute('active-scheme')).toBe('light'); // our stub returns dark=false
+  });
+
+  it('PCM listener does NOT attach when [persist] has a saved scheme', async () => {
+    try { localStorage.setItem('adia-theme-scheme', 'dark'); } catch {}
+    const tp = mount('<theme-panel persist scheme-toggle></theme-panel>');
+    await tick();
+    expect(mqlListeners.length).toBe(0);
+    expect(tp.getAttribute('active-scheme')).toBe('dark');
+  });
+
+  it('[target] scoped selector writes to that element, not <html>', async () => {
+    const preview = document.createElement('div');
+    preview.id = 'preview';
+    document.body.appendChild(preview);
+    const tp = mount('<theme-panel target="#preview"></theme-panel>');
+    await tick();
+    tp.querySelector('button-ui[data-theme-slug="ocean"]').dispatchEvent(new Event('click', { bubbles: true }));
+    await tick();
+    expect(preview.getAttribute('data-theme')).toBe('ocean');
+    expect(document.documentElement.getAttribute('data-theme')).toBeNull();
+  });
+
+  it('cleans up listeners on disconnect (no zombie listeners)', async () => {
+    const tp = mount('<theme-panel scheme-toggle></theme-panel>');
+    await tick();
+    expect(mqlListeners.length).toBeGreaterThan(0);
+    tp.remove();
+    await tick();
+    expect(mqlListeners.length).toBe(0);
+  });
+
+  it('restricted [themes] list renders only the listed slugs', async () => {
+    const tp = mount('<theme-panel themes="default ocean"></theme-panel>');
+    await tick();
+    const buttons = [...tp.querySelectorAll('[part="themes"] button-ui')];
+    expect(buttons.length).toBe(2);
+    expect(buttons.map((b) => b.getAttribute('data-theme-slug'))).toEqual(['default', 'ocean']);
+  });
+});

package/theme/theme-panel/theme-panel.yaml

@@ -0,0 +1,213 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: ThemePanel
+tag: theme-panel
+component: ThemePanel
+category: layout
+version: 1
+description: |
+  Module-tier appearance-preferences control surface. Owns the three knobs
+  of the AdiaUI theming contract: [data-theme=<slug>] named themes,
+  --a-density / --a-radius-k parametric overrides, and color-scheme
+  light/dark switching, plus optional localStorage persistence behind a
+  small attribute API.
+
+  Drops into any consumer's <popover-ui slot="content"> (the canonical
+  composition) or directly into a sidebar section. Eight named themes
+  ship by default; section visibility flips on/off via boolean attributes
+  ([parametric], [presets], [scheme-toggle]).
+
+  Promoted from the duplicated <div id="theme-panel"> block in site/ and
+  playgrounds/admin-shell/ — see docs/specs/theme-panel-module.md.
+
+props:
+  themes:
+    description: |
+      Space-separated list of theme slugs to render as buttons. Author
+      may restrict ([themes="default ocean"]) or extend. Tolerant —
+      unknown slugs render a button; clicking applies [data-theme=slug]
+      regardless of whether themes.css has a matching block.
+    type: string
+    default: "default ocean forest sunset lavender rose slate midnight"
+    reflect: true
+
+  parametric:
+    description: |
+      Renders the density + radius slider block. Sliders bind to
+      --a-density and --a-radius-k on the target element.
+    type: boolean
+    default: false
+    reflect: true
+
+  presets:
+    description: |
+      Renders the compact / reset / spacious preset row. Each preset
+      applies a (density, radius) pair; "default" also clears the
+      [data-theme] attribute.
+    type: boolean
+    default: false
+    reflect: true
+
+  scheme-toggle:
+    description: |
+      Renders an integrated light/dark <segmented-ui> at the top of the
+      panel. When absent, the panel omits scheme entirely — consumers
+      can still drive scheme via the .apply({scheme}) public method.
+    type: boolean
+    default: false
+    reflect: true
+    attribute: scheme-toggle
+
+  persist:
+    description: |
+      Persists selections to localStorage. Defaults to ephemeral so
+      playgrounds and embedded demos do not silently mutate a user's
+      docs-shell preferences.
+    type: boolean
+    default: false
+    reflect: true
+
+  storage-prefix:
+    description: |
+      Namespace for localStorage keys when [persist] is set. Four keys
+      are written: {prefix}theme, {prefix}scheme, {prefix}density,
+      {prefix}radius.
+    type: string
+    default: "adia-theme-"
+    reflect: true
+    attribute: storage-prefix
+
+  target:
+    description: |
+      CSS selector for the element that receives [data-theme] and
+      --a-density / --a-radius-k writes. Defaults to :root (the
+      <html> element). Scoped targets are useful for preview-pane
+      demos.
+    type: string
+    default: ":root"
+    reflect: true
+
+  scheme:
+    description: |
+      Initial color-scheme. "auto" follows prefers-color-scheme via a
+      matchMedia listener; user clicks on the scheme toggle promote to
+      an explicit light or dark choice.
+    type: string
+    default: "auto"
+    enum: ["light", "dark", "auto"]
+    reflect: true
+
+  active-theme:
+    description: |
+      Reflected — the currently selected theme slug. Empty string when
+      unset (default theme). Read-only externally; use .apply({theme})
+      to change.
+    type: string
+    default: ""
+    reflect: true
+    attribute: active-theme
+
+  active-scheme:
+    description: |
+      Reflected — the resolved color-scheme (auto collapsed to a
+      concrete value). Either "light" or "dark".
+    type: string
+    default: ""
+    reflect: true
+    attribute: active-scheme
+
+  active-density:
+    description: |
+      Reflected — mirrors the current --a-density value on the target
+      element. Stringified number.
+    type: string
+    default: ""
+    reflect: true
+    attribute: active-density
+
+  active-radius:
+    description: |
+      Reflected — mirrors the current --a-radius-k value on the target
+      element. Stringified number.
+    type: string
+    default: ""
+    reflect: true
+    attribute: active-radius
+
+events:
+  theme-change:
+    description: |
+      Bubbles when any user-visible state changes (theme click, slider
+      input, preset click, scheme flip, reset). One event per change.
+      No event on auto-rehydrate-from-storage at boot.
+    detail:
+      theme: string
+      scheme: string
+      density: number
+      radius: number
+      source: string
+
+slots: {}
+
+states:
+  - name: idle
+    description: Default — panel rendered, awaiting input.
+  - name: persisted
+    description: |
+      [persist] is set; selections write to localStorage under
+      [storage-prefix].
+    attribute: persist
+  - name: scheme-auto
+    description: |
+      [scheme="auto"] and no user override this session; a
+      prefers-color-scheme listener reapplies on system flip.
+
+traits: []
+
+a2ui:
+  rules:
+    - >-
+      theme-panel is the canonical appearance-preferences popover.
+      Compose inside a <popover-ui slot="content"> in the topbar of a
+      shell (admin, chat, editor, simple) when the page exposes user
+      theming. Avoid hardcoding it as a shell child — placement is the
+      consumer's call.
+    - >-
+      Use [persist] for the docs surface or a real product app; omit
+      [persist] for playgrounds and embedded demos so state stays
+      ephemeral. The default is ephemeral.
+    - >-
+      Add boolean attributes [parametric], [presets], [scheme-toggle]
+      to enable sections; the minimum panel is the theme button grid.
+
+keywords:
+  - theme
+  - theme-panel
+  - palette
+  - density
+  - radius
+  - scheme
+  - dark-mode
+  - light-mode
+  - color-scheme
+  - preferences
+  - settings
+  - color
+  - appearance
+  - skin
+
+synonyms:
+  theme: [palette, skin, appearance]
+  scheme: [mode, color-scheme, dark-mode]
+  density: [compactness, spacing-scale]
+  radius: [corner-roundness, border-radius]
+
+related:
+  - Popover
+  - Button
+  - Slider
+  - Field
+  - Divider
+  - Text
+  - Segmented
+  - AdminShell