@helixui/library 3.3.1-next.118 → 3.4.0-next.121

package/custom-elements.json

@@ -2,269 +2,6 @@
   "schemaVersion": "1.0.0",
   "readme": "",
   "modules": [
-    {
-      "kind": "javascript-module",
-      "path": "src/components/hx-action-bar/hx-action-bar.ts",
-      "declarations": [
-        {
-          "kind": "class",
-          "description": "A horizontal toolbar container for grouping related action buttons and controls.\nImplements the ARIA toolbar pattern with roving tabindex keyboard navigation.",
-          "name": "HelixActionBar",
-          "cssProperties": [
-            {
-              "description": "Bar background color (default variant).",
-              "name": "--hx-action-bar-bg",
-              "default": "transparent"
-            },
-            {
-              "description": "Bar border (default variant).",
-              "name": "--hx-action-bar-border",
-              "default": "none"
-            },
-            {
-              "description": "Inner padding.",
-              "name": "--hx-action-bar-padding",
-              "default": "var(--hx-space-2,0.5rem) var(--hx-space-3,0.75rem)"
-            },
-            {
-              "description": "Gap between slotted items.",
-              "name": "--hx-action-bar-gap",
-              "default": "var(--hx-space-2,0.5rem)"
-            },
-            {
-              "description": "Z-index when sticky or bottom position.",
-              "name": "--hx-action-bar-z-index",
-              "default": "10"
-            },
-            {
-              "description": "Padding.",
-              "name": "--hx-action-bar-padding-block-start",
-              "default": "0px"
-            },
-            {
-              "description": "Padding.",
-              "name": "--hx-action-bar-padding-block-end",
-              "default": "0px"
-            },
-            {
-              "description": "CSS custom property.",
-              "name": "--hx-border-radius-md"
-            },
-            {
-              "description": "Width.",
-              "name": "--hx-border-width-thin"
-            },
-            {
-              "description": "Color.",
-              "name": "--hx-color-neutral-0"
-            },
-            {
-              "description": "Color.",
-              "name": "--hx-color-neutral-200"
-            },
-            {
-              "description": "Color.",
-              "name": "--hx-color-neutral-50"
-            },
-            {
-              "description": "Size token.",
-              "name": "--hx-size-8"
-            },
-            {
-              "description": "Size token.",
-              "name": "--hx-size-10"
-            },
-            {
-              "description": "Size token.",
-              "name": "--hx-size-12"
-            },
-            {
-              "description": "Spacing token.",
-              "name": "--hx-space-1"
-            },
-            {
-              "description": "Spacing token.",
-              "name": "--hx-space-2"
-            },
-            {
-              "description": "Spacing token.",
-              "name": "--hx-space-3"
-            },
-            {
-              "description": "Spacing token.",
-              "name": "--hx-space-4"
-            }
-          ],
-          "cssParts": [
-            {
-              "description": "The root toolbar container element.",
-              "name": "base"
-            },
-            {
-              "description": "The start (left) slot wrapper.",
-              "name": "start"
-            },
-            {
-              "description": "The center (default) slot wrapper.",
-              "name": "center"
-            },
-            {
-              "description": "The end (right) slot wrapper.",
-              "name": "end"
-            },
-            {
-              "description": "The overflow slot wrapper (hidden when no overflow content).",
-              "name": "overflow"
-            }
-          ],
-          "slots": [
-            {
-              "description": "Left-aligned actions.",
-              "name": "start"
-            },
-            {
-              "description": "Center content (default slot).",
-              "name": ""
-            },
-            {
-              "description": "Right-aligned actions.",
-              "name": "end"
-            },
-            {
-              "description": "Actions revealed when the bar is constrained for space.",
-              "name": "overflow"
-            }
-          ],
-          "members": [
-            {
-              "kind": "field",
-              "name": "size",
-              "type": {
-                "text": "'sm' | 'md' | 'lg'"
-              },
-              "default": "'md'",
-              "description": "Size of the action bar — propagated as a data attribute to slotted children.",
-              "attribute": "hx-size",
-              "reflects": true
-            },
-            {
-              "kind": "field",
-              "name": "variant",
-              "type": {
-                "text": "'default' | 'outlined' | 'filled'"
-              },
-              "default": "'default'",
-              "description": "Visual variant controlling the bar background.",
-              "attribute": "variant",
-              "reflects": true
-            },
-            {
-              "kind": "field",
-              "name": "position",
-              "type": {
-                "text": "'top' | 'bottom' | 'sticky'"
-              },
-              "default": "'top'",
-              "description": "Position and sticky behavior of the action bar.\n- `top` — normal flow (default)\n- `sticky` — sticks to the top of the scroll container; add `scroll-padding-top` to the\n  scroll container equal to the bar height to prevent anchor targets from scrolling behind it\n- `bottom` — sticks to the bottom of the scroll container with iOS safe-area-inset support",
-              "attribute": "position",
-              "reflects": true
-            },
-            {
-              "kind": "field",
-              "name": "accessibleLabel",
-              "type": {
-                "text": "string"
-              },
-              "default": "''",
-              "description": "Accessible label for the toolbar.\nRequired when multiple toolbars appear on the same page.\n\nAccepts both `accessible-label` and the standard `aria-label` HTML attribute.\nThe `accessible-label` attribute takes precedence when both are set.\n\nPreviously this was exposed as the `ariaLabel` JS property, which shadowed\nthe native `HTMLElement.ariaLabel`. That shadowing is removed; use\n`accessibleLabel` or the HTML attributes instead.",
-              "attribute": "accessible-label"
-            }
-          ],
-          "attributes": [
-            {
-              "name": "hx-size",
-              "type": {
-                "text": "'sm' | 'md' | 'lg'"
-              },
-              "default": "'md'",
-              "description": "Size of the action bar — propagated as a data attribute to slotted children.",
-              "fieldName": "size",
-              "attribute": "hx-size"
-            },
-            {
-              "name": "variant",
-              "type": {
-                "text": "'default' | 'outlined' | 'filled'"
-              },
-              "default": "'default'",
-              "description": "Visual variant controlling the bar background.",
-              "fieldName": "variant",
-              "attribute": "variant"
-            },
-            {
-              "name": "position",
-              "type": {
-                "text": "'top' | 'bottom' | 'sticky'"
-              },
-              "default": "'top'",
-              "description": "Position and sticky behavior of the action bar.\n- `top` — normal flow (default)\n- `sticky` — sticks to the top of the scroll container; add `scroll-padding-top` to the\n  scroll container equal to the bar height to prevent anchor targets from scrolling behind it\n- `bottom` — sticks to the bottom of the scroll container with iOS safe-area-inset support",
-              "fieldName": "position",
-              "attribute": "position"
-            },
-            {
-              "name": "accessible-label",
-              "type": {
-                "text": "string"
-              },
-              "default": "''",
-              "description": "Accessible label for the toolbar.\nRequired when multiple toolbars appear on the same page.\n\nAccepts both `accessible-label` and the standard `aria-label` HTML attribute.\nThe `accessible-label` attribute takes precedence when both are set.\n\nPreviously this was exposed as the `ariaLabel` JS property, which shadowed\nthe native `HTMLElement.ariaLabel`. That shadowing is removed; use\n`accessibleLabel` or the HTML attributes instead.",
-              "fieldName": "accessibleLabel",
-              "attribute": "accessible-label"
-            }
-          ],
-          "superclass": {
-            "name": "HelixElement",
-            "module": "/src/base/index.js"
-          },
-          "tagName": "hx-action-bar",
-          "customElement": true,
-          "summary": "Horizontal action bar for grouping related controls."
-        }
-      ],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "HelixActionBar",
-          "declaration": {
-            "name": "HelixActionBar",
-            "module": "src/components/hx-action-bar/hx-action-bar.ts"
-          }
-        },
-        {
-          "kind": "custom-element-definition",
-          "name": "hx-action-bar",
-          "declaration": {
-            "name": "HelixActionBar",
-            "module": "src/components/hx-action-bar/hx-action-bar.ts"
-          }
-        }
-      ]
-    },
-    {
-      "kind": "javascript-module",
-      "path": "src/components/hx-action-bar/index.ts",
-      "declarations": [],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "HelixActionBar",
-          "declaration": {
-            "name": "HelixActionBar",
-            "module": "./hx-action-bar.js"
-          }
-        }
-      ]
-    },
     {
       "kind": "javascript-module",
       "path": "src/components/hx-accordion/hx-accordion-item.ts",
@@ -585,6 +322,269 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/components/hx-action-bar/hx-action-bar.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "A horizontal toolbar container for grouping related action buttons and controls.\nImplements the ARIA toolbar pattern with roving tabindex keyboard navigation.",
+          "name": "HelixActionBar",
+          "cssProperties": [
+            {
+              "description": "Bar background color (default variant).",
+              "name": "--hx-action-bar-bg",
+              "default": "transparent"
+            },
+            {
+              "description": "Bar border (default variant).",
+              "name": "--hx-action-bar-border",
+              "default": "none"
+            },
+            {
+              "description": "Inner padding.",
+              "name": "--hx-action-bar-padding",
+              "default": "var(--hx-space-2,0.5rem) var(--hx-space-3,0.75rem)"
+            },
+            {
+              "description": "Gap between slotted items.",
+              "name": "--hx-action-bar-gap",
+              "default": "var(--hx-space-2,0.5rem)"
+            },
+            {
+              "description": "Z-index when sticky or bottom position.",
+              "name": "--hx-action-bar-z-index",
+              "default": "10"
+            },
+            {
+              "description": "Padding.",
+              "name": "--hx-action-bar-padding-block-start",
+              "default": "0px"
+            },
+            {
+              "description": "Padding.",
+              "name": "--hx-action-bar-padding-block-end",
+              "default": "0px"
+            },
+            {
+              "description": "CSS custom property.",
+              "name": "--hx-border-radius-md"
+            },
+            {
+              "description": "Width.",
+              "name": "--hx-border-width-thin"
+            },
+            {
+              "description": "Color.",
+              "name": "--hx-color-neutral-0"
+            },
+            {
+              "description": "Color.",
+              "name": "--hx-color-neutral-200"
+            },
+            {
+              "description": "Color.",
+              "name": "--hx-color-neutral-50"
+            },
+            {
+              "description": "Size token.",
+              "name": "--hx-size-8"
+            },
+            {
+              "description": "Size token.",
+              "name": "--hx-size-10"
+            },
+            {
+              "description": "Size token.",
+              "name": "--hx-size-12"
+            },
+            {
+              "description": "Spacing token.",
+              "name": "--hx-space-1"
+            },
+            {
+              "description": "Spacing token.",
+              "name": "--hx-space-2"
+            },
+            {
+              "description": "Spacing token.",
+              "name": "--hx-space-3"
+            },
+            {
+              "description": "Spacing token.",
+              "name": "--hx-space-4"
+            }
+          ],
+          "cssParts": [
+            {
+              "description": "The root toolbar container element.",
+              "name": "base"
+            },
+            {
+              "description": "The start (left) slot wrapper.",
+              "name": "start"
+            },
+            {
+              "description": "The center (default) slot wrapper.",
+              "name": "center"
+            },
+            {
+              "description": "The end (right) slot wrapper.",
+              "name": "end"
+            },
+            {
+              "description": "The overflow slot wrapper (hidden when no overflow content).",
+              "name": "overflow"
+            }
+          ],
+          "slots": [
+            {
+              "description": "Left-aligned actions.",
+              "name": "start"
+            },
+            {
+              "description": "Center content (default slot).",
+              "name": ""
+            },
+            {
+              "description": "Right-aligned actions.",
+              "name": "end"
+            },
+            {
+              "description": "Actions revealed when the bar is constrained for space.",
+              "name": "overflow"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "size",
+              "type": {
+                "text": "'sm' | 'md' | 'lg'"
+              },
+              "default": "'md'",
+              "description": "Size of the action bar — propagated as a data attribute to slotted children.",
+              "attribute": "hx-size",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "variant",
+              "type": {
+                "text": "'default' | 'outlined' | 'filled'"
+              },
+              "default": "'default'",
+              "description": "Visual variant controlling the bar background.",
+              "attribute": "variant",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "position",
+              "type": {
+                "text": "'top' | 'bottom' | 'sticky'"
+              },
+              "default": "'top'",
+              "description": "Position and sticky behavior of the action bar.\n- `top` — normal flow (default)\n- `sticky` — sticks to the top of the scroll container; add `scroll-padding-top` to the\n  scroll container equal to the bar height to prevent anchor targets from scrolling behind it\n- `bottom` — sticks to the bottom of the scroll container with iOS safe-area-inset support",
+              "attribute": "position",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "accessibleLabel",
+              "type": {
+                "text": "string"
+              },
+              "default": "''",
+              "description": "Accessible label for the toolbar.\nRequired when multiple toolbars appear on the same page.\n\nAccepts both `accessible-label` and the standard `aria-label` HTML attribute.\nThe `accessible-label` attribute takes precedence when both are set.\n\nPreviously this was exposed as the `ariaLabel` JS property, which shadowed\nthe native `HTMLElement.ariaLabel`. That shadowing is removed; use\n`accessibleLabel` or the HTML attributes instead.",
+              "attribute": "accessible-label"
+            }
+          ],
+          "attributes": [
+            {
+              "name": "hx-size",
+              "type": {
+                "text": "'sm' | 'md' | 'lg'"
+              },
+              "default": "'md'",
+              "description": "Size of the action bar — propagated as a data attribute to slotted children.",
+              "fieldName": "size",
+              "attribute": "hx-size"
+            },
+            {
+              "name": "variant",
+              "type": {
+                "text": "'default' | 'outlined' | 'filled'"
+              },
+              "default": "'default'",
+              "description": "Visual variant controlling the bar background.",
+              "fieldName": "variant",
+              "attribute": "variant"
+            },
+            {
+              "name": "position",
+              "type": {
+                "text": "'top' | 'bottom' | 'sticky'"
+              },
+              "default": "'top'",
+              "description": "Position and sticky behavior of the action bar.\n- `top` — normal flow (default)\n- `sticky` — sticks to the top of the scroll container; add `scroll-padding-top` to the\n  scroll container equal to the bar height to prevent anchor targets from scrolling behind it\n- `bottom` — sticks to the bottom of the scroll container with iOS safe-area-inset support",
+              "fieldName": "position",
+              "attribute": "position"
+            },
+            {
+              "name": "accessible-label",
+              "type": {
+                "text": "string"
+              },
+              "default": "''",
+              "description": "Accessible label for the toolbar.\nRequired when multiple toolbars appear on the same page.\n\nAccepts both `accessible-label` and the standard `aria-label` HTML attribute.\nThe `accessible-label` attribute takes precedence when both are set.\n\nPreviously this was exposed as the `ariaLabel` JS property, which shadowed\nthe native `HTMLElement.ariaLabel`. That shadowing is removed; use\n`accessibleLabel` or the HTML attributes instead.",
+              "fieldName": "accessibleLabel",
+              "attribute": "accessible-label"
+            }
+          ],
+          "superclass": {
+            "name": "HelixElement",
+            "module": "/src/base/index.js"
+          },
+          "tagName": "hx-action-bar",
+          "customElement": true,
+          "summary": "Horizontal action bar for grouping related controls."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "HelixActionBar",
+          "declaration": {
+            "name": "HelixActionBar",
+            "module": "src/components/hx-action-bar/hx-action-bar.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "hx-action-bar",
+          "declaration": {
+            "name": "HelixActionBar",
+            "module": "src/components/hx-action-bar/hx-action-bar.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/components/hx-action-bar/index.ts",
+      "declarations": [],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "HelixActionBar",
+          "declaration": {
+            "name": "HelixActionBar",
+            "module": "./hx-action-bar.js"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/components/hx-alert/hx-alert.ts",
@@ -11177,7 +11177,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "A slide-in drawer panel that can appear from any edge of the viewport.\nSupports focus trapping, overlay backdrop, keyboard navigation, and full\nARIA labelling for enterprise healthcare accessibility requirements.\n\n## Architecture Note: Native `<dialog>` Migration\n\nThis component currently uses `role=\"dialog\"` + `aria-modal=\"true\"` on a\n`<div>` rather than the native `<dialog>` element. This is intentional for\nthe current release because:\n\n1. **SSR compatibility**: Native `<dialog>` requires `showModal()` to activate\n   its modal behavior (focus trapping, backdrop, top-layer). This JavaScript\n   call is not available during server-side rendering, which is a primary\n   consumption pattern for Drupal/Twig templates.\n\n2. **Contained mode**: The `contained` property constrains the drawer to a\n   positioned parent. Native `<dialog>` in modal mode renders in the top layer\n   and cannot be constrained to a parent element.\n\n3. **Animation control**: The current CSS transition approach provides precise\n   control over slide-in/slide-out animations. Native `<dialog>` `::backdrop`\n   animations have inconsistent cross-browser support.\n\nMigration to native `<dialog>` is tracked as a future enhancement. When browser\nsupport for `CloseWatcher`, `::backdrop` transitions, and declarative dialog\nopening stabilizes, this component will be migrated to native semantics.",
+          "description": "A slide-in drawer panel that can appear from any edge of the viewport.\nSupports focus trapping, overlay backdrop, keyboard navigation, and full\nARIA labelling for enterprise healthcare accessibility requirements.\n\n## Architecture Note: Host-Canonical ARIA (group-4 round-1, Path A)\n\nThe host carries the announced dialog semantics via `ElementInternals`:\n\n  - `internals.role = 'dialog'` (the host IS the dialog surface)\n  - `internals.ariaModal = 'true'` (modality declared on host)\n  - `internals.ariaLabelledByElements` / `internals.ariaDescribedByElements`\n    project consumer light-DOM IDREFs across the shadow boundary.\n  - `internals.ariaLabel` carries the resolved fallback name when no\n    IDREF chain or slotted title exists.\n\nThe inner `<div part=\"overlay\">` no longer carries `role`, `aria-modal`,\n`aria-labelledby`, or `aria-label` — those would create a nested-dialog\nannouncement above the host's canonical surface. Belt-and-suspenders\nfallback: when the runtime does NOT expose IDL element references on\n`ElementInternals` (older Firefox / Safari builds), the resolved label\ntext is text-flattened and written to the inner overlay's `aria-label`\nso AT walking down from the host still finds an announceable name.\n\nNaming precedence (W3C AccName 1.2 §4.3.1):\n\n  1. Consumer `aria-labelledby` on the host — IDREFs resolved across the\n     shadow boundary via `resolveIdrefTokens` (same scope walk used by\n     every host-canonical hx-* control: own root → ancestor shadow hosts\n     → owner document → slot owners).\n  2. Consumer `aria-label` on the host.\n  3. `<slot name=\"label\">` text content (multi-node aggregation per\n     AccName 1.2 §4.3.10 — decorative `aria-hidden` / `[hidden]` subtrees\n     contribute zero to the name).\n  4. `label` property — explicit author fallback string.\n  5. Hard-coded literal `\"Drawer\"` (last-resort accessible name).\n\nDescription channel: a synthesized `<span id=\"${id}-consumer-desc\">` is\nrendered inside the shadow root and updated to mirror consumer-resolved\ndescription text. The host's `internals.ariaDescribedByElements` carries\nthe live element references on the modern path; the in-shadow span is the\nfallback target for AT that does not walk IDL refs. `aria-description` is\nintentionally NEVER written — the W3C AccName algorithm ignores it\nwhenever `aria-describedby` is also present.\n\nSlot mutation observers track:\n  1. The label slot's text content (in-place i18n re-renders).\n  2. Consumer-resolved external IDREF targets (so a consumer mutating\n     `<label id=\"x\">Patient</label>` in place re-flows the name).\n  3. Host attribute mutations (delegated to `installAriaIdrefMirror`,\n     which also catches late-inserted IDREF targets and id renames in\n     every relevant root).\n\nFocus trap, ESC dismiss, focus-restore, and the inert-outside-content\nsibling-walk are unchanged from the pre-host-canonical implementation —\nthey operate against the shadow-internal panel which is still the focus\ntarget for keyboard users.\n\n## Architecture Note: Native `<dialog>` Migration\n\nThis component currently uses `role=\"dialog\"` + `aria-modal=\"true\"` on a\n`<div>` rather than the native `<dialog>` element. This is intentional for\nthe current release because:\n\n1. **SSR compatibility**: Native `<dialog>` requires `showModal()` to activate\n   its modal behavior (focus trapping, backdrop, top-layer). This JavaScript\n   call is not available during server-side rendering, which is a primary\n   consumption pattern for Drupal/Twig templates.\n\n2. **Contained mode**: The `contained` property constrains the drawer to a\n   positioned parent. Native `<dialog>` in modal mode renders in the top layer\n   and cannot be constrained to a parent element.\n\n3. **Animation control**: The current CSS transition approach provides precise\n   control over slide-in/slide-out animations. Native `<dialog>` `::backdrop`\n   animations have inconsistent cross-browser support.\n\nMigration to native `<dialog>` is tracked as a future enhancement. When browser\nsupport for `CloseWatcher`, `::backdrop` transitions, and declarative dialog\nopening stabilizes, this component will be migrated to native semantics.",
           "name": "HelixDrawer",
           "cssProperties": [
             {
@@ -11682,7 +11682,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "A dropdown component — a button that opens a floating panel on click.\n\n## Architecture Note: Host-Attribute Label Mirror (group-4 round-1)\n\nThe announced surface is the inner `[part=\"panel\"]` element, which carries\n`role=\"menu\"`. The host wraps a slotted trigger and the floating panel and\ndoes NOT claim a role itself (apart from the round-35-style host\n`aria-expanded` fallback used only when the trigger slot is empty).\n\nBecause the panel lives in shadow DOM and `ElementInternals` IDL refs on\nthe host project semantics OUTWARD (host → AT) rather than INWARD\n(host → shadow descendant), we use the **host-attribute mirror** pattern:\nresolve consumer `aria-labelledby` IDREFs against the host's composed-tree\nroots, text-flatten via `flattenAccName`, and write the result to the\npanel's `aria-label`. Host `aria-label` outranks the `label` property in\nthe same precedence used by every host-canonical hx-* control.\n\nNaming precedence (W3C AccName 1.2 §4.3.1):\n  1. Host `aria-labelledby` (resolved IDREFs, text-flattened)\n  2. Host `aria-label`\n  3. `label` property\n  4. Hard-coded literal `\"Menu\"` (last-resort accessible name)\n\n**Group 5 boundary (intentional):** This round is **additive only** — the\nhost-label pipeline is the entire change. The panel's `role=\"menu\"` and\nthe menuitem-roving keyboard pattern are already implemented per APG and\nare NOT touched here. Group 5 (composite navigation: menu, menubar,\nmenuitem, tabs, tree) will own any broader refactor of the menu role and\nroving-tabindex semantics. Codex reviewers: please scope findings to the\nhost-label pipeline; do not flag missing roving-focus / typeahead /\n`aria-orientation` work here.\n\n`aria-controls` is intentionally omitted on the trigger: the panel lives\nin shadow DOM and IDREF values cannot be resolved across shadow\nboundaries by assistive technology (axe-core flags this as a critical\nviolation if attempted). See `_setupTriggerAria` for the inline note.",
+          "description": "A dropdown component — a button that opens a floating panel on click.\n\n## Architecture Note: Host-Attribute Label Mirror (group-4 round-1)\n\nThe announced surface is the inner `[part=\"panel\"]` element, which carries\n`role=\"menu\"`. The host wraps a slotted trigger and the floating panel and\ndoes NOT claim a role itself (apart from the round-35-style host\n`aria-expanded` fallback used only when the trigger slot is empty).\n\nBecause the panel lives in shadow DOM and `ElementInternals` IDL refs on\nthe host project semantics OUTWARD (host → AT) rather than INWARD\n(host → shadow descendant), we use the **host-attribute mirror** pattern:\nresolve consumer `aria-labelledby` IDREFs against the host's composed-tree\nroots, text-flatten via `flattenAccName`, and write the result to the\npanel's `aria-label`. Host `aria-label` outranks the `label` property in\nthe same precedence used by every host-canonical hx-* control.\n\nNaming precedence (W3C AccName 1.2 §4.3.1):\n  1. Host `aria-labelledby` (resolved IDREFs, text-flattened)\n  2. Host `aria-label`\n  3. `label` property\n  4. Hard-coded literal `\"Menu\"` (last-resort accessible name)\n\n**Group 4b → Group 5b boundary:** Group 4b added the host-attribute\nlabel mirror **only** — additive on top of the existing dropdown\nbehaviour. Group 5b (this commit) adds the composite-navigation\nportion that 4b explicitly deferred:\n  - **Roving tabindex** inside the panel (`_applyRovingTabIndex` +\n    `_rovingIndex`). Only the focused item carries `tabindex=0`.\n  - **First-character typeahead** with 500ms timeout (`_handleTypeahead`)\n    matching `hx-menu`, `hx-overflow-menu`, `hx-split-button`.\n  - Submenu auto-handling is delegated to slotted `hx-menu` /\n    `hx-menu-item` (whose `hx-item-submenu-open` / `hx-item-submenu-close`\n    events are auto-handled by the parent `hx-menu` after Group 5b).\n\nThe panel's inner-div `role=\"menu\"` is intentionally NOT migrated to\nthe host: the host wraps a slotted consumer trigger AND the panel,\nso it cannot canonically carry the menu role. Slotted `hx-menu-item`\nchildren carry `role=\"menuitem\"` on their HOST after Group 5b's menu\nmigration, which fixes the cross-shadow walk concern from the\nconsumer's perspective.\n\n`aria-controls` is intentionally omitted on the trigger: the panel lives\nin shadow DOM and IDREF values cannot be resolved across shadow\nboundaries by assistive technology (axe-core flags this as a critical\nviolation if attempted). See `_setupTriggerAria` for the inline note.",
           "name": "HelixDropdown",
           "cssProperties": [
             {
@@ -14613,6 +14613,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"
             }
           ],
           "slots": [
@@ -14675,6 +14679,17 @@
               "attribute": "disabled",
               "reflects": true
             },
+            {
+              "kind": "field",
+              "name": "loading",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether the button is in a loading state. Shows the spinner, prevents\nactivation, and sets `aria-busy=\"true\"` on the inner element. Does NOT\nset the native `disabled` attribute (loading is transient; disabled is\npersistent, and AT announces them differently).",
+              "attribute": "loading",
+              "reflects": true
+            },
             {
               "kind": "field",
               "name": "href",
@@ -14784,6 +14799,16 @@
               "fieldName": "disabled",
               "attribute": "disabled"
             },
+            {
+              "name": "loading",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether the button is in a loading state. Shows the spinner, prevents\nactivation, and sets `aria-busy=\"true\"` on the inner element. Does NOT\nset the native `disabled` attribute (loading is transient; disabled is\npersistent, and AT announces them differently).",
+              "fieldName": "loading",
+              "attribute": "loading"
+            },
             {
               "name": "href",
               "type": {
@@ -14815,6 +14840,12 @@
               "attribute": "value"
             }
           ],
+          "mixins": [
+            {
+              "name": "mixinDelegatesAria",
+              "module": "/src/mixins/index.js"
+            }
+          ],
           "superclass": {
             "name": "HelixElement",
             "module": "/src/base/index.js"
@@ -15455,6 +15486,16 @@
               "default": "undefined",
               "description": "Relationship between the current document and the linked URL.\nAutomatically set to \"noopener noreferrer\" when target=\"_blank\".",
               "attribute": "rel"
+            },
+            {
+              "kind": "field",
+              "name": "externalLabel",
+              "type": {
+                "text": "string"
+              },
+              "default": "'(opens in new tab)'",
+              "description": "Localised announcement text appended (visually hidden) to the link's\naccessible name when `target=\"_blank\"`. Defaults to English. Override\nfor i18n contexts so AT users hear the new-tab notice in their locale.",
+              "attribute": "external-label"
             }
           ],
           "events": [
@@ -15526,6 +15567,22 @@
               "description": "Relationship between the current document and the linked URL.\nAutomatically set to \"noopener noreferrer\" when target=\"_blank\".",
               "fieldName": "rel",
               "attribute": "rel"
+            },
+            {
+              "name": "external-label",
+              "type": {
+                "text": "string"
+              },
+              "default": "'(opens in new tab)'",
+              "description": "Localised announcement text appended (visually hidden) to the link's\naccessible name when `target=\"_blank\"`. Defaults to English. Override\nfor i18n contexts so AT users hear the new-tab notice in their locale.",
+              "fieldName": "externalLabel",
+              "attribute": "external-label"
+            }
+          ],
+          "mixins": [
+            {
+              "name": "mixinDelegatesAria",
+              "module": "/src/mixins/index.js"
             }
           ],
           "superclass": {
@@ -15585,7 +15642,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "A rich list item for use inside `hx-list`.",
+          "description": "A rich list item for use inside `hx-list`.\n\nGroup 7 host-canonical: `role=\"option\"` (interactive listbox mode) is\nmirrored onto the **host** via `_internals.role` AND the legacy\nsetAttribute('role',...) path. The dual-surface pattern preserves the\nexisting imperative host-attribute behaviour (so consumers querying\n`host.getAttribute('role')` still work) while adding cross-shadow IDREF\nwiring through `internals.ariaLabelledByElements` for engines that\nsupport it.",
           "name": "HelixListItem",
           "cssProperties": [
             {
@@ -15830,7 +15887,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "A styled list container supporting plain, bulleted, numbered, description, and interactive variants.",
+          "description": "A styled list container supporting plain, bulleted, numbered, description, and interactive variants.\n\nGroup 7 host-canonical: `role=\"list\"` (or `role=\"listbox\"` in interactive\nmode) lives on the **host** via `_internals.role`, harmonizing with\n`hx-structured-list` (the gold-standard exemplar for Group 7). The `<dl>`\ndescription variant keeps native semantics — no host role assigned, since\n`<dl>` IS the semantic surface and AT walks it directly.",
           "name": "HelixList",
           "cssProperties": [
             {
@@ -16000,7 +16057,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "A visual separator for grouping items within an `hx-menu`.",
+          "description": "A visual separator for grouping items within an `hx-menu`.\n\nGroup 5b host-canonical: `role=\"separator\"` lives on the **host** via\n`_internals.role` so the parent `<hx-menu>` (`role=\"menu\"`) sees the\nseparator as a direct child. `aria-orientation` is mirrored onto the host\nvia `internals.ariaOrientation`. The inner div is presentational on the\nmodern path and stripped of its role; the legacy fallback keeps the\ninner role for engines without ElementInternals IDL accessors.",
           "name": "HelixMenuDivider",
           "cssProperties": [
             {
@@ -16050,7 +16107,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "A single interactive item for use inside `hx-menu`. Supports normal, checkbox,\nand radio types, loading state, prefix/suffix slots, and submenu nesting.\nUse `aria-label` on the parent `hx-menu` to provide an accessible name.",
+          "description": "A single interactive item for use inside `hx-menu`. Supports normal, checkbox,\nand radio types, loading state, prefix/suffix slots, and submenu nesting.\n\nGroup 5b host-canonical: `role=\"menuitem\"` (or `menuitemcheckbox` /\n`menuitemradio` based on `type`) lives on the **host** via\n`_internals.role`. The roving tabindex is written to the host, so the host\nis the focusable surface and lands directly under the parent `<hx-menu>`\n(which carries `role=\"menu\"`) in the AT walked tree. The inner element is\npresentational on the modern path — no role, no aria-* attributes — and\ncarries only click/keyboard event handlers. Keyboard activation\n(Enter/Space) is owned by the host's `keydown` handler.\n\nCross-shadow naming: consumer-supplied `aria-label` / `aria-labelledby` on\nthe host project to `internals.ariaLabel` / `internals.ariaLabelledByElements`\nvia the shared IDREF mirror. The slotted text content is used as the default\naccessible name when no override is set (AT walks slotted children\nautomatically through the host's role).",
           "name": "HelixMenuItem",
           "cssProperties": [
             {
@@ -16198,7 +16255,7 @@
                   }
                 }
               ],
-              "description": "Focus the inner interactive element."
+              "description": "Focus the menu item. On the modern host-canonical path, focus lands on\nthe host (which carries the roving tabindex and announced role). On the\nlegacy fallback path, focus delegates to the inner element which still\ncarries the role."
             }
           ],
           "events": [
@@ -16210,18 +16267,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"
             }
           ],
           "attributes": [
@@ -16310,7 +16367,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "A menu container that manages keyboard navigation over a list of menu items.\nUse with `hx-menu-item` and `hx-menu-divider`.",
+          "description": "A menu container that manages keyboard navigation over a list of menu items.\nUse with `hx-menu-item` and `hx-menu-divider`.\n\nGroup 5b host-canonical: `role=\"menu\"` lives on the **host** via\n`_internals.role`. The host carries the announced surface so AT walks\n`<hx-menu>` (role=menu) → slotted `<hx-menu-item>` (role=menuitem on host)\ndirectly without two layers of indirection. Consumer-supplied\n`aria-label` / `aria-labelledby` on the host are resolved via the shared\nIDREF mirror; cross-shadow naming uses `ariaLabelledByElements` (modern)\nwith a flattened-string fallback (legacy).\n\nSubmenu coordination: when an `hx-menu-item` emits `hx-item-submenu-open`\nor `hx-item-submenu-close`, the parent menu auto-handles the toggle by\ncalling `setSubmenuOpen()` on the item — UNLESS the consumer has called\n`event.preventDefault()` on the bubbled event, signaling that they own the\nsubmenu lifecycle. This matches APG-mandated behaviour while leaving an\nopt-out for advanced consumers.",
           "name": "HelixMenu",
           "cssProperties": [
             {
@@ -16387,7 +16444,7 @@
                 "text": "string"
               },
               "default": "''",
-              "description": "Accessible label for the menu. Rendered as `aria-label` on the inner\n`role=\"menu\"` element when set.",
+              "description": "Accessible label for the menu. Used as a fallback when no consumer-supplied\n`aria-label` / `aria-labelledby` is present on the host. On the modern\nhost-canonical path this projects onto `internals.ariaLabel`; on the\nlegacy fallback path it appears as `aria-label` on the inner div.",
               "attribute": "label",
               "reflects": true
             },
@@ -16435,7 +16492,7 @@
                 "text": "string"
               },
               "default": "''",
-              "description": "Accessible label for the menu. Rendered as `aria-label` on the inner\n`role=\"menu\"` element when set.",
+              "description": "Accessible label for the menu. Used as a fallback when no consumer-supplied\n`aria-label` / `aria-labelledby` is present on the host. On the modern\nhost-canonical path this projects onto `internals.ariaLabel`; on the\nlegacy fallback path it appears as `aria-label` on the inner div.",
               "fieldName": "label",
               "attribute": "label"
             }
@@ -16505,7 +16562,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "A scalar measurement within a known range — e.g., disk usage, health score,\nor any numeric value with defined min/max bounds. Supports low/high/optimum\nthreshold markers for semantic color feedback.",
+          "description": "A scalar measurement within a known range — e.g., disk usage, health score,\nor any numeric value with defined min/max bounds. Supports low/high/optimum\nthreshold markers for semantic color feedback.\n\nGroup 7 host-canonical: `role=\"meter\"` is mirrored onto the **host** via\n`_internals.role` AND kept on the inner `[role=\"meter\"]` element. The dual\nsurface is the hx-progress-ring pattern (Group 7 gold-standard exemplar):\nthe host carries the cross-shadow IDREF wiring (`ariaLabelledByElements`\nresolves through the shared mirror) while the inner element keeps its\nexisting role/state surface so legacy AT and consumer queries continue to\nwork. AccName 1.2 §4.3.1 precedence is implemented uniformly: consumer\nhost `aria-labelledby` (flattened) > consumer host `aria-label` >\n`label` property / slotted label > derived value-text fallback.",
           "name": "HelixMeter",
           "cssProperties": [
             {
@@ -17909,7 +17966,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "An overflow menu (kebab/meatball menu) that reveals hidden actions via a\nfloating panel. Composed from a trigger button and a slotted menu panel.",
+          "description": "An overflow menu (kebab/meatball menu) that reveals hidden actions via a\nfloating panel. Composed from a trigger button and a slotted menu panel.\n\n## Architecture Note: Host-Attribute Trigger Label Mirror (group-5b)\n\nThe composite has TWO ARIA-bearing surfaces inside its shadow DOM: the\ntrigger button (`role` defaulted from `<button>`, with `aria-haspopup`,\n`aria-expanded`, `aria-controls`) and the panel (`role=\"menu\"` on the\ninner div). The host wraps both — it cannot carry either canonical role\nitself, so role placement remains on the inner elements.\n\nWhat Group 5b adds:\n- **Roving tabindex** on slotted menu items (only the focused item has\n  tabindex=0; arrow keys move focus and rewrite tabindex). Closing-Tab\n  path is preserved (Tab moves focus past the menu and closes it).\n- **First-character typeahead** with 500ms timeout matching `hx-menu`.\n- **Host-attribute label mirror**: consumer-supplied `aria-label` /\n  `aria-labelledby` on the host flow to the trigger button's\n  `aria-label` (the trigger is the announced surface of the disclosure\n  pattern; consumer override wins over the `label` property). The panel\n  continues to use `labelMenu` for its own slot label.",
           "name": "HelixOverflowMenu",
           "cssProperties": [
             {
@@ -18128,7 +18185,7 @@
                 "text": "string"
               },
               "default": "'More actions'",
-              "description": "Accessible label for the trigger button.",
+              "description": "Accessible label for the trigger button. Used as a fallback when no\nconsumer-supplied `aria-label` / `aria-labelledby` is present on the\nhost. Consumer host attributes win in the AccName 1.2 §4.3.1 cascade.",
               "attribute": "label",
               "reflects": true
             },
@@ -18214,7 +18271,7 @@
                 "text": "string"
               },
               "default": "'More actions'",
-              "description": "Accessible label for the trigger button.",
+              "description": "Accessible label for the trigger button. Used as a fallback when no\nconsumer-supplied `aria-label` / `aria-labelledby` is present on the\nhost. Consumer host attributes win in the AccName 1.2 §4.3.1 cascade.",
               "fieldName": "label",
               "attribute": "label"
             },
@@ -19334,11 +19391,6 @@
               "name": "--hx-phi-field-disabled-opacity",
               "default": "var(--hx-opacity-50,0.5)"
             },
-            {
-              "description": "Color for auto-hide countdown warning (future use).",
-              "name": "--hx-phi-field-auto-hide-warning-color",
-              "default": "var(--hx-color-warning-500,#C2711C)"
-            },
             {
               "description": "Spacing token.",
               "name": "--hx-space-2"
@@ -20383,7 +20435,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "A linear progress indicator for determinate and indeterminate states.",
+          "description": "A linear progress indicator for determinate and indeterminate states.\n\nGroup 7 host-canonical: `role=\"progressbar\"` is mirrored onto the **host**\nvia `_internals.role` (cross-shadow IDREF wiring) AND kept on the inner\n`[role=\"progressbar\"]` track for legacy AT and consumer queries. This is\nthe hx-progress-ring dual-surface pattern (Group 7 gold-standard).\nConsumer-supplied `aria-labelledby` / `aria-describedby` on the host\nresolves through the shared IDREF mirror so cross-shadow naming reaches\nthe announced surface even when the labels live in another shadow tree.\n\nThe internal `aria-live=\"polite\"` announcer for the \"Complete\" milestone\nis preserved (`role=\"progressbar\"` does NOT imply a live region — an\nexplicit live announcer is required for value-update announcements).",
           "name": "HelixProgressBar",
           "cssProperties": [
             {
@@ -22695,6 +22747,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"
             }
           ],
           "attributes": [
@@ -24433,7 +24492,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "A split button combining a primary action button with an attached dropdown\nmenu for secondary actions. Implements the ARIA menu button pattern for\nfull keyboard and screen reader support.",
+          "description": "A split button combining a primary action button with an attached dropdown\nmenu for secondary actions. Implements the ARIA menu button pattern for\nfull keyboard and screen reader support.\n\n## Architecture Note: Composite host with two interactive children (Group 5b)\n\nThe host wraps a primary `<button>`, a dropdown trigger `<button>`, and a\npanel `<div role=\"menu\">` — three ARIA-bearing surfaces that cannot all\ncollapse onto the host. Group 5b keeps role placement on the inner\nelements (consistent with `hx-overflow-menu`). The host carries no role.\n\nWhat Group 5b adds:\n- **Host-attribute label mirror** via `installAriaIdrefMirror`: consumer\n  `aria-label` / `aria-labelledby` on the host flow to the inner primary\n  button's `aria-label`. Replaces the legacy `accessible-label` shim,\n  which was a workaround for ARIAMixin shadowing on the host. The shim\n  is preserved with a one-time devWarn for one minor version of back-\n  compat; new code should use the standard `aria-label` attribute.\n- **Roving tabindex** on slotted `hx-menu-item` children inside the\n  panel. Only the focused item carries `tabindex=0`; arrow key\n  navigation rewrites the tabindex map via `_applyRovingTabIndex()`.\n  `setRovingTabIndex` is the same setter used by `hx-menu` for cross-\n  family pattern alignment.\n- **First-character typeahead** with 500ms timeout matching `hx-menu`.",
           "name": "HelixSplitButton",
           "cssProperties": [
             {
@@ -24732,7 +24791,7 @@
                 "text": "string"
               },
               "default": "''",
-              "description": "Accessible label for the primary action button. Required for icon-only usage\nor when the button label alone is insufficient context.\nUses `accessible-label` attribute instead of `aria-label` to avoid\nARIAMixin shadowing on the host element.\n\nNote: `mixinDelegatesAria` is not applied to this component because the\n`accessible-label` attribute approach avoids the ARIAMixin property conflict\nwithout requiring mixin overhead.",
+              "deprecated": "Use the standard host `aria-label` attribute instead. Group\n5b replaces the `accessible-label` shim with a host-attribute mirror\ndriven by `installAriaIdrefMirror` — consumer host `aria-label` /\n`aria-labelledby` flow to the inner primary button's `aria-label`,\nwhich is the same composed-tree result as the legacy shim without\nthe ARIAMixin shadowing concern.\n\nThe attribute remains observed for one minor version so existing\nconsumers do not regress; setting it logs a devWarn pointing them to\nthe standard `aria-label` path.",
               "attribute": "accessible-label"
             },
             {
@@ -24819,7 +24878,7 @@
                 "text": "string"
               },
               "default": "''",
-              "description": "Accessible label for the primary action button. Required for icon-only usage\nor when the button label alone is insufficient context.\nUses `accessible-label` attribute instead of `aria-label` to avoid\nARIAMixin shadowing on the host element.\n\nNote: `mixinDelegatesAria` is not applied to this component because the\n`accessible-label` attribute approach avoids the ARIAMixin property conflict\nwithout requiring mixin overhead.",
+              "deprecated": "Use the standard host `aria-label` attribute instead. Group\n5b replaces the `accessible-label` shim with a host-attribute mirror\ndriven by `installAriaIdrefMirror` — consumer host `aria-label` /\n`aria-labelledby` flow to the inner primary button's `aria-label`,\nwhich is the same composed-tree result as the legacy shim without\nthe ARIAMixin shadowing concern.\n\nThe attribute remains observed for one minor version so existing\nconsumers do not regress; setting it logs a devWarn pointing them to\nthe standard `aria-label` path.",
               "fieldName": "accessibleLabel",
               "attribute": "accessible-label"
             },
@@ -25507,7 +25566,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "A static stat display component for presenting key metrics in a healthcare dashboard.",
+          "description": "A static stat display component for presenting key metrics in a healthcare dashboard.\n\nGroup 7 host-canonical: `role=\"group\"` lives on the **host** via\n`_internals.role`. The host carries the resolved accessible name so AT\nwalks `<hx-stat>` (role=group, label=\"value: label\") directly. The\ninternal `aria-live=\"polite\"` announcer remains in the shadow tree —\n`role=\"group\"` does NOT imply a live region, so the announcer is required\nfor value/label/trend update announcements.",
           "name": "HelixStat",
           "cssProperties": [
             {
@@ -27972,7 +28031,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Semantic table data cell. Must be a child of `hx-tr`.",
+          "description": "Semantic table data cell. Must be a child of `hx-tr`.\n\nGroup 7 host-canonical: `role=\"cell\"` lives on the **host** via\n`_internals.role`. The host carries the cell's accessible name (resolved\nfrom the `label` property — fixing audit B-A1, where mobile screen reader\nusers lost column context because `data-label` was visual-only).",
           "name": "HelixTableCell",
           "cssProperties": [
             {
@@ -28032,7 +28091,7 @@
                 "text": "string"
               },
               "default": "''",
-              "description": "Column header label for this cell. Forwarded as `data-label` on the native `<td>` for\nthe mobile card layout (`td::before { content: attr(data-label) }`) and as `aria-label`\nso screen readers identify the column when the header row is hidden.",
+              "description": "Column header label for this cell. Forwarded as `data-label` on the native\n`<td>` for the mobile card layout (`td::before { content: attr(data-label) }`)\nAND projected to `aria-label` so screen readers identify the column when\nthe header row is hidden via the mobile breakpoint. Group 7 audit B-A1\nfix: prior to migration, the JSDoc claimed aria-label projection but the\nimplementation only set `data-label` — `::before { content: attr(...) }`\nis not reliably announced by VoiceOver / NVDA across versions.",
               "attribute": "label"
             }
           ],
@@ -28073,7 +28132,7 @@
                 "text": "string"
               },
               "default": "''",
-              "description": "Column header label for this cell. Forwarded as `data-label` on the native `<td>` for\nthe mobile card layout (`td::before { content: attr(data-label) }`) and as `aria-label`\nso screen readers identify the column when the header row is hidden.",
+              "description": "Column header label for this cell. Forwarded as `data-label` on the native\n`<td>` for the mobile card layout (`td::before { content: attr(data-label) }`)\nAND projected to `aria-label` so screen readers identify the column when\nthe header row is hidden via the mobile breakpoint. Group 7 audit B-A1\nfix: prior to migration, the JSDoc claimed aria-label projection but the\nimplementation only set `data-label` — `::before { content: attr(...) }`\nis not reliably announced by VoiceOver / NVDA across versions.",
               "fieldName": "label",
               "attribute": "label"
             }
@@ -28161,7 +28220,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Semantic table header cell. Must be a child of `hx-tr`.\nSupports sortable columns with accessible sort state.",
+          "description": "Semantic table header cell. Must be a child of `hx-tr`.\nSupports sortable columns with accessible sort state.\n\nGroup 7 host-canonical: `role=\"columnheader\"` lives on the **host** via\n`_internals.role`. The host carries `aria-sort` reflecting the current\nsort direction (when `sortable` is true). The sort `<button>` aria-label\nincorporates the slotted column text so AT users hear \"Sort by Patient\nname, currently sorted ascending\" rather than just \"Sort ascending\".",
           "name": "HelixTableHeader",
           "cssParts": [
             {
@@ -28377,7 +28436,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Semantic table row. Must be a child of `hx-thead`, `hx-tbody`, or `hx-tfoot`.\nContains `hx-th` or `hx-td` cells.",
+          "description": "Semantic table row. Must be a child of `hx-thead`, `hx-tbody`, or `hx-tfoot`.\nContains `hx-th` or `hx-td` cells.\n\nGroup 7 host-canonical: `role=\"row\"` lives on the **host** via\n`_internals.role`. The host carries `aria-selected` / `aria-disabled`\nmirroring `selected` / `disabled` reflected attributes. Consumer-supplied\n`aria-label` / `aria-labelledby` on the host project to the host's\nannounced surface so AT walks `<hx-tr>` (role=row) directly. Fallback\npath keeps the inner `<tr role=\"row\">` as the announced surface for\nengines without IDL element references.",
           "name": "HelixTableRow",
           "cssParts": [
             {
@@ -28542,7 +28601,7 @@
       "declarations": [
         {
           "kind": "class",
-          "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>`.\nGroup 5a host-canonical: `role=\"tabpanel\"` lives on the host via\n`_internals.role`. The host carries the canonical AT surface — consumer\n`aria-labelledby` / `aria-describedby` on the host resolve through the\nshared IDREF mirror. The parent `hx-tabs` writes `internals.ariaLabelledByElements`\nreferencing the corresponding `<hx-tab>` host so cross-shadow naming works\nvia IDL element references (the modern path) without serializing tab text.",
           "name": "HelixTabPanel",
           "cssProperties": [
             {
@@ -28632,7 +28691,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "An individual tab button, designed to be used inside an `<hx-tabs>` container.\nMust be placed in the `tab` named slot of `<hx-tabs>`.",
+          "description": "An individual tab button, designed to be used inside an `<hx-tabs>` container.\nMust be placed in the `tab` named slot of `<hx-tabs>`.\n\nGroup 5a host-canonical: `role=\"tab\"` lives on the **host** via\n`_internals.role`. The host is the focusable surface (carries the roving\ntabindex); the inner `<button>` retains click activation semantics\n(Enter/Space and pointer events) but is no longer the AT-announced surface\n— its role and ARIA state are stripped on the modern path so the host's\ncanonical surface wins. `internals.ariaSelected`, `ariaDisabled`, and\n`ariaControlsElements` mirror reactive state. The host `aria-label` /\n`aria-labelledby` resolved via the shared IDREF mirror name the tab\ncross-shadow.",
           "name": "HelixTab",
           "cssProperties": [
             {
@@ -28825,7 +28884,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "A tabbed content organizer that manages a set of `<hx-tab>` and `<hx-tab-panel>` children.\nSupports horizontal and vertical orientations, automatic and manual activation modes,\nand full keyboard navigation per the ARIA Authoring Practices Guide.",
+          "description": "A tabbed content organizer that manages a set of `<hx-tab>` and `<hx-tab-panel>` children.\nSupports horizontal and vertical orientations, automatic and manual activation modes,\nand full keyboard navigation per the ARIA Authoring Practices Guide.\n\nGroup 5a host-canonical: `role=\"tablist\"` lives on the host via\n`_internals.role`. `aria-orientation`, `aria-label`, and consumer\n`aria-labelledby` resolve through the host. Per-tab `role=\"tab\"` and\nper-panel `role=\"tabpanel\"` likewise live on their respective hosts.\n\nActivation defaults to **manual** per healthcare patterns — keyboard arrow\nkeys move focus only; Enter/Space activates. APG explicitly allows both\nautomatic and manual activation; manual is safer when panels are heavy or\nannounce changes via live regions.",
           "name": "HelixTabs",
           "cssProperties": [
             {
@@ -28974,8 +29033,8 @@
               "type": {
                 "text": "'manual' | 'automatic'"
               },
-              "default": "'automatic'",
-              "description": "Controls how keyboard navigation activates tabs.\nIn `automatic` mode, focus also activates the tab.\nIn `manual` mode, focus moves independently; Space or Enter activates.",
+              "default": "'manual'",
+              "description": "Controls how keyboard navigation activates tabs.\nIn `automatic` mode, focus also activates the tab.\nIn `manual` mode, focus moves independently; Space or Enter activates.\n\nGroup 5a default: `manual` — safer for healthcare patterns where panel\ncontent may be heavy or announce updates via live regions. APG explicitly\nallows both modes; manual avoids disorienting auto-activation when users\nscan tabs with arrow keys.",
               "attribute": "activation",
               "reflects": true
             },
@@ -28986,7 +29045,7 @@
                 "text": "string"
               },
               "default": "''",
-              "description": "Accessible label for the tablist. Rendered as `aria-label` on the tablist container.\nProvide a brief description of what the tabs represent (e.g., \"Patient record sections\").",
+              "description": "Accessible label for the tablist. Drives the host `internals.ariaLabel`.\nProvide a brief description of what the tabs represent (e.g., \"Patient\nrecord sections\"). Consumer `aria-label` / `aria-labelledby` on the host\noverride this property when present.",
               "attribute": "label",
               "reflects": true
             },
@@ -29027,8 +29086,8 @@
               "type": {
                 "text": "'manual' | 'automatic'"
               },
-              "default": "'automatic'",
-              "description": "Controls how keyboard navigation activates tabs.\nIn `automatic` mode, focus also activates the tab.\nIn `manual` mode, focus moves independently; Space or Enter activates.",
+              "default": "'manual'",
+              "description": "Controls how keyboard navigation activates tabs.\nIn `automatic` mode, focus also activates the tab.\nIn `manual` mode, focus moves independently; Space or Enter activates.\n\nGroup 5a default: `manual` — safer for healthcare patterns where panel\ncontent may be heavy or announce updates via live regions. APG explicitly\nallows both modes; manual avoids disorienting auto-activation when users\nscan tabs with arrow keys.",
               "fieldName": "activation",
               "attribute": "activation"
             },
@@ -29038,7 +29097,7 @@
                 "text": "string"
               },
               "default": "''",
-              "description": "Accessible label for the tablist. Rendered as `aria-label` on the tablist container.\nProvide a brief description of what the tabs represent (e.g., \"Patient record sections\").",
+              "description": "Accessible label for the tablist. Drives the host `internals.ariaLabel`.\nProvide a brief description of what the tabs represent (e.g., \"Patient\nrecord sections\"). Consumer `aria-label` / `aria-labelledby` on the host\noverride this property when present.",
               "fieldName": "label",
               "attribute": "label"
             }
@@ -31135,25 +31194,37 @@
           "name": "HelixTheme",
           "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"
             },
             {
-              "description": "Color.",
-              "name": "--hx-color-text-primary"
+              "description": "Base surface background (theme-injected).",
+              "name": "--hx-color-surface-base"
             },
             {
-              "description": "Spacing token.",
+              "description": "Default border color (theme-injected).",
+              "name": "--hx-color-border-default"
+            },
+            {
+              "description": "Spacing token (theme-injected).",
               "name": "--hx-space-4"
             },
             {
-              "description": "Animation duration.",
+              "description": "Animation duration (theme-injected).",
               "name": "--hx-duration-fast"
+            },
+            {
+              "description": "Medium border-radius (theme-injected).",
+              "name": "--hx-radius-md"
+            },
+            {
+              "description": "Body font family (theme-injected).",
+              "name": "--hx-font-family-body"
             }
           ],
           "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"
             }
           ],
@@ -31737,6 +31808,16 @@
               "attribute": "format",
               "reflects": true
             },
+            {
+              "kind": "field",
+              "name": "accessibleLabel",
+              "type": {
+                "text": "string | null"
+              },
+              "default": "null",
+              "description": "Accessible name for screen readers, if different from the visible label.\nUses `accessible-label` attribute instead of `aria-label` to avoid\nARIAMixin shadowing on the host element. Highest-precedence naming source.",
+              "attribute": "accessible-label"
+            },
             {
               "kind": "field",
               "name": "_id",
@@ -31872,6 +31953,16 @@
               "description": "Display format for the time input. '12h' shows AM/PM; '24h' is bare HH:MM.",
               "fieldName": "format",
               "attribute": "format"
+            },
+            {
+              "name": "accessible-label",
+              "type": {
+                "text": "string | null"
+              },
+              "default": "null",
+              "description": "Accessible name for screen readers, if different from the visible label.\nUses `accessible-label` attribute instead of `aria-label` to avoid\nARIAMixin shadowing on the host element. Highest-precedence naming source.",
+              "fieldName": "accessibleLabel",
+              "attribute": "accessible-label"
             }
           ],
           "mixins": [
@@ -31941,7 +32032,7 @@
           "name": "HelixToastStack",
           "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"
             }
@@ -33559,7 +33650,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "A tree item used within an hx-tree-view component.\nSupports expand/collapse, selection, keyboard navigation, and icon/children slots.",
+          "description": "A tree item used within an hx-tree-view component.\nSupports expand/collapse, selection, keyboard navigation, and icon/children slots.\n\nGroup 5c host-canonical: `role=\"treeitem\"` lives on the **host** via\n`_internals.role`. The roving tabindex is written to the host on the\nmodern path so the host is the focusable surface and lands directly\nunder the parent `<hx-tree-view>` (which carries `role=\"tree\"`) in the\nAT-walked tree. The inner `.item-row` is presentational on the modern\npath — no role, no aria-* attributes — and carries only click/keyboard\nevent handlers. Keyboard activation (Enter/Space) and expand/collapse\n(ArrowLeft/Right at the leaf level) are owned by the host's `keydown`\nhandler; ArrowUp/Down/Home/End and typeahead bubble to the parent\n`<hx-tree-view>` for navigation.\n\nThe nested `[role=\"group\"]` element that wraps the `slot=\"children\"`\nstays in the inner shadow DOM regardless of path — that group is a\nseparate sub-surface for the children, not a duplicate of the\ntreeitem role.\n\nOn the legacy fallback path the inner `.item-row` carries\n`role=\"treeitem\"` + aria-* state, the host role is suppressed, and the\nroving tabindex is written to the inner element so there is only ONE\nfocusable surface per item (mirrors hx-menu-item round-8).",
           "name": "HelixTreeItem",
           "cssProperties": [
             {
@@ -33604,7 +33695,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"
             },
             {
@@ -33616,7 +33707,7 @@
               "name": "label"
             },
             {
-              "description": "The children container.",
+              "description": "The children container (always carries role=\"group\").",
               "name": "children"
             }
           ],
@@ -33707,7 +33798,7 @@
                   }
                 }
               ],
-              "description": "Sets the roving tabindex state for this item.\nWhen `active` is true, the item row gets `tabindex=\"0\"` making it the\nTab-reachable item in the tree. All other items should be set to false.\nCalled by the parent hx-tree-view to manage the roving tabindex pattern."
+              "description": "Sets the roving tabindex state for this item.\nWhen `active` is true, the host (modern) or inner row (fallback) gets\n`tabindex=\"0\"` making it the Tab-reachable surface in the tree. All\nother items should be set to false. Called by the parent hx-tree-view\nto manage the roving tabindex pattern."
             },
             {
               "kind": "method",
@@ -33717,7 +33808,16 @@
                   "text": "void"
                 }
               },
-              "description": "Focus this item's interactive row element."
+              "parameters": [
+                {
+                  "name": "options",
+                  "optional": true,
+                  "type": {
+                    "text": "FocusOptions"
+                  }
+                }
+              ],
+              "description": "Focus this item. On the modern host-canonical path, focus lands on the\nhost (which carries the roving tabindex and announced role). On the\nlegacy fallback path, focus delegates to the inner `.item-row` which\nstill carries the role."
             }
           ],
           "events": [
@@ -33795,7 +33895,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "A hierarchical tree component for navigating nested data structures.\nUsed in healthcare applications for org charts, ICD-10 code hierarchies, and department navigation.\n\nImplements WAI-ARIA tree view pattern with `role=\"tree\"` on the container\nand `role=\"treeitem\"` on each item. Supports `aria-label` via the `label` property\nfor screen reader identification. Full keyboard navigation: Arrow keys for movement,\nEnter/Space for selection, Home/End for first/last item.\n\n## Scale Limits\n\nThis component renders all tree items simultaneously in the DOM. It is suitable for\ntrees with up to ~500 visible items. For large taxonomies (e.g., ICD-10 with 70,000+\ncodes), use async/lazy loading: only render top-level nodes initially and populate\nchild nodes on `hx-select` or expand events. The component exposes the `expanded`\nproperty on `hx-tree-item` for programmatic control of subtrees, enabling consumer-level\nvirtualization strategies without requiring changes to this component.",
+          "description": "A hierarchical tree component for navigating nested data structures.\nUsed in healthcare applications for org charts, ICD-10 code hierarchies, and department navigation.\n\nGroup 5c host-canonical: `role=\"tree\"` lives on the **host** via\n`_internals.role` on the modern path. The host carries the announced\nsurface so AT walks `<hx-tree-view>` (role=tree) → slotted\n`<hx-tree-item>` (role=treeitem on host) directly without two layers of\nindirection. Consumer-supplied `aria-label` / `aria-labelledby` on the\nhost are resolved via the shared IDREF mirror; cross-shadow naming uses\n`ariaLabelledByElements` (modern) with a flattened-string fallback\n(legacy). On the legacy fallback path the inner `[role=\"tree\"]` carries\nthe role + accessible name and the host role is suppressed so AT only\nsees one tree per logical surface (mirrors `hx-menu` round-8).\n\nFull keyboard navigation: Arrow keys for movement, Enter/Space for\nselection, Home/End for first/last item, ArrowRight/Left for\nexpand/collapse + parent/child traversal, typeahead.\n\n## Scale Limits\n\nThis component renders all tree items simultaneously in the DOM. It is suitable for\ntrees with up to ~500 visible items. For large taxonomies (e.g., ICD-10 with 70,000+\ncodes), use async/lazy loading: only render top-level nodes initially and populate\nchild nodes on `hx-select` or expand events. The component exposes the `expanded`\nproperty on `hx-tree-item` for programmatic control of subtrees, enabling consumer-level\nvirtualization strategies without requiring changes to this component.",
           "name": "HelixTreeView",
           "cssProperties": [
             {
@@ -33830,7 +33930,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"
             }
           ],
@@ -33848,7 +33948,7 @@
                 "text": "string"
               },
               "default": "''",
-              "description": "Accessible label for the tree. Applied as `aria-label` on the tree container.\nProvides context to screen readers about the tree's purpose.",
+              "description": "Accessible label for the tree. Used as a fallback when no\nconsumer-supplied `aria-label` / `aria-labelledby` is present on the\nhost. On the modern host-canonical path this projects onto\n`internals.ariaLabel`; on the legacy fallback path it appears as\n`aria-label` on the inner `[role=\"tree\"]` element.",
               "attribute": "label",
               "reflects": true
             },
@@ -33880,7 +33980,7 @@
                 "text": "string"
               },
               "default": "''",
-              "description": "Accessible label for the tree. Applied as `aria-label` on the tree container.\nProvides context to screen readers about the tree's purpose.",
+              "description": "Accessible label for the tree. Used as a fallback when no\nconsumer-supplied `aria-label` / `aria-labelledby` is present on the\nhost. On the modern host-canonical path this projects onto\n`internals.ariaLabel`; on the legacy fallback path it appears as\n`aria-label` on the inner `[role=\"tree\"]` element.",
               "fieldName": "label",
               "attribute": "label"
             },