@adia-ai/web-components 0.8.33 → 0.8.34

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog — @adia-ai/web-components
 
+## [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-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

@@ -22,7 +22,9 @@
     --badge-px:        var(--a-space-1-5);
     --badge-py:        var(--a-space-0-5);
     --badge-gap:       var(--a-space-1);
-    --badge-font-size: var(--a-ui-sm);
+    /* 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
@@ -45,8 +47,8 @@
     --badge-px-lg:  var(--a-space-2);
     --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-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 */
 }
 
@@ -241,7 +243,7 @@
   :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-font-size: var(--a-ui-xs);
   }
   :scope[size="lg"] {
     --badge-px:        var(--badge-px-lg);

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/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": [
     {

package/components/date-range-picker/date-range-picker.class.js

@@ -15,9 +15,12 @@
  * <date-range-picker-ui>
  *
  * Compound form primitive for selecting a start + end date pair with
- * optional preset shortcuts. Composes <calendar-picker-ui> (two
- * instances — start + end pane) + <popover-ui> + <button-ui> for the
- * trigger and preset rail.
+ * optional preset shortcuts. Composes <calendar-grid-ui> (two panes
+ * showing adjacent months) + <popover-ui> + <button-ui> for the
+ * trigger and preset rail. Selection is click-start-then-click-end
+ * across BOTH panes as one surface (gh#948) — the panes differ only
+ * in which month they display, never in which half of the range a
+ * click writes.
  *
  * Form participation:
  *   ElementInternals serializes the selected range as JSON:
@@ -345,8 +348,8 @@ export class UIDateRangePicker extends UIFormElement {
       this.#triggerRef.addEventListener('keydown', this.#onTriggerKey, true);
       this.#popoverRef.addEventListener('click', this.#onPopoverClick);
       this.#popoverRef.addEventListener('keydown', this.#onPopoverKey);
-      this.#calFromRef.addEventListener('change', this.#onCalFromChange);
-      this.#calToRef.addEventListener('change', this.#onCalToChange);
+      this.#calFromRef.addEventListener('change', this.#onDaySelect);
+      this.#calToRef.addEventListener('change', this.#onDaySelect);
     }
     // Wire form value on first connect.
     this.syncValue();
@@ -364,8 +367,8 @@ export class UIDateRangePicker extends UIFormElement {
       this.#popoverRef.removeEventListener('keydown', this.#onPopoverKey);
       this.#popoverRef.hidePopover?.();
     }
-    if (this.#calFromRef) this.#calFromRef.removeEventListener('change', this.#onCalFromChange);
-    if (this.#calToRef) this.#calToRef.removeEventListener('change', this.#onCalToChange);
+    if (this.#calFromRef) this.#calFromRef.removeEventListener('change', this.#onDaySelect);
+    if (this.#calToRef) this.#calToRef.removeEventListener('change', this.#onDaySelect);
     document.removeEventListener('pointerdown', this.#onOutside);
     document.removeEventListener('keydown', this.#onDocKey);
     this.#anchorCleanup?.();
@@ -449,14 +452,16 @@ export class UIDateRangePicker extends UIFormElement {
     // Cascade min/max + selection state into the calendar panes.
     const range = parseRange(this.value);
     const pending = this.#pending;
-    // Effective endpoints — pending (mid-click) takes precedence over
-    // value. Push the SAME from/to onto BOTH grids so each independently
-    // lights up its in-range cells via `[data-in-range]`. Without this,
-    // only the two endpoint cells got `[data-selected]` and the days
-    // between them rendered as plain background — the "fill the cells
-    // between start and end dates" trap.
-    const effFrom = pending?.from || range?.from || '';
-    const effTo   = pending?.to   || range?.to   || '';
+    // Effective endpoints — an in-flight pending selection REPLACES the
+    // committed value wholesale (no per-half fallback: mixing the new
+    // start with the old committed end would light a range the user
+    // never picked, gh#948). Push the SAME from/to onto BOTH grids so
+    // each independently lights up its in-range cells via
+    // `[data-in-range]`. Without this, only the two endpoint cells got
+    // `[data-selected]` and the days between them rendered as plain
+    // background — the "fill the cells between start and end dates" trap.
+    const effFrom = pending ? pending.from : (range?.from || '');
+    const effTo   = pending ? pending.to   : (range?.to   || '');
     const setRangeAttrs = (cal) => {
       if (effFrom) cal.setAttribute('range-start', effFrom);
       else cal.removeAttribute('range-start');
@@ -466,13 +471,13 @@ export class UIDateRangePicker extends UIFormElement {
     if (this.#calFromRef) {
       if (this.min) this.#calFromRef.setAttribute('min', this.min);
       if (this.max) this.#calFromRef.setAttribute('max', this.max);
-      this.#calFromRef.value = pending?.from || range?.from || '';
+      this.#calFromRef.value = effFrom;
       setRangeAttrs(this.#calFromRef);
     }
     if (this.#calToRef) {
       if (this.min) this.#calToRef.setAttribute('min', this.min);
       if (this.max) this.#calToRef.setAttribute('max', this.max);
-      this.#calToRef.value = pending?.to || range?.to || '';
+      this.#calToRef.value = effTo;
       setRangeAttrs(this.#calToRef);
     }
 
@@ -680,37 +685,31 @@ export class UIDateRangePicker extends UIFormElement {
     }
   };
 
-  #onCalFromChange = (e) => {
+  // Unified day selection across BOTH grids — first click = start,
+  // second click = end, whichever pane the click lands in (gh#948).
+  // The panes' [data-cal-from]/[data-cal-to] roles are display-only
+  // (left month / next month); they no longer lock which half of the
+  // range a click writes. A second click EARLIER than the pending start
+  // restarts the selection at that day (the industry-standard dual-pane
+  // model) instead of emitting a reversed-range `invalid`. A click
+  // while a range is already committed starts a fresh selection.
+  #onDaySelect = (e) => {
     if (this.readonly) return;
     e.stopPropagation();
-    const iso = e.detail?.value || this.#calFromRef?.value || '';
+    const iso = e.detail?.value || '';
     if (!iso) return;
-    const existing = parseRange(this.value);
-    if (!this.#pending) this.#pending = { from: '', to: '' };
-    this.#pending.from = iso;
-    // Live emit `input` for pending state.
-    this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: { from: iso, to: null } } }));
-    // Attempt commit when both halves are set (in either order). The
-    // commit path handles reversed-range invalidation.
-    const toCandidate = this.#pending.to || existing?.to || null;
-    if (toCandidate) {
-      this.#commitRange({ from: iso, to: toCandidate });
+    const startFresh =
+      !this.#pending?.from ||           // nothing pending (incl. committed-value state)
+      this.#pending.to ||               // previous selection fully picked
+      iso < this.#pending.from;         // earlier than pending start → restart there
+    if (startFresh) {
+      this.#pending = { from: iso, to: '' };
+      this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: { from: iso, to: null } } }));
+      return;
     }
-  };
-
-  #onCalToChange = (e) => {
-    if (this.readonly) return;
-    e.stopPropagation();
-    const iso = e.detail?.value || this.#calToRef?.value || '';
-    if (!iso) return;
-    const existing = parseRange(this.value);
-    if (!this.#pending) this.#pending = { from: '', to: '' };
     this.#pending.to = iso;
-    this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: { from: this.#pending.from || existing?.from || null, to: iso } } }));
-    const fromCandidate = this.#pending.from || existing?.from || null;
-    if (fromCandidate) {
-      this.#commitRange({ from: fromCandidate, to: iso });
-    }
+    this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: { from: this.#pending.from, to: iso } } }));
+    this.#commitRange({ from: this.#pending.from, to: iso });
   };
 
   #onOutside = (e) => {

package/components/date-range-picker/date-range-picker.css

@@ -158,6 +158,17 @@ date-range-picker-ui [slot="popover"] {
   /* Opt into a wider anchor.js max-width cap so both month panes fit side-by-side
      (the 32rem default clipped the second month). Viewport safety still applies. */
   --popover-max-width: var(--date-range-picker-popover-max-width);
+  /* Content sizing lives in the STYLESHEET, not only in anchor.js inline
+     styles (gh#948): only the native-anchor path applies width/max-width
+     hints inline — the JS fallback (Safari/Firefox) and any placement
+     where anchoring fails otherwise leave the popover's size to whatever
+     the surrounding cascade produces, which is how the viewport-huge
+     mostly-empty panel renders. These caps make the popover content-sized
+     in every path; anchor.js inline styles still win where they apply. */
+  width: max-content;
+  max-width: min(calc(100vw - 1rem), var(--date-range-picker-popover-max-width));
+  max-height: calc(100vh - 2rem);
+  overflow: auto;
   padding: var(--date-range-picker-py) var(--date-range-picker-px);
   border: 1px solid var(--date-range-picker-popover-border);
   border-radius: var(--date-range-picker-popover-radius);

package/components/date-range-picker/date-range-picker.yaml

@@ -10,9 +10,12 @@ description: >-
   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.
+  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.
 # Per ADR-0027 — primitives that programmatically create other primitives
 # do NOT auto-import them. Consumer (or demo shell) must explicitly import.
 composes:

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

@@ -6,10 +6,21 @@
     --description-list-term-min-width: 8rem;
 
     /* ── Typography ── */
-    --description-list-term-font-size: var(--a-ui-sm);
-    --description-list-term-weight:    var(--a-weight-medium);
-    --description-list-desc-font-size: var(--a-ui-sm);
-    --description-list-desc-weight:    var(--a-weight-normal);
+    /* Term reads as a kicker/data-label (operator ruling 2026-08-11,
+       matching the docs site's [data-label] convention): code family at
+       label size, normal weight — a quiet technical eyebrow the medium-
+       weight desc answers. */
+    --description-list-term-font-family: var(--a-font-family-code);
+    --description-list-term-font-size: var(--a-label-size);
+    --description-list-term-weight:    var(--a-weight-normal);
+    /* 1em, not a fixed step — the desc inherits the surrounding body/
+       context size (operator ruling 2026-08-11), so a dl inside prose
+       matches the prose and inside a compact card matches the card. */
+    --description-list-desc-font-size: 1em;
+    /* Semibold — the desc (value) carries the pair's content and reads
+       clearly bolder than the muted normal-weight kicker term (operator
+       rulings 2026-08-11: first normal → medium, then medium → semibold). */
+    --description-list-desc-weight:    var(--a-weight-semibold);
 
     /* ── Colors ── */
     --description-list-term-fg:        var(--a-fg-muted);
@@ -29,6 +40,7 @@
   [data-dl-term],
   dt {
     margin: 0;
+    font-family: var(--description-list-term-font-family);
     font-size: var(--description-list-term-font-size);
     font-weight: var(--description-list-term-weight);
     color: var(--description-list-term-fg);

package/components/modal/modal.class.js

@@ -51,6 +51,12 @@ export class UIModal extends UIElement {
   #closeTimer = null;
   #dialogRef = null;
 
+  // Monotonic, instance-agnostic counter for the fallback aria-labelledby
+  // id stamped onto an author's [slot="heading"] (see render()) — multiple
+  // <modal-ui> instances on one page must not collide on the same id.
+  // (Extracted from PR #944 — gh#947.)
+  static #headingIdSeq = 0;
+
   // Phosphor icons this primitive auto-stamps (without consumer markup).
   // Aggregated by installIconLoadersForRegistered() across all defined
   // elements. Audited by check-required-icons.mjs.
@@ -150,8 +156,25 @@ export class UIModal extends UIElement {
     const panel = this.ensure('panel');
     if (panel.parentElement !== dialog) dialog.appendChild(panel);
 
-    const header = this.ensure('header');
-    if (header.parentElement !== panel) panel.prepend(header);
+    // Header — accept an authored bare <header> or [slot="header"] child
+    // (card-ui style), mirroring the footer contract below. Without this
+    // branch an authored <header> fell through to the loose-children
+    // migration and rendered inside the BODY, displacing icon/heading to
+    // the bottom of the modal (gh#941).
+    const userHeader = [...this.children].find(c =>
+      c.getAttribute('slot') === 'header' || (!c.getAttribute('slot') && c.localName === 'header')
+    );
+    let header;
+    if (userHeader) {
+      if (userHeader.getAttribute('slot') !== 'header') userHeader.setAttribute('slot', 'header');
+      if (userHeader.parentElement !== panel) panel.prepend(userHeader);
+      panel.querySelector(':scope > [slot="header"][data-stamped]')?.remove();
+      header = userHeader;
+    } else {
+      header = this.ensure('header');
+      header.setAttribute('data-stamped', '');
+      if (header.parentElement !== panel) panel.prepend(header);
+    }
     // Only set `text=` when actually present — the CSS rule
     // `:scope [slot="header"][text]:not([text=""])::before { content: attr(text); flex: 1 }`
     // generates a flex:1 pseudo-element. Setting `text=""` unconditionally
@@ -165,6 +188,24 @@ export class UIModal extends UIElement {
       header.removeAttribute('text');
     }
 
+    // Accessible name — [text] stamps aria-label (host + dialog), the
+    // long-standing contract above. Absent that, fall back to the author's
+    // [slot="heading"] via aria-labelledby so a heading-only modal (e.g.
+    // destructive-confirm-modal, gh#941) still satisfies the WAI-ARIA APG
+    // dialog-modal pattern's accessible-name requirement. Re-evaluated
+    // every render so a later `text=` set, or the heading being removed,
+    // clears the reference instead of leaving it stale. (gh#947, from
+    // PR #944.)
+    const authoredHeading = header.querySelector(':scope > [slot="heading"]');
+    if (!this.text && authoredHeading) {
+      if (!authoredHeading.id) authoredHeading.id = `modal-heading-${++UIModal.#headingIdSeq}`;
+      if (dialog.getAttribute('aria-labelledby') !== authoredHeading.id) {
+        dialog.setAttribute('aria-labelledby', authoredHeading.id);
+      }
+    } else {
+      dialog.removeAttribute('aria-labelledby');
+    }
+
     if (!this.permanent) {
       const close = this.ensure('close');
       if (close.parentElement !== header) header.appendChild(close);

package/components/modal/modal.css

@@ -131,6 +131,29 @@
     flex: 1;
   }
 
+  /* ═══════ Header icon + heading pair (drawer-ui/card-ui parity) ═══════
+     Author-supplied icon/heading content nested inside <header> — an
+     alternative to [text]. Positioned by tag + DOM order, not by reading
+     [slot="icon"]/[slot="heading"] (AGENTS.md: "slot= attributes are
+     decorative metadata; positioning is CSS by tag + ancestor + DOM
+     order") — `button-ui` identifies the stamped auto-close affordance by
+     TAG, and render() guarantees it's the header's trailing child when
+     present. The header's last non-button child claims the row's free
+     space (heading position); any earlier content child (a leading
+     icon/avatar) stays fixed-width. (gh#947, from PR #944.) */
+  :scope [slot="header"] > :not(button-ui):has(~ :not(button-ui)) {
+    display: flex;
+    align-items: center;
+    flex-shrink: 0;
+  }
+  :scope [slot="header"] > :not(button-ui):not(:has(~ :not(button-ui))) {
+    display: flex;
+    align-items: center;
+    gap: var(--a-space-2);
+    flex: 1;
+    min-width: 0;
+  }
+
   /* ═══════ Close button (button-ui) ═══════ */
   :scope [slot="close"] {
     flex-shrink: 0;