@adia-ai/web-components 0.5.9 → 0.5.10

package/USAGE.md

@@ -1103,6 +1103,41 @@ Two heuristics consumers ask about repeatedly:
 
 §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

package/components/feed/feed.d.ts

@@ -1,24 +1,71 @@
 /**
- * `<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(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.
+ * 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';
 
+/** Lane positions where `<feed-ui>` containers mount. */
+export type FeedPosition =
+  | 'top-left' | 'top-center' | 'top-right'
+  | 'bottom-left' | 'bottom-center' | 'bottom-right'
+  | 'inline';
+
+/**
+ * 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 */
+  /** 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,
@@ -31,17 +78,17 @@ export class UIFeedContainer extends UIElement {
 export type FeedItemCloseEvent = CustomEvent<unknown>;
 
 export class UIFeedItem extends UIElement {
-  /** Render an x close button (default true for sticky, false for auto-fade) */
+  /** 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) */
+  /** Auto-fade timer in ms; `null` / `0` = sticky (requires user input). */
   duration: number;
-  /** Optional emphasis line above text */
+  /** Optional emphasis line above text. */
   heading: string;
-  /** Optional leading icon name */
+  /** Optional leading icon name. */
   icon: string;
-  /** Body copy */
+  /** Body copy. */
   text: string;
-  /** Semantic variant */
+  /** Semantic variant. */
   variant: 'default' | 'info' | 'success' | 'warning' | 'danger';
 
   addEventListener<K extends keyof HTMLElementEventMap>(
@@ -51,3 +98,25 @@ export class UIFeedItem extends UIElement {
   ): 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/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/rating/rating.d.ts

@@ -23,6 +23,14 @@ export class UIRating extends UIFormElement {
   /** Allow half-step values (0.5, 1.5, …). */
   allowHalf: boolean;
   size: 'sm' | 'md' | 'lg';
+  /**
+   * §247 (v0.5.10, FB-26 §1): visual treatment family. `star` (default) /
+   * `heart` / `thumbs` swap the rendered icon set + selected-state color.
+   * Yaml-declared `enum` was not previously typed in `.d.ts`; consumers
+   * authoring `el.variant = 'heart'` got TS2339 despite the runtime
+   * accepting the value.
+   */
+  variant: 'star' | 'heart' | 'thumbs';
 
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,

package/components/select/select.d.ts

@@ -42,6 +42,20 @@ export class UISelect extends UIFormElement {
   divider: boolean;
   /** §207 (v0.5.7): hint text below the field, wired to aria-describedby. */
   hint: string;
+  /**
+   * §247 (v0.5.10, FB-26 §1): visual variant. `default` = canonical chrome
+   * (border + bg); `outline` = bordered transparent; `ghost` = inline
+   * (no border); `soft` = subtle background tint. Mirrors `<input-ui>`
+   * variant family.
+   */
+  variant: 'default' | 'outline' | 'ghost' | 'soft';
+  /**
+   * §247 (v0.5.10, FB-26 §1): universal `[size]` attribute system —
+   * `xs` / `sm` / `md` (default) / `lg` / `xl`. Sets `--a-size` token
+   * locally; cascades to child icons / labels via the size-cascade pattern
+   * documented in USAGE.md §221a.
+   */
+  size: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
 
   /**
    * Dynamic option list. Setting `.options = [...]` stamps option elements at

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(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.
+ * 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/core/form.d.ts

@@ -43,6 +43,7 @@ export class UIFormElement extends UIElement {
     pattern: { type: StringConstructor; default: ''; reflect: true };
     minlength: { type: NumberConstructor; default: null; reflect: true };
     maxlength: { type: NumberConstructor; default: null; reflect: true };
+    throttle: { type: NumberConstructor; default: 0; reflect: true };
   };
 
   // ── Inherited UIFormElement properties (typed) ──
@@ -66,6 +67,40 @@ export class UIFormElement extends UIElement {
   minlength: number | null;
   /** Maximum length — `null` to disable. */
   maxlength: number | null;
+  /**
+   * §220 (v0.5.9, FEEDBACK-14 §3). Trailing-debounce on the `input` event by
+   * N ms. `0` = no throttle (default; preserves synchronous emission). Useful
+   * for expensive `input`-driven computation (server-side autocomplete, large
+   * list filter, palette regen). `change` fires unthrottled; any pending
+   * `input` flushes before `change` via `flushPendingInput()`.
+   *
+   * §247 (v0.5.10, FB-25): declared on the base class so all 17 form-bearing
+   * primitives inherit the type via TS `extends`. The runtime already worked
+   * via `...UIFormElement.properties` spread; this declaration closes the
+   * matching type surface.
+   */
+  throttle: number;
+
+  /**
+   * §220 (v0.5.9). Schedule a trailing-debounced `input` dispatch when
+   * `throttle > 0`; fire synchronously when `0`. Subclasses call this from
+   * their internal `input`-event handlers.
+   */
+  scheduleThrottledInput(detail?: { value: string | number } | null): void;
+
+  /**
+   * §220 (v0.5.9). Synchronously flush any pending throttled `input` dispatch.
+   * Call from `change` / blur / explicit-commit paths so consumers see the
+   * trailing `input` BEFORE the commit. No-op when no timer is pending.
+   */
+  flushPendingInput(detail?: { value: string | number } | null): void;
+
+  /**
+   * §220 (v0.5.9). Drop any pending throttled `input` dispatch without firing.
+   * Called automatically from `disconnected()` to avoid late dispatches after
+   * teardown.
+   */
+  dropPendingInput(): void;
 
   // ── ElementInternals accessors ──
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-components",
-  "version": "0.5.9",
+  "version": "0.5.10",
   "description": "AdiaUI web components — vanilla custom elements. A2UI runtime (renderer, registry, streams, wiring) lives in @adia-ai/a2ui-runtime.",
   "type": "module",
   "types": "./index.d.ts",