@adia-ai/web-components 0.8.31 → 0.8.32

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

@@ -75,14 +75,14 @@ document locale. `h12` forces a 12-hour cycle with an AM/PM
   /** Current value as ISO 8601 datetime ("YYYY-MM-DDTHH:mm" or "YYYY-MM-DDTHH:mm:ss"). Empty when no value selected. */
   value: string;
 
-  addEventListener<K extends keyof HTMLElementEventMap>(
-    type: K,
-    listener: (this: UIDatetimePicker, ev: HTMLElementEventMap[K]) => unknown,
-    options?: boolean | AddEventListenerOptions,
-  ): void;
   addEventListener(type: 'change', listener: (ev: DatetimePickerChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'close', listener: (ev: DatetimePickerCloseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'input', listener: (ev: DatetimePickerInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'invalid', listener: (ev: DatetimePickerInvalidEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'open', listener: (ev: DatetimePickerOpenEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIDatetimePicker, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
 }

package/components/demo-toggle/demo-toggle.d.ts

@@ -29,10 +29,10 @@ export class UIDemoToggle extends UIElement {
   /** Current toggle state ("on" | "off"). Reflected as data-state on the host. */
   state: '' | 'on' | 'off';
 
+  addEventListener(type: 'change', listener: (ev: DemoToggleChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UIDemoToggle, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'change', listener: (ev: DemoToggleChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/drawer/drawer.d.ts

@@ -32,11 +32,11 @@ export class UIDrawer extends UIElement {
   /** Title text displayed in the drawer header */
   text: string;
 
+  addEventListener(type: 'close', listener: (ev: DrawerCloseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'opened', listener: (ev: DrawerOpenedEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UIDrawer, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'close', listener: (ev: DrawerCloseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'opened', listener: (ev: DrawerOpenedEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/heatmap/heatmap.d.ts

@@ -36,14 +36,14 @@ export class UIHeatmap extends UIElement {
   /** ISO start date; labels months in day-grid mode */
   startDate: string;
 
-  addEventListener<K extends keyof HTMLElementEventMap>(
-    type: K,
-    listener: (this: UIHeatmap, ev: HTMLElementEventMap[K]) => unknown,
-    options?: boolean | AddEventListenerOptions,
-  ): void;
   addEventListener(type: 'cell-click', listener: (ev: HeatmapCellClickEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'cell-hover', listener: (ev: HeatmapCellHoverEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'chart-hover', listener: (ev: HeatmapChartHoverEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'chart-leave', listener: (ev: HeatmapChartLeaveEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'chart-select', listener: (ev: HeatmapChartSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIHeatmap, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
 }

package/components/index.js

@@ -24,6 +24,7 @@ export { UIInput } from './input/input.js';
 export { UITextarea } from './textarea/textarea.js';
 export { UICheck } from './check/check.js';
 export { UIRadio } from './radio/radio.js';
+export { UIRadioGroup } from './radio-group/radio-group.js';
 export { UIOptionCard } from './option-card/option-card.js';
 export { UIIntegrationCard } from './integration-card/integration-card.js';
 export { UISwitch } from './switch/switch.js';

package/components/inline-edit/inline-edit.d.ts

@@ -40,13 +40,13 @@ by consumers. Listen to `edit-start` / `edit-end` events instead.
   /** Hint text shown when the value is empty (inline-edit reads this in the static state). */
   placeholder: string;
 
+  addEventListener(type: 'cancel', listener: (ev: InlineEditCancelEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'change', listener: (ev: InlineEditChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'edit-end', listener: (ev: InlineEditEditEndEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'edit-start', listener: (ev: InlineEditEditStartEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UIInlineEdit, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'cancel', listener: (ev: InlineEditCancelEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'change', listener: (ev: InlineEditChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'edit-end', listener: (ev: InlineEditEditEndEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'edit-start', listener: (ev: InlineEditEditStartEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/input/input.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Input.json",
   "title": "Input",
-  "description": "Text input field with contenteditable surface. Supports prefix/suffix icons, label, form participation, and a `type=\"number\"` mode that renders [+]/[-] stepper buttons, numeric input filtering, and ARIA spinbutton semantics — no native `<input type=\"number\">` under the hood. Password type uses a native `<input>` (only path that still wraps native, for `-webkit-text-security` disc masking).",
+  "description": "Text input field with contenteditable surface. Supports prefix/suffix icons, label, form participation, and a `type=\"number\"` mode that renders [+]/[-] stepper buttons, numeric input filtering, and ARIA spinbutton semantics — no native `<input type=\"number\">` under the hood. Password type uses a native `<input>` (only path that still wraps native, for `-webkit-text-security` disc masking). Has a 20ch minimum width (`--input-min-width`, mirrors the native `<input>` baseline) so a bare, placeholder-only instance stays usable inside a flex row (row-ui) with no explicit sizing — explicit `width`/`flex` or CSS can size the host above the floor; values below the floor remain clamped unless `--input-min-width` is lowered.",
   "type": "object",
   "allOf": [
     {
@@ -319,6 +319,9 @@
       "--input-line-height": {
         "description": "Override line height"
       },
+      "--input-min-width": {
+        "description": "Override the minimum-width floor (20ch, mirrors the native `<input>` baseline). Keeps an empty, placeholder-only instance legible when placed directly in a flex row (row-ui) with no explicit width/flex sizing — the placeholder renders via an out-of-flow ::before that contributes no intrinsic width of its own, so without this floor the host collapses to near-zero as a flex item. Explicit sizing (width/flex) can grow the host above the floor but does not bypass it — set to 0 or another lower value to permit a narrower explicit size."
+      },
       "--input-padding": {
         "description": "Override base padding (density-scaled)"
       },

package/components/input/input.css

@@ -32,6 +32,11 @@ input-ui:not([disabled]) [slot="field"]:hover [slot="suffix"] {
     --input-affix-fg:        var(--a-ui-text-placeholder);
     --input-field-gap:       var(--a-space-1);
     --input-label-min-width: 8ch;
+    /* Native-<input> baseline (historically ~20 characters). Floors the
+       host so an empty, placeholder-only instance stays legible as a
+       flex item — see the :scope min-width rule below for the collapse
+       mechanism this guards against. */
+    --input-min-width:       20ch;
 
     /* ── Transitions ── */
     --input-duration:        var(--a-duration-fast);
@@ -53,6 +58,19 @@ input-ui:not([disabled]) [slot="field"]:hover [slot="suffix"] {
     /* ── Base ── */
     box-sizing: border-box;
     display: block;
+    /* `display: block` gives no width once this host becomes a flex item
+       (row-ui, or any display:flex parent) — flex items size from
+       content/flex-basis, not display type. The one child that could
+       drive content-based sizing, [slot="text"], is EMPTY when the
+       input has no value; its placeholder renders via an out-of-flow
+       ::before (deliberately, for caret positioning — see the pseudo
+       below) that contributes zero intrinsic width. Without a floor,
+       an empty placeholder-only input-ui collapses to near-zero in any
+       flex context that doesn't otherwise force a width (gh#781).
+       min-width, not width, so explicit width/flex can size the host
+       above the floor; values below the floor remain clamped. Override
+       via --input-min-width (e.g. 0 to opt back out) or size explicitly. */
+    min-width: var(--input-min-width);
   }
 
   /* Inline label — sits inside [slot="field"] as a leading caption,

package/components/input/input.yaml

@@ -8,7 +8,9 @@ version: 1
 description: Text input field with contenteditable surface. Supports prefix/suffix icons, label, form participation, and a
   `type="number"` mode that renders [+]/[-] stepper buttons, numeric input filtering, and ARIA spinbutton semantics — no native
   `<input type="number">` under the hood. Password type uses a native `<input>` (only path that still wraps native, for `-webkit-text-security`
-  disc masking).
+  disc masking). Has a 20ch minimum width (`--input-min-width`, mirrors the native `<input>` baseline) so a bare,
+  placeholder-only instance stays usable inside a flex row (row-ui) with no explicit sizing — explicit `width`/`flex`
+  or CSS can size the host above the floor; values below the floor remain clamped unless `--input-min-width` is lowered.
 # Per ADR-0027 — primitives that programmatically create other primitives
 # do NOT auto-import them. Consumer (or demo shell) must explicitly import.
 composes:
@@ -230,6 +232,14 @@ tokens:
     description: Override hover state border color
   --input-line-height:
     description: Override line height
+  --input-min-width:
+    description: Override the minimum-width floor (20ch, mirrors the native `<input>`
+      baseline). Keeps an empty, placeholder-only instance legible when placed directly
+      in a flex row (row-ui) with no explicit width/flex sizing — the placeholder renders
+      via an out-of-flow ::before that contributes no intrinsic width of its own, so
+      without this floor the host collapses to near-zero as a flex item. Explicit sizing
+      (width/flex) can grow the host above the floor but does not bypass it — set to 0
+      or another lower value to permit a narrower explicit size.
   --input-padding:
     description: Override base padding (density-scaled)
   --input-placeholder-color:

package/components/integration-card/integration-card.d.ts

@@ -51,13 +51,13 @@ export class UIIntegrationCard extends UIElement {
   /** Current connection state — drives the button label, variant, and visibility. `available` shows a primary `Connect`; `connected` shows an outline `Configure`; `error` shows an outline `Retry`; `pending` shows a non-interactive spinner; `coming-soon` hides the button. */
   status: string;
 
+  addEventListener(type: 'configure', listener: (ev: IntegrationCardConfigureEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'connect', listener: (ev: IntegrationCardConnectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'disconnect', listener: (ev: IntegrationCardDisconnectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'retry', listener: (ev: IntegrationCardRetryEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UIIntegrationCard, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'configure', listener: (ev: IntegrationCardConfigureEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'connect', listener: (ev: IntegrationCardConnectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'disconnect', listener: (ev: IntegrationCardDisconnectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'retry', listener: (ev: IntegrationCardRetryEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/link/link.d.ts

@@ -63,10 +63,10 @@ export class UILink extends UIElement {
   /** Visual treatment. `default` underlines on rest + hover (standard link affordance). `subtle` underlines only on hover (for tighter designs where always-underlined would be noisy). `quiet` drops the link color and matches surrounding text color (used for footer-link rows where the link affordance is implied by context, not by color). */
   variant: 'default' | 'subtle' | 'quiet';
 
+  addEventListener(type: 'press', listener: (ev: LinkPressEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UILink, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'press', listener: (ev: LinkPressEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/list/list.class.js

@@ -45,9 +45,12 @@ export class UIList extends UIElement {
   static template = () => null;
 
   #bound = false;
+  #stampedSelection = false;
 
   connected() {
-    this.setAttribute('role', 'list');
+    // Adopt-or-stamp (gh#753): a consumer-authored role survives connect —
+    // only stamp when absent.
+    if (!this.hasAttribute('role')) this.setAttribute('role', 'list');
     if (!this.#bound) {
       this.#bound = true;
       this.addEventListener('click', this.#onClick);
@@ -63,13 +66,21 @@ export class UIList extends UIElement {
 
   render() {
     if (!this.selectable) {
-      // Clear selection chrome from children
-      for (const ch of this.#items()) {
-        ch.removeAttribute('aria-selected');
-        ch.removeAttribute('tabindex');
+      // Clear selection chrome from children — but ONLY chrome this list
+      // stamped (selectable toggled off). An unconditional strip clobbered
+      // consumer-managed focusability: a non-selectable list re-render
+      // silently removed tabindex the consumer set on its own rows
+      // (patient-visit rail's roving tabindex, gh#746).
+      if (this.#stampedSelection) {
+        for (const ch of this.#items()) {
+          ch.removeAttribute('aria-selected');
+          ch.removeAttribute('tabindex');
+        }
+        this.#stampedSelection = false;
       }
       return;
     }
+    this.#stampedSelection = true;
     const key = this.selectedKey || '';
     const items = this.#items();
     let focusTarget = null;
@@ -121,7 +132,8 @@ export class UIList extends UIElement {
 
   #onClick = (e) => {
     if (!this.selectable) return;
-    const item = e.target.closest?.('[role="listitem"]');
+    // tag-or-role: adopt-or-stamp (gh#753) means a consumer role must not break click-select
+    const item = e.target.closest?.('list-item-ui, [role="listitem"]');
     if (!item || item.parentElement !== this) return;
     const key = this.#keyOf(item);
     if (key) this.#selectKey(key);
@@ -166,7 +178,10 @@ export class UIListItem extends UIElement {
   static template = () => null;
 
   connected() {
-    this.setAttribute('role', 'listitem');
+    // Adopt-or-stamp (gh#753): a consumer-authored role (e.g. role="button"
+    // on a clickable row) survives connect AND reconnect — only stamp
+    // "listitem" when the host has no author-set role at all.
+    if (!this.hasAttribute('role')) this.setAttribute('role', 'listitem');
     this.#stamp();
   }
 

package/components/list/list.d.ts

@@ -46,12 +46,12 @@ so content sits at the list-ui edges (canonical edge-to-edge style).
   /** Item spacing */
   spacing: string;
 
+  addEventListener(type: 'selection-change', listener: (ev: ListSelectionChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UIList, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'selection-change', listener: (ev: ListSelectionChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }
 
 export class UIListItem extends UIElement {

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

@@ -71,14 +71,14 @@ export class UIListWindow extends UIElement {
   /** Index to scroll to on mount. Useful for restoring scroll position on remount. */
   startIndex: number;
 
-  addEventListener<K extends keyof HTMLElementEventMap>(
-    type: K,
-    listener: (this: UIListWindow, ev: HTMLElementEventMap[K]) => unknown,
-    options?: boolean | AddEventListenerOptions,
-  ): void;
   addEventListener(type: 'item-click', listener: (ev: ListWindowItemClickEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'measure', listener: (ev: ListWindowMeasureEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'range-change', listener: (ev: ListWindowRangeChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'scroll-end', listener: (ev: ListWindowScrollEndEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'scroll-start', listener: (ev: ListWindowScrollStartEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIListWindow, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
 }

package/components/menu/menu.css

@@ -106,11 +106,11 @@ menu-item-ui:hover {
 menu-item-ui:hover [slot="icon"] {
   color: var(--menu-item-icon-fg-hover);
 }
-menu-item-ui[variant="danger"]:hover {
+menu-item-ui[variant="danger"]:hover:not(:focus-visible) {
   --menu-item-bg: var(--menu-item-danger-bg);
   --menu-item-fg: var(--menu-item-danger-fg);
 }
-menu-item-ui[variant="danger"]:hover [slot="icon"] {
+menu-item-ui[variant="danger"]:hover:not(:focus-visible) [slot="icon"] {
   color: var(--menu-item-danger-fg);
 }
 

package/components/menu/menu.d.ts

@@ -29,12 +29,12 @@ export class UIMenu extends UIElement {
   /** Preferred position relative to the anchor element */
   placement: 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end';
 
+  addEventListener(type: 'action', listener: (ev: MenuActionEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UIMenu, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'action', listener: (ev: MenuActionEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }
 
 export class UIMenuDivider extends UIElement {

package/components/modal/modal.d.ts

@@ -33,10 +33,10 @@ export class UIModal extends UIElement {
   /** Aria label applied to the surface element for accessibility */
   text: string;
 
+  addEventListener(type: 'close', listener: (ev: ModalCloseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UIModal, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'close', listener: (ev: ModalCloseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/nav/nav.css

@@ -20,6 +20,14 @@
     --nav-duration: var(--a-duration);  /* §230-bundle (v0.5.9): canonical mid-tier duration (250ms). Was orphaned --a-duration-base. */
     --nav-easing:   var(--a-easing, ease);
 
+    /* Collapsed-rail icon sizing — one shared source for nav-item-ui's
+       and nav-group-ui's [slot="header"] icons at the narrow (<=96px)
+       container-query breakpoint (gh#767). Was two independently
+       drifting values: nav-item pinned a literal 18px, nav-group
+       referenced an undefined --nav-group-icon-font-size (guaranteed-
+       invalid, silently riding icon-ui's ambient-font-size fallback). */
+    --nav-icon-size-collapsed: 18px;
+
     /* Group-heading kicker */
     --nav-label-fg:        var(--a-fg-muted);
     --nav-label-font-size: var(--a-kicker-sm);

package/components/nav/nav.d.ts

@@ -41,10 +41,10 @@ export class UINav extends UIElement {
   /** Visual treatment. primary = app sidebar; section = subnav rail. */
   variant: 'primary' | 'section';
 
+  addEventListener(type: 'nav-select', listener: (ev: NavSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UINav, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'nav-select', listener: (ev: NavSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/nav-group/nav-group.css

@@ -16,6 +16,7 @@
     --nav-group-fg-selected:   var(--a-fg-strong);
     --nav-group-icon-fg-selected: var(--md-sys-color-primary); /* one selection color with --nav-item-accent (gh#522) */
     --nav-group-bg-hover:      var(--a-bg-muted);
+    --nav-group-bg-selected:   var(--a-bg-selected); /* mirrors --nav-item-bg-selected — the missing container fill (gh#795) */
     --nav-group-icon-size:     calc(var(--nav-group-row-height) - var(--a-space-2));
     --nav-group-badge-size:    var(--a-ui-sm);
 
@@ -52,8 +53,22 @@
   }
   /* Selected-look header treatment keys on [selected] — the CSS half of
      gh issue 459 (PR 460 corrected the icon weight): the group CONTAINING
-     the selected route reads strong; a merely-expanded group does not. */
-  :scope[selected] > [slot="header"] {
+     the selected route reads strong; a merely-expanded group does not.
+     Text color applies in BOTH rail modes — subtle, no double-marking risk.
+     The BACKGROUND fill (gh#795) is collapsed-only (see the two
+     nav-ui[collapsed] / @container sidebar blocks below): [selected] and
+     [data-selected-within] both mean "CONTAINS the selected route", never
+     "IS the selected route" (nav-group.class.js's own doc comment on the
+     `selected` prop — consumers set it from active-route logic exactly
+     like the JS-derived data-selected-within case; there is no
+     directly-selected-leaf-group state distinct from it). In the expanded
+     rail the contained child already paints its own real selected pill
+     (nav-item.css), so a header background here double-marks the same
+     selection (gh#806 — operator screenshot, profile-security). Collapsed
+     hides the children, so the header becomes the ONLY selection signal
+     and needs the fill nav-item-ui gets. */
+  :scope[selected] > [slot="header"],
+  :scope[data-selected-within] > [slot="header"] {
     color: var(--nav-group-fg-selected);
   }
   /* Icon color = the SELECTION color, one language with nav-item's accent
@@ -111,9 +126,12 @@
     justify-content: center;
   }
 
-  [slot="header"] [slot="icon"] icon-ui {
-    --a-icon-size: calc(var(--nav-group-icon-font-size) + 2px);
-  }
+  /* Default (non-collapsed) icon size: no explicit --a-icon-size here —
+     icon-ui rides its own ambient-font-size fallback
+     (calc(1em + 0.125rem), icon.css). Was a reference to
+     --nav-group-icon-font-size, a token defined nowhere — guaranteed-
+     invalid, so it silently resolved to the exact same fallback anyway;
+     removed as dead code (gh#767), same defect as nav-item's mirror rule. */
 
   [slot="header"] [slot="text"] {
     flex: 1;
@@ -175,10 +193,29 @@
     padding: 0;
   }
 
-  nav-ui[collapsed] & {
-    align-self: stretch;
+  /* gh#806: the header background fill lives HERE, collapsed-only —
+     children are display:none in this mode (rule above), so the header
+     is the sole selection signal and needs the real container fill
+     nav-item-ui gets. Expanded mode never sets this background (the
+     :scope[selected]/[data-selected-within] rule above is color-only) —
+     the selected child already paints its own pill there. */
+  nav-ui[collapsed] &[selected] > [slot="header"],
+  nav-ui[collapsed] &[data-selected-within] > [slot="header"] {
+    background: var(--nav-group-bg-selected);
   }
 
+  /* No align-self override here (there was one — `align-self: stretch` —
+     until gh#767): in expanded mode :scope already stretches full-width
+     via nav-ui's default flex-column align-items:stretch, so the
+     explicit rule was a no-op there. In collapsed mode it silently
+     fought admin-shell.collapsed.css's square-footprint contract
+     (align-items:center at the nav-ui level, FEEDBACK-39) — stretching
+     the header to the full rail width and defeating the min-width floor
+     that pins nav-item-ui/nav-group-ui to a matching square. Falling
+     through to the ambient align-items (stretch normally, center under
+     admin-shell's collapsed rail) matches nav-item-ui, which never had
+     an override here. */
+
   nav-ui[collapsed] &::after {
     display: none;
   }
@@ -199,12 +236,24 @@
        invalid at the icon's var() site: a silent no-op. The caret is
        display:none in collapsed mode anyway; the icon keeps the
        inherited --a-icon-size.) */
-    :scope {
-      align-self: stretch;
+    /* No align-self override here either (gh#767) — same reasoning as
+       the nav-ui[collapsed] & block above; this duplicate fought the
+       same square-footprint contract inside the container-query path. */
+    [slot="header"] [slot="icon"] icon-ui {
+      --a-icon-size: var(--nav-icon-size-collapsed);
     }
     :scope::after {
       display: none;
     }
+    /* gh#806 — mirrors the nav-ui[collapsed] block above: this container
+       query is the OTHER mechanism that puts the rail in collapsed mode
+       (admin-sidebar's own collapse path), and children are hidden here
+       too ([slot="header"] nav-item-ui rule above), so the same
+       collapsed-only header background applies. */
+    :scope[selected] > [slot="header"],
+    :scope[data-selected-within] > [slot="header"] {
+      background: var(--nav-group-bg-selected);
+    }
   }
 
   /* ── Size variants ── */

package/components/nav-group/nav-group.d.ts

@@ -45,10 +45,10 @@ export class UINavGroup extends UIElement {
   /** Visual treatment. Default ('') renders as a primary-rail group (icon row, caret, collapsible). 'section' renders the header as a static kicker label with always-visible children. When the parent <nav-ui> carries variant="section", this group inherits it via CSS cascade unless an explicit variant is set on the group. */
   variant: '' | 'section';
 
+  addEventListener(type: 'group-toggle', listener: (ev: NavGroupGroupToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UINavGroup, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'group-toggle', listener: (ev: NavGroupGroupToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/nav-item/nav-item.css

@@ -106,9 +106,12 @@ nav-item-ui[selected] [slot="icon"]:empty::before {
     transition: color var(--nav-duration-fast) var(--nav-easing);
   }
 
-  [slot="icon"] icon-ui {
-    --a-icon-size: calc(var(--nav-item-icon-font-size) + 2px);
-  }
+  /* Default (non-collapsed) icon size: no explicit --a-icon-size here —
+     icon-ui rides its own ambient-font-size fallback
+     (calc(1em + 0.125rem), icon.css). Was a reference to
+     --nav-item-icon-font-size, a token defined nowhere — guaranteed-
+     invalid, so it silently resolved to the exact same fallback anyway;
+     removed as dead code (gh#767). */
 
   /* Selected accent line on empty icon slot moved outside @scope — see Safari 17.x bug note at top. */
 
@@ -157,7 +160,7 @@ nav-item-ui[selected] [slot="icon"]:empty::before {
       display: none !important;
     }
     [slot="icon"] icon-ui {
-      --a-icon-size: 18px;
+      --a-icon-size: var(--nav-icon-size-collapsed);
     }
     :scope {
       justify-content: center;

package/components/nav-item/nav-item.d.ts

@@ -47,10 +47,10 @@ export class UINavItem extends UIElement {
   /** Visual treatment. Default ('') renders as a primary-rail item (reserved icon space, in-icon selected accent). 'section' renders flat — no icon space when absent, left-edge accent bar for selected. When the parent <nav-ui> carries variant="section", this item inherits it via CSS cascade unless an explicit variant is set. */
   variant: '' | 'section';
 
+  addEventListener(type: 'nav-select', listener: (ev: NavItemNavSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UINavItem, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'nav-select', listener: (ev: NavItemNavSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/noodles/noodles.d.ts

@@ -62,12 +62,12 @@ export class UINoodles extends UIElement {
   /** Bezier control point distance (0-1). Higher = wider curves */
   tension: number;
 
+  addEventListener(type: 'noodle-connect', listener: (ev: NoodlesNoodleConnectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'noodle-disconnect', listener: (ev: NoodlesNoodleDisconnectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'noodle-drag', listener: (ev: NoodlesNoodleDragEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UINoodles, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'noodle-connect', listener: (ev: NoodlesNoodleConnectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'noodle-disconnect', listener: (ev: NoodlesNoodleDisconnectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'noodle-drag', listener: (ev: NoodlesNoodleDragEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/option-card/option-card.css

@@ -1,7 +1,7 @@
 /* Safari 17.x bug: `:scope:not(...):hover` (Flavor A) and `:scope[checked]`
    (Flavor B — attribute-removal restyle) both fail inside `@scope`.
    Selectors moved out. See docs/BROWSER-COMPAT.md §3a. */
-option-card-ui:not([checked]):not([disabled]):hover {
+option-card-ui:not([checked]):not([disabled]):hover:not(:focus-visible) {
   background: var(--option-card-bg-hover);
   border-color: var(--option-card-border-hover);
 }

package/components/pagination/pagination.d.ts

@@ -35,10 +35,10 @@ default; pass `size="sm"` for a denser numbered row.
   /** Visual variant — `default` (ghost buttons w/ hover bg) or `button` (1×1 bordered cells; active page filled). */
   variant: 'default' | 'button';
 
+  addEventListener(type: 'page-change', listener: (ev: PaginationPageChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UIPagination, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'page-change', listener: (ev: PaginationPageChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/pane/pane.d.ts

@@ -38,10 +38,10 @@ grabber when resizable).
  */
   side: '' | 'leading' | 'trailing';
 
+  addEventListener(type: 'toggle', listener: (ev: PaneToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UIPane, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'toggle', listener: (ev: PaneToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/password-strength/password-strength.d.ts

@@ -50,10 +50,10 @@ meter.value = e.target.value)`.
  */
   value: string;
 
+  addEventListener(type: 'score-change', listener: (ev: PasswordStrengthScoreChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UIPasswordStrength, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'score-change', listener: (ev: PasswordStrengthScoreChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }