@helixui/library 3.3.1 → 3.4.0

package/dist/utils/aria-idref.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Shared utilities for resolving `aria-labelledby` and `aria-describedby`
+ * IDREF token lists across the Shadow DOM boundary.
+ *
+ * Selection-control components (`hx-checkbox`, `hx-radio-group`, `hx-switch`,
+ * etc.) elevate their semantic surface to the host via `ElementInternals` so
+ * that consumer-supplied `aria-labelledby` / `aria-describedby` on the host
+ * resolves to light-DOM elements rather than being trapped on inner shadow
+ * nodes.
+ *
+ * Modern Chromium 134+ and Safari 17.4+ expose the IDL element-references API
+ * (`internals.ariaLabelledByElements`, `internals.ariaDescribedByElements`).
+ * For those engines we resolve token IDs against the host's root node (a
+ * Document or ShadowRoot) and assign the resulting elements directly.
+ *
+ * Older engines fall back to the host-attribute path: the ARIA delegation
+ * mixin keeps the original token list in `data-aria-labelledby`/
+ * `data-aria-describedby`, which assistive technology cannot follow into the
+ * shadow root, but that is the same surface area as the pre-fix code and is
+ * not a regression.
+ *
+ * Component authors do NOT need to wire this directly — see
+ * `installAriaIdrefMirror()` for an installable observer that keeps an inner
+ * node's `aria-*` attributes in sync with the token list across mutations.
+ */
+/**
+ * Resolves a whitespace-separated IDREF token list to live element references.
+ *
+ * Searches the host's containing root first (Document or ShadowRoot), then
+ * walks up through enclosing shadow hosts, and finally falls back to the
+ * top-level Document. Codex round-15 P1: hx-* controls embedded inside an
+ * outer component's shadow tree often legitimately reference labels/descriptions
+ * declared in the outer document or in an ancestor shadow tree. Restricting
+ * resolution to a single root left those controls anonymous on the
+ * `ariaLabelledByElements` / `ariaDescribedByElements` path. The IDL
+ * element-references API accepts any element regardless of root, so widening
+ * the search closes that gap.
+ *
+ * Codex round-16 P1: when the host is **slotted into** another component
+ * (light-DOM child of a shadow-root-bearing element), `host.getRootNode()`
+ * is still the document, so IDREF targets declared in the slot owner's
+ * shadow root are unreachable through the ancestor-shadow-host chain. We
+ * additionally walk `host.assignedSlot.getRootNode()` — that resolves to
+ * the slot owner's shadow root — and continue up that root's host chain so
+ * cross-shadow IDREF resolution works for the composed-tree slotting
+ * pattern. The walk is recursive: a slot owner that is itself slotted into
+ * another shadow tree contributes its own ancestor chain too.
+ *
+ * Tokens that fail to resolve at every level are silently dropped — matching
+ * native attribute-string platform behaviour where unresolved tokens are
+ * ignored.
+ */
+export declare function resolveIdrefTokens(host: Element, tokens: string | null): Element[];
+/**
+ * True when the runtime exposes the IDL element-references API on
+ * `ElementInternals`. Older Firefox / Safari builds return `undefined`
+ * for these accessors.
+ */
+export declare function supportsIdrefElementReferences(internals: ElementInternals): boolean;
+/**
+ * Mirror snapshot describing what should be applied to inner ARIA-bearing
+ * shadow nodes. Components consume this to project the correct attributes
+ * onto whichever inner element owns the announced semantic role.
+ */
+export interface AriaIdrefSnapshot {
+    /** Computed `aria-labelledby` token list, or `null` to omit. */
+    labelledBy: string | null;
+    /** Computed `aria-describedby` token list, or `null` to omit. */
+    describedBy: string | null;
+}
+/**
+ * Merges two whitespace-separated token lists, preserving order and removing
+ * duplicates. `null`/empty inputs are skipped. Returns `null` when the merged
+ * list is empty.
+ */
+export declare function mergeTokenLists(...lists: Array<string | null | undefined>): string | null;
+/**
+ * Options accepted by `installAriaIdrefMirror()`.
+ */
+export interface AriaIdrefMirrorOptions {
+    /**
+     * Attribute names on the host whose mutations should trigger a resync.
+     * Defaults to `['aria-labelledby', 'aria-describedby', 'aria-label']` plus
+     * the `data-aria-*` mirrors used by `mixinDelegatesAria`.
+     */
+    observedAttributes?: string[];
+    /**
+     * Whether to observe the resolved root for `id` attribute and `childList`
+     * mutations so that late-inserted IDREF targets and id renames trigger a
+     * resync. Defaults to `true`.
+     */
+    observeRoot?: boolean;
+}
+/**
+ * Handle returned by `installAriaIdrefMirror()`. Call `disconnect()` from
+ * `disconnectedCallback()` to tear the observers down. `resync()` forces an
+ * immediate sync — useful from `connectedCallback()` after the host has been
+ * re-attached to a new root.
+ */
+export interface AriaIdrefMirrorHandle {
+    /** Force an immediate sync. */
+    resync(): void;
+    /** Tear down all observers and listeners. */
+    disconnect(): void;
+}
+/**
+ * Installs a `MutationObserver` pair that keeps host ARIA semantics in sync
+ * with mutations to consumer-supplied attributes AND late-target / id
+ * mutations in the host's resolved root.
+ *
+ * The `sync` callback is invoked on:
+ *   1. Initial install (synchronously)
+ *   2. Any change to one of the observed host attributes
+ *   3. Any `id` attribute mutation, child insertion, or child removal in the
+ *      resolved root (Document or ShadowRoot containing the host)
+ *
+ * Components should call this from `connectedCallback()` and call
+ * `handle.disconnect()` from `disconnectedCallback()`. The handle's
+ * `resync()` method is safe to call from any lifecycle hook.
+ *
+ * Costs are bounded: the host observer touches one element; the root
+ * observer is shared per `Document`/`ShadowRoot` (codex round-7 #11) so every
+ * subscribing host pays a single attach cost regardless of how many other
+ * IDREF-aware controls share the root.
+ */
+export declare function installAriaIdrefMirror(host: Element, sync: () => void, options?: AriaIdrefMirrorOptions): AriaIdrefMirrorHandle;
+//# sourceMappingURL=aria-idref.d.ts.map

package/dist/utils/aria-idref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aria-idref.d.ts","sourceRoot":"","sources":["../../src/utils/aria-idref.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,EAAE,CA6BlF;AAsGD;;;;GAIG;AACH,wBAAgB,8BAA8B,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAOnF;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,gEAAgE;IAChE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,iEAAiE;IACjE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,KAAK,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,MAAM,GAAG,IAAI,CAazF;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,+BAA+B;IAC/B,MAAM,IAAI,IAAI,CAAC;IACf,6CAA6C;IAC7C,UAAU,IAAI,IAAI,CAAC;CACpB;AAoGD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,MAAM,IAAI,EAChB,OAAO,GAAE,sBAA2B,GACnC,qBAAqB,CAsGvB"}

package/dist/utils/menu-label.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Read the typeahead label for a menu item — the item's OWN text content
+ * EXCLUDING any nested submenu subtree projected through `slot="submenu"`.
+ *
+ * Codex push-gate round-6 finding 3 (hx-menu) + round-7 finding 3 (composites):
+ * a naive `item.textContent` walks the entire light-DOM tree, which on a
+ * parent menuitem includes the slotted nested `<hx-menu>` and its descendants.
+ * Typing the first letter of a child item then matches the parent (because
+ * the parent's subtree contains that text), causing first-character nav to
+ * focus the parent instead of the next sibling. Filter `slot="submenu"` out.
+ *
+ * Single source of truth for `hx-menu`, `hx-dropdown`, `hx-overflow-menu`,
+ * and `hx-split-button` typeahead matchers.
+ *
+ * @internal
+ */
+export declare function getMenuItemTypeaheadLabel(item: Element): string;
+//# sourceMappingURL=menu-label.d.ts.map

package/dist/utils/menu-label.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"menu-label.d.ts","sourceRoot":"","sources":["../../src/utils/menu-label.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAS/D"}

package/dist/utils/menu-roving.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Write the roving tabindex value through the right surface for each menu
+ * item shape used inside `hx-menu`, `hx-dropdown`, `hx-overflow-menu`, and
+ * `hx-split-button` panels.
+ *
+ * Codex push-gate round-2 (hx-overflow-menu) + round-8 finding 2
+ * (hx-dropdown): host-canonical `hx-menu-item` cannot be addressed via the
+ * raw `tabIndex` setter on the host because:
+ *
+ * - On the modern path the host carries the announced role + IDL ARIA, so
+ *   the roving tabindex must land on the host (so Tab and arrow advance to
+ *   the announced surface).
+ * - On the fallback path the host is forced to `tabindex=-1` so the inner
+ *   `.menu-item` element is the single focusable surface; the roving
+ *   tabindex must land on the inner element.
+ *
+ * `hx-menu-item.setRovingTabIndex(value)` routes to the correct surface
+ * internally. For plain slotted `[role="menuitem"]` elements (legacy
+ * `<button>` / `<a>` children), fall back to the direct `tabIndex` write
+ * so consumers without `hx-menu-item` keep working.
+ *
+ * Single source of truth across hx-dropdown, hx-overflow-menu, etc. so
+ * future host-canonical menu shapes only have to teach this helper.
+ *
+ * @internal
+ */
+export declare function writeMenuItemRovingTabIndex(item: HTMLElement, value: number): void;
+//# sourceMappingURL=menu-roving.d.ts.map

package/dist/utils/menu-roving.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"menu-roving.d.ts","sourceRoot":"","sources":["../../src/utils/menu-roving.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAUlF"}

package/dist/utils/menu-tree.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Composed-tree walkers for the `hx-menu` family.
+ *
+ * Extracted from `hx-menu.ts` (codex push-gate round-9) because the same
+ * walks are now needed by `hx-dropdown`, `hx-overflow-menu`, and
+ * `hx-split-button` to route nested `hx-item-submenu-open` /
+ * `hx-item-submenu-close` events to the correct parent. Keeping the helpers
+ * in a shared util avoids importing `hx-menu.ts` from the composites
+ * (cyclic) and keeps the tag-name string checks in one place.
+ *
+ * @module
+ */
+/**
+ * Walks the composed tree from `start` outward and returns the closest
+ * enclosing `<hx-menu>` element, or `null` if none exists. Crosses both
+ * shadow boundaries (`getRootNode().host`) and slot boundaries
+ * (`assignedSlot`) so an item nested inside a submenu resolves to the
+ * inner menu, not the outer one. Codex push-gate round-4 P1.
+ *
+ * Returned as `Element` (rather than the concrete `HelixMenu` class) to
+ * avoid a circular import between `hx-menu` and this util; callers can
+ * narrow with `instanceof HelixMenu` if they need typed access.
+ *
+ * @internal
+ */
+export declare function findClosestMenuAncestor(start: Element): Element | null;
+/**
+ * Returns the `hx-menu-item` that owns `menu` as a nested submenu, or
+ * `null` if `menu` is a top-level menu (not slotted into a parent item's
+ * `slot="submenu"`). Used by ArrowLeft handling to close the correct
+ * submenu and return focus to the right parent. Codex push-gate round-4
+ * P1.
+ *
+ * Returned as `HTMLElement` (rather than the concrete `HelixMenuItem`
+ * class) to avoid a circular import with `hx-menu-item`; callers can
+ * narrow with `instanceof HelixMenuItem` if they need typed access.
+ *
+ * @internal
+ */
+export declare function findOwningMenuItem(menu: Element): HTMLElement | null;
+//# sourceMappingURL=menu-tree.d.ts.map

package/dist/utils/menu-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"menu-tree.d.ts","sourceRoot":"","sources":["../../src/utils/menu-tree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CAiCtE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAWpE"}

package/dist/utils/tree-walk.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Composed-tree walkers for the `hx-tree-view` family.
+ *
+ * Mirrors the `menu-tree.ts` utilities (codex push-gate round-9 extraction
+ * for the menu family), but specialized for `hx-tree-view` / `hx-tree-item`
+ * where nesting is structural rather than slot-based — child items live in a
+ * named `slot="children"` projected into the parent item's shadow root,
+ * and any number of nesting levels are legal.
+ *
+ * Group 5c (codex push-gate round-1 lift): `hx-tree-view`'s host-bound
+ * keydown / select handlers receive bubbled events from EVERY descendant
+ * tree-item, including ones that legitimately belong to an inner
+ * `hx-tree-view`. The same guard pattern that `hx-menu` uses (act only when
+ * THIS host is the closest enclosing surface of the dispatching item) is
+ * required for trees too. `hx-tree-item._handleClick` /
+ * `_handleKeyDown` need to ignore bubbled events from a CHILD `hx-tree-item`
+ * — otherwise selecting Child also activates Parent and Enter on Child
+ * re-fires Parent's handler.
+ *
+ * @module
+ */
+/**
+ * Walks the composed tree from `start` outward and returns the closest
+ * enclosing `<hx-tree-view>` element, or `null` if none exists. Crosses
+ * shadow boundaries (`getRootNode().host`) and slot boundaries
+ * (`assignedSlot`) so that an item nested inside a child tree-item — which
+ * lives in the parent item's `slot="children"`, projected into the parent's
+ * shadow root — resolves to the correct enclosing tree.
+ *
+ * Returned as `Element` to avoid a circular import between `hx-tree-view`
+ * and this util; callers narrow with `instanceof HelixTreeView` if needed.
+ *
+ * @internal
+ */
+export declare function findClosestTreeView(start: Element): Element | null;
+/**
+ * Walks the composed tree from `start` outward and returns the closest
+ * enclosing `<hx-tree-item>` element, or `null` if none exists. Includes
+ * `start` itself when it is an `hx-tree-item`.
+ *
+ * Used by `hx-tree-item`'s `_isOwnEvent` origin guard: a click or keydown
+ * is "ours" iff the closest `hx-tree-item` ancestor of the original event
+ * target is THIS item (not a child item slotted into our `children` slot).
+ * The walk crosses shadow + slot boundaries so a deeply nested child item
+ * resolves correctly.
+ *
+ * Returned as `Element` to avoid a circular import; callers narrow with
+ * `instanceof HelixTreeItem` if needed.
+ *
+ * @internal
+ */
+export declare function findClosestTreeItem(start: Element): Element | null;
+//# sourceMappingURL=tree-walk.d.ts.map

package/dist/utils/tree-walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-walk.d.ts","sourceRoot":"","sources":["../../src/utils/tree-walk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CAsBlE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CAsBlE"}

package/figma-inventory.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-05-03T13:42:50.577Z",
+  "generatedAt": "2026-05-06T11:01:35.731Z",
   "sourceCem": "custom-elements.json",
-  "helixVersion": "3.3.1",
+  "helixVersion": "3.4.0",
   "tokensVersion": "3.3.1",
   "components": [
     {
@@ -5519,6 +5519,30 @@
           "type": "text",
           "defaultValue": ""
         },
+        {
+          "figmaPropertyName": "label",
+          "cemAttribute": "label",
+          "type": "text",
+          "defaultValue": "undefined"
+        },
+        {
+          "figmaPropertyName": "accessibleLabel",
+          "cemAttribute": "accessible-label",
+          "type": "text",
+          "defaultValue": "undefined"
+        },
+        {
+          "figmaPropertyName": "helpText",
+          "cemAttribute": "help-text",
+          "type": "text",
+          "defaultValue": "undefined"
+        },
+        {
+          "figmaPropertyName": "error",
+          "cemAttribute": "error",
+          "type": "text",
+          "defaultValue": "undefined"
+        },
         {
           "figmaPropertyName": "labelGradient",
           "cemAttribute": "label-gradient",
@@ -5569,6 +5593,27 @@
           "type": "instance-swap",
           "default": null,
           "description": "Custom trigger element. Default: a color swatch button."
+        },
+        {
+          "figmaPropertyName": "label",
+          "cemSlot": "label",
+          "type": "instance-swap",
+          "default": null,
+          "description": "Visible label projected above the trigger; aggregated text contributes to the host's accessible name when no stronger naming source (aria-labelledby/aria-label/accessible-label/label) is supplied."
+        },
+        {
+          "figmaPropertyName": "help-text",
+          "cemSlot": "help-text",
+          "type": "instance-swap",
+          "default": null,
+          "description": "Help text rendered below the trigger and joined into the host's announced description channel."
+        },
+        {
+          "figmaPropertyName": "error",
+          "cemSlot": "error",
+          "type": "instance-swap",
+          "default": null,
+          "description": "Error message rendered below help text. When present, marks the trigger as aria-invalid and is announced via a polite live region."
         }
       ],
       "cssParts": [
@@ -5599,6 +5644,18 @@
         {
           "description": "The text input area.",
           "name": "input"
+        },
+        {
+          "description": "The visible label container above the trigger.",
+          "name": "label"
+        },
+        {
+          "description": "The help-text container rendered below the trigger.",
+          "name": "help-text"
+        },
+        {
+          "description": "The error-message container rendered below help text.",
+          "name": "error"
         }
       ],
       "events": [
@@ -7808,6 +7865,12 @@
           "cemAttribute": "next-month-label",
           "type": "text",
           "defaultValue": "Next month"
+        },
+        {
+          "figmaPropertyName": "accessibleLabel",
+          "cemAttribute": "accessible-label",
+          "type": "text",
+          "defaultValue": "null"
         }
       ],
       "slots": [
@@ -11396,6 +11459,17 @@
             "true"
           ],
           "default": "false"
+        },
+        {
+          "figmaAxisName": "loading",
+          "cemAttribute": "loading",
+          "cemFieldName": "loading",
+          "type": "boolean",
+          "values": [
+            "false",
+            "true"
+          ],
+          "default": "false"
         }
       ],
       "textProperties": [
@@ -11442,6 +11516,10 @@
         {
           "description": "The icon container span wrapping the default slot.",
           "name": "icon"
+        },
+        {
+          "description": "The loading spinner SVG element shown when `loading` is true.",
+          "name": "spinner"
         }
       ],
       "events": [
@@ -11918,6 +11996,12 @@
           "cemAttribute": "rel",
           "type": "text",
           "defaultValue": "undefined"
+        },
+        {
+          "figmaPropertyName": "externalLabel",
+          "cemAttribute": "external-label",
+          "type": "text",
+          "defaultValue": "(opens in new tab)"
         }
       ],
       "slots": [
@@ -12685,7 +12769,7 @@
       "figmaEligible": true,
       "figmaComponentName": "hx-menu-item",
       "figmaPagePlacement": "4a",
-      "description": "A single interactive item for use inside `hx-menu`. Supports normal, checkbox, and radio types, loading state, prefix/suffix slots, and submenu nesting. Use `aria-label` on the parent `hx-menu` to…",
+      "description": "A single interactive item for use inside `hx-menu`. Supports normal, checkbox, and radio types, loading state, prefix/suffix slots, and submenu nesting.",
       "tier": "atom",
       "variantAxes": [
         {
@@ -12807,18 +12891,18 @@
           "description": "Dispatched when the item is activated via click, Enter, or Space."
         },
         {
-          "name": "hx-item-submenu-open",
           "type": {
             "text": "CustomEvent<{item: HelixMenuItem}>"
           },
-          "description": "Dispatched when ArrowRight is pressed on an item with a submenu."
+          "description": "Dispatched when ArrowRight is pressed on an item with a submenu.",
+          "name": "hx-item-submenu-open"
         },
         {
-          "name": "hx-item-submenu-close",
           "type": {
             "text": "CustomEvent<{item: HelixMenuItem}>"
           },
-          "description": "Dispatched when ArrowLeft is pressed on an item, signaling the parent to close the submenu and return focus."
+          "description": "Dispatched when ArrowLeft is pressed on an item, signaling the parent to close the submenu and return focus.",
+          "name": "hx-item-submenu-close"
         }
       ],
       "cssProperties": [
@@ -17071,6 +17155,13 @@
             "text": "CustomEvent<{value: string}>"
           },
           "description": "Dispatched when the selected option changes."
+        },
+        {
+          "type": {
+            "text": "Event"
+          },
+          "description": "Platform constraint-validation event fired when checkValidity() / reportValidity() determine the value is invalid (form-associated component contract via ElementInternals.setValidity).",
+          "name": "invalid"
         }
       ],
       "cssProperties": [
@@ -21641,7 +21732,7 @@
       "figmaEligible": true,
       "figmaComponentName": "hx-tab-panel",
       "figmaPagePlacement": "4a",
-      "description": "A content panel associated with an `<hx-tab>`, managed by a parent `<hx-tabs>`.",
+      "description": "A content panel associated with an `<hx-tab>`, managed by a parent `<hx-tabs>`. Group 5a host-canonical: `role=\"tabpanel\"` lives on the host via `_internals.role`. The host carries the canonical AT…",
       "tier": "atom",
       "variantAxes": [],
       "textProperties": [
@@ -21980,7 +22071,7 @@
             "manual",
             "automatic"
           ],
-          "default": "automatic"
+          "default": "manual"
         }
       ],
       "textProperties": [
@@ -24138,31 +24229,46 @@
       ],
       "cssParts": [
         {
-          "description": "The inner slot wrapper element. `display: contents` — no layout effect.",
+          "description": "The inner slot wrapper element. `display: contents` — no layout effect. Theme-injected CSS custom properties (semantic surface — full token catalog lives in `@helixui/tokens`; the wildcard `--hx-*` was previously documented here but the CEM cssProperties[] surface requires explicit names).",
           "name": "base"
         }
       ],
       "events": [],
       "cssProperties": [
         {
-          "description": "All design tokens for the selected theme are injected as CSS custom properties on the host element.",
-          "name": "--hx-*",
+          "description": "Primary text color (theme-injected).",
+          "name": "--hx-color-text-primary",
           "figmaBinding": null
         },
         {
-          "description": "Color.",
-          "name": "--hx-color-text-primary",
+          "description": "Base surface background (theme-injected).",
+          "name": "--hx-color-surface-base",
           "figmaBinding": null
         },
         {
-          "description": "Spacing token.",
+          "description": "Default border color (theme-injected).",
+          "name": "--hx-color-border-default",
+          "figmaBinding": null
+        },
+        {
+          "description": "Spacing token (theme-injected).",
           "name": "--hx-space-4",
           "figmaBinding": null
         },
         {
-          "description": "Animation duration.",
+          "description": "Animation duration (theme-injected).",
           "name": "--hx-duration-fast",
           "figmaBinding": null
+        },
+        {
+          "description": "Medium border-radius (theme-injected).",
+          "name": "--hx-radius-md",
+          "figmaBinding": null
+        },
+        {
+          "description": "Body font family (theme-injected).",
+          "name": "--hx-font-family-body",
+          "figmaBinding": null
         }
       ],
       "dependsOn": [],
@@ -24255,6 +24361,12 @@
           "cemAttribute": "error",
           "type": "text",
           "defaultValue": ""
+        },
+        {
+          "figmaPropertyName": "accessibleLabel",
+          "cemAttribute": "accessible-label",
+          "type": "text",
+          "defaultValue": "null"
         }
       ],
       "slots": [
@@ -25087,7 +25199,7 @@
       "events": [],
       "cssProperties": [
         {
-          "description": "Z-index for the fixed stack.",
+          "description": "Z-index for the fixed stack. ─── ARIA scope (group-6 §3.2 / §5.9) ───────────────────────────────────── `hx-toast-stack` deliberately has NO `role`, `aria-live`, `aria-atomic`, or `aria-relevant` on its host or inner container. Each child `hx-toast` is its own live region (role=alert/status via ElementInternals). Wrapping those toasts in a second live region (e.g. `role=\"log\"` on the stack) would create nested live regions, which causes older NVDA/JAWS to announce every toast TWICE — once for the toast's own role, once for the surrounding log region. The stack is purely a positional/z-index container; it is invisible to the AT tree. Do NOT add a container role unless this entire architecture is rewritten so individual toasts no longer carry their own roles.",
           "name": "--hx-z-index-toast",
           "default": "9000",
           "figmaBinding": {
@@ -26205,7 +26317,7 @@
           "name": "item"
         },
         {
-          "description": "The interactive item row (contains expand icon, icon slot, and label).",
+          "description": "The interactive item row (presentational on the modern path; carries role=\"treeitem\" + aria-* on the legacy fallback).",
           "name": "row"
         },
         {
@@ -26217,7 +26329,7 @@
           "name": "label"
         },
         {
-          "description": "The children container.",
+          "description": "The children container (always carries role=\"group\").",
           "name": "children"
         }
       ],
@@ -26361,7 +26473,7 @@
       ],
       "cssParts": [
         {
-          "description": "The tree container element with role=\"tree\".",
+          "description": "The tree container element with role=\"tree\" (legacy fallback path) or the inner shadow surface (modern path; role lives on the host).",
           "name": "tree"
         }
       ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helixui/library",
-  "version": "3.3.1",
+  "version": "3.4.0",
   "description": "Enterprise Web Component Library built with Lit 3.x",
   "type": "module",
   "sideEffects": [