@adia-ai/web-components 0.5.6 → 0.5.7

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

@@ -34,12 +34,29 @@
     "anti_patterns": [],
     "category": "layout",
     "composes": [],
-    "events": {},
+    "events": {
+      "toggle": {
+        "description": "Fired when the section opens or closes.",
+        "detail": {
+          "open": {
+            "description": "New open state.",
+            "type": "boolean"
+          }
+        }
+      }
+    },
     "examples": [],
     "keywords": [],
     "name": "UIAccordionItem",
     "related": [],
-    "slots": {},
+    "slots": {
+      "action": {
+        "description": "§206 (v0.5.7): action buttons inside a custom header (e.g. Copy /\nDownload / settings). Children placed at `[slot=\"action\"]` (or\n`[slot=\"actions\"]`, or marked `[data-no-toggle]`) are excluded from\nthe toggle-on-click cascade — clicking them fires their own handler\nwithout also toggling the section."
+      },
+      "header": {
+        "description": "Custom header content. By default `[text]` renders as a plain header\nlabel, but a `[slot=\"header\"]` override lets consumers author rich\nheaders (icon + title + action buttons + caret)."
+      }
+    },
     "states": [],
     "synonyms": {},
     "tag": "accordion-item-ui",

package/components/accordion/accordion-item.yaml

@@ -25,3 +25,23 @@ props:
     description: Whether the section is expanded.
     type: boolean
     default: false
+slots:
+  header:
+    description: |-
+      Custom header content. By default `[text]` renders as a plain header
+      label, but a `[slot="header"]` override lets consumers author rich
+      headers (icon + title + action buttons + caret).
+  action:
+    description: |-
+      §206 (v0.5.7): action buttons inside a custom header (e.g. Copy /
+      Download / settings). Children placed at `[slot="action"]` (or
+      `[slot="actions"]`, or marked `[data-no-toggle]`) are excluded from
+      the toggle-on-click cascade — clicking them fires their own handler
+      without also toggling the section.
+events:
+  toggle:
+    description: Fired when the section opens or closes.
+    detail:
+      open:
+        type: boolean
+        description: New open state.

package/components/accordion/accordion.a2ui.json

@@ -76,7 +76,7 @@
     ],
     "slots": {
       "default": {
-        "description": "pane-ui children"
+        "description": "accordion-item-ui children"
       }
     },
     "states": [

package/components/accordion/accordion.yaml

@@ -25,7 +25,7 @@ events:
         description: New open state of the panel.
 slots:
   default:
-    description: pane-ui children
+    description: accordion-item-ui children
 states:
   - name: idle
     description: Default, ready for interaction.

package/components/accordion/class.js

@@ -128,6 +128,11 @@ export class UIAccordionItem extends UIElement {
   #onClick = (e) => {
     const header = this.querySelector('[slot="header"]');
     if (!header || !header.contains(e.target)) return;
+    // FEEDBACK-16 §2 (v0.5.7 §206): skip toggle when click originates inside an
+    // action slot or an opt-out marker. Lets consumers author action buttons in
+    // custom headers without bubbling-toggle UX. Slot vocabulary matches
+    // drawer-ui + pane-ui.
+    if (e.target.closest('[slot="action"], [slot="actions"], [data-no-toggle]')) return;
 
     this.open = !this.open;
     this.dispatchEvent(new CustomEvent('toggle', {

package/components/agent-artifact/agent-artifact.yaml

@@ -52,6 +52,9 @@ states:
     description: Default, ready for interaction.
 traits: []
 tokens: {}
+requiredIcons:
+  - caret-right
+  - caret-down
 a2ui:
   rules: []
 anti_patterns: []

package/components/agent-artifact/class.js

@@ -58,6 +58,11 @@ export class UIAgentArtifact extends UIElement {
     tone:      { type: String,  default: 'neutral', reflect: true },
   };
 
+  // §205 (v0.5.7): dynamic chevron icons stamped on collapse/expand state
+  // transition (class.js:119+188). Per FEEDBACK-16 §1 + §209 slot-11 ternary-
+  // walker discovery. Note: `this.icon` consumer-supplied — not declared here.
+  static requiredIcons = ['caret-right', 'caret-down'];
+
   static template = () => null;
 
   #headerEl = null;

package/components/calendar-picker/calendar-picker.d.ts

@@ -17,6 +17,16 @@ export class UICalendarPicker extends UIFormElement {
   value: string;
   /** Open/closed reflected state. */
   open: boolean;
+  /** §207 (v0.5.7): label rendered above the trigger. */
+  label: string;
+  /** §207 (v0.5.7): placeholder text when no date is selected. */
+  placeholder: string;
+  /** §207 (v0.5.7): display format for the trigger label (e.g. `"YYYY-MM-DD"`). */
+  format: string;
+  /** §207 (v0.5.7): earliest selectable ISO-date; `null` to disable. */
+  min: string | null;
+  /** §207 (v0.5.7): latest selectable ISO-date; `null` to disable. */
+  max: string | null;
 
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,

package/components/code/code.d.ts

@@ -56,6 +56,14 @@ export class UICode extends UIFormElement {
   /** Drop chrome (border, background) for inline composition. */
   bare: boolean;
   placeholder: string;
+  /** §207 (v0.5.7): native form-element name for `<form>` submission. */
+  name: string;
+  /** §207 (v0.5.7): form-validity `required` flag. */
+  required: boolean;
+  /** §207 (v0.5.7): native `disabled` flag — suppresses input + form submission. */
+  disabled: boolean;
+  /** §207 (v0.5.7): readonly mode — user cannot type but value is form-submitted. */
+  readonly: boolean;
 
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,

package/components/color-picker/class.js

@@ -127,7 +127,13 @@ export class UIColorPicker extends UIFormElement {
   // consumer markup). Aggregated by installIconLoadersForRegistered()
   // across all defined elements. Audited by check-required-icons.mjs
   // (slot 11). Per FEEDBACK-06 §4 + FEEDBACK-07 §4.
-  static requiredIcons = ['copy'];
+  static requiredIcons = ['copy', 'check', 'warning'];
+
+  // §201 (v0.5.7): once-per-element warn dedup for #parseValue malformed
+  // input. Matches the v0.5.5 §184 §8 button-ui icon-only safety-net pattern
+  // + v0.5.7 §215 select-ui parseOptions pattern. Per FEEDBACK-13 §1 +
+  // FEEDBACK-14 §2 (co-credited).
+  static #warnedBadParse = new WeakSet();
 
   static properties = {
     ...UIFormElement.properties,
@@ -418,9 +424,41 @@ export class UIColorPicker extends UIFormElement {
     if (val.startsWith('#')) {
       const o = hexToOklch(val);
       this.#L = o.L; this.#C = o.C; this.#H = o.H;
-    } else if (val.startsWith('oklch(')) {
-      const m = val.match(/oklch\(\s*([\d.]+)\s+([\d.]+)\s+([\d.]+)/);
-      if (m) { this.#L = +m[1]; this.#C = +m[2]; this.#H = +m[3]; }
+      return;
+    }
+    if (val.startsWith('oklch(')) {
+      // §201 (v0.5.7, FEEDBACK-13 §1 + FEEDBACK-14 §2): accept floats, percent
+      // on L, NaN (culori chromaless convention), and 'none' (CSS Color L4
+      // powerless-component syntax). Channel-level normalization: NaN/none → 0;
+      // percent on L → divide by 100. Per the CSS Color L4 "powerless" cascade
+      // (https://www.w3.org/TR/css-color-4/#powerless), zeroing the hue channel
+      // is the spec-defined resolution when chroma is 0 or near-0.
+      const m = val.match(
+        /oklch\(\s*([\d.]+%?|NaN|none)\s+([\d.]+%?|NaN|none)\s+([\d.]+|NaN|none)/i,
+      );
+      if (m) {
+        const parseChan = (s, isL) => {
+          if (s === 'none' || /^NaN$/i.test(s)) return 0;
+          if (isL && s.endsWith('%')) return +s.slice(0, -1) / 100;
+          if (s.endsWith('%')) return +s.slice(0, -1) / 100;
+          return +s;
+        };
+        this.#L = parseChan(m[1], true);
+        this.#C = parseChan(m[2], false);
+        this.#H = parseChan(m[3], false);
+        return;
+      }
+      // No regex match — warn once per element so consumers can correct.
+      // WeakSet dedup matches v0.5.5 §184 §8 button-ui icon-only pattern.
+      if (!UIColorPicker.#warnedBadParse.has(this)) {
+        UIColorPicker.#warnedBadParse.add(this);
+        // eslint-disable-next-line no-console
+        console.warn(
+          `<color-picker-ui>: could not parse value=${JSON.stringify(val)}. ` +
+          `Expected #rrggbb or oklch(L C H) with numeric, NaN, 'none' (CSS L4 ` +
+          `powerless), or % channels. Picker is keeping prior state.`,
+        );
+      }
     }
   }
 

package/components/color-picker/color-picker.test.js

@@ -0,0 +1,96 @@
+/**
+ * color-picker-ui #parseValue tests — §201 (v0.5.7, FEEDBACK-13 §1 +
+ * FEEDBACK-14 §2 co-credited).
+ *
+ * Verifies the relaxed `oklch(L C H)` parser accepts:
+ *   - Numeric channels (regression — the v0.5.6 baseline)
+ *   - `NaN` on any channel (culori chromaless convention; coerces to 0)
+ *   - `none` on any channel (CSS Color L4 powerless syntax; coerces to 0)
+ *   - Percent on L (e.g. `oklch(53% 0.05 240)`; divides by 100)
+ *
+ * Plus:
+ *   - Truly malformed input emits ONE console.warn per element (WeakSet dedup),
+ *     not one per #parseValue call.
+ *   - Hex pass-through remains intact.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import '../../core/element.js';
+import './color-picker.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('color-picker-ui #parseValue (§201)', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('accepts numeric oklch (baseline regression)', async () => {
+    const p = mount('<color-picker-ui format="oklch" value="oklch(0.6 0.15 240)"></color-picker-ui>');
+    await tick();
+    // Read back via the public value getter — round-tripped through the parser.
+    expect(p.value).toMatch(/oklch/);
+  });
+
+  it('accepts NaN hue (culori chromaless convention)', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const p = mount('<color-picker-ui format="oklch" value="oklch(0.53 0.01 NaN)"></color-picker-ui>');
+    await tick();
+    // No warn — NaN is accepted, coerced to 0.
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it('accepts `none` (CSS Color L4 powerless)', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const p = mount('<color-picker-ui format="oklch" value="oklch(0.5 0 none)"></color-picker-ui>');
+    await tick();
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it('accepts percent on L', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const p = mount('<color-picker-ui format="oklch" value="oklch(53% 0.05 240)"></color-picker-ui>');
+    await tick();
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it('accepts hex (regression)', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const p = mount('<color-picker-ui format="hex" value="#3b82f6"></color-picker-ui>');
+    await tick();
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it('warns once per element on malformed input', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const p = mount('<color-picker-ui format="oklch" value="oklch(banana)"></color-picker-ui>');
+    await tick();
+    // Drive multiple re-parses via setAttribute — should NOT compound the warn count.
+    p.setAttribute('value', 'oklch(orange juice)');
+    await tick();
+    p.setAttribute('value', 'oklch(still broken)');
+    await tick();
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn.mock.calls[0][0]).toMatch(/could not parse value/);
+    warn.mockRestore();
+  });
+
+  it('two independent pickers each get their own warn budget', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const p1 = mount('<color-picker-ui format="oklch" value="oklch(broken-1)"></color-picker-ui>');
+    const p2 = mount('<color-picker-ui format="oklch" value="oklch(broken-2)"></color-picker-ui>');
+    await tick();
+    // Two separate instances — each gets their own first-warn.
+    expect(warn).toHaveBeenCalledTimes(2);
+    warn.mockRestore();
+  });
+});

package/components/color-picker/color-picker.yaml

@@ -97,6 +97,8 @@ traits: []
 tokens: {}
 requiredIcons:
   - copy
+  - check
+  - warning
 a2ui:
   rules: []
 anti_patterns: []

package/components/input/class.js

@@ -16,13 +16,25 @@
  * Uses contenteditable for text entry, ElementInternals for form participation.
  *
  * Slots inside [slot="field"]:
- *   prefix → label → text → suffix → controls (number mode)
+ *   prefix → [leading] → label → text → suffix → [trailing] → controls (number mode)
  *
  *   <input-ui label="Email" placeholder="you@acme.com"></input-ui>
  *   <input-ui label="Email" prefix="user" placeholder="you@acme.com"></input-ui>
  *   <input-ui placeholder="Search" prefix="magnifying-glass"></input-ui>
  *   <input-ui prefix="@" value="kim"></input-ui>
  *
+ *   <!-- Trailing buttons inside the input chrome (§199 v0.5.7) -->
+ *   <input-ui value="Theme 1" suffix="Light">
+ *     <button-ui slot="trailing" icon="arrow-square-out"
+ *                variant="ghost" size="sm"
+ *                aria-label="Open theme browser"></button-ui>
+ *   </input-ui>
+ *
+ *   <!-- Leading button for inline actions before the value -->
+ *   <input-ui value="https://...">
+ *     <button-ui slot="leading" icon="link" variant="ghost" size="sm"></button-ui>
+ *   </input-ui>
+ *
  *   <input-ui type="number" value="42" min="0" max="100" step="1"></input-ui>
  *   <input-ui type="number" value="9.99" step="0.01" precision="2" prefix="$"></input-ui>
  *
@@ -118,9 +130,22 @@ export class UIInput extends UIFormElement {
     super.connected();
     this.setAttribute('role', this.#isNumberMode ? 'spinbutton' : 'textbox');
 
+    // §199 (v0.5.7): consumer-supplied leading/trailing buttons live as
+    // direct children of <input-ui> at author time. Capture references
+    // BEFORE innerHTML wipes them, so we can move them into [slot="field"]
+    // after the shell is built. Querying `:scope > [slot="leading|trailing"]`
+    // (direct-child) avoids matching anything we already moved on a prior
+    // re-render.
+    const leadingNodes = Array.from(this.querySelectorAll(':scope > [slot="leading"]'));
+    const trailingNodes = Array.from(this.querySelectorAll(':scope > [slot="trailing"]'));
+
     if (!this.querySelector('[slot="text"]')) {
       const labelId = this.label ? `input-label-${++UIInput.#labelSeq}` : '';
       this.innerHTML = this.#shellHTML(labelId);
+      // innerHTML wiped the consumer-supplied leading/trailing nodes; re-attach
+      // them into the field at the right positions. Order matches the JSDoc:
+      //   prefix → leading → label → text → suffix → trailing → controls
+      this.#installAffordances(leadingNodes, trailingNodes);
     }
 
     this.#textEl  = this.querySelector('[slot="text"]');
@@ -208,6 +233,81 @@ export class UIInput extends UIFormElement {
     `;
   }
 
+  /**
+   * §199 (v0.5.7) — Move consumer-supplied [slot="leading"] +
+   * [slot="trailing"] nodes into the field at the right insertion points.
+   *
+   * Yaml has declared `leading` + `trailing` slots since v1 ("Leading/
+   * Trailing icon slot, sized to --content-height. Collapses text inline
+   * padding when present.") but the shell never rendered them, so any
+   * consumer-authored `<button-ui slot="trailing">` sat OUTSIDE the
+   * field chrome. §199 closes the schema-vs-impl gap by:
+   *
+   *   1. Capturing the consumer's [slot="leading|trailing"] direct
+   *      children BEFORE `innerHTML = shellHTML` wipes them.
+   *   2. Re-inserting each into `[slot="field"]` at the canonical
+   *      position: leading goes right after [slot="label"] (or after
+   *      [slot="prefix"] when no label), trailing goes right after
+   *      [slot="suffix"] (or after [slot="text"] when no suffix), but
+   *      always BEFORE [slot="controls"] (number-mode stepper column).
+   *
+   * Consumers typically pass `<button-ui slot="trailing">` for inline
+   * actions (copy / clear / open-in-modal); CSS handles the chrome
+   * inheritance (border continuity + size token wiring) via
+   * input.css §199 rules.
+   */
+  #installAffordances(leadingNodes, trailingNodes) {
+    const field = this.querySelector(':scope > [slot="field"]');
+    if (!field) return;
+
+    if (leadingNodes.length) {
+      // Insertion point: after [slot="label"] if present, else after
+      // [slot="prefix"] if present, else as the first child. Walk the
+      // anchor forward so author-order is preserved (first node lands
+      // earliest in DOM).
+      const start =
+        field.querySelector(':scope > [slot="label"]') ||
+        field.querySelector(':scope > [slot="prefix"]');
+      if (start) {
+        let anchor = start;
+        for (const node of leadingNodes) {
+          anchor.after(node);
+          anchor = node;
+        }
+      } else {
+        // No prefix/label — prepend in reverse so the FIRST author-order
+        // node ends up first after all prepends complete.
+        for (const node of leadingNodes.slice().reverse()) field.prepend(node);
+      }
+    }
+
+    if (trailingNodes.length) {
+      // Insertion point: after [slot="suffix"] if present, else after
+      // [slot="text"], but always before [slot="controls"] (number-mode
+      // stepper column). Insert in author order: walk the anchor forward
+      // for each node so the first author-order node lands first in DOM.
+      const controls = field.querySelector(':scope > [slot="controls"]');
+      const after =
+        field.querySelector(':scope > [slot="suffix"]') ||
+        field.querySelector(':scope > [slot="text"]');
+      if (after) {
+        let anchor = after;
+        for (const node of trailingNodes) {
+          anchor.after(node);
+          anchor = node;
+        }
+      } else if (controls) {
+        let anchor = controls.previousElementSibling || controls;
+        for (const node of trailingNodes) {
+          anchor.after(node);
+          anchor = node;
+        }
+      } else {
+        for (const node of trailingNodes) field.appendChild(node);
+      }
+    }
+  }
+
   #promoteAffixes() {
     if (!this.isConnected) return;
     for (const which of ['prefix', 'suffix']) {

package/components/input/input.a2ui.json

@@ -227,13 +227,13 @@
     ],
     "slots": {
       "leading": {
-        "description": "Leading icon slot, sized to --content-height. Collapses text inline padding when present."
+        "description": "Leading affordance slot, inside the field chrome, before the\nvalue. Sized to chrome height. Author `<button-ui slot=\"leading\"\nicon=\"...\" variant=\"ghost\" size=\"sm\">` (or any inline element)\nfor inline actions before the value — e.g. a link-icon button\nnext to a URL input. Wired §199 v0.5.7."
       },
       "text": {
         "description": "Contenteditable text surface for user input"
       },
       "trailing": {
-        "description": "Trailing icon slot, sized to --content-height. Collapses text inline padding when present."
+        "description": "Trailing affordance slot, inside the field chrome, after the\nvalue (and after [slot=\"suffix\"] if present). Sized to chrome\nheight. Author `<button-ui slot=\"trailing\" icon=\"...\"\nvariant=\"ghost\" size=\"sm\" aria-label=\"...\">` for inline actions\nlike copy / clear / open-in-modal. For trailing text/icon\nlabels (e.g. \"Light\" in a theme picker), use the `suffix` prop\ninstead — affordance slots are for interactive buttons, not\ntext. Wired §199 v0.5.7."
       }
     },
     "states": [

package/components/input/input.css

@@ -268,6 +268,63 @@ input-ui:not([disabled]) [slot="field"]:hover [slot="suffix"] {
     margin-inline-start: auto;
   }
 
+  /* §199 (v0.5.7) — Leading + trailing affordance slots inside the field.
+     Consumer authors `<button-ui slot="leading|trailing">` as a direct
+     child of <input-ui>; class.js#installAffordances moves it into
+     [slot="field"] at the right insertion point on connected(). CSS
+     normalizes the chrome here.
+
+     The yaml declared these slots since v1 ("sized to --content-height,
+     collapses text inline padding when present") but no shell rule ever
+     wired them — the canonical schema-vs-impl gap that motivated audit
+     slot 19 (§192 v0.5.6). §199 closes the gap for input-ui specifically. */
+
+  [slot="field"] > [slot="leading"],
+  [slot="field"] > [slot="trailing"] {
+    flex-shrink: 0;
+    /* Sized to chrome height per yaml contract. The button-ui or icon-ui
+       child receives the sizing tokens; we just constrain the slot box
+       and align it to the field's baseline. */
+    align-self: stretch;
+    display: inline-flex;
+    align-items: center;
+    /* Inline padding moves from [slot="text"] (handled by the field's px)
+       to the slot wrapper, so the button-ui sits flush with the field
+       chrome edge instead of inheriting the field's px gap. Authors who
+       want a gap between value and trailing affordance use [slot="suffix"]
+       for the text — the auto-margin on suffix pushes everything after it
+       to the inline-end edge naturally. */
+  }
+
+  /* Default sizing for `<button-ui>` children of the affordance slots.
+     Token-driven so consumers can override via standard --button-* hooks.
+     Without these defaults, a vanilla `<button-ui slot="trailing" icon="...">`
+     would render at button-ui's default --button-height (40px md) and
+     blow out the input chrome. We bind to the field's content height
+     instead so the button visually matches the input's intrinsic size. */
+  [slot="field"] > [slot="leading"] button-ui,
+  [slot="field"] > [slot="trailing"] button-ui {
+    --button-height: calc(var(--input-height) - 4px);
+    --button-bg: transparent;
+    --button-border: transparent;
+    --button-fg: var(--input-affix-fg);
+    --button-px: var(--a-space-1);
+  }
+
+  [slot="field"] > [slot="leading"] button-ui:hover,
+  [slot="field"] > [slot="trailing"] button-ui:hover {
+    --button-bg: var(--a-ui-bg-hover);
+    --button-fg: var(--a-fg);
+  }
+
+  /* When a trailing affordance is present in number mode, reserve room
+     for the stepper column so it doesn't overlap. (controls is
+     absolutely positioned at inset-inline-end: 0; trailing sits in the
+     flex flow.) Same pattern as [slot="suffix"] in number mode. */
+  [data-number]:has(> [slot="trailing"]) > [slot="trailing"] {
+    margin-inline-end: var(--input-controls-width, calc(var(--input-height) * 0.7));
+  }
+
   /* Disabled */
   :scope[disabled] [slot="field"] {
     background: var(--input-bg-disabled);

package/components/input/input.d.ts

@@ -58,4 +58,6 @@ export class UIInput extends UIFormElement {
   ): void;
   addEventListener(type: 'change', listener: (ev: InputChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'input', listener: (ev: InputInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  /** §207 (v0.5.7): Enter-key + native form-submit semantics; dispatched bubbling. */
+  addEventListener(type: 'submit', listener: (ev: Event) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/input/input.test.js

@@ -0,0 +1,123 @@
+/**
+ * input-ui — focused unit tests for the §199 (v0.5.7) leading/trailing
+ * affordance-slot wiring.
+ *
+ * Pre-§199 the yaml declared `slot="leading"` + `slot="trailing"` since
+ * v1 but nothing rendered them — consumer-authored buttons sat OUTSIDE
+ * the field chrome. §199 closes the schema-vs-impl gap by moving
+ * consumer-supplied affordance nodes into [slot="field"] at the right
+ * insertion points on connected().
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import '../../core/element.js';
+import './input.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('input-ui — §199 leading/trailing affordance slots', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('renders a baseline input without any affordances (no regression)', () => {
+    const el = mount('<input-ui value="hello"></input-ui>');
+    const field = el.querySelector(':scope > [slot="field"]');
+    expect(field).not.toBeNull();
+    expect(field.querySelector('[slot="text"]')).not.toBeNull();
+    expect(field.querySelector('[slot="leading"]')).toBeNull();
+    expect(field.querySelector('[slot="trailing"]')).toBeNull();
+  });
+
+  it('moves consumer [slot="trailing"] into [slot="field"]', () => {
+    const el = mount(`
+      <input-ui value="Theme 1" suffix="Light">
+        <button slot="trailing" data-test="open" aria-label="Open">↗</button>
+      </input-ui>
+    `);
+    const field = el.querySelector(':scope > [slot="field"]');
+    const trailing = field.querySelector(':scope > [slot="trailing"]');
+    expect(trailing).not.toBeNull();
+    expect(trailing.dataset.test).toBe('open');
+    // No stray trailing nodes left as direct children of <input-ui>
+    expect(el.querySelector(':scope > [slot="trailing"]')).toBeNull();
+  });
+
+  it('moves consumer [slot="leading"] into [slot="field"]', () => {
+    const el = mount(`
+      <input-ui value="https://...">
+        <button slot="leading" data-test="link" aria-label="Open link">↗</button>
+      </input-ui>
+    `);
+    const field = el.querySelector(':scope > [slot="field"]');
+    const leading = field.querySelector(':scope > [slot="leading"]');
+    expect(leading).not.toBeNull();
+    expect(leading.dataset.test).toBe('link');
+    expect(el.querySelector(':scope > [slot="leading"]')).toBeNull();
+  });
+
+  it('positions trailing after suffix and before controls (number mode)', () => {
+    const el = mount(`
+      <input-ui type="number" value="42" suffix="kg">
+        <button slot="trailing" data-test="reset">↺</button>
+      </input-ui>
+    `);
+    const field = el.querySelector(':scope > [slot="field"]');
+    const children = Array.from(field.children);
+    const suffixIdx = children.findIndex((c) => c.getAttribute('slot') === 'suffix');
+    const trailingIdx = children.findIndex((c) => c.getAttribute('slot') === 'trailing');
+    const controlsIdx = children.findIndex((c) => c.getAttribute('slot') === 'controls');
+    expect(suffixIdx).toBeGreaterThanOrEqual(0);
+    expect(trailingIdx).toBeGreaterThanOrEqual(0);
+    expect(controlsIdx).toBeGreaterThanOrEqual(0);
+    expect(suffixIdx).toBeLessThan(trailingIdx);
+    expect(trailingIdx).toBeLessThan(controlsIdx);
+  });
+
+  it('positions leading after label (when label present)', () => {
+    const el = mount(`
+      <input-ui label="Theme" value="Theme 1">
+        <button slot="leading" data-test="picker">🎨</button>
+      </input-ui>
+    `);
+    const field = el.querySelector(':scope > [slot="field"]');
+    const children = Array.from(field.children);
+    const labelIdx = children.findIndex((c) => c.getAttribute('slot') === 'label');
+    const leadingIdx = children.findIndex((c) => c.getAttribute('slot') === 'leading');
+    const textIdx = children.findIndex((c) => c.getAttribute('slot') === 'text');
+    expect(labelIdx).toBeGreaterThanOrEqual(0);
+    expect(leadingIdx).toBeGreaterThanOrEqual(0);
+    expect(textIdx).toBeGreaterThanOrEqual(0);
+    expect(labelIdx).toBeLessThan(leadingIdx);
+    expect(leadingIdx).toBeLessThan(textIdx);
+  });
+
+  it('supports multiple trailing nodes in author order', () => {
+    const el = mount(`
+      <input-ui value="hello">
+        <button slot="trailing" data-test="a">A</button>
+        <button slot="trailing" data-test="b">B</button>
+      </input-ui>
+    `);
+    const field = el.querySelector(':scope > [slot="field"]');
+    const trailings = Array.from(field.querySelectorAll(':scope > [slot="trailing"]'));
+    expect(trailings.map((n) => n.dataset.test)).toEqual(['a', 'b']);
+  });
+
+  it('preserves contenteditable surface alongside affordances', () => {
+    const el = mount(`
+      <input-ui value="Theme 1" suffix="Light">
+        <button slot="trailing" data-test="open">↗</button>
+      </input-ui>
+    `);
+    const text = el.querySelector('[slot="text"]');
+    expect(text).not.toBeNull();
+    expect(text.getAttribute('contenteditable')).toBe('plaintext-only');
+    expect(text.textContent).toBe('Theme 1');
+  });
+});

package/components/input/input.yaml

@@ -153,11 +153,24 @@ events:
     description: Fired when Enter commits the value.
 slots:
   leading:
-    description: Leading icon slot, sized to --content-height. Collapses text inline padding when present.
+    description: |-
+      Leading affordance slot, inside the field chrome, before the
+      value. Sized to chrome height. Author `<button-ui slot="leading"
+      icon="..." variant="ghost" size="sm">` (or any inline element)
+      for inline actions before the value — e.g. a link-icon button
+      next to a URL input. Wired §199 v0.5.7.
   text:
     description: Contenteditable text surface for user input
   trailing:
-    description: Trailing icon slot, sized to --content-height. Collapses text inline padding when present.
+    description: |-
+      Trailing affordance slot, inside the field chrome, after the
+      value (and after [slot="suffix"] if present). Sized to chrome
+      height. Author `<button-ui slot="trailing" icon="..."
+      variant="ghost" size="sm" aria-label="...">` for inline actions
+      like copy / clear / open-in-modal. For trailing text/icon
+      labels (e.g. "Light" in a theme picker), use the `suffix` prop
+      instead — affordance slots are for interactive buttons, not
+      text. Wired §199 v0.5.7.
 states:
 - name: idle
   description: Default, ready for interaction.

package/components/select/select.d.ts

@@ -40,6 +40,8 @@ export class UISelect extends UIFormElement {
   /** Allow values not in the option list (combobox mode). */
   freeText: boolean;
   divider: boolean;
+  /** §207 (v0.5.7): hint text below the field, wired to aria-describedby. */
+  hint: string;
 
   /**
    * Dynamic option list. Setting `.options = [...]` stamps option elements at

package/components/slider/slider.d.ts

@@ -20,6 +20,10 @@ export class UISlider extends UIFormElement {
   step: number;
   label: string;
   suffix: string;
+  /** §184 (v0.5.5, FEEDBACK-08 §4): debounce `input` event by this many ms. 0 = no throttle. */
+  throttle: number;
+  /** §184 (v0.5.5, FEEDBACK-08 §4): hint text rendered below the track, wired to aria-describedby. */
+  hint: string;
 
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,

package/components/switch/switch.d.ts

@@ -20,6 +20,8 @@ export class UISwitch extends UIFormElement {
   label: string;
   /** Size — `sm` / `md` / `lg`. */
   size: '' | 'sm' | 'md' | 'lg';
+  /** §207 (v0.5.7): hint text rendered below the switch, wired to aria-describedby. */
+  hint: string;
 
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,

package/components/table/class.js

@@ -95,7 +95,15 @@ export class UITable extends UIElement {
   // consumer markup). Aggregated by installIconLoadersForRegistered()
   // across all defined elements. Audited by check-required-icons.mjs
   // (slot 11). Per FEEDBACK-06 §4 + FEEDBACK-07 §4.
-  static requiredIcons = ['caret-right', 'caret-up-down', 'table'];
+  static requiredIcons = [
+    'caret-right',
+    'caret-up-down',
+    'table',
+    'arrow-up',
+    'arrow-down',
+    'funnel-simple',
+    'funnel-simple-fill',
+  ];
 
   static properties = {
     sortable:   { type: Boolean, default: false, reflect: true },

package/components/table/table.yaml

@@ -200,6 +200,10 @@ requiredIcons:
   - caret-right
   - caret-up-down
   - table
+  - arrow-up
+  - arrow-down
+  - funnel-simple
+  - funnel-simple-fill
 a2ui:
   rules: []
 anti_patterns: []

package/components/table-toolbar/class.js

@@ -124,6 +124,11 @@ export class UITableToolbar extends UIElement {
     variant:     { type: String,  default: 'default',  reflect: true },
   };
 
+  // §205 (v0.5.7): dynamic sort-indicator icons (class.js:576 — nested ternary
+  // `dir === 'asc' ? 'arrow-up' : dir === 'desc' ? 'arrow-down' : 'caret-up-down'`).
+  // Per FEEDBACK-16 §1 + §209 slot-11 ternary-walker discovery.
+  static requiredIcons = ['arrow-up', 'arrow-down', 'caret-up-down'];
+
   static template = () => null;
 
   #target = null;

package/components/table-toolbar/table-toolbar.yaml

@@ -113,6 +113,10 @@ tokens:
     description: Title font size
   --table-toolbar-title-weight:
     description: Title font weight
+requiredIcons:
+  - arrow-up
+  - arrow-down
+  - caret-up-down
 a2ui:
   rules: []
 anti_patterns: []

package/components/text/text.a2ui.json

@@ -41,7 +41,6 @@
       "enum": [
         "body",
         "heading",
-        "subheading",
         "title",
         "subsection",
         "display",
@@ -51,13 +50,7 @@
         "deck",
         "section",
         "metric",
-        "code",
-        "h1",
-        "h2",
-        "h3",
-        "h4",
-        "h5",
-        "h6"
+        "code"
       ],
       "default": "body"
     }

package/components/text/text.css

@@ -48,6 +48,19 @@
   :scope[variant="kicker"]     { --text-family: var(--a-kicker-family);  --text-weight: var(--a-kicker-weight);  --text-size: var(--a-kicker-size);  --text-leading: var(--a-kicker-leading);  --text-tracking: var(--a-kicker-tracking);  --text-case: uppercase;             --text-color: var(--a-kicker-color); }
   :scope[variant="code"]       { --text-family: var(--a-code-family);    --text-weight: var(--a-code-weight);    --text-size: var(--a-code-size);    --text-leading: var(--a-code-leading);    --text-tracking: var(--a-code-tracking);    --text-case: var(--a-code-case);    --text-color: var(--a-code-color); }
 
+  /* §210 (v0.5.7, FEEDBACK-17 §1): three token-backed variants whose
+     `--a-<role>-{family,weight,leading,tracking,case,color,size}` tokens
+     ship in `styles/typography.css` but had no matching :scope rule —
+     authoring `<text-ui variant="subsection|deck|metric">` per the
+     documented yaml enum silently rendered as `body` defaults. The
+     `subheading` + `h1`–`h6` enum entries are deliberately omitted from
+     this batch: their tokens don't ship anywhere (verified in this same
+     arc), so the enum entries are retired from text.yaml / text.d.ts /
+     text.a2ui.json. */
+  :scope[variant="subsection"] { --text-family: var(--a-subsection-family); --text-weight: var(--a-subsection-weight); --text-size: var(--a-subsection-size); --text-leading: var(--a-subsection-leading); --text-tracking: var(--a-subsection-tracking); --text-case: var(--a-subsection-case); --text-color: var(--a-subsection-color); }
+  :scope[variant="deck"]       { --text-family: var(--a-deck-family);       --text-weight: var(--a-deck-weight);       --text-size: var(--a-deck-size);       --text-leading: var(--a-deck-leading);       --text-tracking: var(--a-deck-tracking);       --text-case: var(--a-deck-case);       --text-color: var(--a-deck-color); }
+  :scope[variant="metric"]     { --text-family: var(--a-metric-family);     --text-weight: var(--a-metric-weight);     --text-size: var(--a-metric-size);     --text-leading: var(--a-metric-leading);     --text-tracking: var(--a-metric-tracking);     --text-case: var(--a-metric-case);     --text-color: var(--a-metric-color); }
+
   /* ── Truncation (single-line) ── */
   :scope[truncate] {
     overflow: hidden;

package/components/text/text.d.ts

@@ -22,5 +22,5 @@ export class UIText extends UIElement {
   /** Single-line truncation with ellipsis. Ignored when `lines` is set. */
   truncate: boolean;
   /** Typography variant — sets role tokens (size/weight/tracking/color). */
-  variant: 'body' | 'heading' | 'subheading' | 'title' | 'subsection' | 'display' | 'caption' | 'label' | 'kicker' | 'deck' | 'section' | 'metric' | 'code' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+  variant: 'body' | 'heading' | 'title' | 'subsection' | 'display' | 'caption' | 'label' | 'kicker' | 'deck' | 'section' | 'metric' | 'code';
 }

package/components/text/text.test.js

@@ -0,0 +1,106 @@
+/**
+ * text-ui variant rendering tests — §210 (v0.5.7, FEEDBACK-17 §1).
+ *
+ * Verifies the 12 documented enum values in `text.yaml`/`text.d.ts`/
+ * `text.a2ui.json` all render distinctly per the `:scope[variant=…]`
+ * rules in `text.css`. Pre-§210 the three token-backed variants
+ * `subsection` / `deck` / `metric` silently rendered as `body`
+ * defaults because the matching `:scope` rules were missing — the
+ * yaml + d.ts advertised them but the CSS didn't consume the tokens.
+ *
+ * Plus a guard: the 6 phantom enum entries removed in §210
+ * (`subheading`, `h1`-`h6`) must NOT be in the .d.ts type union or
+ * the a2ui.json enum — they had no shipped tokens and rendering them
+ * was always body-defaults.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import '../../core/element.js';
+import './text.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;
+}
+
+// jsdom doesn't evaluate @scope rules in `getComputedStyle()`. We
+// validate the CSS by reading the rule out of text.css text and
+// asserting the variant-specific properties are present — coarse
+// but catches the §210 regression class (rule missing entirely).
+const HERE = dirname(fileURLToPath(import.meta.url));
+const TEXT_CSS = readFileSync(resolve(HERE, 'text.css'), 'utf8');
+const TEXT_DTS = readFileSync(resolve(HERE, 'text.d.ts'), 'utf8');
+const TEXT_A2UI = JSON.parse(readFileSync(resolve(HERE, 'text.a2ui.json'), 'utf8'));
+
+describe('text-ui §210 — variant enum vs CSS rule completeness', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  // ── Mounting smoke — every documented variant constructs without crash ──
+  const documentedVariants = [
+    'body', 'heading', 'title', 'subsection', 'display', 'caption',
+    'label', 'kicker', 'deck', 'section', 'metric', 'code',
+  ];
+
+  it.each(documentedVariants)('mounts <text-ui variant="%s"> without error', async (variant) => {
+    const t = mount(`<text-ui variant="${variant}">Sample</text-ui>`);
+    await tick();
+    expect(t).toBeDefined();
+    expect(t.getAttribute('variant')).toBe(variant);
+  });
+
+  // ── CSS-side: every documented variant has a :scope rule ──
+  it.each(documentedVariants)('text.css ships a :scope[variant="%s"] rule', (variant) => {
+    expect(TEXT_CSS).toMatch(new RegExp(`:scope\\[variant="${variant}"\\]`));
+  });
+
+  // ── Three token-backed variants restored in §210 ──
+  it.each(['subsection', 'deck', 'metric'])(
+    'text.css :scope[variant="%s"] consumes role tokens (not body defaults)',
+    (variant) => {
+      // The rule must reference the role-specific token, not fall through
+      // to var(--a-body-*) defaults.
+      const ruleMatch = TEXT_CSS.match(
+        new RegExp(`:scope\\[variant="${variant}"\\]\\s*\\{([^}]+)\\}`)
+      );
+      expect(ruleMatch, `rule missing for variant="${variant}"`).toBeTruthy();
+      const rule = ruleMatch[1];
+      expect(rule).toMatch(new RegExp(`var\\(--a-${variant}-family\\)`));
+      expect(rule).toMatch(new RegExp(`var\\(--a-${variant}-weight\\)`));
+      expect(rule).toMatch(new RegExp(`var\\(--a-${variant}-size\\)`));
+    }
+  );
+
+  // ── Type-side: 6 phantom entries removed in §210 ──
+  const removedPhantoms = ['subheading', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6'];
+
+  it.each(removedPhantoms)('text.d.ts variant union does NOT contain phantom "%s"', (variant) => {
+    expect(TEXT_DTS).not.toMatch(new RegExp(`'${variant}'`));
+  });
+
+  it.each(removedPhantoms)('text.a2ui.json variant enum does NOT contain phantom "%s"', (variant) => {
+    expect(TEXT_A2UI.properties.variant.enum).not.toContain(variant);
+  });
+
+  // ── 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;
+    const dtsUnionMatch = TEXT_DTS.match(/variant:\s*((?:'[^']+'\s*\|?\s*)+);/);
+    expect(dtsUnionMatch).toBeTruthy();
+    const dtsVariants = [...dtsUnionMatch[1].matchAll(/'([^']+)'/g)].map(m => m[1]);
+
+    expect(a2uiVariants.sort()).toEqual(dtsVariants.sort());
+    expect(a2uiVariants.sort()).toEqual([...documentedVariants].sort());
+
+    // Every variant has a CSS rule.
+    for (const v of a2uiVariants) {
+      expect(TEXT_CSS).toMatch(new RegExp(`:scope\\[variant="${v}"\\]`));
+    }
+  });
+});

package/components/text/text.yaml

@@ -34,7 +34,6 @@ props:
     enum:
       - body
       - heading
-      - subheading
       - title
       - subsection
       - display
@@ -45,12 +44,6 @@ props:
       - section
       - metric
       - code
-      - h1
-      - h2
-      - h3
-      - h4
-      - h5
-      - h6
 events: {}
 slots: {}
 states:

package/components/timeline/class.js

@@ -87,6 +87,11 @@ export class UITimelineItem extends UIElement {
     spinner:     { type: Boolean, default: false,     reflect: true },
   };
 
+  // §205 (v0.5.7): dynamic chevron icons stamped on expanded-state ternary
+  // (class.js:167). Per FEEDBACK-16 §1 + §209 slot-11 ternary-walker discovery.
+  // Note: `this.icon` consumer-supplied — not declared here.
+  static requiredIcons = ['caret-down', 'caret-right'];
+
   static template = () => null;
 
   #outcomes = [];

package/components/timeline/timeline.yaml

@@ -40,6 +40,9 @@ states:
     description: Default, ready for interaction.
 traits: []
 tokens: {}
+requiredIcons:
+  - caret-down
+  - caret-right
 a2ui:
   rules: []
 anti_patterns: []

package/components/toggle-scheme/class.js

@@ -78,6 +78,12 @@ export class UIToggleScheme extends UIElement {
   #mqlHandler = null;
   #onPress = null;
   #stamped = false;
+  // §200 (v0.5.7, FEEDBACK-10 §1): set true after first user-driven scheme
+  // mutation (button press OR programmatic setScheme/toggle). Until then,
+  // the `scheme` attribute is treated as "reactive consumer-driven" — any
+  // post-connect attribute application re-runs #initState() so the reactive
+  // value wins over the template-strip race.
+  #userTouched = false;
 
   connected() {
     if (!this.#stamped) {
@@ -87,6 +93,26 @@ export class UIToggleScheme extends UIElement {
     this.#initState();
   }
 
+  attributeChangedCallback(name, oldVal, newVal) {
+    // §200 (v0.5.7, FEEDBACK-10 §1): UIElement.attributeChangedCallback syncs
+    // attr → property. After it runs, if the `scheme` attribute changed AFTER
+    // connect AND the user hasn't yet chosen explicitly, re-run #initState()
+    // so the reactive consumer value wins over the template-engine's strip-
+    // then-restamp race. Once the user clicks the button or calls
+    // setScheme()/toggle() programmatically, #userTouched flips true and we
+    // stop auto-reinit so user choice survives subsequent re-renders.
+    super.attributeChangedCallback(name, oldVal, newVal);
+    if (
+      name === 'scheme' &&
+      this.isConnected &&
+      this.#stamped &&
+      !this.#userTouched &&
+      oldVal !== newVal
+    ) {
+      this.#initState();
+    }
+  }
+
   disconnected() {
     if (this.#button && this.#onPress) {
       this.#button.removeEventListener('press', this.#onPress);
@@ -98,6 +124,7 @@ export class UIToggleScheme extends UIElement {
 
   /** Flip between light and dark — defeats auto. */
   toggle() {
+    this.#userTouched = true;
     const next = this.activeScheme === DARK ? LIGHT : DARK;
     this.#apply(next, 'programmatic');
   }
@@ -106,6 +133,7 @@ export class UIToggleScheme extends UIElement {
    * @param {"light"|"dark"|"auto"} s
    */
   setScheme(s) {
+    this.#userTouched = true;
     if (s === AUTO) {
       this.#clearTargetOverride();
       const resolved = this.#resolvePrefersScheme();
@@ -135,6 +163,9 @@ export class UIToggleScheme extends UIElement {
       // so consumers see one semantic event, not the inner button's.
       e.stopPropagation();
       if (this.disabled) return;
+      // §200 (v0.5.7): mark user-touched so post-connect reactive `scheme`
+      // attribute writes don't override the user's explicit choice.
+      this.#userTouched = true;
       const next = this.activeScheme === DARK ? LIGHT : DARK;
       this.#apply(next, 'press');
     };

package/components/toggle-scheme/toggle-scheme.test.js

@@ -0,0 +1,110 @@
+/**
+ * toggle-scheme-ui §200 race-fix tests — v0.5.7 (FEEDBACK-10 §1).
+ *
+ * Verifies the post-connect attribute application is HONORED — not raced over
+ * by the synchronous #initState() call in connected(). Per the bug class:
+ *
+ *   1. template.js scan() strips placeholder attributes pre-insertion
+ *   2. replaceChildren() upgrades the element; connectedCallback fires
+ *   3. #initState() reads this.scheme (default 'auto')
+ *   4. template.js update() then setAttribute('scheme', 'dark')
+ *   5. attributeChangedCallback syncs to property — but #initState already ran
+ *
+ * Pre-§200, step 4 was a no-op for the scheme cascade. Post-§200,
+ * attributeChangedCallback re-runs #initState() (until user-touched).
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import '../../core/element.js';
+import './toggle-scheme.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('toggle-scheme-ui §200 race fix', () => {
+  beforeEach(() => {
+    document.body.innerHTML = '';
+    document.documentElement.style.removeProperty('color-scheme');
+  });
+
+  it('honors post-connect scheme attribute application (reactive consumer)', async () => {
+    // Simulate template.js's strip-then-restamp pattern: mount without scheme,
+    // then set the attribute immediately afterward (mimics post-connect apply).
+    const t = mount('<toggle-scheme-ui></toggle-scheme-ui>');
+    await tick();
+    t.setAttribute('scheme', 'dark');
+    await tick();
+    expect(t.activeScheme).toBe('dark');
+    expect(document.documentElement.style.colorScheme).toBe('dark');
+  });
+
+  it('honors the initial scheme attribute (no race scenario)', async () => {
+    const t = mount('<toggle-scheme-ui scheme="dark"></toggle-scheme-ui>');
+    await tick();
+    expect(t.activeScheme).toBe('dark');
+  });
+
+  it('user button press locks #userTouched — subsequent attr changes are ignored', async () => {
+    const t = mount('<toggle-scheme-ui scheme="dark"></toggle-scheme-ui>');
+    await tick();
+    expect(t.activeScheme).toBe('dark');
+
+    // User press: flips to light. #userTouched flips true.
+    const btn = t.querySelector(':scope > button-ui');
+    btn.dispatchEvent(new CustomEvent('press', { bubbles: true }));
+    await tick();
+    expect(t.activeScheme).toBe('light');
+
+    // Consumer re-renders with scheme="dark" — should NOT clobber user choice.
+    t.setAttribute('scheme', 'dark');
+    await tick();
+    expect(t.activeScheme).toBe('light'); // user choice survives
+  });
+
+  it('programmatic setScheme also locks #userTouched', async () => {
+    const t = mount('<toggle-scheme-ui scheme="auto"></toggle-scheme-ui>');
+    await tick();
+
+    t.setScheme('dark');
+    await tick();
+    expect(t.activeScheme).toBe('dark');
+
+    // Consumer reactive write should NOT override.
+    t.setAttribute('scheme', 'light');
+    await tick();
+    expect(t.activeScheme).toBe('dark');
+  });
+
+  it('toggle() also locks #userTouched', async () => {
+    const t = mount('<toggle-scheme-ui scheme="auto"></toggle-scheme-ui>');
+    await tick();
+    const initial = t.activeScheme;  // depends on prefers-color-scheme (likely light in test env)
+
+    t.toggle();
+    await tick();
+    expect(t.activeScheme).not.toBe(initial);
+
+    const afterToggle = t.activeScheme;
+    t.setAttribute('scheme', initial === 'dark' ? 'dark' : 'light');
+    await tick();
+    expect(t.activeScheme).toBe(afterToggle); // user choice survives
+  });
+
+  it('removing the attribute (back to auto) is honored pre-touch', async () => {
+    const t = mount('<toggle-scheme-ui scheme="dark"></toggle-scheme-ui>');
+    await tick();
+    expect(t.activeScheme).toBe('dark');
+
+    t.removeAttribute('scheme');
+    await tick();
+    // After removal, attr is null; #initState falls to auto → resolves
+    // prefers-color-scheme. Test env should resolve to light by default.
+    expect(['light', 'dark']).toContain(t.activeScheme);
+  });
+});

package/components/upload/upload.d.ts

@@ -17,6 +17,12 @@ export type UploadChangeEvent = CustomEvent<UploadChangeEventDetail>;
 export class UIUpload extends UIFormElement {
   /** Files currently selected. */
   readonly files: FileList | File[];
+  /** §207 (v0.5.7): label rendered above the dropzone. */
+  label: string;
+  /** §207 (v0.5.7): MIME-type accept filter (e.g. `"image/*"` or `".pdf,.txt"`). */
+  accept: string;
+  /** §207 (v0.5.7): allow multi-file selection. */
+  multiple: boolean;
 
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adia-ai/web-components",
-  "version": "0.5.6",
-  "description": "AdiaUI web components \u2014 vanilla custom elements. A2UI runtime (renderer, registry, streams, wiring) lives in @adia-ai/a2ui-runtime.",
+  "version": "0.5.7",
+  "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",
   "exports": {
@@ -28,6 +28,8 @@
       "default": "./components/*/class.js"
     },
     "./components/*.css": "./components/*/*.css",
+    "./components/*/*.css": "./components/*/*.css",
+    "./components/*/css/*.css": "./components/*/css/*.css",
     "./styles/*": "./styles/*",
     "./traits": "./traits/index.js",
     "./traits/*": "./traits/*.js",

package/styles/components.css

@@ -13,6 +13,7 @@
 /* ── Components ── */
 @import "../components/icon/icon.css";
 @import "../components/button/button.css";
+@import "../components/link/link.css";
 @import "../components/input/input.css";
 @import "../components/textarea/textarea.css";
 @import "../components/check/check.css";
@@ -84,6 +85,7 @@
 @import "../components/block/block.css";
 @import "../components/text/text.css";
 @import "../components/toggle-group/toggle-group.css";
+@import "../components/toggle-scheme/toggle-scheme.css";
 @import "../components/demo-toggle/demo-toggle.css";
 @import "../components/richtext/richtext.css";
 @import "../components/stream/stream.css";