@adia-ai/web-components 0.5.8 → 0.5.10

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

@@ -1,26 +1,77 @@
 /**
- * `<text-ui>` — Typography wrapper that applies role tokens. Supports truncation and line clamping.
+ * `<text-ui>` — Typography wrapper that applies role tokens. Supports
+ * truncation and line clamping.
  *
  * @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`,
- * 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 §247 (v0.5.10) — the yaml `enum:` schema
+ * carries variant names but not per-value descriptions; codegen emits a
+ * single property-level JSDoc and loses the per-variant disambiguation that
+ * the §221k chooser guide documents. Hand-authored .d.ts carries per-variant
+ * JSDoc inline so IDE hover surfaces the disambiguation at authoring time.
+ * Also carries the FB-23 §2 ARIA-role disclaimer on the property doc.
+ * `dts-codegen.mjs` keeps this file in its `HAND_AUTHORED_DTS` skip list.
  */
 
 import { UIElement } from '../../core/element.js';
 
+/**
+ * Typography variants — visual rank from `display` (largest, hero) to
+ * `code` (inline monospace). Pick by intent, not by visual size — every
+ * variant has a distinct typographic role per §221k chooser guide.
+ *
+ * See `packages/web-components/USAGE.md` "v0.5.9 — Consumer-feedback
+ * discoverability sweep" §221k for the picker heuristics.
+ */
+export type UITextVariant =
+  /** Default body copy. 14px / regular. Paragraphs, multi-line content, running prose. */
+  | 'body'
+  /** Top-level hero / brand display. Tallest visual rank. Use for page-level hero one-liners. */
+  | 'display'
+  /** Page title (visual rank H1). Largest under display. Use at the top of an authoritative page or dialog. */
+  | 'title'
+  /** Major page heading (visual rank H2). 16-18px / bold. Use for major sub-section dividers. */
+  | 'heading'
+  /** Sub-landmark within a section (visual rank H3). 14px / semibold. Use for card titles within a section. */
+  | 'subsection'
+  /** Inline form-group / navlist heading (visual rank H4). Small-cap. Use for form group labels, nav list headings. */
+  | 'section'
+  /** Annotation under a primary line — smaller + muted. Use for image captions, footnotes. */
+  | 'caption'
+  /** Form-control label (above an `<input-ui>` / `<select-ui>` etc). UI-sized + medium-weight. Use for field labels bound to form controls. */
+  | 'label'
+  /** Eyebrow text above a `title`. UPPERCASE + small + tracking. Use for content eyebrows (NOT form labels — use `label` for those). */
+  | 'kicker'
+  /** Sub-title under a `title`. One-line lead, slightly larger than body. Use for the lead sentence after a title. */
+  | 'deck'
+  /** Numeric KPI / big-number stat. Bold + large. Use for dashboard metric numbers. */
+  | 'metric'
+  /** Inline monospace code reference. Use for `\`code\`` inline within prose. */
+  | 'code';
+
 export class UIText extends UIElement {
-  /** Multi-line clamp count (0 = no clamp) */
-  lines: number;
-  /** When true, applies stronger emphasis (heavier weight + accent color). Styled via :scope[strong] in text.css. Use instead of variant=heading when you want a single emphasized word inline in body copy. */
+  /**
+   * Typography variant — sets design-role tokens (size / weight / tracking /
+   * color / leading) per the L0 typography token family.
+   *
+   * **PRESENTATIONAL-ONLY (§247, FB-23 §2).** `<text-ui variant="heading">`
+   * does NOT set `role="heading"` + `aria-level` on the host. Document-outline
+   * assistive technology will treat the element as `role="generic"`. For
+   * **semantic** headings (screen-reader heading-navigation, document
+   * outline), wrap with native `<h1>`-`<h6>` OR add
+   * `role="heading" aria-level="N"` on the host element directly.
+   *
+   * For visual-only labels (eyebrows, kickers, captions, deck), the
+   * presentational default is correct. The §221k chooser guide in USAGE.md
+   * documents the picker heuristics.
+   */
+  variant: UITextVariant;
+  /** When true, applies stronger emphasis (heavier weight + accent color). Styled via `:scope[strong]` in text.css. Use instead of `variant="heading"` when you want a single emphasized word inline in body copy. */
   strong: boolean;
-  /** Display text content. The main payload field for Text components extracted from HTML. */
-  textContent: string;
   /** Single-line truncation with ellipsis. Ignored when `lines` is set. */
   truncate: boolean;
-  /** Typography variant — sets role tokens (size/weight/tracking/color). */
-  variant: 'body' | 'heading' | 'title' | 'subsection' | 'display' | 'caption' | 'label' | 'kicker' | 'deck' | 'section' | 'metric' | 'code';
+  /** Multi-line clamp count (0 = no clamp). Sets `--_text-lines` for `-webkit-line-clamp`. */
+  lines: number;
+  /** Display text content. The main payload field for Text components extracted from HTML. */
+  textContent: string;
 }

package/components/text/text.test.js

@@ -91,9 +91,15 @@ describe('text-ui §210 — variant enum vs CSS rule completeness', () => {
   // ── a2ui.json enum and .d.ts union and CSS rules are mutually consistent ──
   it('a2ui.json variant enum matches .d.ts union and CSS rules 1:1', () => {
     const a2uiVariants = TEXT_A2UI.properties.variant.enum;
+    // §247b (v0.5.10): text.d.ts was hand-authored to use a named type alias
+    // `UITextVariant` instead of an inline union (per-variant JSDoc + ARIA-role
+    // disclaimer). Match either the type-alias body OR an inline union; both
+    // forms expose the same set of string-literal members.
+    const dtsAliasMatch = TEXT_DTS.match(/export\s+type\s+UITextVariant\s*=\s*((?:[\s\S]*?))(?:;|\n\n)/);
     const dtsUnionMatch = TEXT_DTS.match(/variant:\s*((?:'[^']+'\s*\|?\s*)+);/);
-    expect(dtsUnionMatch).toBeTruthy();
-    const dtsVariants = [...dtsUnionMatch[1].matchAll(/'([^']+)'/g)].map(m => m[1]);
+    const variantsSource = dtsAliasMatch?.[1] ?? dtsUnionMatch?.[1];
+    expect(variantsSource).toBeTruthy();
+    const dtsVariants = [...variantsSource.matchAll(/'([^']+)'/g)].map(m => m[1]);
 
     expect(a2uiVariants.sort()).toEqual(dtsVariants.sort());
     expect(a2uiVariants.sort()).toEqual([...documentedVariants].sort());

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,