@adia-ai/web-components 0.5.8 → 0.5.10

package/USAGE.md

@@ -887,6 +887,259 @@ The function re-runs on every dependency mutation. Same pattern works for derive
 
 ---
 
+## v0.5.9 — Consumer-feedback discoverability sweep
+
+This section collects 11 docs items (§221a–§221k) that emerged from rounds R9, R10, R13, R15, R16, and R20. They document existing behavior that consumers reasonably misread — no behavior changes, only docs gaps closed.
+
+### §221a — Universal `[size]` prop family
+
+Every interactive primitive accepts `[size]` with `xs | sm | md | lg | xl` (some additionally accept `2xs` / `2xl`). The token wiring is in `themes.css`:
+
+```css
+[size="xs"]  { --a-size: 24px; }   /* compact toolbar / inline densities */
+[size="sm"]  { --a-size: 28px; }
+[size="md"]  { --a-size: 32px; }   /* canonical default */
+[size="lg"]  { --a-size: 40px; }
+[size="xl"]  { --a-size: 48px; }   /* hero CTAs, top-level brand */
+```
+
+Authoring: `<button-ui size="lg" text="Continue">`. The element inherits `--a-size` from the closest `[size]` ancestor when the prop is unset, so a `<row-ui size="sm">` containing 5 controls makes them all small without per-element repeat.
+
+When in doubt about whether a primitive supports `[size]`: every form-bearing primitive does (input / textarea / select / switch / check / radio / button / range / slider / search). Display primitives that participate in size cascades also do (avatar / badge / tag / icon / chip / card).
+
+### §221b — `<input-ui>` migration from native `<input>`
+
+Common gotchas during native-`<input>` → `<input-ui>` migration:
+
+| Native pattern | `<input-ui>` equivalent |
+|---|---|
+| `<input type="text">` | `<input-ui>` (no `type` needed) |
+| `<input type="email" required>` | `<input-ui type="email" required>` |
+| `<input type="password">` | `<input-ui type="password">` (wraps a native `<input>` for `-webkit-text-security` disc masking — only path that still uses a native input) |
+| `<input type="number" min="0" max="100" step="0.1">` | `<input-ui type="number" min="0" max="100" step="0.1">` (renders contenteditable + stepper buttons; no native `<input type="number">` underneath) |
+| `<input placeholder="…" value="…">` | `<input-ui placeholder="…" value="…">` |
+| `<input oninput="…">` | `el.addEventListener('input', e => e.detail.value)` (CustomEvent payload, not native InputEvent) |
+| Native form serialization | Works — ElementInternals form participation via `name=` |
+| `el.value` reads/writes | Same; programmatic `.value = "…"` is round-tripped |
+
+The biggest authoring shift: events carry their payload in `e.detail`, not on the host element. Read `e.detail.value`, not `e.target.value`. (Same applies to every form-bearing primitive.)
+
+### §221c — `<switch-ui>` vs `<check-ui>` vs `<segmented-ui>` — the "named binary state" trap
+
+Three primitives can render "is X on or off?" but they signal different semantics:
+
+- **`<switch-ui>`** — for **mutable system state** the user toggles immediately. Use for "Dark mode", "Notifications", "Show grid". Action commits on flip; no submit needed.
+- **`<check-ui>`** — for **decisions the user is committing to a form**. Use for "I agree to the terms", "Subscribe me to updates", multi-select lists.
+- **`<segmented-ui>`** — for **explicit choice between named options** (two or more). Use for "Light / Dark / System", "Day / Week / Month". Even with two options, segmented signals "I'm picking which one" rather than "I'm flipping a switch".
+
+The trap: authoring a `<switch-ui>` for "Confidentiality: Public / Private" reads as "click to toggle confidentiality" — but a `<segmented-ui options="Public,Private">` better signals an explicit named choice.
+
+### §221d — `<select-ui>` native `<option>` children
+
+`<select-ui>` consumes native HTML `<option>` and `<optgroup>`, NOT a sibling custom element. Authoring:
+
+```html
+<select-ui name="theme" value="dark">
+  <option value="light">Light</option>
+  <option value="dark">Dark</option>
+  <option value="system">System</option>
+</select-ui>
+```
+
+Or programmatically:
+
+```js
+el.options = [
+  { value: 'light',  label: 'Light'  },
+  { value: 'dark',   label: 'Dark'   },
+  { value: 'system', label: 'System' },
+];
+```
+
+§225 (v0.5.9) added a once-per-element `console.warn` when unrecognized child elements appear (e.g. `<select-option>`) — they're silently ignored, so the warn surfaces the authoring drift.
+
+### §221e — `<accordion-item-ui>` action buttons in custom headers
+
+When a custom `[slot="header"]` carries action buttons (Copy / Download / Edit), the click would normally bubble to the header's toggle handler and open/close the panel. Mark action elements `[data-no-toggle]` or place them at `[slot="action"]` (or `[slot="actions"]`):
+
+```html
+<accordion-item-ui>
+  <div slot="header">
+    <span>Section title</span>
+    <button-ui slot="action" icon="copy" text="" data-no-toggle></button-ui>
+  </div>
+  <div>Body content</div>
+</accordion-item-ui>
+```
+
+§206 (v0.5.7) added the `[slot="action"]` / `[slot="actions"]` / `[data-no-toggle]` exclusion list to the toggle-cascade.
+
+### §221f — `<color-picker-ui>` inline pattern
+
+For a compact swatch-and-popover authoring shape:
+
+```html
+<popover-ui trigger="click" placement="bottom-start">
+  <button-ui slot="trigger" text="" icon="palette" aria-label="Pick a color"></button-ui>
+  <color-picker-ui slot="content" value="oklch(0.7 0.15 220)" alpha="off"></color-picker-ui>
+</popover-ui>
+```
+
+The popover handles focus management + click-outside dismiss; the button-ui exposes the right ARIA semantics. `<color-picker-ui>` fires `change` events that bubble through the popover — listen on the popover host.
+
+### §221g — `[data-scheme]` ancestor opt-in for color scheme
+
+The light/dark color scheme follows `[data-scheme="light"]` or `[data-scheme="dark"]` on any ancestor, falling back to `prefers-color-scheme`. Common patterns:
+
+```html
+<!-- Whole-app explicit scheme (e.g. user preference saved) -->
+<html data-scheme="dark"> … </html>
+
+<!-- Per-section override (e.g. dark hero on light page) -->
+<section data-scheme="dark"> … </section>
+
+<!-- Dynamic toggle via <toggle-scheme-ui> writes to <html data-scheme> -->
+<toggle-scheme-ui persist></toggle-scheme-ui>
+```
+
+The `themes.css` token cascade reads `[data-scheme]` first, then `@media (prefers-color-scheme: dark)`, then defaults. Setting `[data-scheme]` empty (`data-scheme=""`) is **not** the same as removing the attribute — empty resolves to no-match and falls through to the media query, while a missing attribute does the same. Don't bother setting `data-scheme=""` — just remove the attribute.
+
+### §221h — Effect-dispatch timing (signals)
+
+`effect(fn)` runs `fn` synchronously on creation, then re-runs on every signal change. Re-runs are scheduled via `queueMicrotask` to batch multiple signal mutations in the same tick into one effect run. This means:
+
+```js
+const count = signal(0);
+const log = signal('');
+
+effect(() => log.value = `Count is ${count.value}`);
+
+count.value = 1;       // schedules microtask
+count.value = 2;       // microtask is already scheduled, no re-schedule
+count.value = 3;
+// log.value is still '' here (effect hasn't run yet)
+
+await new Promise(r => queueMicrotask(r));
+// log.value is now 'Count is 3' (effect ran once for the batch)
+```
+
+For test isolation where you need the effect to flush before assertions, await **two** queueMicrotasks — one for the effect to run, one for any downstream effects it triggers:
+
+```js
+const tick = () => new Promise(r => queueMicrotask(r));
+count.value = 5;
+await tick();   // first microtask — effect runs, may schedule another
+await tick();   // second microtask — any downstream effects flush
+expect(log.value).toBe('Count is 5');
+```
+
+The double-`queueMicrotask` pattern is what `core/element.js`'s render scheduler uses internally — same semantics propagate to consumer effects.
+
+### §221i — Backticks inside HTML comments inside `html\`…\`` templates
+
+JS-spec footgun: the first backtick inside an HTML comment **closes** the outer template literal. The TS / parser error reads as "Unterminated template literal" or "TS1005" at the backtick column:
+
+```js
+// ❌ TS1005 at the backtick column
+const tpl = html`
+  <div>
+    <!-- Use `data-scheme="dark"` for dark mode -->
+  </div>
+`;
+
+// ✅ Use single-quoted strings or HTML entities inside HTML comments
+const tpl = html`
+  <div>
+    <!-- Use [data-scheme="dark"] for dark mode -->
+  </div>
+`;
+```
+
+Same rule applies to nested `<style>` and `<script>` blocks inside `html\`...\`` — anything that contains a literal backtick must be escaped (`\\\``) or rephrased.
+
+### §221j — Typography token cheatsheet
+
+Quick-reference for component-CSS authoring. Cross-reference [`styles/typography.css`](./styles/typography.css):
+
+| Layer | Token family | Examples | When to use |
+|---|---|---|---|
+| L0 — raw sizes | `--a-ui-{tiny,xs,sm,md,lg}` | `10px / 12px / 13px / 14px / 15px` | Inline UI text in component CSS (badge labels, kbd text) |
+| L0 — raw weights | `--a-weight-{normal,medium,semibold,bold,extrabold}` | `400 / 500 / 600 / 700 / 800` | font-weight in component CSS |
+| L0 — body roles | `--a-{body,heading,title,display,section,subsection,caption,label,kicker,deck,metric,code}-{family,weight,size,leading,tracking,case,color}` | `--a-heading-weight` | Inside `<text-ui variant="heading">` styles |
+| L1 — UI scale | `--a-ui-{size,leading,line-height,weight,family,tracking,case,color,px,py}` | `--a-ui-size` (= 14px default) | Buttons / inputs / labels / control-row densities |
+| L1 — focus / ring | `--a-focus-ring{,-invalid}` | `0 0 0 2px var(--a-accent)` | `:focus-visible` shadow recipes |
+
+Common misreads:
+
+- `--a-font-semibold` → **doesn't exist**. Use `--a-weight-semibold`.
+- `--a-text-sm` → **doesn't exist**. Use `--a-label-size` (semantic) or `--a-ui-sm` (raw size).
+- `--a-font-weight-normal` → **doesn't exist (removed in v0.5.0)**. Use `--a-weight-normal`.
+
+§231 (v0.5.8) graduated a mechanical audit (`scripts/release/check-component-css-vs-styles-tokens.mjs`) that catches references to undefined `--a-…` tokens at release time.
+
+### §221k — `<text-ui variant>` chooser guide
+
+The 12 canonical variants ship with distinct typographic roles. Pick by intent, not by visual size:
+
+| Variant | Role | Looks like | Choose when |
+|---|---|---|---|
+| `display` | Top-level brand / hero | Tallest possible | Page-level hero one-liner |
+| `title` | Section landmark | Large H1-ish | Top of an authoritative page / dialog |
+| `heading` | Sub-landmark | H2-ish | Major sub-section divider |
+| `subsection` | Lesser landmark | H3-ish | Card title within a section |
+| `section` | Inline section | Smaller heading | Form group label, navlist heading |
+| `body` (default) | Running prose | Body copy | Paragraph text, descriptions |
+| `caption` | Annotation | Slightly smaller, muted | Image captions, footnotes |
+| `label` | Form control label | UI-sized, medium-weight | Field labels above inputs |
+| `kicker` | Eyebrow text above a title | UPPERCASE, small | Optional micro-heading above a `title` |
+| `deck` | Sub-title under a title | Slightly larger than body | One-line lead after a `title` |
+| `metric` | Numeric KPI | Large bold figure | Big-number stats |
+| `code` | Inline code | Monospace | Inline code references |
+
+Two heuristics consumers ask about repeatedly:
+
+1. **"Should I use `kicker` or `label`?"** — `kicker` for content (eyebrow above a section title); `label` for form-control bindings (above an `<input-ui>` / `<select-ui>` etc.).
+2. **"`subsection` or `section`?"** — `subsection` is for visible-rank H3-ish headings; `section` is for inline form-group labels or small-cap navlist headings. Visual rank: `display > title > heading > subsection > section`.
+
+§210 (v0.5.7) closed the variant-vs-CSS-rule drift; §232 (v0.5.9) graduates a mechanical audit that catches future enum-vs-rule drift across all primitives with enum props.
+
+**§247 (v0.5.10) ARIA-role clarification (FB-23 §2):** `<text-ui variant="heading">` (and `title` / `display` / `subsection` / `section`) is **presentational-only** — it 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), one of:
+
+```html
+<!-- ✅ Native semantic — wrap with <h1>-<h6> -->
+<h2><text-ui variant="heading">Section title</text-ui></h2>
+
+<!-- ✅ ARIA-only — add role + aria-level to the host directly -->
+<text-ui variant="heading" role="heading" aria-level="2">Section title</text-ui>
+
+<!-- ⚠️ Presentational-only — fine for visual eyebrows / kickers / captions; do NOT use for document-outline-significant headings -->
+<text-ui variant="kicker">Eyebrow text</text-ui>
+```
+
+The `<text-ui>` API stayed presentational-only by design — the typography role tokens are decoupled from ARIA. v0.6.0 may add a `level=` (or `as=`) attribute to opt-in to semantic-heading rendering; v0.5.x consumers wire ARIA on the host explicitly.
+
+---
+
+## §247 (v0.5.10) — `<swatch-ui shape="block">` label-position
+
+For `<swatch-ui shape="block">`, the label renders **BELOW the tile** (flex-column stack). The label-on-tile use case (key inside the colored tile, with `data-on-light` / `data-on-dark` chrome contrast) is **NOT supported** in v0.5.x — the existing auto-contrast classes are designed for a future overlay mode, not currently consumed by any rendered layout.
+
+```html
+<!-- ✅ Default block layout — label below tile -->
+<swatch-ui shape="block" color="oklch(0.7 0.15 220)">
+  <span slot="label">Accent 600</span>
+</swatch-ui>
+
+<!-- ❌ NOT a label-on-tile API in v0.5.x — label still renders below -->
+<swatch-ui shape="block" color="oklch(0.7 0.15 220)" data-label-position="overlay">
+  <span slot="label">Accent 600</span>
+</swatch-ui>
+```
+
+If your design needs label-on-tile (e.g. Tokens Studio's C1.3 hand-rolled `<div class="dts-swatch">` pattern), file a v0.6.0 feature request. The leading API shape is `<swatch-ui label-position="overlay">`; alternatives include `<swatch-ui shape="block-overlay">` or a sibling `<swatch-tile-ui>` primitive with slot composition.
+
+---
+
 ## More
 
 - [`README.md`](./README.md) — package overview + authoring guide

package/components/accordion/accordion.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/accordion
  *
  * 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.
@@ -30,3 +30,24 @@ export class UIAccordion extends UIElement {
   ): void;
   addEventListener(type: 'toggle', listener: (ev: AccordionToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }
+
+export interface AccordionItemToggleEventDetail {
+  /** New open state. */
+  open: boolean;
+}
+
+export type AccordionItemToggleEvent = CustomEvent<AccordionItemToggleEventDetail>;
+
+export class UIAccordionItem extends UIElement {
+  /** Whether the section is expanded. */
+  open: boolean;
+  /** Header text — the clickable label that toggles the section. */
+  text: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIAccordionItem, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'toggle', listener: (ev: AccordionItemToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

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

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/action-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.
@@ -32,3 +32,16 @@ export class UIActionList extends UIElement {
   ): void;
   addEventListener(type: 'action', listener: (ev: ActionListActionEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }
+
+export class UIActionItem extends UIElement {
+  /** Disables click + keyboard activation; aria-disabled is set. */
+  disabled: boolean;
+  /** Leading icon name (Phosphor). */
+  icon: string;
+  /** Action label. */
+  text: string;
+  /** Identifier passed to the action-list change/activate handlers. */
+  value: string;
+  /** Visual variant (default | accent | danger). */
+  variant: string;
+}

package/components/agent-artifact/agent-artifact.d.ts

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

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

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

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

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

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

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

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/avatar
  *
  * 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.
@@ -26,3 +26,10 @@ export class UIAvatar extends UIElement {
   /** Display string (full name or initials). Initials derive from spaces — first letter of each word, max 2. */
   text: string;
 }
+
+export class UIAvatarGroup extends UIElement {
+  /** Maximum avatars to show before the +N overflow indicator. */
+  max: number;
+  /** Forwards to each child <avatar-ui> (xs|sm|md|lg|xl). Empty uses the per-avatar size. */
+  size: string;
+}

package/components/badge/badge.d.ts

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

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

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

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

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

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

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

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

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/chat-thread
  *
  * 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,42 @@ export class UIChatThread extends UIElement {
   ): void;
   addEventListener(type: 'submit', listener: (ev: ChatThreadSubmitEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }
+
+export interface ChatInputSubmitEventDetail {
+  /** Currently selected model value (empty if no model picker). */
+  model: string;
+  /** Submitted message text from the inner textarea. */
+  text: string;
+}
+
+export type ChatInputSubmitEvent = CustomEvent<ChatInputSubmitEventDetail>;
+
+export class UIChatInput extends UIElement {
+  /** Disable the entire input. Textarea becomes contenteditable=false;
+send button disabled.
+ */
+  disabled: boolean;
+  /** In-flight / streaming state. Send button disabled, submit events
+suppressed, but textarea stays editable so the user can draft a
+follow-up while the model is still responding.
+ */
+  loading: boolean;
+  /** Currently selected model value (reflected, two-way with inner
+`<select-ui slot="model">`). Empty when no model picker is shown.
+ */
+  model: string;
+  /** JSON array of model options for the inner model picker —
+[{value, label}] or [{label, options: [...]}] groups. Empty array
+hides the model picker.
+ */
+  models: unknown[];
+  /** Textarea placeholder. Defaults to "Type a message...". */
+  placeholder: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIChatInput, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'submit', listener: (ev: ChatInputSubmitEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/components/code/code.css

@@ -71,7 +71,7 @@
     --code-lint-error:       var(--a-danger-strong);
     --code-lint-warning:     var(--a-warning-strong);
     --code-lint-info:        var(--a-info-strong);
-    --code-lint-tooltip-bg:  var(--a-surface-floating);
+    --code-lint-tooltip-bg:  var(--a-bg-strong);  /* §230-bundle (v0.5.9): elevated panel surface. Was orphaned --a-surface-floating. */
     --code-lint-tooltip-fg:  var(--a-fg);
     --code-lint-tooltip-border: var(--a-border-subtle);
   }

package/components/col/col.a2ui.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://adiaui.dev/a2ui/v0_9/components/Column.json",
-  "title": "Column",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/Col.json",
+  "title": "Col",
   "description": "Flex column layout primitive.",
   "type": "object",
   "allOf": [
@@ -19,7 +19,7 @@
       "default": "stretch"
     },
     "component": {
-      "const": "Column"
+      "const": "Col"
     },
     "gap": {
       "description": "Gap between children. Accepts either the named scale (xs/sm/md/lg/xl) or a numeric rung on the spacing scale (\"1\"…\"16\", mapped to --a-space-N).",
@@ -62,7 +62,7 @@
       "column",
       "col"
     ],
-    "name": "UIColumn",
+    "name": "UICol",
     "related": [
       "avatar",
       "input",

package/components/col/col.d.ts

@@ -4,7 +4,7 @@
  * @see https://ui-kit.exe.xyz/site/components/col
  *
  * 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.
@@ -12,7 +12,7 @@
 
 import { UIElement } from '../../core/element.js';
 
-export class UIColumn extends UIElement {
+export class UICol extends UIElement {
   /** Align items */
   align: string;
   /** Gap between children. Accepts either the named scale (xs/sm/md/lg/xl) or a numeric rung on the spacing scale ("1"…"16", mapped to --a-space-N). */

package/components/col/col.yaml

@@ -1,9 +1,9 @@
 # Generated by scripts/migrate-yamls-to-v1.mjs — migrated to v1 contract.
 # Edit this file; run `npm run build:components` to regenerate a2ui.json.
 $schema: ../../../../scripts/schemas/component.yaml.schema.json
-name: UIColumn
+name: UICol
 tag: col-ui
-component: Column
+component: Col
 category: layout
 version: 1
 description: Flex column layout primitive.

package/components/command/command.d.ts

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

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