@adia-ai/web-components 0.8.33 → 0.8.35

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog — @adia-ai/web-components
 
+## [0.8.35] — 2026-08-13
+
+### Maintenance
+- **Source fixes this window are carried per-file below; the narrative CHANGELOG entries live with the substantive packages.** Bumped in lockstep per `scripts/release/check-lockstep.mjs`. Headline v0.8.35 work shipped in factory-DX program (scaffold boot+CSS fixes, class-B npm marketplace, consumer CI recipe, DX sweep) + audit-wave plugin hardening + ~20 component/pattern fixes. See `packages/plugins/adia-ui-factory/CHANGELOG.md#0835--2026-08-13` for details.
+- **`components/` touched in this release window** (58 file(s), e.g. `agent-questions/agent-questions.class.js`) — carried by the entries above.
+- **`dist/` bundles rebuilt** in this cut's window (4 file(s)) — regenerated from the source changes described above, not independent edits.
+- **`patterns/` touched in this release window** (43 file(s), e.g. `access-requests/access-requests.examples.html`) — carried by the entries above.
+- **`traits/` touched in this release window** (5 file(s), e.g. `anchor-positioning/anchor-positioning.examples.html`) — carried by the entries above.
+
+## [0.8.34] — 2026-08-11
+
+### Fixed
+
+- **`date-range-picker-ui` — both calendar grids are now ONE click-start-click-end selection surface (gh#948, reported from adiav2 ADIA2-8020).** The change handlers were role-locked per pane (`from`-pane clicks could only ever write the range start), so a same-month range required paging the right pane back a month. First click = start, second = end in either grid; a second click earlier than the pending start restarts there; a click after a committed range starts fresh. Popover content-sizing (`width: max-content` + viewport/token caps) moved into the stylesheet so the JS anchor fallback and anchoring failures can no longer render a viewport-huge panel.
+- **`UIElement` — `reflect:true` booleans with a TRUE default now stamp their attribute on connect (gh#961).** installProps seeds the signal but can't write attributes (constructor restriction), and the setter's `Object.is` short-circuit skips reflection on same-value sets — so attribute-keyed CSS (`chat-thread:not([empty]) > chat-empty`, `editor-canvas:not([empty]) > editor-canvas-empty`, password-strength's `:not([show-label])`) read wrong state forever; 9 components carried the latent shape. The connect-time pre-sync loop now runs inside `untracked()` — its property reads otherwise subscribe a PARENT's render effect to template-created children's signals, the unbounded re-stamp oscillation the signals drain guard traps (the guard now names the still-dirty effect hosts).
+- **`modal-ui` — `aria-labelledby` falls back to an authored `[slot="heading"]` when `text=` is absent (gh#947), and an authored bare `<header>` no longer displaces into the body (gh#941).** Header icon+heading row layout is by tag + DOM order: the last non-button child claims the row, earlier content stays fixed-width.
+- **`table-ui` — composite-cell wrapper flex generalized to CSS (gh#940):** `[data-body] [role="gridcell"] > row-ui { flex: 1 }` covers progress AND avatar cells; the progress bar no longer collapses to ~33px. `<col-def meta>` JSON attribute carries per-column config (badge variant maps) declaratively.
+- **`step-progress-ui` — direction-agnostic sizing (gh#942):** `inline-size: 18rem` + `max-inline-size: 100%` replace the direction-fragile `flex-basis`, so a column-flex parent no longer inflates the component to 288px tall.
+- **`command-ui` / `combobox-ui` — `options` catalog schema corrected to rich objects (`DynamicObjectList`).** Both yamls declare `{value, label, icon?, …}` objects but omitted `items.type`, mapping to the string-list default — the dialect validator rejected every harvested rich-options palette (caught by exit-gate.corpus at release pre-flight).
+
+### Changed
+
+- **`richtext` — inline `<code>` chip background softened to container-low (gh#972):** the opaque `--a-canvas-2` chip out-competed body text where several tag references cluster; the 10% alpha tier recedes behind prose and composites consistently on stacked surfaces. The docs site's own `admin-page code` rule moves to the same tier (superseding its earlier well-strong non-text-contrast ruling — inline code is text formatting, not a UI component).
+- **`nav-item-ui` / `nav-group-ui` — state color spec (gh#968, operator ruling):** idle = neutral icons + neutral-high text on transparent; hover = on-surface on container-low; selected = on-surface on container. Selected glyphs drop the primary accent (supersedes gh#522's glyph half — the accent BAR keeps primary); `neutral/surfaceBright` was considered for the selected fill and ruled out.
+- **`tag-ui` / `badge-ui` / `tabs-ui` — font scale steps one rung (gh#965):** tag/badge default `--a-ui-sm` → `--a-ui-xs` with tiers shifting to `--a-ui-2xs`/`--a-ui-sm` (first consumer of the pre-staged 10px token); tabs `--a-ui-md` → `--a-ui-lg`.
+- **`description-list-ui` — `dt` renders as a kicker/data-label** (code family at `--a-label-size`, normal weight); **`dd` is semibold at context-inherited size** (`1em`) so the value leads the pair and tracks the surrounding prose.
+- **Token docs — the `-strong` semantics split documented (gh#969):** `--a-canvas-strong` is a surface-tonal tier while interactive families' `-strong` is the pressed/high-emphasis foreground — noted at the core.css declarations and in component-token-contract.md. No value changes.
+
+### Maintenance
+- **`dist/` bundles rebuilt** in this cut's window (4 file(s)) — regenerated from the source changes described above, not independent edits.
+- **`patterns/` touched in this release window** (1 file(s), e.g. `responsive-shell-sidebar/responsive-shell-sidebar.examples.html`) — carried by the entries above.
+- **`styles/` touched in this release window** (1 file(s), e.g. `semantics/core.css`) — carried by the entries above.
+
 ## [0.8.33] — 2026-08-11
 
 ### Added

package/components/agent-questions/agent-questions.class.js

@@ -133,7 +133,6 @@ export class UIAgentQuestions extends UIElement {
     this.#submitEl = document.createElement('button-ui');
     this.#submitEl.setAttribute('text', this.submitLabel || 'Continue');
     this.#submitEl.setAttribute('variant', 'primary');
-    this.#submitEl.setAttribute('size', 'sm');
     this.#submitEl.setAttribute('disabled', '');
     if (!this.multi) this.#submitEl.hidden = true;
     this.#submitEl.addEventListener('press', this.#onSubmit);

package/components/agent-reasoning/agent-reasoning.a2ui.json

@@ -111,7 +111,7 @@
     ],
     "slots": {
       "default": {
-        "description": "Default slot — primary child content."
+        "description": "Default slot — NOT a step-authoring surface: the component rebuilds its body from the addStep()/addThought() pipeline and does not consume authored children (gh#938)."
       }
     },
     "states": [

package/components/agent-reasoning/agent-reasoning.yaml

@@ -57,7 +57,7 @@ events:
         description: Whether the reasoning section is now collapsed.
 slots:
   default:
-    description: "Default slot — primary child content."
+    description: "Default slot — NOT a step-authoring surface: the component rebuilds its body from the addStep()/addThought() pipeline and does not consume authored children (gh#938)."
 states:
   - name: idle
     description: Default, ready for interaction.
@@ -72,8 +72,8 @@ a2ui:
   rules:
     - rule: 'Agent inner-monologue + pipeline viewer with steps, thoughts, plans, and iterations.'
       reason: 'Reasoning visualization surface.'
-    - rule: 'Composes <timeline-ui> internally — pass reasoning steps as children rendered as <timeline-item-ui>.'
-      reason: 'Composition contract.'
+    - rule: 'JS-property-driven ONLY — steps arrive via addStep()/addThought(); the component renders them internally as <timeline-item-ui> rows. Authored light-DOM children are NOT consumed (gh#938) — for a static/harvestable reasoning-steps surface, author a plain <timeline-ui> with <timeline-item-ui> children instead.'
+      reason: 'Composition contract — the previous wording ("pass reasoning steps as children") read as declarative-children support the class never had; a stateful pipeline (timers, spine layout, iterations) has no static form.'
     - rule: 'noAutocollapse attribute prevents the auto-collapse-on-complete behavior; useful for debug surfaces.'
       reason: 'Behavior knob.'
     - rule: 'Different from <agent-trace-ui> (metrics + tool-call summary) — reasoning is narrative, trace is structured-data.'

package/components/badge/badge.css

@@ -20,9 +20,25 @@
        only radius moved. */
     --badge-radius:    var(--a-radius-full);
     --badge-px:        var(--a-space-1-5);
-    --badge-py:        var(--a-space-0-5);
+    /* gh#1084: block padding flattened toward 1px per tier — the
+       --badge-min-h floor (below) now owns the chip's vertical size, so
+       py no longer has to carry it. Was --a-space-0-5 (2px); mirrors the
+       identical tag-ui change (same rationale, tag.css). */
+    --badge-py:        var(--a-space-px);
     --badge-gap:       var(--a-space-1);
-    --badge-font-size: var(--a-ui-sm);
+    /* gh#1084 — min-height floor, decoupled from padding (mirrors
+       tags-input-ui's --tags-input-min-h, and tag-ui's own --tag-min-h
+       added in the same change). Component-owned fixed rem constants
+       (not density-scaled) calibrated to badge's CURRENT rendered
+       height at each tier — measured 12/15/20px sm/md/lg before this
+       change — so this is a non-regressing addition: shrinking py
+       toward 1px no longer shrinks the badge, the floor holds the line. */
+    --badge-min-h:     0.9375rem; /* 15px @ d=1 — md */
+    --badge-min-h-sm:  0.75rem;   /* 12px @ d=1 */
+    --badge-min-h-lg:  1.25rem;   /* 20px @ d=1 */
+    /* One rung down the --a-ui-* scale (gh#965) — ladder shifts with it
+       (sm=2xs, lg=sm) so tiers stay one rung apart. Mirrors tag-ui. */
+    --badge-font-size: var(--a-ui-xs);
     /* ── Typographic register (issue 845; weight revised gh#866) — mono
        TRIAL taken: kbd-ui's own stack (--a-font-family-code, kbd.css) held
        up at small badge sizes (roughly a dozen logical pixels) in both
@@ -43,10 +59,13 @@
        and tag share this md baseline and this exact reasoning). */
     --badge-px-sm:  var(--a-space-1);
     --badge-px-lg:  var(--a-space-2);
+    /* gh#1084: py flattened toward 1px/tier now that --badge-min-h
+       floors the box — was --a-space-px/--a-space-1 (1px/4px); mirrors
+       the identical tag-ui change (tag.css). */
     --badge-py-sm:  var(--a-space-px);
-    --badge-py-lg:  var(--a-space-1);
-    --badge-font-size-sm: var(--a-ui-xs);
-    --badge-font-size-lg: var(--a-ui-md);
+    --badge-py-lg:  var(--a-space-0-5);
+    --badge-font-size-sm: var(--a-ui-2xs);
+    --badge-font-size-lg: var(--a-ui-sm);
     text-align: start;  /* §text-align-reset — blocks inheritance from centered ancestors */
 }
 
@@ -58,6 +77,10 @@
     justify-content: center;
     gap: var(--badge-gap);
     width: fit-content;
+    /* gh#1084: floor, not a fixed size — mirrors tags-input-ui's own
+       min-height and tag-ui's identical addition (tag.css). Decouples
+       the badge's vertical size from --badge-py. */
+    min-height: var(--badge-min-h);
     padding: var(--badge-py) var(--badge-px);
     background: var(--badge-bg);
     color: var(--badge-fg);
@@ -237,15 +260,18 @@
     --badge-px:        var(--badge-px-sm);
     --badge-py:        var(--badge-py-sm);
     --badge-font-size: var(--badge-font-size-sm);
+    --badge-min-h:     var(--badge-min-h-sm);
   }
   :scope[size="md"] {
     --badge-px:        var(--a-space-1-5);
-    --badge-py:        var(--a-space-0-5);
-    --badge-font-size: var(--a-ui-sm);
+    --badge-py:        var(--a-space-px);
+    --badge-font-size: var(--a-ui-xs);
+    --badge-min-h:     0.9375rem; /* 15px @ d=1 — matches the :where(:scope) default */
   }
   :scope[size="lg"] {
     --badge-px:        var(--badge-px-lg);
     --badge-py:        var(--badge-py-lg);
     --badge-font-size: var(--badge-font-size-lg);
+    --badge-min-h:     var(--badge-min-h-lg);
   }
 }

package/components/badge/badge.examples.md

@@ -11,8 +11,8 @@
 ```html
 <row-ui gap="6" align="start" wrap>
   <col-ui gap="2">
-    <text-ui variant="caption" color="muted">verse</text-ui>
-    <div verse>
+    <text-ui variant="caption" color="muted">scale="ui-sm"</text-ui>
+    <div scale="ui-sm">
       <row-ui gap="2">
         <badge-ui text="New" variant="success"></badge-ui>
         <badge-ui text="Beta" variant="info"></badge-ui>
@@ -31,8 +31,8 @@
     </div>
   </col-ui>
   <col-ui gap="2">
-    <text-ui variant="caption" color="muted">prose</text-ui>
-    <div prose>
+    <text-ui variant="caption" color="muted">scale="content-md"</text-ui>
+    <div scale="content-md">
       <row-ui gap="2">
         <badge-ui text="New" variant="success"></badge-ui>
         <badge-ui text="Beta" variant="info"></badge-ui>

package/components/button/button.css

@@ -84,6 +84,15 @@ button-ui[variant="ghost"][color="warning"]:not([disabled]):hover   { --button-f
     --button-font-size:        var(--a-ui-size);
     --button-font-weight:      var(--a-ui-weight);
     --button-font-family:      var(--a-font-family-ui);
+    /* Leading for the [text] label box ONLY — never the host. The host's
+       `line-height: 1` is deliberate (it sizes the icon/[slot="trailing"]
+       blocks), but the label's ::after clips to its own line box, so
+       inheriting 1 makes half-leading negative and shears descenders
+       (g/j/p/q/y, parentheses) by ~0.93px at the default size — gh#906.
+       Snug (1.3) contains the font's content box at every [size]; the
+       precedent is stat.css:174,198 setting leading on the truncating
+       box rather than on the component root. */
+    --button-label-line-height: var(--a-leading-snug);
     --button-gap:              var(--a-space-1);
     --button-bg-hover:         var(--a-bg-strong);   /* neutral fill → neutral -strong surface on hover */
     --button-fg-hover:         var(--a-ui-text-hover);
@@ -167,6 +176,9 @@ button-ui[variant="ghost"][color="warning"]:not([disabled]):hover   { --button-f
     overflow: hidden;
     text-overflow: ellipsis;
     min-width: 0;
+    /* `overflow: hidden` (needed for the ellipsis) makes this line box the
+       clip box — give it leading tall enough to contain the descenders. */
+    line-height: var(--button-label-line-height);
   }
 
   /* Display convention (ADR-0037): block-level by default — a text button used

package/components/card/card.css

@@ -80,6 +80,18 @@
     margin-top: auto;
   }
 
+  /* Flex containers never collapse adjacent margins the way block flow
+     does (gh#1098) — once :has(> footer) above switches the card to
+     flex-column, a plain header followed by a plain section stacks BOTH
+     regions' --card-inset margins into a doubled gap instead of the
+     single inset block flow would have collapsed them to. The leading
+     region's own margin-bottom already supplies that inset; zero the
+     trailing region's margin-top. footer is excluded — its margin-top is
+     handled above (bottom-pin `auto`) or by [divider] below. */
+  :scope:has(> footer) > :is(header, section) + :is(header, section) {
+    margin-block-start: 0;
+  }
+
   /* ═══════ Variants — token-only overrides ═══════ */
 
   /* `outline` is a documented alias for `outlined` (yaml). */
@@ -385,6 +397,30 @@
     border-radius: 0;
   }
 
+  /* Guide/value/legend safety inset (gh#1095) — [bleed]'s zero-inset is
+     only collision-free for the bare-marks case: a sparkline (its
+     renderer never emits axis ticks, gridlines, value labels, or a
+     legend — chart.class.js #renderSparkline), or any other chart-ui
+     type with BOTH [hide-grid] and [hide-values] set (the author opted
+     out of every text element). A chart that still draws guides or
+     value text — or is paired with a <chart-legend-ui> — needs
+     clearance from the card's frame, or that text collides with the
+     card edge and clips under the corner-rounded `overflow: hidden`
+     (:scope, top of file). Restore the card's own inset automatically
+     for those cases rather than relying on every author to remember —
+     the :has() selector's specificity already beats the plain [bleed]
+     reset above regardless of source order. Pairing a legend with a
+     genuinely full-bleed chart still works — put the legend in its OWN
+     section below, wired via chart-legend-ui[for="<chart id>"], which
+     never enters this selector (see chart-in-card.examples.html's
+     "Full-bleed chart + legend band" example). */
+  & > section[bleed]:has(> chart-ui:not([type="sparkline"]):not([hide-grid])),
+  & > section[bleed]:has(> chart-ui:not([type="sparkline"]):not([hide-values])),
+  & > section[bleed]:has(> chart-legend-ui) {
+    margin: var(--card-inset);
+    padding: 0;
+  }
+
   /* ═══════ Footer ═══════
      Margin-based inset. Flex row for actions.
      [divider] adds top border.
@@ -414,8 +450,15 @@
     justify-content: flex-end;
   }
 
+  /* Divider clearance is padding-only (matches header[divider]'s
+     padding-bottom pattern) — the space above the line already comes from
+     the preceding section's own trailing margin. An explicit margin-top
+     here on top of that stacked with the footer's base margin instead of
+     collapsing into it (footer/section are flex-column siblings once the
+     card has a footer — see the :has(> footer) rule above — so adjacent
+     margins never collapse), tripling the gap to the divider vs. the
+     content gaps around it (gh#1096). */
   & > footer[divider] {
-    margin-top: var(--card-inset);
     padding-top: var(--card-inset);
     border-top: 1px solid var(--card-divider);
   }

package/components/check/check.a2ui.json

@@ -46,6 +46,11 @@
       "type": "string",
       "default": ""
     },
+    "labelHidden": {
+      "description": "When true, [label] still sets the accessible name (aria-label) but the visible text is suppressed via the canonical sr-only technique (gh#1010). Use when a sibling element already shows the same name visually (e.g. a title next to a check-ui used as a list-item icon) and the plain-visible label would paint it twice.",
+      "type": "boolean",
+      "default": false
+    },
     "name": {
       "description": "Form field name",
       "type": "string",
@@ -123,26 +128,35 @@
     },
     "tag": "check-ui",
     "tokens": {
-      "--check-box-background": {
+      "--check-bg": {
         "description": "Unchecked background"
       },
-      "--check-box-border-color": {
-        "description": "Unchecked border color"
+      "--check-bg-checked": {
+        "description": "Checked/indeterminate background"
       },
-      "--check-box-radius": {
-        "description": "Checkbox border radius"
+      "--check-bg-checked-hover": {
+        "description": "Checked/indeterminate background on hover"
       },
-      "--check-box-size": {
-        "description": "Checkbox indicator size"
+      "--check-bg-hover": {
+        "description": "Unchecked background on hover"
       },
-      "--check-checked-background": {
-        "description": "Checked/indeterminate background"
+      "--check-border": {
+        "description": "Unchecked border color"
       },
-      "--check-checked-border-color": {
+      "--check-border-checked": {
         "description": "Checked/indeterminate border"
       },
-      "--check-checked-foreground": {
+      "--check-border-hover": {
+        "description": "Unchecked border color on hover"
+      },
+      "--check-fg-checked": {
         "description": "Checkmark/dash color"
+      },
+      "--check-radius": {
+        "description": "Checkbox border radius"
+      },
+      "--check-size": {
+        "description": "Checkbox indicator size"
       }
     },
     "traits": [],

package/components/check/check.class.js

@@ -26,6 +26,11 @@ export class UICheck extends UIFormElement {
     checked:       { type: Boolean, default: false, reflect: true },
     indeterminate: { type: Boolean, default: false, reflect: true },
     label:         { type: String,  default: '', reflect: true },
+    /* gh#1010: keeps [label] as the accessible name (aria-label, set
+       below) while suppressing the VISIBLE `::after` text — for
+       compositions that already show the name elsewhere (e.g. a
+       sibling title) and would otherwise paint it twice. */
+    labelHidden:   { type: Boolean, default: false, reflect: true, attribute: 'label-hidden' },
   };
 
   static template = () => html`<span slot="box"></span>`;

package/components/check/check.css

@@ -122,6 +122,27 @@ check-ui[indeterminate] {
   /* Label */
   :scope[label]::after { content: attr(label); }
 
+  /* Visually-hidden label (gh#1010) — [label-hidden] keeps the a11y name
+     (aria-label, set from [label] in check.class.js render()) but drops
+     the visible text, for compositions that already show the name
+     elsewhere. Same canonical sr-only recipe as <visually-hidden-ui>
+     (visually-hidden.css) — clip-path does the real hiding; the rest is
+     belt-and-suspenders for cross-UA. More specific than the bare
+     `[label]::after` rule above, so it wins whenever both are set. */
+  :scope[label][label-hidden]::after {
+    content: attr(label);
+    position: absolute !important;
+    width: 1px !important;
+    height: 1px !important;
+    padding: 0 !important;
+    margin: -1px !important;
+    overflow: hidden !important;
+    clip: rect(0, 0, 0, 0) !important;
+    clip-path: inset(100%) !important;
+    white-space: nowrap !important;
+    border: 0 !important;
+  }
+
   /* Focus */
   :scope:focus-visible [slot="box"] { box-shadow: var(--check-focus-ring); border-color: transparent; }
 

package/components/check/check.d.ts

@@ -20,6 +20,8 @@ export class UICheck extends UIFormElement {
   /** Indeterminate (mixed) state — visual only; cleared on click. */
   indeterminate: boolean;
   label: string;
+  /** When true, [label] still sets the accessible name but the visible text is sr-only hidden (gh#1010). */
+  labelHidden: boolean;
 
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,

package/components/check/check.examples.md

@@ -11,8 +11,8 @@
 ```html
 <row-ui gap="6" align="start" wrap>
   <col-ui gap="2">
-    <text-ui variant="caption" color="muted">verse</text-ui>
-    <div verse>
+    <text-ui variant="caption" color="muted">scale="ui-sm"</text-ui>
+    <div scale="ui-sm">
       <check-ui label="Notify me" checked></check-ui>
     </div>
   </col-ui>
@@ -23,8 +23,8 @@
     </div>
   </col-ui>
   <col-ui gap="2">
-    <text-ui variant="caption" color="muted">prose</text-ui>
-    <div prose>
+    <text-ui variant="caption" color="muted">scale="content-md"</text-ui>
+    <div scale="content-md">
       <check-ui label="Notify me" checked></check-ui>
     </div>
   </col-ui>

package/components/check/check.yaml

@@ -48,6 +48,17 @@ props:
     required: true
     type: string
     default: ""
+  labelHidden:
+    description: >-
+      When true, [label] still sets the accessible name (aria-label) but
+      the visible text is suppressed via the canonical sr-only technique
+      (gh#1010). Use when a sibling element already shows the same name
+      visually (e.g. a title next to a check-ui used as a list-item icon)
+      and the plain-visible label would paint it twice.
+    type: boolean
+    default: false
+    reflect: true
+    attribute: label-hidden
   value:
     description: Form value (submitted as 'on' when checked)
     type: string
@@ -68,23 +79,31 @@ states:
     attribute: disabled
 traits: []
 tokens:
-  --check-box-background:
+  --check-bg:
     description: Unchecked background
-  --check-box-border-color:
+  --check-border:
     description: Unchecked border color
-  --check-box-radius:
+  --check-radius:
     description: Checkbox border radius
-  --check-box-size:
+  --check-size:
     description: Checkbox indicator size
-  --check-checked-background:
+  --check-bg-checked:
     description: Checked/indeterminate background
-  --check-checked-border-color:
+  --check-border-checked:
     description: Checked/indeterminate border
-  --check-checked-foreground:
+  --check-fg-checked:
     description: Checkmark/dash color
+  --check-border-hover:
+    description: Unchecked border color on hover
+  --check-bg-hover:
+    description: Unchecked background on hover
+  --check-bg-checked-hover:
+    description: Checked/indeterminate background on hover
 a2ui:
   rules:
     - "Self-labeling widget — use the [label] attribute directly; do NOT wrap in <field-ui>. The widget renders its own label inline via CSS attr() pattern. Wrapping breaks the consent-row layout (see field-ui anti_patterns)."
+    - rule: 'When check-ui is used as a list-item icon/indicator beside a separate title element carrying the same name (a title column, a list-item-ui slot="text"), set [label-hidden] alongside [label] so the accessible name is preserved without painting the name twice.'
+      reason: 'gh#1010 — the visible ::after label and an adjacent title both showed the step name, and the visible labels varied width, producing a ragged title column.'
     - rule: 'Three states supported: unchecked (default), checked (via [checked]), and indeterminate (via [indeterminate]); form-associated.'
       reason: 'Per ADR-0025 — host IS the control, no wrapped <input>.'
     - rule: 'For binary on/off toggles where visual switch metaphor matters, use <switch-ui> instead; check-ui is for multi-select sets and form-acceptance gates.'

package/components/combobox/combobox.a2ui.json

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

package/components/combobox/combobox.yaml

@@ -85,6 +85,9 @@ props:
       or grouped {label, options:[…]}. Alternative to declarative
       <option> / <optgroup> children.
     type: array
+    # Rich option objects — same DynamicObjectList mapping fix as command-ui.
+    items:
+      type: object
     default: []
     dynamic: true  # JS-set collection prop with a custom setter — deliberately not in static properties
   open:

package/components/command/command.a2ui.json

@@ -21,6 +21,10 @@
       "type": "boolean",
       "default": false
     },
+    "options": {
+      "description": "Programmatic item list. Array of {value, label, icon?, shortcut?, disabled?} or grouped {label, options:[…]}. `icon` renders as a leading icon-ui, `shortcut` as a trailing keyboard-shortcut hint — the same fields as the data-icon/data-shortcut attributes on declarative <option> children. Alternative to declarative <option data-icon data-shortcut> / <optgroup label> children.",
+      "$ref": "common_types.json#/$defs/DynamicObjectList"
+    },
     "placeholder": {
       "description": "Placeholder text for the search input",
       "type": "string",

package/components/command/command.class.js

@@ -85,10 +85,15 @@ export class UICommand extends UIElement {
   render() {
     // Stamp internal structure once
     if (!this.#inputEl) {
-      // Parse options + capture author-provided slot="empty" content
-      // before replacing innerHTML (dogfood-status yaml-drift finding:
-      // yaml documented an overridable empty state that was never wired).
-      this.#parseOptions();
+      // Parse declarative <option>/<optgroup> children once, unless
+      // `.options` was already set programmatically before first render
+      // (mirrors combobox-ui's connected()-time guard) + capture
+      // author-provided slot="empty" content before replacing innerHTML
+      // (dogfood-status yaml-drift finding: yaml documented an overridable
+      // empty state that was never wired).
+      if (this.#items.length === 0) {
+        this.#parseOptions();
+      }
       this.#emptyNodes = logicalSlotted(this, 'empty');
 
       this.innerHTML = `
@@ -143,6 +148,51 @@ export class UICommand extends UIElement {
     this.#renderItems();
   }
 
+  // ── Programmatic options (gh#887) ──
+  //
+  // Public API mirroring combobox-ui's `options` prop: an array of flat
+  // {value, label, icon?, shortcut?, disabled?} entries, or grouped
+  // {label, options:[…]} entries — same field names as the data-icon/
+  // data-shortcut attributes on declarative <option> children. Normalized
+  // into the internal #items shape #renderItems() already consumes (flat
+  // items carry `category`; groups carry `.items` not `.options`), so
+  // programmatic and declarative authoring render identically.
+
+  set options(list) {
+    this.#items = this.#normalizeOptions(Array.isArray(list) ? list : []);
+    // Only re-render if the internal list has already been stamped —
+    // otherwise the pending #items feed the first render() pass directly.
+    if (this.#listEl) this.#renderItems(this.#inputEl?.value || '');
+  }
+
+  get options() { return this.#items; }
+
+  #normalizeOptions(list) {
+    const out = [];
+    for (const entry of list) {
+      if (entry && Array.isArray(entry.options)) {
+        const label = entry.label || '';
+        out.push({ label, items: entry.options.map((opt) => this.#optionObjectToItem(opt, label)) });
+      } else if (entry) {
+        out.push(this.#optionObjectToItem(entry, ''));
+      }
+    }
+    return out;
+  }
+
+  /** Plain-object counterpart of #optionToItem (which reads a DOM <option>). */
+  #optionObjectToItem(opt, category = '') {
+    return {
+      value: opt.value,
+      label: opt.label ?? opt.value,
+      icon: opt.icon || '',
+      shortcut: opt.shortcut || '',
+      keywords: opt.keywords || '',
+      disabled: !!opt.disabled,
+      category,
+    };
+  }
+
   // ── Parse declarative <option>/<optgroup> ──
 
   // Wrapper-piercing walk for consumer-authored <option>/<optgroup> children.

package/components/command/command.d.ts

@@ -35,6 +35,8 @@ export type CommandSelectEvent = CustomEvent<CommandSelectEventDetail>;
 export class UICommand extends UIElement {
   /** Whether the command palette is visible */
   open: boolean;
+  /** Programmatic item list. Array of {value, label, icon?, shortcut?, disabled?} or grouped {label, options:[…]}. `icon` renders as a leading icon-ui, `shortcut` as a trailing keyboard-shortcut hint — the same fields as the data-icon/data-shortcut attributes on declarative <option> children. Alternative to declarative <option data-icon data-shortcut> / <optgroup label> children. */
+  options: string;
   /** Placeholder text for the search input */
   placeholder: string;
 

package/components/command/command.yaml

@@ -24,6 +24,24 @@ props:
     description: Placeholder text for the search input
     type: string
     default: Type a command...
+  options:
+    description: >-
+      Programmatic item list. Array of {value, label, icon?, shortcut?,
+      disabled?} or grouped {label, options:[…]}. `icon` renders as a
+      leading icon-ui, `shortcut` as a trailing keyboard-shortcut hint —
+      the same fields as the data-icon/data-shortcut attributes on
+      declarative <option> children. Alternative to declarative
+      <option data-icon data-shortcut> / <optgroup label> children.
+    type: array
+    # Rich option OBJECTS ({value, label, icon?, …} / grouped) — declares
+    # items.type so the a2ui catalog maps to DynamicObjectList, not the
+    # string-list default (components.mjs TKT-0010 mapping). Without this
+    # the dialect validator rejected every harvested rich-options palette
+    # (exit-gate.corpus caught it at release pre-flight).
+    items:
+      type: object
+    default: []
+    dynamic: true  # JS-set collection prop with a custom setter — mirrors combobox-ui's `options`
 events:
   dismiss:
     description: Fired when Escape is pressed
@@ -69,9 +87,13 @@ a2ui:
       shortcut. Do NOT hand-roll a <dialog> + Cmd+K key listener.
     - >-
       Author items as native <option value data-icon data-shortcut>
-      elements inside <optgroup label="…"> for grouped sections. The
-      `select` event's detail.category mirrors the parent optgroup's
-      label. Detail = { value, label, category }.
+      elements inside <optgroup label="…"> for grouped sections, OR set
+      `.options` programmatically as an array of
+      `{value, label, icon?, shortcut?, disabled?}` (grouped form:
+      `{label, options:[…]}`) — same fields, alternative to declarative
+      children. The `select` event's detail.category mirrors the parent
+      optgroup's label (or the group's `label` when authored via
+      `options`). Detail = { value, label, category }.
     - >-
       Decision rule vs adjacent surfaces. Use <menu-ui> for small
       NON-searchable popover menus (≤10 actions, triggered by a

package/components/date-range-picker/date-range-picker.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/DateRangePicker.json",
   "title": "DateRangePicker",
-  "description": "Compound form primitive for selecting a start + end date pair with optional named preset shortcuts (\"Today\", \"Last 7 days\", \"This month\", ...). Default presentation is a trigger button showing the formatted range; on activation a popover opens with two synchronized calendar panes + a preset side rail. Composes <calendar-picker-ui> twice; emits {from, to} ISO 8601 dates. Optional comparison-range mode emits a secondary range for analytics surfaces.",
+  "description": "Compound form primitive for selecting a start + end date pair with optional named preset shortcuts (\"Today\", \"Last 7 days\", \"This month\", ...). Default presentation is a trigger button showing the formatted range; on activation a popover opens with two synchronized calendar panes + a preset side rail. Composes <calendar-grid-ui> twice; emits {from, to} ISO 8601 dates. Both panes are ONE selection surface: first click = start, second click = end, in either grid; a second click earlier than the start restarts the range there. Optional comparison-range mode emits a secondary range for analytics surfaces.",
   "type": "object",
   "allOf": [
     {