@adia-ai/web-components 0.4.4 → 0.4.6

package/components/toggle-scheme/toggle-scheme.js

@@ -0,0 +1,277 @@
+/**
+ * <toggle-scheme-ui>
+ *
+ * Icon-button primitive that toggles `color-scheme` between light and dark
+ * on a target element (default `:root`). Replaces the hand-wired
+ * `<button-ui id="theme-toggle"> + applyScheme()` boilerplate previously
+ * duplicated across apps/genui, apps/construct-canvas, playgrounds/chat.
+ *
+ * Composition: light-DOM host, internally stamps a single <button-ui>.
+ *
+ * Authoring API:
+ *   [scheme="auto"|"light"|"dark"]   initial scheme (default "auto")
+ *   [target=":root"]                 CSS selector for target element
+ *   [persist]                        write selection to localStorage
+ *   [storage-prefix="adia-theme-"]   LS key namespace (matches theme-panel)
+ *   [icon-light="sun"]               icon shown when active-scheme is light
+ *   [icon-dark="moon"]               icon shown when active-scheme is dark
+ *   [label-light]                    aria-label / title in light mode
+ *   [label-dark]                     aria-label / title in dark mode
+ *   [size="md"]                      forwarded to internal <button-ui>
+ *   [variant="ghost"]                forwarded to internal <button-ui>
+ *   [color=""]                       forwarded to internal <button-ui>
+ *   [disabled]                       forwarded to internal <button-ui>
+ *
+ * Reflected state (read-only externally; use .setScheme() to mutate):
+ *   [active-scheme]   resolved scheme ("light" | "dark")
+ *
+ * Events:
+ *   scheme-change — bubbles. detail: { scheme, source }
+ *     source ∈ "press" | "media" | "programmatic"
+ *
+ * Public methods:
+ *   .toggle()                 flip between light and dark (defeats auto)
+ *   .setScheme(s)             "light" | "dark" | "auto"; programmatic write
+ */
+
+import { UIElement } from '../../core/element.js';
+import '../button/button.js';
+
+const LIGHT = 'light';
+const DARK  = 'dark';
+const AUTO  = 'auto';
+
+class UIToggleScheme extends UIElement {
+  static properties = {
+    scheme:        { type: String,  default: AUTO,   reflect: true },
+    target:        { type: String,  default: ':root', reflect: true },
+    persist:       { type: Boolean, default: false, reflect: true },
+    storagePrefix: { type: String,  default: 'adia-theme-', reflect: true, attribute: 'storage-prefix' },
+    iconLight:     { type: String,  default: 'sun',  reflect: true, attribute: 'icon-light' },
+    iconDark:      { type: String,  default: 'moon', reflect: true, attribute: 'icon-dark' },
+    labelLight:    { type: String,  default: 'Switch to dark mode',  reflect: true, attribute: 'label-light' },
+    labelDark:     { type: String,  default: 'Switch to light mode', reflect: true, attribute: 'label-dark' },
+    size:          { type: String,  default: 'md',    reflect: true },
+    variant:       { type: String,  default: 'ghost', reflect: true },
+    color:         { type: String,  default: '',      reflect: true },
+    disabled:      { type: Boolean, default: false,   reflect: true },
+    activeScheme:  { type: String,  default: '',      reflect: true, attribute: 'active-scheme' },
+  };
+
+  static template = () => null;
+
+  #button = null;
+  #mql = null;
+  #mqlHandler = null;
+  #onPress = null;
+  #stamped = false;
+
+  connected() {
+    if (!this.#stamped) {
+      this.#stamp();
+      this.#stamped = true;
+    }
+    this.#initState();
+  }
+
+  disconnected() {
+    if (this.#button && this.#onPress) {
+      this.#button.removeEventListener('press', this.#onPress);
+    }
+    this.#detachPcm();
+  }
+
+  // ── Public API ──────────────────────────────────────────────────────
+
+  /** Flip between light and dark — defeats auto. */
+  toggle() {
+    const next = this.activeScheme === DARK ? LIGHT : DARK;
+    this.#apply(next, 'programmatic');
+  }
+
+  /**
+   * @param {"light"|"dark"|"auto"} s
+   */
+  setScheme(s) {
+    if (s === AUTO) {
+      this.#clearTargetOverride();
+      const resolved = this.#resolvePrefersScheme();
+      this.activeScheme = resolved;
+      this.#syncButton();
+      this.#attachPcm();
+      this.#emit('programmatic');
+    } else if (s === LIGHT || s === DARK) {
+      this.#apply(s, 'programmatic');
+    }
+  }
+
+  // ── Internal — stamping ─────────────────────────────────────────────
+
+  #stamp() {
+    const btn = document.createElement('button-ui');
+    btn.setAttribute('part', 'button');
+    btn.setAttribute('variant', this.variant || 'ghost');
+    btn.setAttribute('size', this.size || 'md');
+    if (this.color) btn.setAttribute('color', this.color);
+    if (this.disabled) btn.setAttribute('disabled', '');
+    this.appendChild(btn);
+
+    this.#button = btn;
+    this.#onPress = (e) => {
+      // Internal button bubbles 'press'; we re-emit our own 'scheme-change'
+      // so consumers see one semantic event, not the inner button's.
+      e.stopPropagation();
+      if (this.disabled) return;
+      const next = this.activeScheme === DARK ? LIGHT : DARK;
+      this.#apply(next, 'press');
+    };
+    btn.addEventListener('press', this.#onPress);
+  }
+
+  // ── Internal — initial state ────────────────────────────────────────
+
+  #initState() {
+    // Priority: persisted > [scheme] attr > auto
+    let initial = null;
+    if (this.persist) {
+      try {
+        const v = localStorage.getItem(`${this.storagePrefix}scheme`);
+        if (v === LIGHT || v === DARK) initial = v;
+      } catch {}
+    }
+    if (initial === null) {
+      const attr = (this.scheme || AUTO);
+      if (attr === LIGHT || attr === DARK) initial = attr;
+    }
+
+    if (initial === LIGHT || initial === DARK) {
+      // Explicit choice — write to target, no MQL listening
+      this.#writeTarget(initial);
+      this.activeScheme = initial;
+    } else {
+      // Auto — follow prefers-color-scheme, attach listener
+      this.activeScheme = this.#resolvePrefersScheme();
+      this.#attachPcm();
+    }
+    this.#syncButton();
+  }
+
+  // ── Internal — mutation (single path) ───────────────────────────────
+
+  #apply(next, source) {
+    if (next !== LIGHT && next !== DARK) return;
+    this.#writeTarget(next);
+    this.activeScheme = next;
+    if (this.persist) {
+      try { localStorage.setItem(`${this.storagePrefix}scheme`, next); } catch {}
+    }
+    // User picked explicitly — stop tracking OS preference
+    this.#detachPcm();
+    this.#syncButton();
+    this.#emit(source);
+  }
+
+  #syncButton() {
+    if (!this.#button) return;
+    const dark = this.activeScheme === DARK;
+    const icon = dark ? this.iconDark : this.iconLight;
+    const label = dark ? this.labelDark : this.labelLight;
+    if (this.#button.getAttribute('icon') !== icon) {
+      this.#button.setAttribute('icon', icon);
+    }
+    this.#button.setAttribute('aria-label', label);
+    this.#button.setAttribute('title', label);
+    // Forward style passthrough so authors can change variant/size/color
+    // at runtime and the internal button reflects it.
+    if (this.#button.getAttribute('variant') !== this.variant) {
+      this.#button.setAttribute('variant', this.variant || 'ghost');
+    }
+    if (this.#button.getAttribute('size') !== this.size) {
+      this.#button.setAttribute('size', this.size || 'md');
+    }
+    if (this.color) {
+      this.#button.setAttribute('color', this.color);
+    } else {
+      this.#button.removeAttribute('color');
+    }
+    if (this.disabled) {
+      this.#button.setAttribute('disabled', '');
+    } else {
+      this.#button.removeAttribute('disabled');
+    }
+  }
+
+  render() {
+    // Property writes after connect (e.g. el.size = 'sm') route through here.
+    this.#syncButton();
+  }
+
+  #emit(source) {
+    this.dispatchEvent(new CustomEvent('scheme-change', {
+      bubbles: true,
+      detail: { scheme: this.activeScheme, source },
+    }));
+  }
+
+  // ── Internal — target resolution + write ────────────────────────────
+
+  #resolveTarget() {
+    const sel = this.target || ':root';
+    if (sel === ':root') return document.documentElement;
+    try {
+      return document.querySelector(sel) ?? document.documentElement;
+    } catch {
+      return document.documentElement;
+    }
+  }
+
+  #writeTarget(scheme) {
+    const t = this.#resolveTarget();
+    t.style.setProperty('color-scheme', scheme);
+  }
+
+  #clearTargetOverride() {
+    const t = this.#resolveTarget();
+    t.style.removeProperty('color-scheme');
+    if (this.persist) {
+      try { localStorage.removeItem(`${this.storagePrefix}scheme`); } catch {}
+    }
+  }
+
+  // ── Internal — prefers-color-scheme ─────────────────────────────────
+
+  #resolvePrefersScheme() {
+    try {
+      if (typeof matchMedia === 'function' &&
+          matchMedia('(prefers-color-scheme: dark)').matches) return DARK;
+    } catch {}
+    return LIGHT;
+  }
+
+  #attachPcm() {
+    if (this.#mql || typeof matchMedia !== 'function') return;
+    try {
+      this.#mql = matchMedia('(prefers-color-scheme: dark)');
+      this.#mqlHandler = () => {
+        const resolved = this.#mql.matches ? DARK : LIGHT;
+        if (resolved === this.activeScheme) return;
+        this.activeScheme = resolved;
+        this.#syncButton();
+        this.#emit('media');
+      };
+      this.#mql.addEventListener('change', this.#mqlHandler);
+    } catch {}
+  }
+
+  #detachPcm() {
+    if (this.#mql && this.#mqlHandler) {
+      try { this.#mql.removeEventListener('change', this.#mqlHandler); } catch {}
+    }
+    this.#mql = null;
+    this.#mqlHandler = null;
+  }
+}
+
+customElements.define('toggle-scheme-ui', UIToggleScheme);
+
+export { UIToggleScheme };

package/components/toggle-scheme/toggle-scheme.yaml

@@ -0,0 +1,173 @@
+# Edit this file; run `node scripts/build/components.mjs` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIToggleScheme
+tag: toggle-scheme-ui
+component: ToggleScheme
+category: control
+version: 1
+description: >-
+  Icon-button primitive that toggles `color-scheme` between light and dark on
+  a target element (default `:root`). Encapsulates the prefers-color-scheme
+  initial-resolution, the inline-style write to the target, optional
+  localStorage persistence (sharing the `adia-theme-` namespace with
+  <theme-panel>), and the moon/sun icon swap. Replaces the hand-wired
+  `<button-ui id="theme-toggle">` + `applyScheme()` pattern previously
+  duplicated across apps/genui, apps/construct-canvas, playgrounds/chat.
+props:
+  scheme:
+    description: Initial scheme — "auto" follows prefers-color-scheme; "light" / "dark" force.
+    type: string
+    default: auto
+    enum:
+      - auto
+      - light
+      - dark
+    reflect: true
+  target:
+    description: CSS selector for the element receiving `color-scheme`. ":root" → <html>.
+    type: string
+    default: ":root"
+    reflect: true
+  persist:
+    description: Persist the user's choice to localStorage under `${storage-prefix}scheme`.
+    type: boolean
+    default: false
+    reflect: true
+  storagePrefix:
+    description: LocalStorage key prefix; default matches <theme-panel> for cross-element interop.
+    type: string
+    default: "adia-theme-"
+    attribute: storage-prefix
+    reflect: true
+  iconLight:
+    description: Phosphor icon shown when active-scheme is "light" (clicking switches to dark).
+    type: string
+    default: sun
+    attribute: icon-light
+    reflect: true
+  iconDark:
+    description: Phosphor icon shown when active-scheme is "dark" (clicking switches to light).
+    type: string
+    default: moon
+    attribute: icon-dark
+    reflect: true
+  labelLight:
+    description: aria-label / title applied to the internal button when active-scheme is "light".
+    type: string
+    default: "Switch to dark mode"
+    attribute: label-light
+    reflect: true
+  labelDark:
+    description: aria-label / title applied to the internal button when active-scheme is "dark".
+    type: string
+    default: "Switch to light mode"
+    attribute: label-dark
+    reflect: true
+  size:
+    description: Sizing scale forwarded to the internal <button-ui>.
+    type: string
+    default: md
+    enum:
+      - xs
+      - sm
+      - md
+      - lg
+      - xl
+    reflect: true
+  variant:
+    description: Visual style forwarded to the internal <button-ui>. Defaults to "ghost" (matches app practice).
+    type: string
+    default: ghost
+    enum:
+      - default
+      - solid
+      - outline
+      - ghost
+      - primary
+      - secondary
+      - soft
+    reflect: true
+  color:
+    description: Semantic intent forwarded to the internal <button-ui>.
+    type: string
+    default: ""
+    enum:
+      - ""
+      - default
+      - accent
+      - info
+      - success
+      - warning
+      - danger
+    reflect: true
+  disabled:
+    description: Disables the internal button.
+    type: boolean
+    default: false
+    reflect: true
+  activeScheme:
+    description: Resolved scheme ("light" | "dark"). Read-only; mutate via .setScheme() or .toggle().
+    type: string
+    default: ""
+    enum:
+      - ""
+      - light
+      - dark
+    attribute: active-scheme
+    reflect: true
+events:
+  scheme-change:
+    description: >-
+      Fired when the active scheme changes. detail contains
+      { scheme: "light" | "dark", source: "press" | "media" | "programmatic" }.
+slots: {}
+states:
+  - name: idle
+    description: Default, ready for interaction.
+  - name: light
+    description: Active scheme is light.
+    attribute: active-scheme
+  - name: dark
+    description: Active scheme is dark.
+    attribute: active-scheme
+  - name: disabled
+    description: Non-interactive; the internal button is disabled.
+    attribute: disabled
+traits: []
+tokens:
+  --toggle-scheme-icon-transition:
+    description: Duration + easing for icon-color transition when scheme flips.
+a2ui:
+  rules: []
+anti_patterns: []
+examples:
+  - name: header-action
+    description: Drop into a toolbar / app header as a single icon-button affordance.
+    a2ui: >-
+      [
+        {
+          "id": "root",
+          "component": "ToggleScheme",
+          "persist": true
+        }
+      ]
+keywords:
+  - scheme
+  - color-scheme
+  - dark-mode
+  - light-mode
+  - theme
+  - toggle
+  - moon
+  - sun
+synonyms:
+  toggle:
+    - toggle-scheme
+    - switch
+  dark-mode:
+    - toggle-scheme
+  theme-toggle:
+    - toggle-scheme
+related:
+  - Button
+  - Switch

package/components/upload/upload.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `<upload-ui>` — File upload dropzone + picker.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/upload
+ */
+
+import { UIFormElement } from '../../core/form.js';
+
+export interface UploadChangeEventDetail {
+  /** Form value — comma-joined filenames (FormData carries the actual files). */
+  value: string;
+  /** Selected files as a FileList. */
+  files: FileList | File[];
+}
+export type UploadChangeEvent = CustomEvent<UploadChangeEventDetail>;
+
+export class UIUpload extends UIFormElement {
+  /** Files currently selected. */
+  readonly files: FileList | File[];
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIUpload, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'change', listener: (ev: UploadChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/components/upload/upload.js

@@ -168,7 +168,7 @@ class UIUpload extends UIFormElement {
     }
     this.internals.setFormValue(fd);
 
-    this.dispatchEvent(new Event('change', { bubbles: true }));
+    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value, files: this.files } }));
     this.render();
   }
 

package/core/element.d.ts

@@ -0,0 +1,174 @@
+/**
+ * UIElement — light-DOM reactive base class.
+ *
+ * Every primitive in `@adia-ai/web-components` extends this (or `UIFormElement`
+ * for form-bearing primitives). Provides signal-backed property reactivity,
+ * lifecycle hooks (`connected`/`render`/`updated`/`disconnected`), and
+ * tagged-template rendering.
+ *
+ * @see ../USAGE.md#lifecycle
+ * @see ../USAGE.md#property-reactivity-signal-backed
+ */
+
+import type { ReadonlySignal, Signal } from './signals.js';
+import type { TemplateResult } from './template.js';
+
+/** Property declaration in a component's `static properties = { … }` map. */
+export interface PropertyConfig<T = unknown> {
+  /** Coercion target — `Boolean`, `Number`, `String`, or custom. */
+  type?: BooleanConstructor | NumberConstructor | StringConstructor | (new (...args: unknown[]) => T);
+  /** Initial value. Defaults to `undefined`. */
+  default?: T;
+  /** Mirror property changes to an HTML attribute. */
+  reflect?: boolean;
+  /** Custom attribute name. Default: kebab-case of property key. */
+  attribute?: string;
+}
+
+/** Map of property name → config. The shape consumed by `static properties`. */
+export type PropertiesMap = Record<string, PropertyConfig>;
+
+/** Trait name + config tuple passed via `static traits`. */
+export type TraitDeclaration = string | { name: string; [opt: string]: unknown };
+
+/** Map of slot name → markup string. Consumed by `static parts`. */
+export type PartsMap = Record<string, string>;
+
+/**
+ * Light-DOM reactive base class. Subclass to author a primitive.
+ *
+ * @example
+ *   class MyWidget extends UIElement {
+ *     static properties = { label: { type: String, default: '' } };
+ *     render() { this.textContent = this.label; }
+ *   }
+ *   customElements.define('my-widget', MyWidget);
+ */
+export class UIElement extends HTMLElement {
+  /**
+   * Property declarations — signal-backed getters/setters wired by the
+   * constructor. Override in subclasses.
+   */
+  static properties: PropertiesMap;
+
+  /** Trait declarations — applied during `connectedCallback`. */
+  static traits: readonly TraitDeclaration[];
+
+  /** Slot blueprints used by `ensure(slotName)`. */
+  static parts?: PartsMap;
+
+  /** Stylesheets to adopt onto the document on first render. */
+  static styles?: CSSStyleSheet | readonly CSSStyleSheet[];
+
+  /**
+   * Pure-function template — called inside the host's render effect. Reading
+   * `this.foo` inside subscribes the effect to the `foo` signal.
+   *
+   * Override OR return `null` and update DOM imperatively in `render()`.
+   */
+  static template: <T extends UIElement>(host: T) => TemplateResult | null;
+
+  /** Observed attribute names — derived from `static properties`. */
+  static readonly observedAttributes: readonly string[];
+
+  /** ElementInternals — attached in the constructor; carries form state etc. */
+  readonly internals: ElementInternals;
+
+  /**
+   * Setup hook — called after construction + insertion, before the first render
+   * effect installs. Set up listeners on document / external targets here.
+   *
+   * Override in subclasses; default is a no-op. Runs inside `untracked()` so
+   * reads don't leak subscriptions to outer effects.
+   */
+  connected(): void;
+
+  /**
+   * Imperative update hook — called every time any property signal mutates.
+   * Reading `this.foo` here subscribes the effect to `foo`.
+   *
+   * Override in subclasses; default is a no-op.
+   */
+  render(): void;
+
+  /**
+   * Post-render hook — called after `render()`. `changed` is a map of every
+   * property that mutated this tick, keyed by property name with old value.
+   *
+   * Override in subclasses; default is a no-op.
+   */
+  updated(changed: ReadonlyMap<string, unknown>): void;
+
+  /**
+   * Teardown hook — called on element removal. Clean up listeners + intervals
+   * + observers here.
+   *
+   * Override in subclasses; default is a no-op.
+   */
+  disconnected(): void;
+
+  /**
+   * Error hook — called when the host's render effect throws. Receives the
+   * thrown value. Default behavior: rethrow.
+   */
+  onError?(err: unknown): void;
+
+  // ── Standard custom-element callbacks (overridable but rarely needed) ──
+
+  connectedCallback(): void;
+  disconnectedCallback(): void;
+  attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+
+  // ── Convenience helpers ──
+
+  /**
+   * Create a local signal bound to this element's lifetime. Disposed on
+   * `disconnectedCallback`.
+   */
+  signal<T>(initial: T): Signal<T>;
+
+  /**
+   * Get or stamp a slot child by name. If a `[slot="name"]` child exists,
+   * returns it; otherwise stamps the blueprint from `static parts[name]`,
+   * appends it, and returns the new node.
+   */
+  ensure(slotName: string): Element | null;
+
+  /** Remove the `[slot="name"]` child if present. */
+  drop(slotName: string): void;
+
+  /**
+   * Keyed-reconcile a parent's children against `items`. Used internally by
+   * the `repeat` directive; consumers rarely call directly.
+   */
+  reconcile<T>(
+    parent: Element,
+    items: readonly T[],
+    keyFn: (item: T, i: number) => string | number,
+    stampFn: (item: T, i: number, existing: Element | null) => Element,
+  ): void;
+
+  // ── Controller pattern (optional advanced) ──
+
+  /** Set the controller; calls connect/disconnect on it through lifecycle. */
+  set controller(c: UIController | null);
+  get controller(): UIController | null;
+
+  /**
+   * Factory — create an instance of this element with the given props applied.
+   * Tag must already be registered.
+   */
+  static create<T extends typeof UIElement>(
+    this: T,
+    props?: Partial<InstanceType<T>>,
+  ): InstanceType<T>;
+}
+
+/**
+ * Controller — optional pluggable behavior attached to a UIElement via
+ * `element.controller = …`. Lifecycle mirrors the host.
+ */
+export interface UIController {
+  connect?(host: UIElement): void;
+  disconnect?(host: UIElement): void;
+}