@adia-ai/web-components 0.7.5 → 0.7.6

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog — @adia-ai/web-components
 
+## [0.7.6] — 2026-06-02
+
+### Added
+
+- **`[padding]` / `[margin]` named scale (`xs`–`xl`) — complete + parametric.** Previously the named padding/margin vocabulary was only `sm`/`md`/`lg` (literal `--a-space-4`/`6`/`8`). Now the full `xs`–`xl` set, each `calc(--a-space-N × --a-{padding,margin}-k)` — mirroring the `[gap]` scale's `value × --a-*-k` form. New `@property --a-padding-k` / `--a-margin-k` knobs (`<number>`, init 1, inherits — a root/provider-level control, subtree-inert like `--a-gap-k`/`--a-density`) retune all named padding/margin at once, per-dimension. `sm`/`md`/`lg` keep their prior values (16/24/32px @k=1) — **behavior-neutral**; `xs` (8px) + `xl` (40px) are new. Integer rungs (`[padding="4"]`) stay literal space-rungs (k-independent). Composes on `--a-density`. Verified: 8/16/24/32/40 @k=1; root `--a-padding-k:2` → md 48 / xl 80; `--a-margin-k` independent of padding. Files: `styles/foundation/space.css`, `styles/api/sizing.css`.
+
+### Changed
+
+- **`styles/host.css` is now foundation-only (tokens + resets + page-frame); `styles/index.css` becomes the primitives barrel.** Previously `host.css` bundled the full library (tokens + all 120 component styles + resets, via `index.css`) plus the page-frame. Now: `host.css` = `tokens.css` + `resets.css` + `:where(html)` page-frame only; `styles/index.css` = `components.css` wrapped in `layer(components)` (the primitives barrel). Pages link both in order. The package-root `index.css` (`@adia-ai/web-components/css`) imports both and preserves the existing full-stack published entry — no change for consumers using the package entry. All 119 component dev shells and `site/index.html` updated. **Migration for `host.css`-only consumers:** add `<link rel="stylesheet" href="@adia-ai/web-components/styles/index.css" />` after the `host.css` link.
+- **`<block-ui>` padding/margin unified with the global `[padding]`/`[margin]` scale — now parametric (behavior change).** `block-ui` carried its own literal padding/margin scale (`none`/`xs`/`sm`/`md`/`lg`/`xl` = `0`/`--a-space-1/2/4/6/10` = 0/4/8/16/24/40px, k-independent), duplicated across `block.css` (static `:scope[padding=…]` rules) and `block.class.js` `_SPACE` (the `@bp` responsive path), and diverging from the global `[padding]`/`[margin]` attribute API — `<block-ui padding="md">` rendered 16px while `[padding="md"]` is 24px (same vocabulary, different sizes). Both paths now reference the parametric `--a-{padding,margin}-{xs..xl}` tokens (`foundation/space.css`), so the two grammars AGREE (the same "one named scale" principle as the `[gap]` unification), `block-ui` tracks the `--a-padding-k`/`--a-margin-k` knobs, and the scale is no longer duplicated. **Behavior change** — `block-ui` spacing grows at `xs`/`sm`/`md`/`lg`: `xs` 4→8, `sm` 8→16, **`md` (the default) 16→24**, `lg` 24→32px; `xl` (40) + `none` (0) unchanged. Verified by computed-style probe (8/16/24/32/40 @k=1, default 24, `--a-padding-k:2` → md 48, `@bp` responsive + margins all correct, 0 console errors) + dev-shell visual QA. Files: `components/block/block.css`, `components/block/block.class.js`. **Migration:** a `<block-ui>` that relied on the prior tighter spacing should step the named value one rung down (`md`→`sm`, `lg`→`md`, …) or use the integer rungs (`padding="4"` = literal 16px, k-independent).
+- **CDN bundles rebuilt** — `dist/host.min.css`, `dist/web-components.min.css`, and `dist/web-components.min.js` regenerated so the barrel split + `<block-ui>` + parametric `[padding]`/`[margin]` + `[verse]` re-scaling reach `@adia-ai/web-components@0.7` CDN consumers.
+
+### Fixed
+
+- **`[verse]` register now scales icon + caret sizes down with its type + controls.** The compact `[verse]` register (`styles/verse.css`) shifted inset, gap, radius, control-size (`--a-size`), and every type role down — but left `--a-icon-size` (16px @md) and `--a-caret-size` (14px @md) at their regular-register values. So in a verse context a `<select-ui>` caret (an `<icon-ui>` reading `--a-icon-size`) stayed 16×16 against verse's 12px text in a 43px-tall control, and form-element chrome icons read full size — visually oversized. Added a one-tier-down icon/caret scale to `[verse]`, mirroring how it already re-implements `--a-size`: base `[verse]` = 14/12px (= regular-`sm`), `[verse][size="lg"]` = 16/14px (= regular-`md`), `[verse][size="sm"]` = 12/10px. The explicit `[size]` tier rules are **required** because the global `[size]` icon/caret rules live in the `utilities` layer, which verse's `context` layer shadows (same reason `--a-size` needs them). Covers both `<icon-ui>`-based carets (select / combobox, via `--a-icon-size`) and CSS-drawn carets (calendar-grid / calendar-picker / nav-group / pane, via `--a-caret-size`). Verified by computed-style + render-box probe: verse(md) caret 16→14px, verse-`sm` 14→12px, verse-`lg` 20→16px; regular register unchanged. File: `styles/verse.css`.
+- **`<command-ui>` now parses `.map()`/`repeat()`-rendered `<option>`/`<optgroup>` palette items (5th sighting of the `display:contents` wrapper trap).** `#parseOptions()` walked `this.children` directly, so options rendered via `.map()` arrived nested in the template engine's `display:contents`/`role="presentation"` wrapper span and were missed — leaving an empty palette ("No results found.") when the consumer interpolated its option list. New `#logicalOptionChildren()` walks direct children and pierces wrapper spans, mirroring `select-ui#logicalOptionChildren` (FB-98). Eight other `for (const x of this.children)` loops across 8 components (context-menu, field, fields, integration-card, list, menu, swatch, toolbar) were audited and marked `// wrapper-trap-ok` — all read component-stamped or single-literal children that are never consumer-interpolated. `audit:wrapper-trap:strict` added to `check:dogfood-audits:strict`; the audit now reports 0 un-allowlisted loops. File: `components/command/command.class.js`.
+- **`<select-ui>` now parses `.map()`/`repeat()`-rendered `<option>` children (FB-98).** `#parseOptions()` walked `this.children` and matched only `tagName === 'OPTION'`/`'OPTGROUP'`, so interpolated options — each nested in the template engine's `display:contents`/`role="presentation"` wrapper span (`core/template.js` Array branch) — were invisible, leaving the popover empty ("No options"); static-literal options worked (direct children, no wrapper). New `#logicalOptionChildren()` collects `<option>`/`<optgroup>` direct OR nested inside the wrapper spans (skipping component-stamped `[slot]` children), and a re-entrancy-guarded `MutationObserver` re-parses options that arrive after `connected()` (the template's `update()` pass) so the empty-state clears. The same `display:contents` wrapper trap fixed for `menu-ui#show()` (FB-92) and `tree-item-ui#stamp()` (FB-96), now in the third component; mirrors tree's `#logicalSlotChildren`. Static-literal selects + the FB-36 `<option selected>` initial-value path are unchanged. +2 regression tests. File: `components/select/select.class.js`. (Tokens Studio / color-app FB-98)
+- **`<menu-ui>` — a closed declarative menu no longer takes layout space (FB-97).** The closed-state hide rule (`menu.css`) used a child combinator (`:scope > menu-item-ui`), so `.map()`/`repeat()`-rendered items — nested in the template engine's `display:contents`/`role="presentation"` wrapper span — escaped it on the initial (never-opened) render and laid out in flow, ballooning a compact menu to its widest item's width (a 388px file menu displaced a centered toolbar tab-row until a tab became un-clickable). Added wrapper-piercing descendant selectors (`:scope > [role="presentation"] menu-item-ui`, + `menu-divider-ui`); safe vs. the open state since `#show()` appendChild's the bare items into `[data-menu-popover]` (never the wrappers). Verified: a closed `.map()` menu collapses 388px → trigger width (~41px), items `display:none`, neighbour un-displaced; open still renders all items. The CSS instance of the FB-92/96/98 `display:contents` wrapper trap; makes the FB-92/95 "render menu items declaratively" guidance safe for compact menus. File: `components/menu/menu.css`. (Tokens Studio / color-app FB-97)
+- **`button.yaml` `aria-label` prop marked `dynamic: true` — clears dogfood drift.** `aria-label` is a native ARIA attribute managed via `setAttribute` in `connected()` and deliberately kept out of `static properties` (would clobber native `ariaLabel` reflection via `installProps`). The `static-properties-vs-yaml` dogfood audit flagged the yaml declaration as a drift; `dynamic: true` is the established opt-out (same pattern as the `text` prop). `button.a2ui.json` regenerated (`aria-label` → `DynamicString $ref`); dogfood advisory count: 43 → 42.
+- **`<button-ui>` trailing slot kbd-pill now tracks the button's label color on every variant.** A `<kbd-ui slot="trailing">` pill rendered `kbd-ui`'s dark default even on a primary (white-label) button. `kbd-ui` styles its own `color`/`background`/`border` inside `@scope (kbd-ui)`, which wins over the button's `[slot="trailing"]` rule by **scope proximity** (closer scope root) — so setting `color` (even `inherit`) on the slot is inert. Fix: the button overrides `kbd-ui`'s own *tokens* — `[slot="trailing"] { --kbd-fg: currentColor; --kbd-bg / --kbd-border: color-mix(in oklab, currentColor …, transparent) }`. `kbd-ui` declares those tokens at `:where(:scope)` (specificity 0,0,0), so the button's `[slot]` decls (0,1,0) win on **specificity — which the cascade resolves before proximity** — and the pill (text + translucent fill + border) tracks the label: white on primary/colored fills, dark on outline/ghost. Verified on a fresh serve (kbd computed `color` == button label across variants). File: `components/button/button.css`.
+
 ## [0.7.5] — 2026-06-02
 
 ### Fixed

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

@@ -66,8 +66,8 @@
       "Button"
     ],
     "slots": {
-      "default (action-item-ui children)": {
-        "description": "Child content region for the `default (action-item-ui children)` slot."
+      "default": {
+        "description": "Holds the list's `<action-item-ui>` children (the action items)."
       }
     },
     "states": [

package/components/action-list/action-list.yaml

@@ -28,8 +28,8 @@ events:
         type: object
         description: The triggering list-item element.
 slots:
-  default (action-item-ui children):
-    description: "Child content region for the `default (action-item-ui children)` slot."
+  default:
+    description: "Holds the list's `<action-item-ui>` children (the action items)."
 states:
   - name: idle
     description: Default, ready for interaction.

package/components/badge/badge.yaml

@@ -90,6 +90,7 @@ props:
       - muted
       - solid
       - outline
+    reflect: false  # declarative presentational attribute — CSS/author-time read, non-reactive by design
 events: {}
 slots: {}
 states:

package/components/block/block.class.js

@@ -19,13 +19,29 @@
  * Properties:
  *   padding — none | xs | sm | md | lg | xl (default 'md')
  *   margin  — none | xs | sm | md | lg | xl (default 'none')
+ *
+ * Values resolve to the parametric --a-{padding,margin}-{xs..xl} scale
+ * (foundation/space.css), unified with the global [padding]/[margin] attribute
+ * API: md = 24px @k=1, tracks --a-{padding,margin}-k. The `@bp` responsive
+ * path below emits the same tokens as the static block.css rules.
  */
 
 import { UIElement } from '../../core/element.js';
 import { parseResponsive, breakpoint } from '../../core/responsive.js';
 
-const _SPACE = { none: '0', xs: 'var(--a-space-1)', sm: 'var(--a-space-2)', md: 'var(--a-space-4)', lg: 'var(--a-space-6)', xl: 'var(--a-space-10)' };
-function _spaceToCss(v) { return _SPACE[v] ?? (/^\d+$/.test(v ?? '') ? `var(--a-space-${v})` : v ?? ''); }
+const _NAMED = new Set(['xs', 'sm', 'md', 'lg', 'xl']);
+/** Resolve a (responsive-parsed) padding/margin value to CSS for dimension
+ *  `dim` ('padding' | 'margin'). Named rungs map to the parametric
+ *  --a-{dim}-{xs..xl} scale (foundation/space.css) so this responsive JS path
+ *  AGREES with the static block.css rules + the global [padding]/[margin]
+ *  attribute API; bare integers stay literal --a-space-N rungs; 'none' → 0. */
+function _spaceToCss(v, dim) {
+  if (v == null || v === '') return '';
+  if (v === 'none') return '0';
+  if (_NAMED.has(v)) return `var(--a-${dim}-${v})`;
+  if (/^\d+$/.test(v)) return `var(--a-space-${v})`;
+  return v;
+}
 
 export class UIBlock extends UIElement {
   static properties = {
@@ -42,13 +58,13 @@ export class UIBlock extends UIElement {
     const bp      = anyR ? breakpoint.value : '';
 
     if (padding?.includes('@')) {
-      this.style.setProperty('--block-padding', _spaceToCss(parseResponsive(padding, bp)));
+      this.style.setProperty('--block-padding', _spaceToCss(parseResponsive(padding, bp), 'padding'));
     } else {
       this.style.removeProperty('--block-padding');
     }
 
     if (margin?.includes('@')) {
-      this.style.setProperty('--block-margin', _spaceToCss(parseResponsive(margin, bp)));
+      this.style.setProperty('--block-margin', _spaceToCss(parseResponsive(margin, bp), 'margin'));
     } else {
       this.style.removeProperty('--block-margin');
     }

package/components/block/block.css

@@ -1,6 +1,6 @@
 @scope (block-ui) {
   :where(:scope) {
-    --block-padding: var(--a-space-4);
+    --block-padding: var(--a-padding-md);
     --block-margin:  0;
   }
 
@@ -11,19 +11,24 @@
     margin: var(--block-margin);
   }
 
-  /* ── Padding variants ── */
+  /* ── Padding variants — the parametric --a-padding-{xs..xl} scale
+     (foundation/space.css), unified with the global [padding] attribute API
+     (api/sizing.css) so <block-ui padding="md"> == [padding="md"] == 24px @k=1,
+     and block-ui now tracks the --a-padding-k knob. Was a literal --a-space-N
+     scale (md=16px, k-independent) — see CHANGELOG 0.7.7 behavior change. ── */
   :scope[padding="none"] { --block-padding: 0; }
-  :scope[padding="xs"]   { --block-padding: var(--a-space-1); }
-  :scope[padding="sm"]   { --block-padding: var(--a-space-2); }
-  :scope[padding="md"]   { --block-padding: var(--a-space-4); }
-  :scope[padding="lg"]   { --block-padding: var(--a-space-6); }
-  :scope[padding="xl"]   { --block-padding: var(--a-space-10); }
+  :scope[padding="xs"]   { --block-padding: var(--a-padding-xs); }
+  :scope[padding="sm"]   { --block-padding: var(--a-padding-sm); }
+  :scope[padding="md"]   { --block-padding: var(--a-padding-md); }
+  :scope[padding="lg"]   { --block-padding: var(--a-padding-lg); }
+  :scope[padding="xl"]   { --block-padding: var(--a-padding-xl); }
 
-  /* ── Margin variants ── */
+  /* ── Margin variants — the parametric --a-margin-{xs..xl} scale, unified
+     with the global [margin] attribute API (tracks --a-margin-k). ── */
   :scope[margin="none"] { --block-margin: 0; }
-  :scope[margin="xs"]   { --block-margin: var(--a-space-1); }
-  :scope[margin="sm"]   { --block-margin: var(--a-space-2); }
-  :scope[margin="md"]   { --block-margin: var(--a-space-4); }
-  :scope[margin="lg"]   { --block-margin: var(--a-space-6); }
-  :scope[margin="xl"]   { --block-margin: var(--a-space-10); }
+  :scope[margin="xs"]   { --block-margin: var(--a-margin-xs); }
+  :scope[margin="sm"]   { --block-margin: var(--a-margin-sm); }
+  :scope[margin="md"]   { --block-margin: var(--a-margin-md); }
+  :scope[margin="lg"]   { --block-margin: var(--a-margin-lg); }
+  :scope[margin="xl"]   { --block-margin: var(--a-margin-xl); }
 }

package/components/button/button.a2ui.json

@@ -20,8 +20,7 @@
     },
     "aria-label": {
       "description": "Accessible label for screen readers. Auto-set from `text` when text is non-empty; meaningful override for icon-only buttons.",
-      "type": "string",
-      "default": ""
+      "$ref": "common_types.json#/$defs/DynamicString"
     },
     "color": {
       "description": "Semantic intent — composes with [variant]. `<button-ui variant=\"solid\" color=\"danger\">` = filled destructive action; `<button-ui variant=\"outline\" color=\"success\">` = outlined success affordance.",

package/components/button/button.css

@@ -71,11 +71,12 @@ button-ui[color="danger"]:not([disabled]):hover {
 
     /* ── Trailing slot ── */
     --button-trailing-font-size:  var(--a-ui-sm);
-    /* kbd-pill tracks the button's OWN text color (currentColor) so it reads
-       on any variant fill — on a primary button the fixed --a-fg-muted gray
-       was nearly invisible against the white label. Border is a translucent
-       slice of the same color so the pill outline adapts too. */
-    --button-trailing-fg:         currentColor;
+    /* kbd-ui styles its color/bg/border inside `@scope (kbd-ui)`, which beats
+       this scope by PROXIMITY — so setting `color`/`border` on [slot="trailing"]
+       here is inert for a kbd pill. The pill is recolored through kbd's OWN
+       tokens (--kbd-fg/-bg/-border) in the rule below instead. The
+       --button-trailing-* tokens remain the fallback for non-kbd trailing
+       content (badges, plain spans). */
     --button-trailing-border:     color-mix(in oklab, currentColor 28%, transparent);
     --button-trailing-radius:     var(--a-radius-sm);
     --button-trailing-px:         var(--a-space-0-5);
@@ -142,12 +143,22 @@ button-ui[color="danger"]:not([disabled]):hover {
     order: 99;
     margin-inline-start: auto;
     font-size: var(--button-trailing-font-size);
-    color: var(--button-trailing-fg);
+    color: inherit;
     font-family: inherit;
     border: 1px solid var(--button-trailing-border);
     border-radius: var(--button-trailing-radius);
     padding: 0 var(--button-trailing-px);
     line-height: 1;
+    /* Recolor a <kbd-ui slot="trailing"> pill via kbd's OWN tokens so it tracks
+       the button label color on every variant (primary white, ghost subtle,
+       colored fills). kbd-ui's `:scope { color: var(--kbd-fg) }` wins over the
+       `color: inherit` above by scope proximity, but its tokens are declared at
+       :where(:scope) (0,0,0) — these (0,1,0) decls win on specificity, which the
+       cascade resolves BEFORE proximity. currentColor here is the inherited
+       button label color. */
+    --kbd-fg:     currentColor;
+    --kbd-bg:     color-mix(in oklab, currentColor 16%, transparent);
+    --kbd-border: color-mix(in oklab, currentColor 30%, transparent);
   }
 
   /* :scope:active moved outside @scope — see Safari 17.x bug note at top. */

package/components/button/button.yaml

@@ -18,6 +18,7 @@ props:
     description: Accessible label for screen readers. Auto-set from `text` when text is non-empty; meaningful override for icon-only buttons.
     type: string
     default: ""
+    dynamic: true  # native ARIA attr — managed in connected() (setAttribute), deliberately NOT in `static properties` (would clobber native ariaLabel reflection per the installProps memory)
   type:
     description: HTML button type (button, submit, reset)
     type: string

package/components/card/card.yaml

@@ -16,6 +16,7 @@ props:
       rung ("1"…"16").
     type: string
     default: md
+    reflect: false  # declarative presentational attribute — CSS/author-time read, non-reactive by design
   draggable:
     description: Enables drag handle + cursor:grab. Wires the draggable trait; dispatches drag-end.
     type: boolean

package/components/chart/chart.a2ui.json

@@ -55,8 +55,7 @@
     },
     "data": {
       "description": "JS property (set programmatically — `el.data = [...]`). An array of plain objects; each object's keys are named by the `x` and `y` attributes — e.g. `<chart-ui x=\"month\" y=\"revenue\">` consumes `[{month:'Jan', revenue:3200}, {month:'Feb', revenue:4100}]`. The Chart.js `{labels, datasets}` envelope is NOT chart-ui's API — passing it (or any non-array value) renders an empty chart. May also be supplied declaratively as a JSON-array `data=\"[…]\"` attribute, hydrated once at connect. Custom accessor on the element class, not a reflected attribute.",
-      "type": "array",
-      "default": []
+      "$ref": "common_types.json#/$defs/DynamicStringList"
     },
     "format": {
       "description": "Number-format mode applied to axis labels + value overlays + donut total + gauge value + treemap value + funnel value + internal tooltip. `abbr` is the legacy 1.2K / 3M format; `decimal` fixes 2 decimals; `currency` prefixes via `--chart-currency-prefix` token (default \"$\"); `percent` multiplies × 100 and adds a % suffix.",

package/components/chart/chart.d.ts

@@ -23,7 +23,7 @@ export class UIChart extends UIElement {
   /** Color scheme */
   color: 'accent' | 'success' | 'warning' | 'danger' | 'info';
   /** JS property (set programmatically — `el.data = [...]`). An array of plain objects; each object's keys are named by the `x` and `y` attributes — e.g. `<chart-ui x="month" y="revenue">` consumes `[{month:'Jan', revenue:3200}, {month:'Feb', revenue:4100}]`. The Chart.js `{labels, datasets}` envelope is NOT chart-ui's API — passing it (or any non-array value) renders an empty chart. May also be supplied declaratively as a JSON-array `data="[…]"` attribute, hydrated once at connect. Custom accessor on the element class, not a reflected attribute. */
-  data: unknown[];
+  data: string;
   /** Number-format mode applied to axis labels + value overlays + donut total + gauge value + treemap value + funnel value + internal tooltip. `abbr` is the legacy 1.2K / 3M format; `decimal` fixes 2 decimals; `currency` prefixes via `--chart-currency-prefix` token (default "$"); `percent` multiplies × 100 and adds a % suffix. */
   format: 'abbr' | 'decimal' | 'currency' | 'percent';
   /** When true, suppress the overlaid average line */

package/components/chart/chart.yaml

@@ -123,6 +123,7 @@ props:
       reflected attribute.
     type: array
     default: []
+    dynamic: true  # JS-set collection prop with a custom setter — deliberately not in static properties
 events:
   chart-hover:
     description: >-

package/components/check/check.a2ui.json

@@ -98,9 +98,6 @@
       "box": {
         "description": "Visual checkbox indicator"
       },
-      "hint": {
-        "description": "Help text below the label"
-      },
       "label": {
         "description": "Label text beside the checkbox"
       }

package/components/check/check.yaml

@@ -58,8 +58,6 @@ events:
 slots:
   box:
     description: Visual checkbox indicator
-  hint:
-    description: Help text below the label
   label:
     description: Label text beside the checkbox
 states:

package/components/combobox/combobox.a2ui.json

@@ -93,8 +93,7 @@
     },
     "options": {
       "description": "Programmatic option list. Array of {value, label, disabled?, group?} or grouped {label, options:[…]}. Alternative to declarative <option> / <optgroup> children.",
-      "type": "array",
-      "default": []
+      "$ref": "common_types.json#/$defs/DynamicStringList"
     },
     "placeholder": {
       "description": "Placeholder text in the input when value is empty",

package/components/combobox/combobox.yaml

@@ -84,6 +84,7 @@ props:
       <option> / <optgroup> children.
     type: array
     default: []
+    dynamic: true  # JS-set collection prop with a custom setter — deliberately not in static properties
   open:
     description: Reflects popover open / closed state
     type: boolean

package/components/command/command.a2ui.json

@@ -103,9 +103,6 @@
       },
       "list": {
         "description": "Container for command items and groups"
-      },
-      "search": {
-        "description": "Search input with combobox role"
       }
     },
     "states": [

package/components/command/command.class.js

@@ -140,9 +140,27 @@ export class UICommand extends UIElement {
 
   // ── Parse declarative <option>/<optgroup> ──
 
+  // Wrapper-piercing walk for consumer-authored <option>/<optgroup> children.
+  // Mirrors select-ui's #logicalOptionChildren (FB-98): .map()/repeat()-rendered
+  // options arrive in display:contents/role="presentation" wrapper spans; a plain
+  // this.children iteration misses them (FB-98 class, 5th sighting in command-ui).
+  #logicalOptionChildren() {
+    const out = [];
+    const walk = (parent) => {
+      for (const ch of parent.children) {
+        if (ch.hasAttribute('slot')) continue;            // component-stamped — skip
+        if (ch.tagName === 'OPTION' || ch.tagName === 'OPTGROUP') { out.push(ch); continue; }
+        if (ch.matches('[role="presentation"]') || ch.style?.display === 'contents') { walk(ch); continue; }
+        // unknown authored child — ignore (command-ui only uses option/optgroup)
+      }
+    };
+    walk(this);
+    return out;
+  }
+
   #parseOptions() {
     const items = [];
-    for (const child of this.children) {
+    for (const child of this.#logicalOptionChildren()) {
       if (child.tagName === 'OPTGROUP') {
         const groupLabel = child.label;
         const group = { label: groupLabel, items: [] };

package/components/command/command.yaml

@@ -51,8 +51,6 @@ slots:
     description: Keyboard hint bar
   list:
     description: Container for command items and groups
-  search:
-    description: Search input with combobox role
 states:
 - name: idle
   description: Default, ready for interaction.

package/components/context-menu/context-menu.class.js

@@ -105,6 +105,7 @@ export class UIContextMenu extends UIElement {
         return [];
       }
     }
+    // wrapper-trap-ok: detects non-menu-item children as custom content; context-menu items are always static declarative children (right-click actions are not .map()'d)
     for (const child of this.children) {
       const tag = child.tagName.toLowerCase();
       if (tag !== 'menu-item-ui' && tag !== 'menu-divider-ui') return [child];

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

@@ -15,8 +15,7 @@
   "properties": {
     "items": {
       "description": "Optional JSON array of {term, description} — alternative to declarative <dt>/<dd> children",
-      "type": "array",
-      "default": []
+      "$ref": "common_types.json#/$defs/DynamicStringList"
     },
     "align": {
       "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",

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

@@ -14,7 +14,7 @@ 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[];
+  items: string;
   /** 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';

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

@@ -30,6 +30,7 @@ props:
     description: Optional JSON array of {term, description} — alternative to declarative <dt>/<dd> children
     type: array
     default: []
+    dynamic: true  # JS-set collection prop with a custom setter — deliberately not in static properties
   layout:
     description: "stacked: term above description. inline: term and description on one row."
     type: string

package/components/field/field.class.js

@@ -245,6 +245,7 @@ export class UIField extends UIElement {
 
   /** The default-slot control — first child without a `slot` attribute. */
   #findControl() {
+    // wrapper-trap-ok: field control is always a single literal child (one <input>/<textarea>/<select>); interpolating the control via .map() is not a documented field pattern
     for (const ch of this.children) {
       if (!ch.hasAttribute('slot')) return ch;
     }

package/components/fields/fields.class.js

@@ -81,6 +81,7 @@ export class UIFields extends UIElement {
 
   #syncInline() {
     const inline = this.hasAttribute('inline');
+    // wrapper-trap-ok: fields-ui children are authored as static field-ui literals within a form group; dynamic .map() field collections use the programmatic API
     for (const child of this.children) {
       if (child.localName !== 'field-ui') continue;
       if (inline) {

package/components/grid/grid.yaml

@@ -23,6 +23,7 @@ props:
       in a 2-column hero. Sets grid-item alignment, NOT text alignment.
     type: string
     default: stretch
+    reflect: false  # declarative presentational attribute — CSS/author-time read, non-reactive by design
   columnGap:
     description: Column gap override
     type: string
@@ -50,6 +51,7 @@ props:
       justify-items. Default stretch (items fill their column track).
     type: string
     default: stretch
+    reflect: false  # declarative presentational attribute — CSS/author-time read, non-reactive by design
   minColumnWidth:
     description: >-
       Minimum track width for columns="auto-fit"/"auto-fill" (any CSS length,

package/components/input/input.a2ui.json

@@ -40,8 +40,7 @@
     },
     "autocomplete": {
       "description": "Browser autofill behavior per HTML autocomplete spec. Routed via setAttribute to the host element. Common values: off, on, cc-number, cc-exp, cc-csc, cc-name, email, username, current-password, new-password, one-time-code, given-name, family-name, street-address, postal-code.",
-      "type": "string",
-      "default": ""
+      "$ref": "common_types.json#/$defs/DynamicString"
     },
     "component": {
       "const": "Input"
@@ -58,18 +57,7 @@
     },
     "inputmode": {
       "description": "Mobile keyboard hint per HTML inputmode spec. Routed via setAttribute to the host element. Values: text, decimal, numeric, tel, search, email, url.",
-      "type": "string",
-      "enum": [
-        "text",
-        "decimal",
-        "numeric",
-        "tel",
-        "search",
-        "email",
-        "url",
-        "none"
-      ],
-      "default": null
+      "$ref": "common_types.json#/$defs/DynamicString"
     },
     "label": {
       "description": "Inline label rendered as a leading caption inside the input chrome, between any prefix and the value. Wires aria-labelledby on the editable surface. For stacked label / hint / error compositions, wrap with field-ui.",

package/components/input/input.yaml

@@ -80,12 +80,14 @@ props:
     - email
     - url
     - none
+    dynamic: true  # native attr — routed via setAttribute to the host, deliberately NOT in static properties (would clobber native reflection)
   autocomplete:
     description: 'Browser autofill behavior per HTML autocomplete spec. Routed via setAttribute to the host element. Common
       values: off, on, cc-number, cc-exp, cc-csc, cc-name, email, username, current-password, new-password, one-time-code,
       given-name, family-name, street-address, postal-code.'
     type: string
     default: ''
+    dynamic: true  # native attr — routed via setAttribute to the host, deliberately NOT in static properties (would clobber native reflection)
   min:
     description: Minimum numeric value. Applies when `type="number"`. Clamps + drives aria-valuemin + the [-] button's disabled
       state.

package/components/integration-card/integration-card.class.js

@@ -226,6 +226,7 @@ export class UIIntegrationCard extends UIElement {
   #hasConsumerDescription() {
     // Author description = direct child element that is neither one of our
     // stamped data- markers nor an [slot="actions"] / [slot="action"] node.
+    // wrapper-trap-ok: detects presence of consumer-provided description; wrapper spans from interpolated content also qualify as "consumer description present" (correct — the content IS there)
     for (const child of this.children) {
       if (child === this.#bodyEl) continue;
       if (child === this.#descEl) continue;

package/components/list/list.class.js

@@ -174,6 +174,7 @@ export class UIListItem extends UIElement {
   // otherwise we'd accidentally remove e.g. a <span slot="icon"> inside a
   // child <card-ui> when list-item-ui has no `icon` prop.
   #ownChild(selector) {
+    // wrapper-trap-ok: finds component-stamped children (identified by [data-list-stamped]) — consumer list-item-ui children are never queried here
     for (const ch of this.children) {
       if (ch.matches(selector)) return ch;
     }

package/components/list/list.yaml

@@ -34,6 +34,7 @@ props:
       so content sits at the list-ui edges (canonical edge-to-edge style).
     type: boolean
     default: false
+    reflect: false  # declarative presentational attribute — CSS/author-time read, non-reactive by design
   selectable:
     description: Enable selection on child listitems (roving tabindex + aria-selected).
     type: boolean

package/components/menu/menu.class.js

@@ -290,6 +290,7 @@ export class UIMenuItem extends UIElement {
   #wasStamped(el) { return el?.dataset?.menuItemStamped === '1'; }
 
   #ownChild(selector) {
+    // wrapper-trap-ok: finds component-stamped children (data-menuItemStamped); consumer menu-item-ui children are adopted by #show() using logical children
     for (const ch of this.children) {
       if (ch.matches(selector)) return ch;
     }

package/components/menu/menu.css

@@ -21,9 +21,21 @@
 
   /* Items/dividers in Light DOM are hidden unless they've been adopted
      into the popover on open. Popover API also hides the popover itself
-     when closed. */
+     when closed.
+
+     FB-97: interpolated items (`.map()` / `repeat()`) arrive nested in the
+     template engine's `display:contents` / `role="presentation"` wrapper
+     span (core/template.js), so the direct-child combinator alone misses
+     them on the initial (never-opened) render — a CLOSED declarative menu
+     would lay them out in flow and balloon to its widest item's width,
+     displacing siblings. The wrapper-piercing descendant selectors hide
+     those too. Safe vs. the open state: #show() appendChild's the real
+     items (not the wrappers) into [data-menu-popover], so open-state items
+     are neither `:scope >` children nor under a `:scope > [role]` wrapper. */
   :scope > menu-item-ui,
-  :scope > menu-divider-ui {
+  :scope > menu-divider-ui,
+  :scope > [role="presentation"] menu-item-ui,
+  :scope > [role="presentation"] menu-divider-ui {
     display: none;
   }
 }

package/components/pipeline-status/pipeline-status.yaml

@@ -15,6 +15,7 @@ props:
     description: 'Component property: complete.'
     type: boolean
     default: false
+    reflect: false  # declarative presentational attribute — CSS/author-time read, non-reactive by design
   message:
     description: 'Component property: message.'
     type: string

package/components/radio/radio.a2ui.json

@@ -108,9 +108,6 @@
       "dot": {
         "description": "Radio dot indicator, sized via --dot-size"
       },
-      "hint": {
-        "description": "Hint text container, rendered via CSS attr(hint) on ::after"
-      },
       "label": {
         "description": "Label text container, rendered via CSS attr(label) on ::after"
       }

package/components/radio/radio.yaml

@@ -59,8 +59,6 @@ events:
 slots:
   dot:
     description: Radio dot indicator, sized via --dot-size
-  hint:
-    description: Hint text container, rendered via CSS attr(hint) on ::after
   label:
     description: Label text container, rendered via CSS attr(label) on ::after
 states:

package/components/rating/rating.yaml

@@ -53,6 +53,7 @@ props:
       - ""
       - accent
       - warning
+    reflect: false  # declarative presentational attribute — CSS/author-time read, non-reactive by design
 events:
   "[object Object]":
     description: "Fired on [object Object]."

package/components/search/search.a2ui.json

@@ -99,14 +99,7 @@
       "Command",
       "Select"
     ],
-    "slots": {
-      "clear": {
-        "description": "Clear button (shown when value is non-empty)"
-      },
-      "input": {
-        "description": "Native search input element"
-      }
-    },
+    "slots": {},
     "states": [
       {
         "description": "Default, ready for interaction.",