@adia-ai/web-components 0.5.7 → 0.5.9

package/components/slider/class.js

@@ -42,16 +42,17 @@ export class UISlider extends UIFormElement {
     step:   { type: Number,  default: 1,  reflect: true },
     label:  { type: String,  default: '', reflect: true },
     suffix: { type: String,  default: '', reflect: true },
-    // §184 (v0.5.5, FEEDBACK-08 §4): declarative debounce for the
-    // `input` event when driving expensive computation (palette regen,
-    // shader compile, large list reflow). When > 0, value updates +
-    // visual feedback are immediate but `input` event emission is
-    // debounced — only the FINAL value in the throttle window dispatches.
-    // `change` fires unthrottled on pointerup / track click / keyboard;
-    // any pending `input` flushes BEFORE `change` so consumers always
-    // see input→input→…→input→change ordering. throttle="0" (default)
+    // §184 (v0.5.5, FEEDBACK-08 §4) → §220 (v0.5.9, FEEDBACK-14 §3):
+    // declarative trailing-debounce on `input` for expensive consumers
+    // (palette regen, shader compile, large list reflow). When > 0,
+    // value updates + visual feedback are immediate but `input` is
+    // collapsed across the window. `change` fires unthrottled on
+    // pointerup / track click / keyboard; any pending `input` flushes
+    // BEFORE `change` so consumers always see
+    // input→input→…→input→change ordering. throttle="0" (default)
     // preserves the pre-§184 every-pointer-move-fires-input behavior.
-    throttle: { type: Number, default: 0, reflect: true },
+    // The mechanism graduated to UIFormElement at v0.5.9 §220 — slider
+    // delegates via scheduleThrottledInput() + flushPendingInput().
   };
 
   static template = () => null;
@@ -62,11 +63,6 @@ export class UISlider extends UIFormElement {
   #trackEl = null;
   #thumbEl = null;
   #dragging = false;
-  // §184 (v0.5.5, FEEDBACK-08 §4): debounce timer for the `input`
-  // event. When `throttle > 0`, #setValue stores a pending dispatch
-  // here + restarts the timer on every value change. Flushed before
-  // any `change` event so input always precedes change.
-  #inputTimer = null;
 
   get #pct() {
     const range = this.max - this.min;
@@ -171,34 +167,11 @@ export class UISlider extends UIFormElement {
   #setValue(v) {
     if (v === this.value) return;
     this.value = v;
-    // §184: when throttle > 0, debounce the `input` dispatch.
-    // The value update + UI is still immediate; only event emission is
-    // accumulated. Same value can dispatch input multiple times across
-    // pointer moves, but the throttle collapses them to one trailing
-    // emission at quiet+throttle ms.
-    const t = Number(this.throttle) || 0;
-    if (t > 0) {
-      if (this.#inputTimer != null) clearTimeout(this.#inputTimer);
-      this.#inputTimer = setTimeout(() => {
-        this.#inputTimer = null;
-        this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
-      }, t);
-      return;
-    }
-    this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
-  }
-
-  /**
-   * §184: flush any pending throttled `input` dispatch synchronously.
-   * Called before `change` so consumers see the trailing input event
-   * BEFORE the change commit. No-op when no timer is pending.
-   */
-  #flushInput() {
-    if (this.#inputTimer != null) {
-      clearTimeout(this.#inputTimer);
-      this.#inputTimer = null;
-      this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
-    }
+    // §220 (v0.5.9): delegate to UIFormElement's shared throttle helper.
+    // When `this.throttle > 0`, the dispatch is trailing-debounced
+    // (collapses pointer-move bursts to one emission). When 0, fires
+    // synchronously.
+    this.scheduleThrottledInput();
   }
 
   #onPointerDown = (e) => {
@@ -220,14 +193,14 @@ export class UISlider extends UIFormElement {
     this.#thumbEl.releasePointerCapture(e.pointerId);
     this.#thumbEl.removeEventListener('pointermove', this.#onPointerMove);
     this.#thumbEl.removeEventListener('pointerup', this.#onPointerUp);
-    this.#flushInput(); // §184: pending throttled input fires before change
+    this.flushPendingInput(); // §220 (was §184 #flushInput): pending throttled input fires before change
     this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
   };
 
   #onTrackClick = (e) => {
     if (this.disabled || e.target === this.#thumbEl) return;
     this.#setValue(this.#valueFromX(e.clientX));
-    this.#flushInput(); // §184: ensure trailing input precedes change
+    this.flushPendingInput(); // §220 (was §184 #flushInput): ensure trailing input precedes change
     this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
   };
 
@@ -245,7 +218,7 @@ export class UISlider extends UIFormElement {
     }
     e.preventDefault();
     this.#setValue(this.#snap(v));
-    this.#flushInput(); // §184: trailing input fires before change
+    this.flushPendingInput(); // §220 (was §184 #flushInput): trailing input fires before change
     this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
   };
 
@@ -256,11 +229,8 @@ export class UISlider extends UIFormElement {
     this.#thumbEl?.removeEventListener('pointermove', this.#onPointerMove);
     this.#thumbEl?.removeEventListener('pointerup', this.#onPointerUp);
     this.removeEventListener('keydown', this.#onKey);
-    // §184: drop any pending throttle timer (no flush — element is gone)
-    if (this.#inputTimer != null) {
-      clearTimeout(this.#inputTimer);
-      this.#inputTimer = null;
-    }
+    // §220 (v0.5.9): UIFormElement.disconnected() auto-drops the pending
+    // throttled input dispatch via super.disconnected().
     this.#trackEl = null;
     this.#thumbEl = null;
   }

package/components/slider/slider.css

@@ -143,7 +143,7 @@
   [slot="hint"] {
     display: block;
     margin-top: var(--slider-hint-mt, var(--a-space-1));
-    font-size: var(--slider-hint-size, var(--a-fine-size));
+    font-size: var(--slider-hint-size, var(--a-ui-xs));
     color: var(--slider-hint-fg, var(--a-fg-muted));
     line-height: var(--slider-hint-lh, 1.4);
   }

package/components/stack/stack.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/stack
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
  * run `npm run build:components`, then `npm run codegen:dts` to
  * regenerate; or hand-author this file fully if rich event types are
  * needed beyond what the yaml `events:` block can express.

package/components/step-progress/step-progress.d.ts

@@ -10,7 +10,7 @@ primitive.
  * @see https://ui-kit.exe.xyz/site/components/step-progress
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
  * run `npm run build:components`, then `npm run codegen:dts` to
  * regenerate; or hand-author this file fully if rich event types are
  * needed beyond what the yaml `events:` block can express.

package/components/stepper/stepper-item.a2ui.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/StepperItem.json",
+  "title": "StepperItem",
+  "description": "Child of `<stepper-ui>`. One stage in a multi-step flow with status (idle | active | completed | error) + optional icon + description.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "description": {
+      "description": "Secondary description line under the label.",
+      "type": "string",
+      "default": ""
+    },
+    "component": {
+      "const": "StepperItem"
+    },
+    "icon": {
+      "description": "Optional leading Phosphor icon name; overrides the auto-stamped numeric badge.",
+      "type": "string",
+      "default": ""
+    },
+    "status": {
+      "description": "Canonical stage-progress state. Mutually exclusive (prevents the\n`active && completed` footgun the prior multi-Boolean shape allowed).",
+      "type": "string",
+      "enum": [
+        "idle",
+        "active",
+        "completed",
+        "error"
+      ],
+      "default": "idle"
+    },
+    "text": {
+      "description": "Stage label.",
+      "type": "string",
+      "default": ""
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "navigation",
+    "composes": [],
+    "events": {},
+    "examples": [],
+    "keywords": [],
+    "name": "UIStepperItem",
+    "related": [],
+    "slots": {
+      "description": {
+        "description": "Custom description content; falls through to `[description]` prop if not slotted."
+      },
+      "label": {
+        "description": "Custom label content; falls through to `[text]` prop if not slotted."
+      }
+    },
+    "states": [],
+    "synonyms": {},
+    "tag": "stepper-item-ui",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/components/stepper/stepper-item.yaml

@@ -0,0 +1,45 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+#
+# §228 (v0.5.9): authored to close the §229 baseline class-export-undeclared
+# drift for UIStepperItem. Ships as a sibling class in stepper/class.js
+# + is registered alongside UIStepper.
+
+# Child component of <stepper-ui>. Surface only inside that parent.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIStepperItem
+tag: stepper-item-ui
+component: StepperItem
+category: navigation
+version: 1
+description: |-
+  Child of `<stepper-ui>`. One stage in a multi-step flow with status (idle | active | completed | error) + optional icon + description.
+
+props:
+  text:
+    description: Stage label.
+    type: string
+    default: ""
+  description:
+    description: Secondary description line under the label.
+    type: string
+    default: ""
+  icon:
+    description: Optional leading Phosphor icon name; overrides the auto-stamped numeric badge.
+    type: string
+    default: ""
+  status:
+    description: |-
+      Canonical stage-progress state. Mutually exclusive (prevents the
+      `active && completed` footgun the prior multi-Boolean shape allowed).
+    type: string
+    default: idle
+    enum:
+      - idle
+      - active
+      - completed
+      - error
+slots:
+  label:
+    description: Custom label content; falls through to `[text]` prop if not slotted.
+  description:
+    description: Custom description content; falls through to `[description]` prop if not slotted.

package/components/stepper/stepper.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/stepper
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
  * run `npm run build:components`, then `npm run codegen:dts` to
  * regenerate; or hand-author this file fully if rich event types are
  * needed beyond what the yaml `events:` block can express.
@@ -18,3 +18,15 @@ export class UIStepper extends UIElement {
   /** Current step index (0-based). */
   step: number;
 }
+
+export class UIStepperItem extends UIElement {
+  /** Secondary description line under the label. */
+  description: string;
+  /** Optional leading Phosphor icon name; overrides the auto-stamped numeric badge. */
+  icon: string;
+  /** Canonical stage-progress state. Mutually exclusive (prevents the
+`active && completed` footgun the prior multi-Boolean shape allowed). */
+  status: 'idle' | 'active' | 'completed' | 'error';
+  /** Stage label. */
+  text: string;
+}

package/components/stream/stream.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/stream
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
  * run `npm run build:components`, then `npm run codegen:dts` to
  * regenerate; or hand-author this file fully if rich event types are
  * needed beyond what the yaml `events:` block can express.

package/components/swatch/swatch.css

@@ -261,7 +261,7 @@
     border-radius: var(--a-radius-xs);
     transition: color 100ms ease-out, background 100ms ease-out;
   }
-  :scope > [data-copy]:hover { color: var(--a-fg); background: var(--a-bg-2); }
+  :scope > [data-copy]:hover { color: var(--a-fg); background: var(--a-bg-muted); }
   :scope > [data-copy]:focus-visible {
     outline: var(--swatch-select-ring-width) solid var(--swatch-select-ring);
     outline-offset: 1px;

package/components/swatch/swatch.d.ts

@@ -9,7 +9,7 @@ spacing demo pages.
  * @see https://ui-kit.exe.xyz/site/components/swatch
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
  * run `npm run build:components`, then `npm run codegen:dts` to
  * regenerate; or hand-author this file fully if rich event types are
  * needed beyond what the yaml `events:` block can express.

package/components/swiper/swiper.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/swiper
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
  * run `npm run build:components`, then `npm run codegen:dts` to
  * regenerate; or hand-author this file fully if rich event types are
  * needed beyond what the yaml `events:` block can express.

package/components/switch/switch.css

@@ -110,7 +110,7 @@ switch-ui[checked] [slot="thumb"] {
   [slot="hint"] {
     display: block;
     margin-top: var(--switch-hint-mt, var(--a-space-1));
-    font-size: var(--switch-hint-size, var(--a-fine-size));
+    font-size: var(--switch-hint-size, var(--a-ui-xs));
     color: var(--switch-hint-fg, var(--a-fg-muted));
     line-height: var(--switch-hint-lh, 1.4);
   }

package/components/table/table.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/table
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
  * run `npm run build:components`, then `npm run codegen:dts` to
  * regenerate; or hand-author this file fully if rich event types are
  * needed beyond what the yaml `events:` block can express.

package/components/table-toolbar/table-toolbar.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/table-toolbar
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
  * run `npm run build:components`, then `npm run codegen:dts` to
  * regenerate; or hand-author this file fully if rich event types are
  * needed beyond what the yaml `events:` block can express.

package/components/tabs/tabs.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/tabs
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
  * run `npm run build:components`, then `npm run codegen:dts` to
  * regenerate; or hand-author this file fully if rich event types are
  * needed beyond what the yaml `events:` block can express.
@@ -34,3 +34,14 @@ export class UITabs extends UIElement {
   ): void;
   addEventListener(type: 'change', listener: (ev: TabsChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }
+
+export class UITab extends UIElement {
+  /** Whether the tab is selectable. */
+  disabled: boolean;
+  /** Optional leading icon name (Phosphor) for the tab button. */
+  icon: string;
+  /** Tab button label (rendered by parent <tabs-ui>). */
+  text: string;
+  /** Stable id for the tab. Parent uses this to coordinate active state. */
+  value: string;
+}

package/components/tag/tag.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/tag
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
  * run `npm run build:components`, then `npm run codegen:dts` to
  * regenerate; or hand-author this file fully if rich event types are
  * needed beyond what the yaml `events:` block can express.

package/components/text/text.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/text
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
  * run `npm run build:components`, then `npm run codegen:dts` to
  * regenerate; or hand-author this file fully if rich event types are
  * needed beyond what the yaml `events:` block can express.

package/components/textarea/class.js

@@ -90,18 +90,24 @@ export class UITextarea extends UIFormElement {
     this.value = text;
     this.#textEl.toggleAttribute('data-empty', !text);
     this.syncValue(text);
-    this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
+    // §220 (v0.5.9, FEEDBACK-14 §3): trailing-debounce when `throttle > 0`.
+    this.scheduleThrottledInput();
   };
 
   #onKeydown = (e) => {
     // Enter without shift submits; shift+enter inserts newline
     if (e.key === 'Enter' && !e.shiftKey) {
       e.preventDefault();
+      // §220: flush any pending throttled input before submit so listeners
+      // observe the latest value.
+      this.flushPendingInput();
       this.dispatchEvent(new Event('submit', { bubbles: true }));
     }
   };
 
   #onBlur = () => {
+    // §220: trailing `input` precedes `change`.
+    this.flushPendingInput();
     this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
   };
 

package/components/textarea/textarea.a2ui.json

@@ -51,6 +51,11 @@
       "description": "Number of visible text rows (sets min-height).",
       "type": "number",
       "default": 3
+    },
+    "throttle": {
+      "description": "§220 (v0.5.9, FEEDBACK-14 §3). Trailing-debounce on the `input`\nevent in milliseconds. When > 0, value mutates immediately + the UI\nstays responsive, but `input` dispatch is collapsed so only the\nfinal value in the throttle window emits. Useful for expensive\n`input`-driven computation (autosave preview, server-side\nautocomplete, large-doc reflow). `change` fires unthrottled on blur\n/ Enter; any pending `input` flushes before `change` so consumers\nsee input→input→…→input→change ordering. Default 0 preserves\nsynchronous emission.",
+      "type": "number",
+      "default": 0
     }
   },
   "required": [

package/components/textarea/textarea.yaml

@@ -37,6 +37,20 @@ props:
     description: Number of visible text rows (sets min-height).
     type: number
     default: 3
+  throttle:
+    description: |-
+      §220 (v0.5.9, FEEDBACK-14 §3). Trailing-debounce on the `input`
+      event in milliseconds. When > 0, value mutates immediately + the UI
+      stays responsive, but `input` dispatch is collapsed so only the
+      final value in the throttle window emits. Useful for expensive
+      `input`-driven computation (autosave preview, server-side
+      autocomplete, large-doc reflow). `change` fires unthrottled on blur
+      / Enter; any pending `input` flushes before `change` so consumers
+      see input→input→…→input→change ordering. Default 0 preserves
+      synchronous emission.
+    type: number
+    default: 0
+    reflect: true
 events:
   change:
     description: Fired when the textarea loses focus after a value change.

package/components/timeline/timeline.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/timeline
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
  * run `npm run build:components`, then `npm run codegen:dts` to
  * regenerate; or hand-author this file fully if rich event types are
  * needed beyond what the yaml `events:` block can express.
@@ -32,3 +32,22 @@ export class UITimeline extends UIElement {
   ): void;
   addEventListener(type: 'timeline-toggle', listener: (ev: TimelineToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }
+
+export class UITimelineItem extends UIElement {
+  /** Subtitle below the label. */
+  description: string;
+  /** Elapsed time (e.g. "1.2s", "340ms"). */
+  duration: string;
+  /** Optional leading icon name (Phosphor). */
+  icon: string;
+  /** Show a spinner instead of the icon while status=pending. */
+  spinner: boolean;
+  /** Lifecycle state (idle | pending | done | failed). */
+  status: string;
+  /** Primary step label. */
+  text: string;
+  /** Absolute timestamp (HH:MM or ISO). */
+  time: string;
+  /** Visual variant (default | accent | success | warning | danger). */
+  variant: string;
+}

package/components/toast/class.js

@@ -82,6 +82,15 @@ export class UIToast extends UIElement {
    */
   static show(opts = {}) {
     const { text, variant = 'info', duration = 4000, position = 'bottom-right' } = opts;
+    // §224 (v0.5.9, FEEDBACK-10 §2): mark the spawned feed container so
+    // DOM-query consumers (Playwright, devtools, instrumentation) can
+    // distinguish toast-spawned <feed-ui> from user-authored ones. The marker
+    // is set once at container-creation time; subsequent posts to the same
+    // container don't re-stamp (idempotent).
+    const container = UIFeed.get(position);
+    if (container && !container.hasAttribute('data-spawned-by')) {
+      container.setAttribute('data-spawned-by', 'toast');
+    }
     return UIFeed.post({
       text,
       variant: variant === 'error' ? 'danger' : variant,

package/components/toast/toast.d.ts

@@ -3,11 +3,11 @@
  *
  * @see https://ui-kit.exe.xyz/site/components/toast
  *
- * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
- * run `npm run build:components`, then `npm run codegen:dts` to
- * regenerate; or hand-author this file fully if rich event types are
- * needed beyond what the yaml `events:` block can express.
+ * HAND-AUTHORED (not codegen'd) per §246 (v0.5.9) — the yaml
+ * `props:`/`events:` shape can't express the imperative `static show()`
+ * API the runtime ships. `dts-codegen.mjs` keeps this file in its
+ * `HAND_AUTHORED_DTS` skip list so subsequent builds preserve the
+ * static-method signature.
  */
 
 import { UIElement } from '../../core/element.js';
@@ -49,6 +49,10 @@ export class UIToast extends UIElement {
    * alternative to declarative `<toast-ui>`. Returns a `UIToastFeedHandle`
    * for programmatic dismiss / update.
    *
+   * §224 (v0.5.9): the spawned `<feed-ui>` container is stamped with
+   * `data-spawned-by="toast"` for DOM-query distinction from user-authored
+   * `<feed-ui>` containers.
+   *
    * Legacy alias `variant: 'error'` is auto-mapped to `variant: 'danger'`.
    *
    * @example

package/components/toast/toast.yaml

@@ -44,6 +44,22 @@ props:
       - muted
       - neutral
 events: {}
+usage: |-
+  §224 (v0.5.9): `UIToast.show()` routes through `UIFeed.post()` — the
+  spawned DOM element is a `<feed-ui>` container with `<feed-item-ui>`
+  children. The container carries `data-spawned-by="toast"` so DOM-query
+  consumers (Playwright, devtools, instrumentation) can distinguish
+  toast-spawned feeds from user-authored ones:
+
+  ```js
+  UIToast.show({ text: 'Saved.', variant: 'success' });
+
+  // Distinguish toast-spawned <feed-ui> in tests / devtools:
+  document.querySelector('feed-ui[data-spawned-by="toast"]');
+  ```
+
+  The marker is set once at container-creation time + per-position (a
+  single `<feed-ui>` instance serves all toasts for a given position).
 slots: {}
 states:
   - name: idle

package/components/toggle-group/toggle-group.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/toggle-group
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
- * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
  * run `npm run build:components`, then `npm run codegen:dts` to
  * regenerate; or hand-author this file fully if rich event types are
  * needed beyond what the yaml `events:` block can express.
@@ -32,3 +32,14 @@ export class UIToggleGroup extends UIElement {
   ): void;
   addEventListener(type: 'change', listener: (ev: ToggleGroupChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }
+
+export class UIToggleOption extends UIElement {
+  /** Disabled state — blocks pointer + keyboard activation. */
+  disabled: boolean;
+  /** Optional Phosphor icon name; renders as a leading icon. */
+  icon: string;
+  /** Visible label text. */
+  text: string;
+  /** Stable identifier matched against the parent group's `value`. */
+  value: string;
+}