@adia-ai/web-components 0.5.17 → 0.5.19

package/CHANGELOG.md

@@ -11,6 +11,28 @@ runtime ships in the sibling `@adia-ai/a2ui-runtime` package
 
 _No pending changes._
 
+## [0.5.19] - 2026-05-17
+
+### Added
+- §348 (FB-51 #3; P3) — `<description-list-ui>` `align="stretch"` enum value (joins `start`, `between`). For `layout="inline"`, sets `justify-self: stretch` + `width: 100%` on `<dd>` (and `width: 100%` on its direct children) so block-level form controls — `<slider-ui>`, `<select-ui>`, `<color-picker-ui>` — reach the column edge rather than shrink-wrapping to content. Closes the Tokens Studio dts-right-panel migration path for property-row pairs where the value is a control, not text. Schema + generated `.d.ts` + `a2ui.json` updated. NEW `description-list.test.js` with 3 cases (CSS source contract, host attribute precondition, yaml enum shape).
+- §347 (FB-50 #3; P3) — `<command-ui>` `select` event detail now carries `category` from the parent `<optgroup label="…">`. Items without a group surface `category = ''` so destructuring stays safe. Schema (`command.yaml`) + generated `.d.ts` + `a2ui.json` updated. Closes Tokens Studio's consumer pattern of routing selected commands by section (Navigation / Edit / etc.) without re-walking the DOM to find the parent optgroup label.
+- §342 (FB-44; P1) — `<swatch-ui>` `MutationObserver` for late-arriving `[slot="chrome"]` children. `#absorbChromeSlot()` runs from `#syncCore()` which only fires on attribute / property changes; `scan()` walks `element.attributes` BEFORE descending to child nodes, so the parent template's `update()` loop assigns properties (→ `render()` → `#syncCore()` → `#absorbChromeSlot()`) BEFORE interpolating child node parts. The once-only absorb pass therefore sees an empty children set and chrome — arriving moments later — sits at its arrival position rather than the canonical post-tile region. Fix: arm a `MutationObserver` on host `childList` in `connected()` that re-runs `#absorbChromeSlot()` whenever a direct `[slot="chrome"]` child OR a `display:contents` wrapper-span containing chrome is added. Observer is torn down in `disconnected()`. Closes the post-§341 follow-up gap in Tokens Studio's C1.3 main-palette dogfood (gamut badges + override / tracked dots invisible despite §341 placeholder-preservation). 3 NEW vitest cases in `swatch.test.js`'s `FB-44 / §-TBD` describe block.
+- §343 (FB-46; P2) — `<tree-ui>` `tree-select` event detail now forwards `ctrlKey` / `metaKey` / `shiftKey` from the originating `MouseEvent` or `KeyboardEvent`. Unblocks consumer-side Ctrl/Cmd+click multi-select implementations (Tokens Studio token-tree). `select(item, originatingEvent = null)` is the new public signature; programmatic calls (no event) surface all three modifiers as `false`. Schema (`tree.yaml`) + generated `.d.ts` + `a2ui.json` updated. 4 NEW vitest cases in new `tree.test.js`. Backward-compatible: existing `detail.{item,text,value}` shape unchanged; new fields are additive.
+
+### Tests
+- §344 (FB-47; partial / misdiagnosed) — 3 NEW vitest cases in `core/template.test.js`'s `FB-47` describe block lock the actual contract: (1) `stamp()` with same template strings reuses the mounted instance (no `replaceChildren()`); (2) `repeat()` with same key preserves wrapper children across re-renders; (3) the `Array.isArray(v)` branch in `applyValue()` DOES rebuild on every re-render (the actual `.map()` destruction surface, documented behavior). The FB-47 author's "`stamp()` is unconditional" + "`repeat()` keyed diffing defeated" claims are empirically false; the tests pin current behavior to catch future drift. See RESPONSE-47 for the consumer-side `.map()` → `repeat()` migration recommendation.
+- §347 (FB-50 #3) — NEW `command.test.js` (first dedicated test file for `<command-ui>`) with 3 cases: emits `category=""` for ungrouped options, emits `category="<optgroup label>"` for items inside an optgroup, backward-compat `{ value, label }` destructuring still works. 3/3 passing.
+
+### Docs
+- USAGE.md — new `§345 (v0.5.19) — .map() vs repeat() for reactive lists (FB-47)` section under the template parser invariants. Documents the keyed-reuse contract, when `repeat()` matters, and the key-selection guidance (use a stable consumer-supplied identifier, NOT array index).
+- USAGE.md — new `§349 (v0.5.19) — Event handling inside reactive lists (FB-49)` section. Explains that `closest()` works through `display:contents` wrapper-spans (DOM walk, not box walk) for typical bubble-phase handlers; reserves `composedPath()` for cross-subtree / shadow-DOM / whitespace-retarget cases with explicit examples. Closes the documentation gap that caused three consumer `composedPath()` workarounds in Tokens Studio to ship without rationale.
+- §346 — NEW `components/command/USAGE.md` (FB-50 #1) — first dedicated USAGE doc for `<command-ui>`. Documents the native `<option data-shortcut data-icon>` content API (the actual shape; there is no `command-item-ui` custom element), the `<optgroup label>` grouping pattern, the new `category` field in `select` detail (per FB-50 #3 above), the Cmd+K wiring pattern, `setItems()` imperative API, recent-items behavior, and the `empty` + `footer` slots. Closes Tokens Studio's discoverability gap that drove ~350 LOC of hand-rolled `<dts-command-palette>` fallback.
+
+## [0.5.18] - 2026-05-16
+
+### Fixed
+- §341 (FB-43; P1) — `<swatch-ui>` chrome destroyed when interpolated via parent `html\`\`` template `${chromeFrag}`. `template.js`'s `scan()` replaces `<!--p:N-->` comments with empty text nodes inside the swatch element when the parent template is cloned; `wrap()` later mutates those text nodes in-place via `replaceWith()`. Pre-§341: the swatch's `#stamp()` ran `innerHTML = ''` between the parent's `mount()` and `update()` (synchronous custom-element connectedCallback timing), wiping the text-node placeholders. Parent's `replaceWith()` then ran on detached nodes — silent no-op — leaving wrapper-spans detached and chrome stamped into a subtree that never reached the live DOM. Symptom: chrome interpolated as `${chromeFrag}` was completely invisible (queryable from neither swatch nor host). Blocked Tokens Studio's C1.3 main-palette dogfood migration (~80 swatches inside `repeat()`). **Fix:** preserve empty text nodes + comment nodes (template-engine placeholders) AND display:contents wrapper-spans through `innerHTML = ''`. Detach them before the wipe, re-attach at the canonical chrome position (between tile + badge) after the canonical structure is stamped. Wrapper-spans preserved in-place keep the template-engine's `part.n` reference stable across re-renders → chrome content updates land in the same DOM location automatically. `#absorbChromeSlot()`'s late-arriving wrapper handler also updated: MOVE the wrapper (not hoist chrome out of it) to canonical position — same identity-preservation rationale. **§331 contract refined:** previously chrome was hoisted to be a direct sibling of the swatch's internal elements (`parentElement === swatch`); §341 keeps chrome inside the wrapper-span which is a direct sibling. Visually identical (display:contents collapses the wrapper's box) but the DOM identity is now wrapper-bearing. 3 NEW vitest cases (`FB-43 / §341`) + 3 §331 (FB-39) tests updated for new contract. 15/15 swatch tests passing.
+
 ## [0.5.17] - 2026-05-16
 
 ### Fixed

package/USAGE.md

@@ -1086,6 +1086,74 @@ Why AdiaUI doesn't implement `?attr=`: custom elements declare their reflective
 - HTML comments containing quoted attributes (`<!-- attr="value" -->`) — same fix (v0.5.3 §155).
 - Backticks inside HTML comments — see §221i above (JS-spec footgun; not a parser bug).
 
+### §-TBD (v0.5.19) — `.map()` vs `repeat()` for reactive lists (FB-47)
+
+Use **`repeat(items, keyFn, tplFn)`** for any list whose items are signal-driven and should preserve identity across re-renders. Plain `.map()` returns an `Array` of template results, which the template engine materializes via `container.replaceChildren()` on every parent update — correct, but per-item DOM is re-created from scratch.
+
+```js
+import { html, repeat } from '@adia-ai/web-components/core/element';
+
+// ❌ .map() — every re-render destroys and re-creates each wrapper-span
+html`
+  <div class="row">
+    ${stops.map(stop => renderSwatch(stop))}
+  </div>
+`;
+
+// ✅ repeat() — wrapper-spans + child custom elements preserved across re-renders
+html`
+  <div class="row">
+    ${repeat(stops, stop => stop.key, stop => renderSwatch(stop))}
+  </div>
+`;
+```
+
+**When `repeat()` matters:**
+
+- Lists of custom elements with internal state (`<swatch-ui>` with chrome slots, `<chat-thread>` with scroll position, `<select-ui>` with focus).
+- Lists where re-creation causes flicker (animations restart, transitions interrupt, IntersectionObservers re-fire).
+- Long lists (≥10 items) where per-item DOM allocation costs add up under signal-driven update churn.
+
+**Mechanism:** `repeat()` keys each item by `keyFn(item)` and stores wrapper-spans in a key-indexed map on the container. On re-render with the same key, the wrapper is reused; `stamp()` falls through to its same-strings cache hit and only `update()`s the parts in-place. With `.map()`, there is no key channel — the runtime cannot tell which result corresponds to which prior item, so it conservatively rebuilds every wrapper.
+
+**Key selection:** pick a stable consumer-supplied identifier (database id, slot.key, etc.), NOT array index. Array indices are unstable under insert/remove and defeat the keyed-reuse contract.
+
+### §-TBD (v0.5.19) — Event handling inside reactive lists (FB-49)
+
+Custom-element children rendered inside `repeat()` (or as an `${array}` interpolation) are each wrapped in a `<span style="display:contents">` by the template engine. These wrapper spans generate no boxes (`display:contents`) and cannot be click targets, but they ARE in the DOM tree.
+
+For most consumer event handlers, this is transparent. `Element.closest()` walks the **DOM tree** (not the box tree), so `display:contents` ancestors are walked through normally:
+
+```js
+// ✅ Bubble-phase listener on or inside the list — closest() works fine
+tree.addEventListener('tree-select', (e) => {
+  const item = e.detail.item;  // tree-ui already does the right walk for you
+});
+
+// ✅ Bubble-phase listener on a parent — closest() walks past display:contents wrappers
+host.addEventListener('click', (e) => {
+  const item = e.target.closest('tree-item-ui');
+  if (item && host.contains(item)) { /* … */ }
+});
+```
+
+Reach for `e.composedPath()` only when one of these specific cases applies:
+
+1. **Cross-subtree listeners.** If the listener's host is in a different subtree than the items (capture-phase on an ancestor far above), `closest()` walks UP from `e.target` but doesn't tell you which descendant of the listener's host was clicked. `composedPath()` returns the full leaf-to-document chain — filter that for the descendant tag you want.
+2. **Crossing shadow-DOM boundaries.** If `e.target` is retargeted to a shadow host (per the shadow DOM spec), `closest()` walks the light-DOM ancestor chain from that host. `composedPath()` exposes the actual leaf inside the shadow root.
+3. **Click on whitespace between list items.** Text nodes sometimes retarget to their parent element. If the parent is a `display:contents` wrapper-span, `closest('your-tag')` from that wrapper returns null (the wrapper's siblings include your tag, but not its descendants). `composedPath()` gives sibling context to walk.
+
+```js
+// ✅ For capture-phase / cross-subtree / shadow-DOM cases
+host.addEventListener('click', (e) => {
+  const item = e.composedPath().find(
+    (el) => el?.tagName?.toLowerCase() === 'tree-item-ui' && host.contains(el)
+  );
+}, { capture: true });
+```
+
+**Don't reach for `composedPath()` reflexively** — it rebuilds the full path on every call and is slower than `closest()`. Default to `closest()` for direct bubble-phase handlers; use `composedPath()` only when one of the three cases above applies.
+
 ### §221j — Typography token cheatsheet
 
 Quick-reference for component-CSS authoring. Cross-reference [`styles/typography.css`](./styles/typography.css):

package/components/command/USAGE.md

@@ -0,0 +1,160 @@
+# `<command-ui>` — Searchable command palette
+
+`<command-ui>` is a searchable command palette with keyboard navigation, recent-items memory, and grouped sections. It accepts **native `<option>` and `<optgroup>` children** as its content API — no custom element wrappers around items.
+
+```html
+<command-ui open placeholder="Type a command…">
+  <optgroup label="Navigation">
+    <option value="home" data-icon="house" data-shortcut="⌘H">Go Home</option>
+    <option value="settings" data-icon="gear" data-shortcut="⌘,">Settings</option>
+  </optgroup>
+  <optgroup label="Edit">
+    <option value="undo" data-icon="arrow-counter-clockwise" data-shortcut="⌘Z">Undo</option>
+    <option value="redo" data-icon="arrow-clockwise" data-shortcut="⌘⇧Z">Redo</option>
+  </optgroup>
+  <option value="logout" data-icon="sign-out" data-shortcut="⌘⇧Q">Log out</option>
+</command-ui>
+```
+
+## Why native `<option>`
+
+The native option semantics carry through to screen readers automatically, mirror the form-control patterns consumers already know, and inherit standard `disabled` handling. The alternative — a `<command-item-ui>` custom element — would duplicate the surface without adding capability.
+
+If you're coming from a primitive that uses `*-item-ui` children (e.g. `<tree-item-ui>` inside `<tree-ui>`, `<menu-item-ui>` inside `<menu-ui>`), the `<option>`-based API here is the deliberate exception. Other primitives ship custom-element children because their item state (open / selected / expanded) is rich; commands are stateless declarative entries.
+
+## Attributes
+
+| On `<command-ui>` | Type | Default | Description |
+|---|---|---|---|
+| `open` | boolean | `false` | Whether the palette is visible (reflected — set via property or attribute). |
+| `placeholder` | string | `Type a command…` | Search input placeholder. |
+
+| On each `<option>` | Description |
+|---|---|
+| `value` | Identifier emitted in the `select` event detail. |
+| `data-icon` | Phosphor icon name (rendered as `<icon-ui>` to the left of the label). |
+| `data-shortcut` | Keyboard shortcut hint string (rendered to the right, e.g. `⌘K`, `⇧E`). Display-only — wiring the actual shortcut is the consumer's responsibility (see "Wiring a global Cmd+K trigger" below). |
+| `data-keywords` | Extra space-separated keywords folded into the search index alongside the label. |
+| `disabled` | Boolean — render as inactive, skipped during keyboard navigation. |
+
+| On each `<optgroup>` | Description |
+|---|---|
+| `label` | Section heading. Propagates to `event.detail.category` on selection (§-TBD / FB-50 #3, v0.5.19+). |
+
+## Events
+
+```ts
+type CommandSelectDetail = {
+  value: string;     // option's [value]
+  label: string;     // option's text content
+  category: string;  // parent <optgroup label="…"> label, or '' if the option has no group
+};
+```
+
+```js
+palette.addEventListener('select', (e) => {
+  const { value, label, category } = e.detail;
+  switch (category) {
+    case 'Navigation': router.navigate(value); break;
+    case 'Edit':       editor.invoke(value);   break;
+    default:           runCommand(value);
+  }
+});
+
+palette.addEventListener('dismiss', () => {
+  // User pressed Escape — close it
+  palette.open = false;
+});
+```
+
+The palette doesn't auto-close on selection — the consumer decides whether to stay open (multi-action flow) or dismiss (typical single-action flow):
+
+```js
+palette.addEventListener('select', () => { palette.open = false; });
+```
+
+## Slots
+
+| Slot | What goes inside |
+|---|---|
+| `empty` | Shown when the filter has no matches. Use for a "No commands match" affordance or a "Create new" call-to-action. |
+| `footer` | Persistent footer band — usually a `<kbd>` hint bar like `↑↓ to navigate · ↵ to select · esc to close`. |
+
+```html
+<command-ui open placeholder="Type a command…">
+  <option value="…">…</option>
+
+  <div slot="empty">
+    <text-ui variant="caption" muted>No commands match — try a different search.</text-ui>
+  </div>
+
+  <div slot="footer">
+    <kbd>↑</kbd> <kbd>↓</kbd> navigate · <kbd>↵</kbd> select · <kbd>esc</kbd> close
+  </div>
+</command-ui>
+```
+
+## Wiring a global Cmd+K trigger
+
+Common pattern — global keyboard listener flips the `[open]` property:
+
+```js
+const palette = document.querySelector('command-ui');
+
+window.addEventListener('keydown', (e) => {
+  // Cmd+K on Mac, Ctrl+K elsewhere
+  if (e.key === 'k' && (e.metaKey || e.ctrlKey)) {
+    e.preventDefault();
+    palette.open = true;
+  }
+});
+
+palette.addEventListener('dismiss', () => { palette.open = false; });
+palette.addEventListener('select',   () => { palette.open = false; });
+```
+
+Once `open` flips to true, the input auto-focuses and Escape / outside-click fire `dismiss`. The palette handles arrow-key navigation, Enter to select, and recent-items recall on its own.
+
+## Dynamic command lists
+
+If your commands change reactively (signal-bound, fetched, etc.), use `palette.setItems([…])` to swap the entire item set in one call. Each item is `{ value, label, icon?, shortcut?, keywords?, disabled?, category? }`:
+
+```js
+palette.setItems([
+  // ungrouped items
+  { value: 'new', label: 'New file', icon: 'plus', shortcut: '⌘N' },
+
+  // a group — pass items inline, the palette renders the group header
+  { label: 'Recent', items: [
+    { value: 'open:foo.ts', label: 'foo.ts' },
+    { value: 'open:bar.ts', label: 'bar.ts' },
+  ]},
+]);
+```
+
+Or stay declarative and update the `<option>` / `<optgroup>` children directly — the palette re-parses on every `open` flip and when `setItems()` is called.
+
+## Recent items
+
+The palette automatically tracks the last 10 selected values and shows them as a "Recent" section when the search input is empty. Items appear in MRU order; selections promote items to the top. Recent items are filtered against the current item set, so a stale recent (item removed via `setItems()`) is silently dropped.
+
+This is a built-in behavior — no consumer wiring needed. To disable, override with an explicit empty group at the top, or skip and use the section-based grouping pattern instead.
+
+## Required icons
+
+`<command-ui>` auto-stamps the `magnifying-glass` icon in the search field. Per `command.yaml` `requiredIcons:`, this is aggregated into the global icon-load manifest by `installIconLoadersForRegistered()`. Any additional `data-icon="<name>"` on options must be in the Phosphor icon set (or registered via `IconRegistry.register(name, svgString)`).
+
+## Accessibility
+
+- The search input has `role="combobox"`, `aria-expanded`, `aria-controls`, and `aria-activedescendant` wiring per WAI-ARIA combobox pattern.
+- Each rendered option has `role="option"` and reflects `aria-disabled` from the source `<option>`.
+- The active item (keyboard-highlighted) gets `data-active` for CSS targeting + `aria-activedescendant` reference from the input.
+- Escape fires `dismiss` (not `close`) — the consumer decides whether to actually close.
+
+## Related primitives
+
+- `<menu-ui>` — for static actionable lists tied to a trigger (e.g. context menu). Not searchable.
+- `<select-ui>` — single-value form input with options. Not searchable.
+- `<tree-ui>` — hierarchical navigation with expand/collapse. Carries selection state.
+
+`<command-ui>` is the right choice when: (a) the user is typing to filter from a list, (b) the action set is broad (10+ items), (c) keyboard-first navigation is the primary affordance, OR (d) you need a Cmd+K-style global launcher.

package/components/command/class.js

@@ -144,19 +144,24 @@ export class UICommand extends UIElement {
     const items = [];
     for (const child of this.children) {
       if (child.tagName === 'OPTGROUP') {
-        const group = { label: child.label, items: [] };
+        const groupLabel = child.label;
+        const group = { label: groupLabel, items: [] };
         for (const opt of child.querySelectorAll('option')) {
-          group.items.push(this.#optionToItem(opt));
+          group.items.push(this.#optionToItem(opt, groupLabel));
         }
         items.push(group);
       } else if (child.tagName === 'OPTION') {
-        items.push(this.#optionToItem(child));
+        items.push(this.#optionToItem(child, ''));
       }
     }
     this.#items = items;
   }
 
-  #optionToItem(opt) {
+  // §-TBD (v0.5.19, FB-50 #3): forward the parent <optgroup label> as
+  // `category` on each item so the `select` event detail can surface
+  // which group the chosen item came from. Items without a group
+  // (direct <option> children of <command-ui>) get category = ''.
+  #optionToItem(opt, category = '') {
     return {
       value: opt.value,
       label: opt.textContent.trim(),
@@ -164,6 +169,7 @@ export class UICommand extends UIElement {
       shortcut: opt.dataset.shortcut || '',
       keywords: opt.dataset.keywords || '',
       disabled: opt.disabled,
+      category,
     };
   }
 
@@ -302,11 +308,18 @@ export class UICommand extends UIElement {
     this.#activate(parseInt(options[next].dataset.idx));
   }
 
+  // §-TBD (v0.5.19, FB-50 #3): emit `category` (from parent <optgroup
+   // label>) in the select detail so consumers can route on group.
+   // Items without a group surface category = ''.
   #select(item) {
     this.#pushRecent(item.value);
     this.dispatchEvent(new CustomEvent('select', {
       bubbles: true,
-      detail: { value: item.value, label: item.label },
+      detail: {
+        value: item.value,
+        label: item.label,
+        category: item.category || '',
+      },
     }));
   }
 
@@ -315,10 +328,14 @@ export class UICommand extends UIElement {
     if (!active) return;
     const value = active.dataset.value;
     const label = active.querySelector('[data-text]')?.textContent || '';
+    // Look up the item to surface category — the rendered DOM doesn't
+    // carry the group label, but #items / #itemByEl do.
+    const item = this.#itemByEl.get(active) || this.#findItem(value);
+    const category = item?.category || '';
     this.#pushRecent(value);
     this.dispatchEvent(new CustomEvent('select', {
       bubbles: true,
-      detail: { value, label },
+      detail: { value, label, category },
     }));
   }
 

package/components/command/command.a2ui.json

@@ -40,8 +40,12 @@
         "description": "Fired when Escape is pressed"
       },
       "select": {
-        "description": "Fired when an item is selected. Detail contains { value, label, item }.",
+        "description": "Fired when an item is selected. detail: { value, label, category }. `category` is the parent `<optgroup label=\"…\">` label, or empty string when the item is a direct child of `<command-ui>` with no group.\n",
         "detail": {
+          "category": {
+            "description": "Parent optgroup label (empty string when item has no group).",
+            "type": "string"
+          },
           "label": {
             "description": "Item label text.",
             "type": "string"

package/components/command/command.d.ts

@@ -14,6 +14,8 @@ import { UIElement } from '../../core/element.js';
 
 export type CommandDismissEvent = CustomEvent<unknown>;
 export interface CommandSelectEventDetail {
+  /** Parent optgroup label (empty string when item has no group). */
+  category: string;
   /** Item label text. */
   label: string;
   /** Item value attribute. */

package/components/command/command.test.js

@@ -0,0 +1,99 @@
+/**
+ * <command-ui> behavioral tests.
+ *
+ * FB-50 #3 (v0.5.19): the `select` event detail now carries `category`
+ * derived from the parent <optgroup label> (or '' when the item has
+ * no group).
+ */
+
+import { describe, it, expect, beforeAll, beforeEach, afterEach } from 'vitest';
+
+beforeAll(async () => {
+  await import('./command.js');
+});
+
+describe('<command-ui> select event detail includes category (FB-50 #3)', () => {
+  let host;
+  let palette;
+
+  beforeEach(async () => {
+    host = document.createElement('div');
+    document.body.appendChild(host);
+
+    palette = document.createElement('command-ui');
+    palette.setAttribute('open', '');
+
+    // Mixed: one ungrouped option, one optgroup with two options.
+    const ungrouped = document.createElement('option');
+    ungrouped.setAttribute('value', 'logout');
+    ungrouped.textContent = 'Log out';
+
+    const optgroup = document.createElement('optgroup');
+    optgroup.setAttribute('label', 'Navigation');
+    const opt1 = document.createElement('option');
+    opt1.setAttribute('value', 'home');
+    opt1.textContent = 'Go Home';
+    const opt2 = document.createElement('option');
+    opt2.setAttribute('value', 'settings');
+    opt2.textContent = 'Settings';
+    optgroup.appendChild(opt1);
+    optgroup.appendChild(opt2);
+
+    palette.appendChild(ungrouped);
+    palette.appendChild(optgroup);
+    host.appendChild(palette);
+
+    await new Promise((r) => setTimeout(r, 50));
+  });
+
+  afterEach(() => {
+    host.remove();
+  });
+
+  it('emits category="" for an ungrouped option', () => {
+    let received = null;
+    palette.addEventListener('select', (e) => { received = e.detail; });
+
+    // Use the imperative setItems() path to bypass DOM-walk ordering;
+    // the optgroup path is exercised in the next test.
+    palette.setItems([{ value: 'logout', label: 'Log out' }]);
+
+    // Simulate user clicking the logout row.
+    const row = palette.querySelector('[role="option"][data-value="logout"]');
+    expect(row).not.toBeNull();
+    row.click();
+
+    expect(received).not.toBeNull();
+    expect(received.value).toBe('logout');
+    expect(received.label).toBe('Log out');
+    expect(received.category).toBe('');
+  });
+
+  it('emits category="<optgroup label>" for an item inside an optgroup', () => {
+    let received = null;
+    palette.addEventListener('select', (e) => { received = e.detail; });
+
+    const homeRow = palette.querySelector('[role="option"][data-value="home"]');
+    expect(homeRow).not.toBeNull();
+    homeRow.click();
+
+    expect(received).not.toBeNull();
+    expect(received.value).toBe('home');
+    expect(received.label).toBe('Go Home');
+    expect(received.category).toBe('Navigation');
+  });
+
+  it('detail shape stays backward-compatible (existing destructuring works)', () => {
+    let received = null;
+    palette.addEventListener('select', (e) => {
+      const { value, label } = e.detail;  // pre-FB-50 destructuring shape
+      received = { value, label };
+    });
+
+    const settingsRow = palette.querySelector('[role="option"][data-value="settings"]');
+    settingsRow.click();
+
+    expect(received.value).toBe('settings');
+    expect(received.label).toBe('Settings');
+  });
+});

package/components/command/command.yaml

@@ -19,7 +19,12 @@ events:
   dismiss:
     description: Fired when Escape is pressed
   select:
-    description: Fired when an item is selected. Detail contains { value, label, item }.
+    description: >
+      Fired when an item is selected.
+      detail: { value, label, category }.
+      `category` is the parent `<optgroup label="…">` label, or empty
+      string when the item is a direct child of `<command-ui>` with no
+      group.
     detail:
       value:
         type: string
@@ -27,6 +32,9 @@ events:
       label:
         type: string
         description: Item label text.
+      category:
+        type: string
+        description: Parent optgroup label (empty string when item has no group).
 slots:
   empty:
     description: Empty state shown when no items match

package/components/description-list/description-list.a2ui.json

@@ -19,11 +19,12 @@
       "default": []
     },
     "align": {
-      "description": "Alignment for inline layout — between = term left, value right.",
+      "description": "Alignment for inline layout. `start` (default): term and value pack to the term column edge. `between`: term left, value right-aligned with `text-align: end`. `stretch`: value fills the remaining track width (e.g. for a `<slider-ui>` / `<select-ui>` / `<color-picker-ui>` as `<dd>` that should span the full row). Sets `justify-self: stretch` and `width: 100%` on `dd` so block-level form controls inside reach the column edge rather than shrink-wrapping to content.\n",
       "type": "string",
       "enum": [
         "start",
-        "between"
+        "between",
+        "stretch"
       ],
       "default": "start"
     },

package/components/description-list/description-list.css

@@ -65,6 +65,22 @@
     text-align: end;
   }
 
+  /* §-TBD (v0.5.19, FB-51 #3): align="stretch" lets dd fill the
+     remaining inline-grid track width. Useful when dd hosts a block-
+     level form control (slider-ui / select-ui / color-picker-ui) that
+     would otherwise shrink-wrap to content. width:100% on direct
+     children reaches block controls that have their own inline-flex
+     :scope rule (e.g. <slider-ui>) so they stretch to track width. */
+  :scope[layout="inline"][align="stretch"] > [data-dl-desc],
+  :scope[layout="inline"][align="stretch"] > dd {
+    justify-self: stretch;
+    width: 100%;
+  }
+  :scope[layout="inline"][align="stretch"] > [data-dl-desc] > *,
+  :scope[layout="inline"][align="stretch"] > dd > * {
+    width: 100%;
+  }
+
   /* Size handled by the universal [size] attribute scaling --a-ui-size;
      components pick up font-size from token chain automatically. */
 }

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

@@ -15,8 +15,9 @@ import { UIElement } from '../../core/element.js';
 export class UIDescriptionList extends UIElement {
   /** Optional JSON array of {term, description} — alternative to declarative <dt>/<dd> children */
   items: unknown[];
-  /** Alignment for inline layout — between = term left, value right. */
-  align: 'start' | 'between';
+  /** Alignment for inline layout. `start` (default): term and value pack to the term column edge. `between`: term left, value right-aligned with `text-align: end`. `stretch`: value fills the remaining track width (e.g. for a `<slider-ui>` / `<select-ui>` / `<color-picker-ui>` as `<dd>` that should span the full row). Sets `justify-self: stretch` and `width: 100%` on `dd` so block-level form controls inside reach the column edge rather than shrink-wrapping to content.
+ */
+  align: 'start' | 'between' | 'stretch';
   /** stacked: term above description. inline: term and description on one row. */
   layout: 'stacked' | 'inline';
 }

package/components/description-list/description-list.test.js

@@ -0,0 +1,72 @@
+/**
+ * <description-list-ui> behavioral tests.
+ *
+ * FB-51 #3 (v0.5.19): align="stretch" lets <dd> fill the remaining
+ * inline-grid track width so block-level form controls inside (e.g.
+ * <slider-ui>, <select-ui>, <color-picker-ui>) reach the column edge
+ * rather than shrink-wrapping to content.
+ */
+
+import { describe, it, expect, beforeAll, beforeEach, afterEach } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+beforeAll(async () => {
+  await import('./description-list.js');
+});
+
+describe('<description-list-ui> align="stretch" (FB-51 #3)', () => {
+  let host;
+  let dl;
+
+  beforeEach(async () => {
+    host = document.createElement('div');
+    host.style.width = '600px';
+    document.body.appendChild(host);
+
+    dl = document.createElement('description-list-ui');
+    dl.setAttribute('layout', 'inline');
+    dl.setAttribute('align', 'stretch');
+
+    const dt = document.createElement('dt');
+    dt.textContent = 'Source hue';
+    const dd = document.createElement('dd');
+    dd.id = 'fb51-stretch-dd';
+    const probe = document.createElement('div');
+    probe.id = 'fb51-stretch-probe';
+    probe.textContent = 'inner';
+    dd.appendChild(probe);
+    dl.appendChild(dt);
+    dl.appendChild(dd);
+
+    host.appendChild(dl);
+    await new Promise((r) => setTimeout(r, 50));
+  });
+
+  afterEach(() => {
+    host.remove();
+  });
+
+  it('CSS source declares justify-self: stretch + width: 100% for align="stretch" inline layout', () => {
+    const cssText = readFileSync(resolve(HERE, 'description-list.css'), 'utf8');
+    expect(cssText).toMatch(/\[layout="inline"\]\[align="stretch"\][^{]*\{[^}]*justify-self:\s*stretch/);
+    expect(cssText).toMatch(/\[layout="inline"\]\[align="stretch"\][^{]*\{[^}]*width:\s*100%/);
+  });
+
+  it('host carries the align="stretch" attribute (CSS selector match precondition)', () => {
+    expect(dl.getAttribute('align')).toBe('stretch');
+    expect(dl.getAttribute('layout')).toBe('inline');
+  });
+
+  it('yaml enum includes "stretch" (schema contract)', () => {
+    const yamlText = readFileSync(resolve(HERE, 'description-list.yaml'), 'utf8');
+    // Match the align enum block specifically (between `align:` and the next prop).
+    const alignBlock = yamlText.match(/align:[\s\S]*?(?=\n  \w+:)/)?.[0] || '';
+    expect(alignBlock).toMatch(/enum:[\s\S]*-\s+start/);
+    expect(alignBlock).toMatch(/enum:[\s\S]*-\s+between/);
+    expect(alignBlock).toMatch(/enum:[\s\S]*-\s+stretch/);
+  });
+});

package/components/description-list/description-list.yaml

@@ -10,12 +10,21 @@ description: Semantic key-value list (dl/dt/dd). Preserves native HTML semantics
   and SSR. Layout supports stacked (default) or inline.
 props:
   align:
-    description: Alignment for inline layout — between = term left, value right.
+    description: >
+      Alignment for inline layout.
+      `start` (default): term and value pack to the term column edge.
+      `between`: term left, value right-aligned with `text-align: end`.
+      `stretch`: value fills the remaining track width (e.g. for a
+      `<slider-ui>` / `<select-ui>` / `<color-picker-ui>` as `<dd>`
+      that should span the full row). Sets `justify-self: stretch` and
+      `width: 100%` on `dd` so block-level form controls inside reach
+      the column edge rather than shrink-wrapping to content.
     type: string
     default: start
     enum:
       - start
       - between
+      - stretch
   items:
     description: Optional JSON array of {term, description} — alternative to declarative <dt>/<dd> children
     type: array