@adia-ai/web-components 0.5.8 → 0.5.10

package/components/description-list/description-list.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/description-list
  *
  * 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/divider/divider.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/divider
  *
  * 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/drawer/drawer.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/drawer
  *
  * 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/embed/embed.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/embed
  *
  * 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/empty-state/class.js

@@ -26,9 +26,13 @@ import { UIElement } from '../../core/element.js';
 
 export class UIEmptyState extends UIElement {
   static properties = {
-    icon:        { type: String, default: '', reflect: true },
-    heading:     { type: String, default: '', reflect: true },
-    description: { type: String, default: '', reflect: true },
+    icon:        { type: String,  default: '',    reflect: true },
+    heading:     { type: String,  default: '',    reflect: true },
+    description: { type: String,  default: '',    reflect: true },
+    // §223 (v0.5.9): minimal layout — single-line muted (no centered column,
+    // no padding bump, no icon-size lg). Use for inline empty-table-row /
+    // inline placeholder cells where the canvas placeholder is too loud.
+    minimal:     { type: Boolean, default: false, reflect: true },
   };
 
   static template = () => null;
@@ -47,7 +51,9 @@ export class UIEmptyState extends UIElement {
     if (!this.#iconEl) {
       this.#iconEl = this.#stampMark(document.createElement('icon-ui'));
       this.#iconEl.setAttribute('slot', 'icon');
-      this.#iconEl.setAttribute('size', 'lg');
+      // §223 (v0.5.9): minimal layout sizes the icon inline; non-minimal
+      // keeps the canonical lg badge.
+      if (!this.minimal) this.#iconEl.setAttribute('size', 'lg');
       this.insertBefore(this.#iconEl, this.firstChild);
     }
 

package/components/empty-state/empty-state.a2ui.json

@@ -30,6 +30,11 @@
       "description": "Icon name displayed above the heading",
       "type": "string",
       "default": ""
+    },
+    "minimal": {
+      "description": "§223 (v0.5.9). Single-line muted layout — drops centered-column chrome\n(no vertical padding, no row-stack, no icon-size bump). Useful for\ninline empty-table-row / inline empty-list / placeholder cells where\nthe full-canvas placeholder is too prominent.",
+      "type": "boolean",
+      "default": false
     }
   },
   "required": [

package/components/empty-state/empty-state.css

@@ -55,4 +55,40 @@
   [slot="action"] {
     margin-top: var(--empty-state-action-mt);
   }
+
+  /* ── §223 (v0.5.9): [minimal] — single-line muted layout ──
+     Drops centered-column chrome (no canvas-style padding, no flex-column
+     stack). Renders as `[icon] heading [description]` inline in muted-fg.
+     Useful for inline placeholder rows / cells where the full placeholder
+     would be too loud. */
+  :scope[minimal] {
+    flex-direction: row;
+    align-items: baseline;
+    text-align: start;
+    padding: var(--a-space-2) var(--a-space-3);
+    gap: var(--a-space-2);
+    color: var(--a-fg-muted);
+    font-size: var(--a-ui-size);
+  }
+  :scope[minimal] [slot="icon"] {
+    font-size: 1em;
+    color: inherit;
+    flex-shrink: 0;
+  }
+  :scope[minimal] [slot="heading"] {
+    font-size: inherit;
+    font-weight: var(--a-weight-normal);
+    color: inherit;
+    line-height: inherit;
+  }
+  :scope[minimal] [slot="description"] {
+    font-size: inherit;
+    color: inherit;
+    line-height: inherit;
+    max-width: none;
+  }
+  :scope[minimal] [slot="action"] {
+    margin-top: 0;
+    margin-inline-start: auto;
+  }
 }

package/components/empty-state/empty-state.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/empty-state
  *
  * 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.
@@ -19,4 +19,9 @@ export class UIEmptyState extends UIElement {
   heading: string;
   /** Icon name displayed above the heading */
   icon: string;
+  /** §223 (v0.5.9). Single-line muted layout — drops centered-column chrome
+(no vertical padding, no row-stack, no icon-size bump). Useful for
+inline empty-table-row / inline empty-list / placeholder cells where
+the full-canvas placeholder is too prominent. */
+  minimal: boolean;
 }

package/components/empty-state/empty-state.test.js

@@ -0,0 +1,77 @@
+/**
+ * empty-state-ui — focused unit tests for the §223 (v0.5.9) `minimal`
+ * boolean prop.
+ *
+ * Pre-§223 only the centered-column canvas layout existed. §223 adds
+ * an inline single-row muted layout for placeholder cells / table rows
+ * where the full-canvas placeholder is too prominent (R13 §4).
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import '../../core/element.js';
+import './empty-state.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('empty-state-ui — §223 (v0.5.9) minimal mode', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('defaults to non-minimal (canvas-style placeholder)', () => {
+    const el = mount('<empty-state-ui heading="No results"></empty-state-ui>');
+    expect(el.minimal).toBe(false);
+    expect(el.hasAttribute('minimal')).toBe(false);
+  });
+
+  it('reflects [minimal] attribute to the property', () => {
+    const el = mount('<empty-state-ui minimal heading="No matches"></empty-state-ui>');
+    expect(el.minimal).toBe(true);
+    expect(el.hasAttribute('minimal')).toBe(true);
+  });
+
+  it('stamps icon WITHOUT size="lg" when minimal', async () => {
+    const el = mount('<empty-state-ui minimal icon="search" heading="No matches"></empty-state-ui>');
+    await tick();
+    const icon = el.querySelector(':scope > [slot="icon"]');
+    expect(icon).not.toBeNull();
+    // Minimal layout uses 1em inherited font-size; non-minimal stamps lg.
+    expect(icon.hasAttribute('size')).toBe(false);
+  });
+
+  it('stamps icon WITH size="lg" when not minimal (no regression)', async () => {
+    const el = mount('<empty-state-ui icon="search" heading="No matches"></empty-state-ui>');
+    await tick();
+    const icon = el.querySelector(':scope > [slot="icon"]');
+    expect(icon).not.toBeNull();
+    expect(icon.getAttribute('size')).toBe('lg');
+  });
+
+  it('stamps heading + description slots in both modes', async () => {
+    const minimal = mount('<empty-state-ui minimal heading="Empty" description="No rows"></empty-state-ui>');
+    const canvas = mount('<empty-state-ui heading="Empty" description="No rows"></empty-state-ui>');
+    await tick();
+
+    for (const el of [minimal, canvas]) {
+      const h = el.querySelector(':scope > [slot="heading"]');
+      const d = el.querySelector(':scope > [slot="description"]');
+      expect(h?.textContent).toBe('Empty');
+      expect(d?.textContent).toBe('No rows');
+    }
+  });
+
+  it('honors a consumer-provided [slot="action"] child in either mode', () => {
+    const el = mount(`
+      <empty-state-ui minimal heading="Empty">
+        <button slot="action" data-test="reset">Reset</button>
+      </empty-state-ui>
+    `);
+    const action = el.querySelector(':scope > [slot="action"][data-test="reset"]');
+    expect(action).not.toBeNull();
+  });
+});

package/components/empty-state/empty-state.yaml

@@ -24,6 +24,15 @@ props:
     description: Icon name displayed above the heading
     type: string
     default: ""
+  minimal:
+    description: |-
+      §223 (v0.5.9). Single-line muted layout — drops centered-column chrome
+      (no vertical padding, no row-stack, no icon-size bump). Useful for
+      inline empty-table-row / inline empty-list / placeholder cells where
+      the full-canvas placeholder is too prominent.
+    type: boolean
+    default: false
+    reflect: true
 events: {}
 slots:
   action:

package/components/feed/feed.css

@@ -102,7 +102,7 @@ feed-item-ui[data-closing] {
     --feed-item-duration: var(--a-duration);
     --feed-item-easing:   var(--a-easing-out);
     --feed-item-gap:      var(--a-space-3);
-    --feed-item-max-width: var(--a-feed-max-width, 22rem);
+    --feed-item-max-width: 22rem;  /* §230-bundle (v0.5.9): component-local. Was orphaned --a-feed-max-width — hoisted per RESPONSE-21 guidance. */
   }
   :scope[variant="info"]    { --feed-item-fg: var(--a-info-fg);    --feed-item-bg: var(--a-info-muted); }
   :scope[variant="success"] { --feed-item-fg: var(--a-success-fg); --feed-item-bg: var(--a-success-muted); }

package/components/feed/feed.d.ts

@@ -1,29 +1,122 @@
 /**
- * `<feed-ui>` — Shared top-layer feed channel. Per docs/specs/feed-channel.md (SPEC-FEED-CHANNEL-001). Per-position singletons mounted lazily into document.body via Popover API; consumers post via the static API (`UIFeed.post()`) or the global 'feed' CustomEvent.
+ * `<feed-ui>` — Shared top-layer feed channel. Per docs/specs/feed-channel.md
+ * (SPEC-FEED-CHANNEL-001). Per-position singletons mounted lazily into
+ * document.body via Popover API; consumers post via the static API
+ * (`UIFeed.post()`) or the global 'feed' CustomEvent.
  *
  * @see https://ui-kit.exe.xyz/site/components/feed
  *
- * 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, FB-24) — the
+ * sibling-yaml codegen walk (v0.5.9 §228) catches the two element classes
+ * (`UIFeedContainer` + `UIFeedItem`) but misses the ambient `UIFeed`
+ * static-API class because it has no tag-registered yaml. Hand-authored
+ * .d.ts adds the static-API + supporting types. `dts-codegen.mjs` keeps
+ * this file in its `HAND_AUTHORED_DTS` skip list.
  */
 
 import { UIElement } from '../../core/element.js';
 
-export type FeedCloseEvent = CustomEvent<unknown>;
+/** Lane positions where `<feed-ui>` containers mount. */
+export type FeedPosition =
+  | 'top-left' | 'top-center' | 'top-right'
+  | 'bottom-left' | 'bottom-center' | 'bottom-right'
+  | 'inline';
 
-export class UIFeed extends UIElement {
-  /** Cap on simultaneously visible items per lane */
+/**
+ * Options for `UIFeed.post()` — the imperative one-shot path. Mirrors
+ * `UIFeedItem`'s reflected props plus `position` (which container lane).
+ */
+export interface UIFeedPostOptions {
+  /** Body copy for the feed item. */
+  text: string;
+  /** Optional emphasis line above text. */
+  heading?: string;
+  /** Optional leading icon name (Phosphor). */
+  icon?: string;
+  /** Semantic variant. */
+  variant?: 'default' | 'info' | 'success' | 'warning' | 'danger';
+  /** Auto-fade timer in ms; `null` / `0` = sticky (requires user input). */
+  duration?: number;
+  /** Render an `x` close button (default `true` for sticky, `false` for auto-fade). */
+  dismissible?: boolean;
+  /** Lane to render into. Defaults to `'bottom-right'`. */
+  position?: FeedPosition;
+  /**
+   * Phase 2 action-required policy: when set, the item carries an action
+   * button. Per `feed-channel.md` §2.3, sets `role="alertdialog"` + focus
+   * is trapped until the action fires (or the item dismisses).
+   */
+  action?: string;
+}
+
+/** Imperative handle returned by `UIFeed.post()` — dismiss / update. */
+export interface FeedHandle {
+  /** Stable id assigned by `<feed-ui>`. `null` if the post failed. */
+  id: string | null;
+  /** Dismiss the item programmatically (triggers exit animation). */
+  dismiss(): void;
+  /** Mutate the item's content in-place (e.g. promote loading→done). */
+  update(patch: Partial<UIFeedPostOptions>): void;
+}
+
+export type FeedContainerCloseEvent = CustomEvent<unknown>;
+
+export class UIFeedContainer extends UIElement {
+  /** Cap on simultaneously visible items per lane. */
   max: number;
-  /** Lane the feed renders into */
-  position: 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right' | 'inline';
+  /** Lane the feed renders into. */
+  position: FeedPosition;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIFeedContainer, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'close', listener: (ev: FeedContainerCloseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}
+
+export type FeedItemCloseEvent = CustomEvent<unknown>;
+
+export class UIFeedItem extends UIElement {
+  /** Render an `x` close button (default `true` for sticky, `false` for auto-fade). */
+  dismissible: boolean;
+  /** Auto-fade timer in ms; `null` / `0` = sticky (requires user input). */
+  duration: number;
+  /** Optional emphasis line above text. */
+  heading: string;
+  /** Optional leading icon name. */
+  icon: string;
+  /** Body copy. */
+  text: string;
+  /** Semantic variant. */
+  variant: 'default' | 'info' | 'success' | 'warning' | 'danger';
 
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
-    listener: (this: UIFeed, ev: HTMLElementEventMap[K]) => unknown,
+    listener: (this: UIFeedItem, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'close', listener: (ev: FeedCloseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'close', listener: (ev: FeedItemCloseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}
+
+/**
+ * Static API for posting `<feed-item-ui>` rows without instantiating
+ * `<feed-ui>` declaratively. Per-position lanes auto-mount into
+ * `document.body` on first call. Use this in place of declarative
+ * `<feed-ui>` for one-shot programmatic messages (toast-style API).
+ *
+ * The class is NOT a custom element — it's a singleton namespace. Don't
+ * try to `new UIFeed()` or extend it; use the static methods only.
+ */
+export class UIFeed {
+  /** Get (or lazily create + mount) the per-position lane container. */
+  static get(position?: FeedPosition): UIFeedContainer;
+  /** Post a feed item. Returns a handle for programmatic dismiss / update. */
+  static post(opts: UIFeedPostOptions): FeedHandle;
+  /** Clear all items in the lane at the given position. */
+  static clear(position?: FeedPosition): void;
+  /** Purge all lanes; tear down DOM containers. */
+  static purge(): void;
+  /** Internal: drop empty container after the last item dismisses. */
+  static releaseContainerIfEmpty(container: UIFeedContainer): void;
 }

package/components/field/field.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/field
  *
  * 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/fields/fields.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/fields
  *
  * 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/grid/grid.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/grid
  *
  * 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/heatmap/heatmap.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/heatmap
  *
  * 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/icon/icon.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/icon
  *
  * 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/image/image.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/image
  *
  * 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/input/class.js

@@ -601,7 +601,8 @@ export class UIInput extends UIFormElement {
     this.value = text;
     if (!this.#isNativePassword) 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();
   };
 
   #onBeforeInput = (e) => {

package/components/input/input.a2ui.json

@@ -146,6 +146,11 @@
       "type": "string",
       "default": ""
     },
+    "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 (palette regen, large list filter,\nserver-side autocomplete). `change` fires unthrottled on blur /\nEnter / stepper commit; any pending `input` flushes before `change`\nso consumers see input→input→…→input→change ordering. Default 0\npreserves synchronous emission.",
+      "type": "number",
+      "default": 0
+    },
     "value": {
       "description": "Current input value, synced with contenteditable text surface. For `type=\"number\"`, this is the formatted numeric string; read `el.valueAsNumber` for the parsed Number.",
       "type": "string",

package/components/input/input.d.ts

@@ -30,6 +30,20 @@ export class UIInput extends UIFormElement {
   suffix: string;
   /** Raw mode — drops chrome (border, padding) for inline composition. */
   raw: boolean;
+  /**
+   * §247 (v0.5.10, FB-26 §1): mobile keyboard hint per HTML `inputmode`
+   * spec — `numeric` / `decimal` / `email` / `tel` / `url` / `search` /
+   * `none`. Forwards to the underlying contenteditable surface. Empty
+   * string = no hint (browser default).
+   */
+  inputmode: string;
+  /**
+   * §247 (v0.5.10, FB-26 §1): HTML `autocomplete` attribute (`off` /
+   * `name` / `email` / `current-password` / `new-password` etc).
+   * Forwards to the underlying contenteditable surface for browser
+   * autofill behavior.
+   */
+  autocomplete: string;
 
   // ── Number-mode properties (active when type="number") ──
   /** Minimum value. `null` to disable. */

package/components/input/input.test.js

@@ -121,3 +121,102 @@ describe('input-ui — §199 leading/trailing affordance slots', () => {
     expect(text.textContent).toBe('Theme 1');
   });
 });
+
+describe('input-ui — §220 (v0.5.9) throttle parity', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('inherits `throttle` property default 0 from UIFormElement', () => {
+    const el = mount('<input-ui></input-ui>');
+    expect(el.throttle).toBe(0);
+  });
+
+  it('reflects [throttle] attribute to the property', () => {
+    const el = mount('<input-ui throttle="150"></input-ui>');
+    expect(el.throttle).toBe(150);
+  });
+
+  it('dispatches `input` synchronously when throttle=0 (default)', async () => {
+    const el = mount('<input-ui></input-ui>');
+    await tick();
+    let count = 0;
+    // Filter for host-emitted CustomEvents (have detail.value); surface
+    // InputEvents bubble up too but have no detail property.
+    el.addEventListener('input', (e) => {
+      if (e.detail?.value !== undefined) count++;
+    });
+
+    // Simulate user typing — set value + dispatch DOM input on the
+    // contenteditable surface so the host's #onInput handler fires.
+    const surface = el.querySelector('[slot="text"]');
+    surface.textContent = 'a';
+    surface.dispatchEvent(new InputEvent('input', { bubbles: true }));
+    surface.textContent = 'ab';
+    surface.dispatchEvent(new InputEvent('input', { bubbles: true }));
+    surface.textContent = 'abc';
+    surface.dispatchEvent(new InputEvent('input', { bubbles: true }));
+
+    expect(count).toBe(3);
+  });
+
+  it('collapses burst dispatches to one trailing `input` when throttle>0', async () => {
+    const el = mount('<input-ui throttle="20"></input-ui>');
+    await tick();
+    const events = [];
+    // Filter for host-emitted CustomEvents (have detail.value); surface
+    // InputEvents bubble up too but have no detail property.
+    el.addEventListener('input', (e) => {
+      if (e.detail?.value !== undefined) events.push(e.detail.value);
+    });
+
+    const surface = el.querySelector('[slot="text"]');
+    surface.textContent = 'a';
+    surface.dispatchEvent(new InputEvent('input', { bubbles: true }));
+    surface.textContent = 'ab';
+    surface.dispatchEvent(new InputEvent('input', { bubbles: true }));
+    surface.textContent = 'abc';
+    surface.dispatchEvent(new InputEvent('input', { bubbles: true }));
+
+    expect(events).toEqual([]);
+
+    await new Promise((r) => setTimeout(r, 35));
+    expect(events).toEqual(['abc']);
+  });
+
+  it('flushPendingInput() fires the pending dispatch synchronously', async () => {
+    const el = mount('<input-ui throttle="50"></input-ui>');
+    await tick();
+    const events = [];
+    // Filter for host-emitted CustomEvents (have detail.value); surface
+    // InputEvents bubble up too but have no detail property.
+    el.addEventListener('input', (e) => {
+      if (e.detail?.value !== undefined) events.push(e.detail.value);
+    });
+
+    const surface = el.querySelector('[slot="text"]');
+    surface.textContent = 'pending';
+    surface.dispatchEvent(new InputEvent('input', { bubbles: true }));
+
+    expect(events).toEqual([]);
+    el.flushPendingInput();
+    expect(events).toEqual(['pending']);
+  });
+
+  it('dropPendingInput() prevents the dispatch (used by disconnected)', async () => {
+    const el = mount('<input-ui throttle="20"></input-ui>');
+    await tick();
+    const events = [];
+    // Filter for host-emitted CustomEvents (have detail.value); surface
+    // InputEvents bubble up too but have no detail property.
+    el.addEventListener('input', (e) => {
+      if (e.detail?.value !== undefined) events.push(e.detail.value);
+    });
+
+    const surface = el.querySelector('[slot="text"]');
+    surface.textContent = 'gone';
+    surface.dispatchEvent(new InputEvent('input', { bubbles: true }));
+
+    el.dropPendingInput();
+    await new Promise((r) => setTimeout(r, 30));
+    expect(events).toEqual([]);
+  });
+});

package/components/input/input.yaml

@@ -139,6 +139,20 @@ props:
     description: Suffix text rendered after the text surface (e.g., unit like 'kg')
     type: string
     default: ''
+  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 (palette regen, large list filter,
+      server-side autocomplete). `change` fires unthrottled on blur /
+      Enter / stepper commit; 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
   value:
     description: Current input value, synced with contenteditable text surface. For `type="number"`, this is the formatted
       numeric string; read `el.valueAsNumber` for the parsed Number.

package/components/inspector/inspector.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/inspector
  *
  * 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/kbd/kbd.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/kbd
  *
  * 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/link/link.d.ts

@@ -28,7 +28,7 @@ wiring. ARIA role is "link" (set automatically by `<a>` element).
  * @see https://ui-kit.exe.xyz/site/components/link
  *
  * 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.