@adia-ai/web-components 0.8.44 → 0.8.45

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog — @adia-ai/web-components
 
+## [0.8.45] — 2026-08-20
+
+### Added
+- **`createStore()` — a signal-backed store primitive in `core/store.js` (gh#1761).** `subscribe(cb) -> unsubscribe`, an `Object.is` no-notify guard, and interop with `UIElement.controller`; ships alongside a new `check-no-hand-rolled-stores.mjs` lint gate (gh#1779) that rejects new hand-rolled Set-of-listeners stores outside `core/`.
+
+### Changed
+- **`for=`-carrying components normalized to an events-only interaction contract (gh#1764/#1780), ADR-0079.** `table-toolbar-ui` → `table-ui` direct writes/calls (`paginate=`, `search=`, `setFilter()`, `clearFilters()`, `columns=`) became five `toolbar-*` command CustomEvents with matching `table-ui` listeners — additive, zero observable-behavior change. `context-menu-ui`'s `for` (selector-flavored) renamed to `target-selector`, `for` kept as a deprecated back-compat alias.
+- **`RouteController` deduplicated into `core/controller.js` (gh#1766).** `provider.js` now imports/re-exports the canonical location.
+- **`[density="compact"|"spacious"]` re-declares `--a-space-*` at the scoped selector, not only `:root` (gh#1771, gh#570).** Element-scoped density was globally inert; `components/table/table.css`'s stale ADR-0054 comment corrected alongside.
+- **Billing composites (`billing-overview`, `invoice-history`, `invoice-detail`, `plan-picker`) route fetch through `core/transport.js`, opting out of the `core/data-stream.js` auto-observer via a new `data-stream-managed="false"` marker (gh#1760).**
+- **`select`/`table-toolbar` — visually-hidden `select` label (`[label-hidden]`) + actions-leading icon-only Filter/Columns reduction (gh#1748).**
+- **`table-ui` adopts an `isEqualNode()`-based `adoptOrDiffChildren()` for SSR adopt-in-place, with `RENDERER_OWNED` `WeakSet` tagging for unconditional replacement of renderer-owned cells (gh#1678).**
+- **`search-ui`/`pagination-ui` post-adopt attribute writes are idempotent under SSR zero-mutation (gh#1755).**
+- **Three independently-authored path-walker implementations in `packages/gen-ui/a2ui/path-pointer.js` unified, preserving each call site's real divergent edge-case semantics rather than silently collapsing them (empty-path, primitive mid-path, doubled-slash) — mechanical staging toward ADR-0078's vendored-model migration.**
+
+### Docs
+- **New `table-with-toolbar-in-card-header` demo** — `table-toolbar-ui` composed inside `card-ui`'s header (sole-child case; a real `card.css` grid/centering conflict documented for the heading+action-slot case, not yet supported).
+- **`nav-group-ui`'s `[data-nav-label]` group-label hook documented (gh#1736).**
+- **Render clock & external-store wiring doctrine ratified in `.claude/docs/specs/component-implementation-patterns.md` (gh#1777/#1778)** — `table-ui`'s rAF-batched render clock named as the sole verified exception to the microtask-flush contract; `BaseController` promoted as a `createStore()` adapter via its existing optional-chaining `controller` setter (no new adapter code needed — the contract was already satisfied).
+
+### Maintenance
+- **`dist/` bundles rebuilt** in this cut's window (6 file(s)) — regenerated from the source changes described above, not independent edits.
+- **`styles/` touched in this release window** (2 file(s), e.g. `api/sizing.css`) — carried by the entries above.
+
 ## [0.8.44] — 2026-08-20
 
 ### Added

package/components/context-menu/context-menu.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/ContextMenu.json",
   "title": "ContextMenu",
-  "description": "Right-click activated menu — the OS-native context-menu pattern as a\nweb component. Distinct from `menu-ui` (which is button-triggered):\nsame item shape (`menu-item-ui` children), different trigger surface\n(`contextmenu` event), and pointer-anchored positioning instead of\nelement-anchored. Pattern: WAI-APG Menu.\n\nTwo binding modes:\n **A. Wrap.** Default-slot child becomes the target:\n `<context-menu-ui><my-table>...</my-table>...items</context-menu-ui>`.\n **B. Selector.** Point at one or more existing elements via [for]:\n `<context-menu-ui for=\"#my-table\">...items</context-menu-ui>`.\n\nOn `contextmenu` event on a target: `preventDefault()`, position the\nmenu at the pointer coords, show via Popover API. Touch long-press\n(configurable via [long-press-ms]) does the same. Shift+F10 / Menu\nkey opens at the focused target's center for keyboard users.\n",
+  "description": "Right-click activated menu — the OS-native context-menu pattern as a\nweb component. Distinct from `menu-ui` (which is button-triggered):\nsame item shape (`menu-item-ui` children), different trigger surface\n(`contextmenu` event), and pointer-anchored positioning instead of\nelement-anchored. Pattern: WAI-APG Menu.\n\nTwo binding modes:\n **A. Wrap.** Default-slot child becomes the target:\n `<context-menu-ui><my-table>...</my-table>...items</context-menu-ui>`.\n **B. Selector.** Point at one or more existing elements via\n [target-selector]:\n `<context-menu-ui target-selector=\"#my-table\">...items</context-menu-ui>`.\n\nOn `contextmenu` event on a target: `preventDefault()`, position the\nmenu at the pointer coords, show via Popover API. Touch long-press\n(configurable via [long-press-ms]) does the same. Shift+F10 / Menu\nkey opens at the focused target's center for keyboard users.\n",
   "type": "object",
   "allOf": [
     {
@@ -17,7 +17,7 @@
       "const": "ContextMenu"
     },
     "for": {
-      "description": "CSS selector(s) for target element(s). Empty = use default-slot child.",
+      "description": "DEPRECATED alias for [target-selector] — still a CSS selector, NOT an id-ref. Honored when [target-selector] is unset, with a one-shot console.warn pointing consumers at the replacement. New authoring should use [target-selector].",
       "type": "string",
       "default": ""
     },
@@ -30,6 +30,11 @@
       "description": "Programmatic open state. Set true to open at target center.",
       "type": "boolean",
       "default": false
+    },
+    "targetSelector": {
+      "description": "CSS selector(s) for target element(s). Empty = use default-slot child. Ratified name (gh#1764/#1780, ADR-0079) for what [for] used to carry — [for] means an id-ref everywhere else in AdiaUI (table-toolbar-ui, chart-legend-ui, tooltip-ui); context-menu-ui's own selector meaning predates that convention and was a same-name/ different-contract collision (ADR-0053's no-shadowing doctrine).",
+      "type": "string",
+      "default": ""
     }
   },
   "required": [
@@ -39,7 +44,7 @@
   "x-adiaui": {
     "anti_patterns": [
       {
-        "fix": "Wrap a target: `<context-menu-ui><my-target></my-target>...items</context-menu-ui>` OR point at one: `<context-menu-ui for=\"#my-target\">...items</context-menu-ui>`.",
+        "fix": "Wrap a target: `<context-menu-ui><my-target></my-target>...items</context-menu-ui>` OR point at one: `<context-menu-ui target-selector=\"#my-target\">...items</context-menu-ui>`.",
         "why": "No target binding — the menu never opens.",
         "wrong": "<context-menu-ui>...just items...</context-menu-ui>"
       }

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

@@ -4,8 +4,16 @@
  * Two binding shapes:
  *   A. Wrap a target — first non-menu-item-ui default-slot child becomes
  *      the contextmenu host.
- *   B. Point at targets via [for="<selector>"] — useful for whole-table
- *      / whole-canvas menus where wrapping isn't practical.
+ *   B. Point at targets via [target-selector="<css-selector>"] — useful for
+ *      whole-table / whole-canvas menus where wrapping isn't practical.
+ *      [for] is a DEPRECATED alias for this (gh#1764/#1780, ADR-0079): `for=`
+ *      means an id-ref everywhere else in AdiaUI (table-toolbar-ui,
+ *      chart-legend-ui, tooltip-ui) — context-menu-ui's own pre-ruling [for]
+ *      carried a CSS-selector meaning instead, the exact same-attribute-
+ *      different-contract shape ADR-0053's no-shadowing doctrine forbids.
+ *      [target-selector] still resolves via `document.querySelectorAll()`
+ *      (multiple targets); a still-set legacy [for] is honored with a
+ *      one-shot console.warn pointing at the replacement.
  *
  * Architecture: reuses the existing anchor pattern (core/anchor.js) by
  * creating a virtual 1×1 anchor element at the pointer coords on each
@@ -23,8 +31,21 @@ import { anchorPopover } from '../../core/anchor.js';
 
 const LONG_PRESS_DEFAULT = 500;
 
+// DEPRECATED [for]-alias one-shot warning guard (gh#1764/#1780, ADR-0079) —
+// module-scope, matching this file's own idiom (a plain top-level const
+// rather than a lazily-created public static field, which stayed mutable
+// and externally visible for no reason).
+const warnedForDeprecated = new WeakSet();
+
 export class UIContextMenu extends UIElement {
   static properties = {
+    // gh#1764/#1780, ADR-0079 — the ratified replacement for the
+    // selector-flavored [for] below; a plain CSS selector, not an id-ref.
+    targetSelector: { type: String,  default: '',                 reflect: true, attribute: 'target-selector' },
+    // DEPRECATED — kept as a back-compat alias for `targetSelector` only.
+    // Honored (with a one-shot console.warn, see #legacyForSelector())
+    // whenever [target-selector] is unset. Never given id-ref semantics;
+    // the sweep did not attempt to dual-purpose this attribute.
     for:         { type: String,  default: '',                 reflect: true },
     open:        { type: Boolean, default: false,              reflect: true },
     longPressMs: { type: Number,  default: LONG_PRESS_DEFAULT, reflect: false, attribute: 'long-press-ms' },
@@ -97,11 +118,12 @@ export class UIContextMenu extends UIElement {
   }
 
   #resolveTargets() {
-    if (this.for) {
-      try { return [...document.querySelectorAll(this.for)]; }
+    const selector = this.targetSelector || this.#legacyForSelector();
+    if (selector) {
+      try { return [...document.querySelectorAll(selector)]; }
       catch (e) {
         // eslint-disable-next-line no-console
-        console.warn(`[context-menu-ui] invalid [for] selector: ${this.for}`, e);
+        console.warn(`[context-menu-ui] invalid [target-selector] selector: ${selector}`, e);
         return [];
       }
     }
@@ -113,6 +135,25 @@ export class UIContextMenu extends UIElement {
     return [];
   }
 
+  // DEPRECATED alias path (gh#1764/#1780, ADR-0079) — [for] used to carry
+  // context-menu-ui's own CSS-selector binding; [target-selector] is now
+  // the canonical name. Warn once per element, never per resolve (this
+  // runs on every #bindTargets() call, including reconnects).
+  #legacyForSelector() {
+    if (!this.for) return '';
+    if (!warnedForDeprecated.has(this)) {
+      warnedForDeprecated.add(this);
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[context-menu-ui] [for="${this.for}"] is deprecated — use ` +
+        `[target-selector="${this.for}"] instead. [for] now means an ` +
+        'id-ref everywhere else in AdiaUI; context-menu-ui\'s own prior ' +
+        '[for] carried a CSS-selector meaning (ADR-0079).',
+      );
+    }
+    return this.for;
+  }
+
   /* ── Trigger event handlers ──────────────────────────────────────── */
 
   #onContextMenu = (e) => {

package/components/context-menu/context-menu.d.ts

@@ -8,8 +8,9 @@ element-anchored. Pattern: WAI-APG Menu.
 Two binding modes:
  **A. Wrap.** Default-slot child becomes the target:
  `<context-menu-ui><my-table>...</my-table>...items</context-menu-ui>`.
- **B. Selector.** Point at one or more existing elements via [for]:
- `<context-menu-ui for="#my-table">...items</context-menu-ui>`.
+ **B. Selector.** Point at one or more existing elements via
+ [target-selector]:
+ `<context-menu-ui target-selector="#my-table">...items</context-menu-ui>`.
 
 On `contextmenu` event on a target: `preventDefault()`, position the
 menu at the pointer coords, show via Popover API. Touch long-press
@@ -54,12 +55,14 @@ export interface ContextMenuSelectEventDetail {
 export type ContextMenuSelectEvent = CustomEvent<ContextMenuSelectEventDetail>;
 
 export class UIContextMenu extends UIElement {
-  /** CSS selector(s) for target element(s). Empty = use default-slot child. */
+  /** DEPRECATED alias for [target-selector] — still a CSS selector, NOT an id-ref. Honored when [target-selector] is unset, with a one-shot console.warn pointing consumers at the replacement. New authoring should use [target-selector]. */
   for: string;
   /** Long-press duration (ms) on touch devices to open the menu. */
   longPressMs: number;
   /** Programmatic open state. Set true to open at target center. */
   open: boolean;
+  /** CSS selector(s) for target element(s). Empty = use default-slot child. Ratified name (gh#1764/#1780, ADR-0079) for what [for] used to carry — [for] means an id-ref everywhere else in AdiaUI (table-toolbar-ui, chart-legend-ui, tooltip-ui); context-menu-ui's own selector meaning predates that convention and was a same-name/ different-contract collision (ADR-0053's no-shadowing doctrine). */
+  targetSelector: string;
 
   addEventListener(type: 'context-menu-close', listener: (ev: ContextMenuCloseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'context-menu-open', listener: (ev: ContextMenuOpenEvent) => unknown, options?: boolean | AddEventListenerOptions): void;

package/components/context-menu/context-menu.examples.md

@@ -17,7 +17,7 @@
 </context-menu-ui>
 ```
 
-## [for] selector mode — point at existing targets
+## [target-selector] mode — point at existing targets
 
 ```html
 <div style="display: grid; gap: var(--a-space-2);">
@@ -25,7 +25,7 @@
   <div data-row tabindex="0" style="padding: var(--a-space-3); border: 1px solid var(--md-sys-color-neutral-outline); border-radius: var(--a-radius-sm); background: var(--md-sys-color-neutral-background);">Row B — right-click</div>
   <div data-row tabindex="0" style="padding: var(--a-space-3); border: 1px solid var(--md-sys-color-neutral-outline); border-radius: var(--a-radius-sm); background: var(--md-sys-color-neutral-background);">Row C — right-click</div>
 </div>
-<context-menu-ui for='[data-chunk="context-menu-for"] [data-row]'>
+<context-menu-ui target-selector='[data-chunk="context-menu-for"] [data-row]'>
   <menu-item-ui value="edit" text="Edit"></menu-item-ui>
   <menu-item-ui value="duplicate" text="Duplicate"></menu-item-ui>
   <menu-divider-ui></menu-divider-ui>

package/components/context-menu/context-menu.yaml

@@ -15,8 +15,9 @@ description: |
   Two binding modes:
    **A. Wrap.** Default-slot child becomes the target:
    `<context-menu-ui><my-table>...</my-table>...items</context-menu-ui>`.
-   **B. Selector.** Point at one or more existing elements via [for]:
-   `<context-menu-ui for="#my-table">...items</context-menu-ui>`.
+   **B. Selector.** Point at one or more existing elements via
+   [target-selector]:
+   `<context-menu-ui target-selector="#my-table">...items</context-menu-ui>`.
 
   On `contextmenu` event on a target: `preventDefault()`, position the
   menu at the pointer coords, show via Popover API. Touch long-press
@@ -25,8 +26,24 @@ description: |
 composes:
   - menu-item-ui
 props:
+  targetSelector:
+    description: >-
+      CSS selector(s) for target element(s). Empty = use default-slot
+      child. Ratified name (gh#1764/#1780, ADR-0079) for what [for] used
+      to carry — [for] means an id-ref everywhere else in AdiaUI
+      (table-toolbar-ui, chart-legend-ui, tooltip-ui); context-menu-ui's
+      own selector meaning predates that convention and was a same-name/
+      different-contract collision (ADR-0053's no-shadowing doctrine).
+    type: string
+    default: ""
+    reflect: true
+    attribute: target-selector
   for:
-    description: CSS selector(s) for target element(s). Empty = use default-slot child.
+    description: >-
+      DEPRECATED alias for [target-selector] — still a CSS selector, NOT
+      an id-ref. Honored when [target-selector] is unset, with a one-shot
+      console.warn pointing consumers at the replacement. New authoring
+      should use [target-selector].
     type: string
     default: ""
     reflect: true
@@ -101,12 +118,12 @@ a2ui:
       reason: 'Trigger surface boundary.'
     - rule: 'Items are <menu-item-ui> children inside the default slot — same shape as <menu-ui> items.'
       reason: 'Single menu vocabulary.'
-    - rule: 'Bind target via wrap (default-slot first non-menu-item-ui child) OR [for] selector. The selector form is useful for whole-table or whole-canvas menus where wrapping isn''t practical.'
+    - rule: 'Bind target via wrap (default-slot first non-menu-item-ui child) OR [target-selector]. The selector form is useful for whole-table or whole-canvas menus where wrapping isn''t practical. [for] still works as a deprecated alias but new authoring should use [target-selector] (gh#1764/#1780, ADR-0079).'
       reason: 'Two binding shapes.'
 anti_patterns:
   - wrong: '<context-menu-ui>...just items...</context-menu-ui>'
     why: 'No target binding — the menu never opens.'
-    fix: 'Wrap a target: `<context-menu-ui><my-target></my-target>...items</context-menu-ui>` OR point at one: `<context-menu-ui for="#my-target">...items</context-menu-ui>`.'
+    fix: 'Wrap a target: `<context-menu-ui><my-target></my-target>...items</context-menu-ui>` OR point at one: `<context-menu-ui target-selector="#my-target">...items</context-menu-ui>`.'
 examples:
   - name: file-actions
     description: Right-click a file row for Open / Rename / Delete.

package/components/nav/nav.a2ui.json

@@ -27,7 +27,7 @@
       "default": false
     },
     "heading": {
-      "description": "Optional kicker label. Section variant renders it via ::before; primary uses it as aria-label only.",
+      "description": "Optional kicker label. Section variant renders it via ::before; primary uses it as aria-label only. For a VISIBLE kicker inside a primary-variant rail — or more than one kicker per <nav-ui> — hand-place <span data-nav-label> in the default slot instead; see slots below.",
       "type": "string",
       "default": ""
     },
@@ -108,7 +108,7 @@
     ],
     "slots": {
       "default": {
-        "description": "Primary slot — accepts <nav-group-ui> + <nav-item-ui> children, plus <hr data-nav-divider> for hand-placed dividers."
+        "description": "Primary slot — accepts <nav-group-ui> + <nav-item-ui> children, plus <hr data-nav-divider> for hand-placed dividers and <span data-nav-label> for hand-placed group-label kickers (titled runs of items/groups that aren't wrapped in a <nav-group-ui>). <span data-nav-label> renders with the same uppercase/tracking/muted kicker treatment as the [heading] ::before kicker, and is hidden alongside dividers whenever the primary-variant rail collapses ([collapsed] or ≤96px container width)."
       }
     },
     "states": [

package/components/nav/nav.css

@@ -32,7 +32,7 @@
     --nav-label-fg:        var(--a-fg-muted);
     --nav-label-font-size: var(--a-kicker-sm);
     --nav-label-weight:    var(--a-weight-medium);
-    --nav-label-px:        var(--a-space-2);
+    --nav-label-px:        var(--a-space-4);
     --nav-label-py:        var(--a-space-3) var(--a-space-1);
   }
 

package/components/nav/nav.d.ts

@@ -36,7 +36,7 @@ export class UINav extends UIElement {
   collapsed: boolean;
   /** Auto-place dividers between adjacent groups + items. */
   divider: boolean;
-  /** Optional kicker label. Section variant renders it via ::before; primary uses it as aria-label only. */
+  /** Optional kicker label. Section variant renders it via ::before; primary uses it as aria-label only. For a VISIBLE kicker inside a primary-variant rail — or more than one kicker per <nav-ui> — hand-place <span data-nav-label> in the default slot instead; see slots below. */
   heading: string;
   /** Opt out of the default single-expanded-group behavior. When unset, selecting a nav-item-ui collapses every nav-group-ui except the one containing the newly selected item (all, when the selection is ungrouped); manual multi-expansion still works up until the next selection. */
   multiExpand: boolean;

package/components/nav/nav.yaml

@@ -38,7 +38,7 @@ props:
   heading:
     type: string
     default: ''
-    description: "Optional kicker label. Section variant renders it via ::before; primary uses it as aria-label only."
+    description: "Optional kicker label. Section variant renders it via ::before; primary uses it as aria-label only. For a VISIBLE kicker inside a primary-variant rail — or more than one kicker per <nav-ui> — hand-place <span data-nav-label> in the default slot instead; see slots below."
   multiExpand:
     type: boolean
     default: false
@@ -62,7 +62,7 @@ events:
 
 slots:
   default:
-    description: "Primary slot — accepts <nav-group-ui> + <nav-item-ui> children, plus <hr data-nav-divider> for hand-placed dividers."
+    description: "Primary slot — accepts <nav-group-ui> + <nav-item-ui> children, plus <hr data-nav-divider> for hand-placed dividers and <span data-nav-label> for hand-placed group-label kickers (titled runs of items/groups that aren't wrapped in a <nav-group-ui>). <span data-nav-label> renders with the same uppercase/tracking/muted kicker treatment as the [heading] ::before kicker, and is hidden alongside dividers whenever the primary-variant rail collapses ([collapsed] or ≤96px container width)."
 
 states:
   - name: idle
@@ -79,7 +79,18 @@ a2ui:
       wrapped in <section-ui> for app sidebars; inside an
       <aside data-subnav> with variant="section" for section / subnav
       rails; standalone on docs / auth pages. Children: <nav-group-ui>,
-      <nav-item-ui>, optional <hr data-nav-divider>.
+      <nav-item-ui>, optional <hr data-nav-divider>, optional
+      <span data-nav-label> (hand-placed titled section header).
+    - >-
+      Titled nav-item groups: hand-place <span data-nav-label>Text</span>
+      directly in the default slot, before a run of <nav-item-ui> /
+      <nav-group-ui> children, to render a section-header kicker — the
+      same uppercase/tracking/muted treatment as the [heading] ::before
+      kicker on variant="section", but usable anywhere in the child list
+      (not limited to one kicker per <nav-ui>) and always visually
+      rendered, unlike [heading] which is aria-only on variant="primary".
+      Hidden automatically whenever the primary-variant rail collapses
+      ([collapsed] or ≤96px container width), same as <hr data-nav-divider>.
     - >-
       Variants: variant="primary" (default) — app sidebar; ResizeObserver
       collapses to icon-only ≤96px; collapsible groups open as a popover

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

@@ -17,13 +17,31 @@
          selected — bg container · icon + text ON-SURFACE
        The selected icon no longer takes primary (supersedes gh#522's
        glyph ruling); Figma's neutral/surfaceBright was considered for the
-       selected fill and RULED OUT — container stays (gh#795's mirror). */
-    --nav-group-fg:            var(--md-sys-color-neutral-high);
+       selected fill and RULED OUT — container stays (gh#795's mirror).
+       gh#968's ladder above is about ROUTE selection (hover/selected);
+       it says nothing about the group's own open/closed disclosure state,
+       which --nav-group-fg left pinned unconditionally to one role
+       (neutral-high) regardless of [open]. gh#1740 (operator ruling,
+       2026-08-19) supersedes that unconditional pin with a second,
+       orthogonal axis — the header text and caret glyph now also shift
+       role by [open], the same way they already shift by [selected]/
+       hover; the two ladders compose (a selected-route header still wins
+       its --nav-group-fg-selected treatment regardless of open state —
+       see the :scope[open] rule below, kept lower-precedence than
+       :scope[selected] by source order). */
+    --nav-group-fg:            var(--md-sys-color-neutral);
+    --nav-group-fg-active:     var(--md-sys-color-neutral-high);
     --nav-group-fg-hover:      var(--a-fg-strong);
     --nav-group-fg-muted:      var(--a-fg-muted);
     --nav-group-fg-selected:   var(--a-fg-strong);
     --nav-group-icon-fg:       var(--md-sys-color-neutral);
     --nav-group-icon-fg-selected: var(--a-fg-strong);
+    /* Caret role ladder (gh#1740) — idle/closed: NEUTRAL-LOW (one step
+       quieter than the muted badge/kicker role); open: NEUTRAL, matching
+       the icon's own idle role so the caret doesn't outshine the icon
+       once the group is expanded. */
+    --nav-group-caret-fg:        var(--md-sys-color-neutral-low);
+    --nav-group-caret-fg-active: var(--md-sys-color-neutral);
     --nav-group-bg-hover:      var(--a-bg-muted);
     --nav-group-bg-selected:   var(--a-bg-selected); /* mirrors --nav-item-bg-selected (gh#795) */
     --nav-group-icon-size:     calc(var(--nav-group-row-height) - var(--a-space-2));
@@ -71,6 +89,20 @@
     background: var(--nav-group-indent-rail-bg, var(--md-sys-color-neutral-outline-variant));
     pointer-events: none;
   }
+  /* Disclosure-state ladder (gh#1740, operator ruling 2026-08-19): the
+     header text and caret glyph step UP a role when the group is open —
+     idle/closed reads NEUTRAL, expanded reads NEUTRAL-HIGH. Placed BEFORE
+     the [selected]/[data-selected-within] block below so an equal-
+     specificity (0,3,0) tie always resolves to the route-selection color:
+     a selected-route group keeps its existing --nav-group-fg-selected
+     treatment regardless of its own open/closed state — this rule only
+     ever wins when the group is open AND not selected. */
+  :scope[open] > [slot="header"] {
+    color: var(--nav-group-fg-active);
+  }
+  :scope[open] > [slot="header"] [slot="caret"] {
+    color: var(--nav-group-caret-fg-active);
+  }
   /* 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.
@@ -174,7 +206,9 @@
 
   [slot="header"] [slot="caret"] {
     /*--a-icon-size: 0.5rem;*/
-    color: var(--nav-group-fg-muted);
+    /* idle/closed caret = NEUTRAL-LOW (gh#1740 role ladder); steps up to
+       --nav-group-caret-fg-active via the :scope[open] rule above. */
+    color: var(--nav-group-caret-fg);
     transition:
       transform var(--nav-duration-fast) var(--nav-easing),
       color var(--nav-duration-fast) var(--nav-easing);

package/components/pagination/pagination.class.js

@@ -24,6 +24,32 @@
 import { UIElement } from '../../core/element.js';
 import { KEY_MAP } from '../../core/template.js';
 
+// ── SSR idempotent-write guard (gh#1755, follow-up to table-ui's gh#1678) ──
+//
+// Local copies of table.class.js's own setAttrIfChanged()/removeAttrIfPresent()
+// — module-local there too (not exported), so a shared-utility extraction for
+// two call sites would be a premature abstraction; these mirror that shape.
+//
+/**
+ * Idempotent attribute set — skip the DOM write entirely when the value
+ * already matches. `setAttribute` mutates (and queues a MutationObserver
+ * record) even when the new value is byte-identical to the old one, so a
+ * per-item attribute this render path sets on EVERY call (`aria-current`,
+ * `variant`, `disabled`, `tabindex`, `text`, `aria-label`, `data-value`,
+ * `size`) must compare-before-write to let a byte-identical adopted SSR
+ * `<nav>` (gh#1687) survive re-render with zero mutations — bare
+ * `setAttribute` cannot give that guarantee even when the value never
+ * actually changes.
+ */
+function setAttrIfChanged(el, name, value) {
+  if (el.getAttribute(name) !== value) el.setAttribute(name, value);
+}
+
+/** Idempotent attribute removal — same rationale as setAttrIfChanged. */
+function removeAttrIfPresent(el, name) {
+  if (el.hasAttribute(name)) el.removeAttribute(name);
+}
+
 export class UIPagination extends UIElement {
   static properties = {
     page:     { type: Number, default: 1, reflect: true },
@@ -251,21 +277,21 @@ export class UIPagination extends UIElement {
     }
 
     const btn = document.createElement('button-ui');
-    btn.setAttribute('size', this.size);
+    setAttrIfChanged(btn, 'size', this.size);
 
     if (item.type === 'prev') {
       btn.setAttribute('data-prev', '');
-      btn.setAttribute('icon', 'caret-left');
-      btn.setAttribute('aria-label', 'Previous page');
+      setAttrIfChanged(btn, 'icon', 'caret-left');
+      setAttrIfChanged(btn, 'aria-label', 'Previous page');
     } else if (item.type === 'next') {
       btn.setAttribute('data-next', '');
-      btn.setAttribute('icon', 'caret-right');
-      btn.setAttribute('aria-label', 'Next page');
+      setAttrIfChanged(btn, 'icon', 'caret-right');
+      setAttrIfChanged(btn, 'aria-label', 'Next page');
     } else {
       btn.setAttribute('data-page', '');
-      btn.dataset.value = String(item.value);
-      btn.setAttribute('text', String(item.value));
-      btn.setAttribute('aria-label', `Page ${item.value}`);
+      setAttrIfChanged(btn, 'data-value', String(item.value));
+      setAttrIfChanged(btn, 'text', String(item.value));
+      setAttrIfChanged(btn, 'aria-label', `Page ${item.value}`);
     }
 
     this.#updateItem(btn, item, page);
@@ -276,32 +302,36 @@ export class UIPagination extends UIElement {
     if (item.type === 'ellipsis') return;
 
     // Keep size in sync \u2014 the host's [size] may change between renders.
-    el.setAttribute('size', this.size);
+    // gh#1755 \u2014 compare-before-write: this runs on EVERY render pass
+    // (including one triggered by an unrelated reactive dependency), so a
+    // bare setAttribute() would re-mutate an already-correct adopted
+    // gh#1687 SSR `<nav>` child even when nothing here actually changed.
+    setAttrIfChanged(el, 'size', this.size);
 
     if (item.type === 'prev') {
-      el.setAttribute('variant', this.#restVariant());
-      if (page <= 1) { el.setAttribute('disabled', ''); el.setAttribute('tabindex', '-1'); }
-      else { el.removeAttribute('disabled'); el.setAttribute('tabindex', '0'); }
+      setAttrIfChanged(el, 'variant', this.#restVariant());
+      if (page <= 1) { setAttrIfChanged(el, 'disabled', ''); setAttrIfChanged(el, 'tabindex', '-1'); }
+      else { removeAttrIfPresent(el, 'disabled'); setAttrIfChanged(el, 'tabindex', '0'); }
     } else if (item.type === 'next') {
-      el.setAttribute('variant', this.#restVariant());
-      if (page >= this.total) { el.setAttribute('disabled', ''); el.setAttribute('tabindex', '-1'); }
-      else { el.removeAttribute('disabled'); el.setAttribute('tabindex', '0'); }
+      setAttrIfChanged(el, 'variant', this.#restVariant());
+      if (page >= this.total) { setAttrIfChanged(el, 'disabled', ''); setAttrIfChanged(el, 'tabindex', '-1'); }
+      else { removeAttrIfPresent(el, 'disabled'); setAttrIfChanged(el, 'tabindex', '0'); }
     } else {
-      el.dataset.value = String(item.value);
-      el.setAttribute('text', String(item.value));
-      el.setAttribute('aria-label', `Page ${item.value}`);
+      setAttrIfChanged(el, 'data-value', String(item.value));
+      setAttrIfChanged(el, 'text', String(item.value));
+      setAttrIfChanged(el, 'aria-label', `Page ${item.value}`);
       if (item.value === page) {
         // Active page reads as `variant="primary"` so the filled-accent
         // state comes from button-ui's primary surface matrix (the
         // canonical token chain) \u2014 not a pagination-tier re-impl.
-        el.setAttribute('variant', 'primary');
+        setAttrIfChanged(el, 'variant', 'primary');
         // aria-current="page" alone carries the active-page state — no
         // private data-active mirror (gh#1332 Category A; admin-roster's
         // aria-checked precedent from PR #1438).
-        el.setAttribute('aria-current', 'page');
+        setAttrIfChanged(el, 'aria-current', 'page');
       } else {
-        el.setAttribute('variant', this.#restVariant());
-        el.removeAttribute('aria-current');
+        setAttrIfChanged(el, 'variant', this.#restVariant());
+        removeAttrIfPresent(el, 'aria-current');
       }
     }
   }

package/components/search/search.class.js

@@ -22,6 +22,30 @@
 
 import { UIFormElement } from '../../core/form.js';
 
+// ── SSR idempotent-write guard (gh#1755, follow-up to table-ui's gh#1678) ──
+//
+// Local copies of table.class.js's own setAttrIfChanged()/removeAttrIfPresent()
+// — module-local there too (not exported), so a shared-utility extraction for
+// two call sites would be a premature abstraction; these mirror that shape.
+//
+/**
+ * Idempotent attribute set — skip the DOM write entirely when the value
+ * already matches. `setAttribute` mutates (and queues a MutationObserver
+ * record) even when the new value is byte-identical to the old one, so a
+ * host/child attribute this render path sets on EVERY call (`placeholder`,
+ * `value`) must compare-before-write to let a byte-identical SSR-rendered
+ * `<input-ui>` survive upgrade with zero mutations — bare `setAttribute`
+ * cannot give that guarantee even when the value never actually changes.
+ */
+function setAttrIfChanged(el, name, value) {
+  if (el.getAttribute(name) !== value) el.setAttribute(name, value);
+}
+
+/** Idempotent attribute removal — same rationale as setAttrIfChanged. */
+function removeAttrIfPresent(el, name) {
+  if (el.hasAttribute(name)) el.removeAttribute(name);
+}
+
 export class UISearch extends UIFormElement {
   static properties = {
     ...UIFormElement.properties,
@@ -37,7 +61,10 @@ export class UISearch extends UIFormElement {
 
   connected() {
     super.connected();
-    this.setAttribute('role', 'search');
+    // gh#1755 — a byte-identical SSR-rendered host already carries this
+    // attribute; an unconditional setAttribute() here would still queue a
+    // mutation record even though the value never actually changes.
+    setAttrIfChanged(this, 'role', 'search');
 
     if (!this.querySelector('input-ui')) {
       const size = this.getAttribute('size');
@@ -69,12 +96,19 @@ export class UISearch extends UIFormElement {
   render() {
     if (!this.#inputEl) return;
 
-    this.#inputEl.setAttribute('placeholder', this.placeholder);
-    if (this.disabled) this.#inputEl.setAttribute('disabled', '');
-    else this.#inputEl.removeAttribute('disabled');
+    // gh#1755 — this render effect re-runs on ANY of this element's
+    // reactive properties changing (element.js's connectedCallback effect
+    // reads every signal unconditionally), not only placeholder/disabled/
+    // value themselves — so a bare setAttribute() here would re-mutate an
+    // already-correct adopted `<input-ui>` (or this host's own `value`
+    // attribute) on every unrelated re-render, defeating SSR zero-mutation
+    // upgrade even when nothing this pass actually cares about changed.
+    setAttrIfChanged(this.#inputEl, 'placeholder', this.placeholder);
+    if (this.disabled) setAttrIfChanged(this.#inputEl, 'disabled', '');
+    else removeAttrIfPresent(this.#inputEl, 'disabled');
 
     // Reflect value for CSS (clear button visibility)
-    this.setAttribute('value', this.value || '');
+    setAttrIfChanged(this, 'value', this.value || '');
   }
 
   #onInput = () => {

package/components/select/select.a2ui.json

@@ -66,6 +66,11 @@
       "type": "string",
       "default": ""
     },
+    "label-hidden": {
+      "description": "When true, [label] still sets the accessible name (aria-label) but the visible `::before` text is suppressed via the canonical sr-only technique (gh#1748, mirrors check-ui's [label-hidden], gh#1010). Use when a sibling/ancestor composition already conveys the same name visually (e.g. a scope/view-switcher select in a table-toolbar-ui [slot=\"scope\"], where the toolbar's own title already names the view) and a second visible \"Scope\"-style label would paint it twice.",
+      "type": "boolean",
+      "default": false
+    },
     "mark": {
       "description": "Renders the Adia brand mark (`<adia-mark-ui>`) as the leading visual — takes precedence over avatar and icon. Token-driven (light/dark handled internally), so it fits a scheme-switching workspace/app switcher where a static logo URL can't invert. Per-option `mark` on an `<option>`/options-array entry works the same way, scoped to that row.",
       "type": "boolean",

package/components/select/select.class.js

@@ -47,6 +47,11 @@ export class UISelect extends UIFormElement {
     size:        { type: String,  default: 'md', reflect: true },
     open:        { type: Boolean, default: false, reflect: true },
     label:       { type: String,  default: '', reflect: true },
+    // gh#1748: keeps [label] as the accessible name (bridged to an explicit
+    // aria-label in #syncAccessibleName below) while suppressing the VISIBLE
+    // `::before` text (select.css) — for compositions that already show the
+    // name elsewhere. Mirrors check-ui's [label-hidden] (gh#1010).
+    labelHidden: { type: Boolean, default: false, reflect: true, attribute: 'label-hidden' },
     icon:        { type: String,  default: '', reflect: true },
     avatar:      { type: String,  default: '', reflect: true },
     mark:        { type: Boolean, default: false, reflect: true },
@@ -361,6 +366,21 @@ export class UISelect extends UIFormElement {
    */
   #syncAccessibleName() {
     const DEFAULT_PLACEHOLDER = 'Select...'; // matches static properties.placeholder.default
+    // gh#1748: [label-hidden] suppresses the visible `::before` text
+    // (select.css's `attr(label)` content) but [label] must still name the
+    // control — bridge it through the SAME tracked-ownership pipeline used
+    // below for the placeholder-only case, so a consumer's own directly-set
+    // aria-label is never clobbered (gh#1646 guarantee extends for free) and
+    // toggling [label-hidden] back off cleanly releases the bridged value
+    // (falls through to the visible-label path, which sets no aria-label —
+    // the generated `::before` content supplies the name instead, unchanged
+    // from today). Mirrors check-ui's [label-hidden] (gh#1010), which
+    // instead sets aria-label unconditionally since check-ui never relies
+    // on generated-content naming.
+    if (this.labelHidden && this.label) {
+      this.#lastAutoAriaLabel = syncAutoAriaLabel(this, this.#lastAutoAriaLabel, this.label);
+      return;
+    }
     const labeledElsewhere = !!this.label || this.hasAttribute('aria-labelledby');
     const namable = !labeledElsewhere
       && this.placeholder && this.placeholder !== DEFAULT_PLACEHOLDER;