@adia-ai/web-components 0.2.3 → 0.2.4

package/components/button/button.js

@@ -43,6 +43,9 @@ class UIButton extends UIElement {
     if (this.type === 'submit') {
       const form = this.closest('form');
       if (form?.requestSubmit) form.requestSubmit();
+    } else if (this.type === 'reset') {
+      const form = this.closest('form');
+      if (form?.reset) form.reset();
     }
     this.dispatchEvent(new Event('press', { bubbles: true }));
   };

package/components/demo-toggle/demo-toggle.a2ui.json

@@ -0,0 +1,144 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/DemoToggle.json",
+  "title": "DemoToggle",
+  "description": "Side-by-side comparison primitive — header bar with a switch + two child slots (\"on\" / \"off\"); toggling the switch swaps which slot is visible. Used on trait detail pages to show \"with trait\" vs \"without trait\" on the same chrome. data-mode=\"overlay\" stacks the slots on the same coordinates so layout never shifts.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "DemoToggle"
+    },
+    "initial": {
+      "description": "Initial state when [state] is not set on connect (\"on\" | \"off\").",
+      "type": "string",
+      "enum": [
+        "on",
+        "off"
+      ],
+      "default": "off"
+    },
+    "labelOff": {
+      "description": "Header label rendered when state is \"off\".",
+      "type": "string",
+      "default": "Off"
+    },
+    "labelOn": {
+      "description": "Header label rendered when state is \"on\".",
+      "type": "string",
+      "default": "On"
+    },
+    "state": {
+      "description": "Current toggle state (\"on\" | \"off\"). Reflected as data-state on the host.",
+      "type": "string",
+      "enum": [
+        "",
+        "on",
+        "off"
+      ],
+      "default": ""
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "container",
+    "events": {
+      "change": {
+        "description": "Fired when the toggle flips. detail contains { state }."
+      }
+    },
+    "examples": [
+      {
+        "description": "Compare a trait-bearing surface against the bare control on the same chrome.",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"DemoToggle\",\n    \"labelOn\": \"With shimmer-loading\",\n    \"labelOff\": \"Without shimmer-loading\",\n    \"initial\": \"off\",\n    \"children\": [\"off\", \"on\"]\n  },\n  {\n    \"id\": \"off\",\n    \"component\": \"Card\",\n    \"slot\": \"off\",\n    \"children\": [\"off-section\"]\n  },\n  {\n    \"id\": \"off-section\",\n    \"component\": \"Section\",\n    \"children\": [\"off-text\"]\n  },\n  {\n    \"id\": \"off-text\",\n    \"component\": \"Text\",\n    \"textContent\": \"Bare surface — no trait attached.\"\n  },\n  {\n    \"id\": \"on\",\n    \"component\": \"Card\",\n    \"slot\": \"on\",\n    \"children\": [\"on-section\"]\n  },\n  {\n    \"id\": \"on-section\",\n    \"component\": \"Section\",\n    \"children\": [\"on-text\"]\n  },\n  {\n    \"id\": \"on-text\",\n    \"component\": \"Text\",\n    \"textContent\": \"Same surface, with trait attached.\"\n  }\n]",
+        "name": "with-without-trait"
+      }
+    ],
+    "keywords": [
+      "demo",
+      "toggle",
+      "compare",
+      "comparison",
+      "trait",
+      "before-after",
+      "a-b",
+      "switch"
+    ],
+    "name": "UIDemoToggle",
+    "related": [
+      "Switch",
+      "Card"
+    ],
+    "slots": {
+      "bar": {
+        "description": "Internal header bar (auto-stamped). Hosts the embedded switch + label."
+      },
+      "off": {
+        "description": "Surface rendered when state is \"off\" (the \"without trait\" variant)."
+      },
+      "on": {
+        "description": "Surface rendered when state is \"on\" (the \"with trait\" variant)."
+      }
+    },
+    "states": [
+      {
+        "description": "Default, ready for interaction.",
+        "name": "idle"
+      },
+      {
+        "description": "On slot is active; bar leans accent.",
+        "attribute": "data-state",
+        "name": "on"
+      },
+      {
+        "description": "Off slot is active; bar is neutral.",
+        "attribute": "data-state",
+        "name": "off"
+      }
+    ],
+    "synonyms": {
+      "compare": [
+        "demo-toggle",
+        "segmented"
+      ],
+      "switch": [
+        "demo-toggle",
+        "toggle-group"
+      ]
+    },
+    "tag": "demo-toggle-ui",
+    "tokens": {
+      "--demo-toggle-bar-bg": {
+        "description": "Header bar background (accent when state=on)"
+      },
+      "--demo-toggle-bar-fg": {
+        "description": "Header bar foreground"
+      },
+      "--demo-toggle-bg": {
+        "description": "Stage background"
+      },
+      "--demo-toggle-border": {
+        "description": "Border color"
+      },
+      "--demo-toggle-radius": {
+        "description": "Outer border-radius"
+      },
+      "--demo-toggle-stage-padding": {
+        "description": "Inner padding around each slot"
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}

package/components/demo-toggle/demo-toggle.css

@@ -0,0 +1,120 @@
+@scope (demo-toggle-ui) {
+  :where(:scope) {
+    /* ── Layout ── */
+    --demo-toggle-radius:        var(--a-radius-lg);
+    --demo-toggle-gap:           var(--a-space-3);
+    --demo-toggle-stage-padding: var(--a-space-4);
+    --demo-toggle-bar-px:        var(--a-space-3);
+    --demo-toggle-bar-py:        var(--a-space-2);
+
+    /* ── Colors ── */
+    --demo-toggle-bg:            var(--a-canvas-1);
+    --demo-toggle-border:        var(--a-border);
+    --demo-toggle-bar-bg:        var(--a-bg-muted);
+    --demo-toggle-bar-fg:        var(--a-fg);
+
+    /* ── Typography ── */
+    --demo-toggle-label-size:    var(--a-ui-size);
+    --demo-toggle-label-weight:  var(--a-weight-medium, 500);
+
+    /* ── Transition ── */
+    --demo-toggle-duration:      var(--a-duration-fast);
+    --demo-toggle-easing:        var(--a-easing);
+  }
+
+  :scope {
+    /* ── Base ── */
+    box-sizing: border-box;
+    display: flex;
+    flex-direction: column;
+    gap: 0;
+    width: 100%;
+
+    background: var(--demo-toggle-bg);
+    border: 1px solid var(--demo-toggle-border);
+    border-radius: var(--demo-toggle-radius);
+    overflow: hidden;
+    isolation: isolate;
+  }
+
+  /* -- Header bar -- */
+  [slot="bar"] {
+    width: 100%;
+    padding: var(--demo-toggle-bar-py) var(--demo-toggle-bar-px);
+    background: var(--demo-toggle-bar-bg);
+    color: var(--demo-toggle-bar-fg);
+    border-bottom: 1px solid var(--demo-toggle-border);
+    justify-content: space-between;
+  }
+
+  [data-demo-toggle-label] {
+    font-size: var(--demo-toggle-label-size);
+    font-weight: var(--demo-toggle-label-weight);
+    color: var(--demo-toggle-bar-fg);
+    transition: color var(--demo-toggle-duration) var(--demo-toggle-easing);
+  }
+
+  /* -- Stage area (where the slotted content lives) -- */
+  /* Slotted children are anything that isn't the [slot="bar"]. They sit in
+     the second flex row; default mode shows only the active slot. */
+  :scope > [slot="on"],
+  :scope > [slot="off"] {
+    box-sizing: border-box;
+    width: 100%;
+    padding: var(--demo-toggle-stage-padding);
+  }
+
+  :scope[data-state="on"]  > [slot="off"] { display: none; }
+  :scope[data-state="off"] > [slot="on"]  { display: none; }
+
+  /* Overlay mode — both slots stack on the same coordinates so toggling
+     never reflows the surrounding layout. The inactive slot is
+     visibility-hidden (still occupying space → still measurable for the
+     active one). The stack is a 1-cell grid; both slots target row 1
+     col 1 via grid-area. */
+  :scope[data-mode="overlay"] {
+    /* The bar is row 1; the stage cell is row 2. The cell's children all
+       claim the same grid-area so they overlap. */
+  }
+  :scope[data-mode="overlay"] > [slot="on"],
+  :scope[data-mode="overlay"] > [slot="off"] {
+    display: block;
+  }
+  :scope[data-mode="overlay"] {
+    /* Use a wrapper-less stack: rely on the parent flex column for the
+       bar/stage stack and turn the stage region into a relative anchor
+       via the second slot's positioning. */
+    position: relative;
+  }
+  :scope[data-mode="overlay"] > [slot="on"] {
+    position: absolute;
+    inset: 0;
+    /* Bar height — the slot starts beneath the bar. We can't query the
+       bar's height in CSS, so the stage region uses the larger of the
+       two slot intrinsic heights (default flow), and the active
+       slot positions on top via inset:0 starting after the bar. The
+       enclosing :scope provides padding-top via the bar; the slot's
+       own padding still applies. */
+    top: auto;
+    height: auto;
+  }
+  :scope[data-mode="overlay"][data-state="on"]  > [slot="off"] {
+    visibility: hidden;
+  }
+  :scope[data-mode="overlay"][data-state="off"] > [slot="on"]  {
+    visibility: hidden;
+  }
+  /* Reset display:none branches above for overlay — already handled by
+     visibility:hidden, but the default-mode display:none rules above
+     would otherwise fight overlay. Override here. */
+  :scope[data-mode="overlay"][data-state="on"]  > [slot="off"],
+  :scope[data-mode="overlay"][data-state="off"] > [slot="on"] {
+    display: block;
+  }
+
+  /* State-themed bar — when on, lean accent; when off, leave neutral. */
+  :scope[data-state="on"] {
+    --demo-toggle-bar-bg: var(--a-accent-muted);
+    --demo-toggle-bar-fg: var(--a-accent-strong);
+  }
+}

package/components/demo-toggle/demo-toggle.js

@@ -0,0 +1,144 @@
+/**
+ * <demo-toggle-ui>
+ *   <section slot="off">…without trait…</section>
+ *   <section slot="on">…with trait…</section>
+ * </demo-toggle-ui>
+ *
+ * Side-by-side "with trait / without trait" comparison primitive.
+ * Renders a header bar with a switch-ui that flips which child slot is
+ * visible. Reflects [data-state="on"|"off"] on the host so consumer CSS
+ * can theme the bar around the active variant.
+ *
+ * Two layout modes:
+ *   default — only the active slot is in the layout (the other is `display: none`).
+ *   data-mode="overlay" — both slots stack on the same coordinates; inactive
+ *     slot is `visibility: hidden` so layout never shifts.
+ *
+ * Authoring API:
+ *   [label-on]  — header label when state=on   (default: "On")
+ *   [label-off] — header label when state=off  (default: "Off")
+ *   [initial]   — "on" | "off"; only consulted when [state] is unset on connect
+ *   [state]     — "on" | "off"; reflected; the live state attribute
+ *
+ * Events:
+ *   change — { detail: { state: "on" | "off" } }
+ *
+ * Keyboard:
+ *   The embedded <switch-ui> handles space + enter via its own keydown wiring.
+ */
+
+import { UIElement } from '../../core/element.js';
+import '../switch/switch.js';
+import '../row/row.js';
+import '../text/text.js';
+
+class UIDemoToggle extends UIElement {
+  static properties = {
+    labelOn:  { type: String, default: 'On',  attribute: 'label-on',  reflect: true },
+    labelOff: { type: String, default: 'Off', attribute: 'label-off', reflect: true },
+    initial:  { type: String, default: 'off', reflect: true },
+    state:    { type: String, default: '',    reflect: true },
+  };
+
+  // Header bar with a switch + active label. Stamped once per class via
+  // static parts; live label text is updated in render() so the same
+  // template covers every (label-on, label-off, state) tuple.
+  static parts = {
+    bar: `
+      <row-ui slot="bar" gap="3" align="center" data-demo-toggle-bar>
+        <text-ui slot="label" data-demo-toggle-label></text-ui>
+        <switch-ui slot="switch" data-demo-toggle-switch></switch-ui>
+      </row-ui>
+    `,
+  };
+
+  static template = () => null;
+
+  #bar = null;
+  #switch = null;
+  #label = null;
+  #bound = false;
+
+  connected() {
+    // Resolve the initial state. Honor [state] if explicitly authored;
+    // otherwise fall back to [initial] (default "off"). Anything other
+    // than the literal "on" coerces to "off" so authors can't poison
+    // the data-state attribute with arbitrary values.
+    if (!this.state) {
+      const seed = (this.initial === 'on') ? 'on' : 'off';
+      this.state = seed;
+    } else {
+      this.state = (this.state === 'on') ? 'on' : 'off';
+    }
+
+    // Stamp the header bar lazily — `this.ensure('bar')` clones the
+    // blueprint into the light DOM the first time it's called.
+    this.#bar = this.ensure('bar');
+    this.#switch = this.#bar.querySelector('[data-demo-toggle-switch]');
+    this.#label = this.#bar.querySelector('[data-demo-toggle-label]');
+
+    if (!this.#bound) {
+      this.#bound = true;
+      this.#switch.addEventListener('change', this.#onSwitchChange);
+    }
+  }
+
+  disconnected() {
+    if (this.#switch) {
+      this.#switch.removeEventListener('change', this.#onSwitchChange);
+    }
+    this.#bar = null;
+    this.#switch = null;
+    this.#label = null;
+    this.#bound = false;
+  }
+
+  render() {
+    if (!this.#bar) return;
+    const on = this.state === 'on';
+
+    // Sync the embedded switch to the host's state. checked is a
+    // reflected property; the assignment fires no event because
+    // syncValue() short-circuits when the next state matches.
+    if (this.#switch.checked !== on) {
+      this.#switch.checked = on;
+    }
+
+    if (this.#label) {
+      this.#label.textContent = on ? this.labelOn : this.labelOff;
+    }
+  }
+
+  /**
+   * Public toggle method — flips the host between on and off and emits
+   * a `change` event. Mirrors the click-on-switch path so consumers
+   * can drive the state from outside without touching the embedded
+   * switch directly.
+   */
+  toggle() {
+    this.state = (this.state === 'on') ? 'off' : 'on';
+    this.dispatchEvent(new CustomEvent('change', {
+      bubbles: true,
+      detail: { state: this.state },
+    }));
+  }
+
+  #onSwitchChange = (e) => {
+    // The embedded <switch-ui> fires a bubbling `change`. Stop it at the
+    // host boundary — we re-dispatch our own `change` with detail.state
+    // so consumers see exactly one event per toggle, not the inner
+    // switch's bare event AND our annotated one.
+    e.stopPropagation();
+    const next = this.#switch.checked ? 'on' : 'off';
+    if (next === this.state) return;
+    this.state = next;
+    this.dispatchEvent(new CustomEvent('change', {
+      bubbles: true,
+      detail: { state: this.state },
+    }));
+  };
+}
+
+customElements.define('demo-toggle-ui', UIDemoToggle);
+
+export { UIDemoToggle };

package/components/demo-toggle/demo-toggle.test.js

@@ -0,0 +1,102 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import '../../core/element.js';
+import './demo-toggle.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;
+}
+
+describe('demo-toggle-ui', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('registers demo-toggle-ui as a custom element', () => {
+    expect(customElements.get('demo-toggle-ui')).toBeDefined();
+  });
+
+  it('defaults to state="off" when [initial] is not set', async () => {
+    const el = mount('<demo-toggle-ui></demo-toggle-ui>');
+    await tick();
+    expect(el.state).toBe('off');
+    expect(el.getAttribute('state')).toBe('off');
+  });
+
+  it('honors [initial="on"] on connect', async () => {
+    const el = mount('<demo-toggle-ui initial="on"></demo-toggle-ui>');
+    await tick();
+    expect(el.state).toBe('on');
+  });
+
+  it('renders the auto-stamped header bar with switch + label', async () => {
+    const el = mount('<demo-toggle-ui label-on="Foo" label-off="Bar"></demo-toggle-ui>');
+    await tick();
+    const bar = el.querySelector('[slot="bar"]');
+    const sw  = el.querySelector('[data-demo-toggle-switch]');
+    const label = el.querySelector('[data-demo-toggle-label]');
+    expect(bar).toBeTruthy();
+    expect(sw).toBeTruthy();
+    expect(label).toBeTruthy();
+    // state defaults to "off"; label-off should be active
+    expect(label.textContent).toBe('Bar');
+  });
+
+  it('toggle() flips state and emits change with detail.state', async () => {
+    const el = mount('<demo-toggle-ui></demo-toggle-ui>');
+    await tick();
+    const events = [];
+    el.addEventListener('change', (e) => events.push(e.detail));
+
+    el.toggle();
+    expect(el.state).toBe('on');
+    expect(events).toHaveLength(1);
+    expect(events[0]).toEqual({ state: 'on' });
+
+    el.toggle();
+    expect(el.state).toBe('off');
+    expect(events).toHaveLength(2);
+    expect(events[1]).toEqual({ state: 'off' });
+  });
+
+  it('clicking the embedded switch flips host state and bubbles change', async () => {
+    const el = mount('<demo-toggle-ui></demo-toggle-ui>');
+    await tick();
+    const sw = el.querySelector('[data-demo-toggle-switch]');
+
+    const events = [];
+    el.addEventListener('change', (e) => events.push(e.detail));
+
+    sw.click();
+    await tick();
+    expect(el.state).toBe('on');
+    expect(events).toHaveLength(1);
+    expect(events[0]).toEqual({ state: 'on' });
+  });
+
+  it('reflects state to the [state] attribute', async () => {
+    const el = mount('<demo-toggle-ui initial="on"></demo-toggle-ui>');
+    await tick();
+    expect(el.getAttribute('state')).toBe('on');
+    el.toggle();
+    expect(el.getAttribute('state')).toBe('off');
+  });
+
+  it('coerces an invalid [state] attribute to "off"', async () => {
+    const el = mount('<demo-toggle-ui state="garbage"></demo-toggle-ui>');
+    await tick();
+    expect(el.state).toBe('off');
+  });
+
+  it('updates the active label when state flips', async () => {
+    const el = mount('<demo-toggle-ui label-on="With trait" label-off="Without trait"></demo-toggle-ui>');
+    await tick();
+    const label = el.querySelector('[data-demo-toggle-label]');
+    expect(label.textContent).toBe('Without trait');
+    el.toggle();
+    await tick();
+    expect(label.textContent).toBe('With trait');
+  });
+});

package/components/demo-toggle/demo-toggle.yaml

@@ -0,0 +1,144 @@
+# Edit this file; run `node scripts/build/components.mjs` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIDemoToggle
+tag: demo-toggle-ui
+component: DemoToggle
+category: container
+version: 1
+description: >-
+  Side-by-side comparison primitive — header bar with a switch + two child
+  slots ("on" / "off"); toggling the switch swaps which slot is visible.
+  Used on trait detail pages to show "with trait" vs "without trait" on
+  the same chrome. data-mode="overlay" stacks the slots on the same
+  coordinates so layout never shifts.
+props:
+  labelOn:
+    description: Header label rendered when state is "on".
+    type: string
+    default: "On"
+    attribute: label-on
+    reflect: true
+  labelOff:
+    description: Header label rendered when state is "off".
+    type: string
+    default: "Off"
+    attribute: label-off
+    reflect: true
+  initial:
+    description: Initial state when [state] is not set on connect ("on" | "off").
+    type: string
+    default: "off"
+    enum:
+      - "on"
+      - "off"
+    reflect: true
+  state:
+    description: Current toggle state ("on" | "off"). Reflected as data-state on the host.
+    type: string
+    default: ""
+    enum:
+      - ""
+      - "on"
+      - "off"
+    reflect: true
+events:
+  change:
+    description: Fired when the toggle flips. detail contains { state }.
+slots:
+  bar:
+    description: Internal header bar (auto-stamped). Hosts the embedded switch + label.
+  "on":
+    description: Surface rendered when state is "on" (the "with trait" variant).
+  "off":
+    description: Surface rendered when state is "off" (the "without trait" variant).
+states:
+  - name: idle
+    description: Default, ready for interaction.
+  - name: on
+    description: On slot is active; bar leans accent.
+    attribute: data-state
+  - name: off
+    description: Off slot is active; bar is neutral.
+    attribute: data-state
+traits: []
+tokens:
+  --demo-toggle-radius:
+    description: Outer border-radius
+  --demo-toggle-bg:
+    description: Stage background
+  --demo-toggle-border:
+    description: Border color
+  --demo-toggle-bar-bg:
+    description: Header bar background (accent when state=on)
+  --demo-toggle-bar-fg:
+    description: Header bar foreground
+  --demo-toggle-stage-padding:
+    description: Inner padding around each slot
+a2ui:
+  rules: []
+anti_patterns: []
+examples:
+  - name: with-without-trait
+    description: Compare a trait-bearing surface against the bare control on the same chrome.
+    a2ui: >-
+      [
+        {
+          "id": "root",
+          "component": "DemoToggle",
+          "labelOn": "With shimmer-loading",
+          "labelOff": "Without shimmer-loading",
+          "initial": "off",
+          "children": ["off", "on"]
+        },
+        {
+          "id": "off",
+          "component": "Card",
+          "slot": "off",
+          "children": ["off-section"]
+        },
+        {
+          "id": "off-section",
+          "component": "Section",
+          "children": ["off-text"]
+        },
+        {
+          "id": "off-text",
+          "component": "Text",
+          "textContent": "Bare surface — no trait attached."
+        },
+        {
+          "id": "on",
+          "component": "Card",
+          "slot": "on",
+          "children": ["on-section"]
+        },
+        {
+          "id": "on-section",
+          "component": "Section",
+          "children": ["on-text"]
+        },
+        {
+          "id": "on-text",
+          "component": "Text",
+          "textContent": "Same surface, with trait attached."
+        }
+      ]
+keywords:
+  - demo
+  - toggle
+  - compare
+  - comparison
+  - trait
+  - before-after
+  - a-b
+  - switch
+synonyms:
+  compare:
+    - demo-toggle
+    - segmented
+  switch:
+    - demo-toggle
+    - toggle-group
+related:
+  - Switch
+  - Card

package/components/index.js

@@ -85,6 +85,7 @@ export { UIEmbed } from './embed/embed.js';
 export { UIBlock } from './block/block.js';
 export { UIText } from './text/text.js';
 export { UIToggleGroup, UIToggleOption } from './toggle-group/toggle-group.js';
+export { UIDemoToggle } from './demo-toggle/demo-toggle.js';
 export { UIRichText } from './richtext/richtext.js';
 export { UIStream } from './stream/stream.js';
 export { UICanvas } from './canvas/canvas.js';