@helixui/library 3.3.1 → 3.4.0

package/custom-elements.json

@@ -8,7 +8,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "An individual accordion item with collapsible content.",
+          "description": "An individual accordion item with collapsible content.\n\n## Architecture Note: Slot Projection vs. Host-Canonical (group-4 round-1)\n\n`hx-accordion-item` deliberately does NOT participate in the\nhost-canonical / `internals.ariaLabelledByElements` pattern used by every\nother group-2/3/4 component. Rationale:\n\n  1. The trigger label comes from `<slot name=\"trigger\">` — consumer\n     light-DOM projected directly into the `<summary>` element. AT reads\n     the slot-projected text natively because slot projection preserves\n     accessible name (the `<summary>` IS the heading and consumes the\n     slotted text in its own accessible name computation).\n  2. `aria-labelledby=\"${_uid}-trigger\"` on the inner content region and\n     `aria-controls=\"${_uid}-content\"` on the summary BOTH resolve\n     same-shadow-root, which works correctly across every AT — these\n     IDREFs never cross a shadow boundary.\n  3. Pushing these ids through `internals.ariaLabelledByElements` would\n     either duplicate the wiring (heading announced twice) or break the\n     native `<details>/<summary>` toggle semantics (the host carrying\n     `role=\"heading\"` would shadow the summary's own heading projection).\n\n`role=\"heading\"` on `<summary>` (with `aria-level=N`) is the APG-canonical\nAccordion pattern. Per the APG note, `<summary>` MUST be a direct child\nof `<details>` for the native toggle to function — wrapping it in an\n`<h3>` would forfeit native disclosure. The role-on-summary approach is\nthe authoritative compromise. NVDA, JAWS, and VoiceOver all announce the\nsummary as a heading at the configured level when this pattern is used.\n\n`aria-controls` on the summary points at the shadow-internal content\nregion; APG marks the relationship as implicit via the heading + region\nstructure, so AT not following the IDREF still announces correctly. The\nIDREF is a hint, not a requirement — and because both ids are in the\nsame shadow root, it resolves cleanly when AT does follow it. This\nmatches the popover/dropdown intentional `aria-controls` omission for\nthe cross-shadow case (see those components' code comments).",
           "name": "HelixAccordionItem",
           "cssProperties": [
             {
@@ -4856,6 +4856,13 @@
               "description": "Accessible label for the checkbox when no visible label text is provided.\nUse when embedding a checkbox in a context where a label element is not practical.\n\nAccepts both `accessible-label` and the standard `aria-label` HTML attribute.\n`accessible-label` takes precedence when both are set.\nWhen set, replaces the visible label as the input's accessible name. Cannot be combined\nwith a visible label — set either `accessible-label` or the `label` slot, not both.",
               "attribute": "accessible-label"
             },
+            {
+              "kind": "field",
+              "name": "_groupedSuppress",
+              "type": {
+                "text": "boolean"
+              }
+            },
             {
               "kind": "field",
               "name": "form",
@@ -4952,7 +4959,7 @@
                   }
                 }
               ],
-              "description": "Moves focus to the checkbox input element."
+              "description": "Moves focus to the announced checkbox surface. Codex round-1 finding #1\nrelocated the focus target from the inner `<input>` to the host on\nmodern engines so AT only sees one announced widget. Round-7 finding #3\nextends that contract to the no-IDL-ref fallback: when the host is\ndemoted (`tabindex=-1`, role/state cleared on `internals`) the inner\n`<input>` owns the announced semantics and tab order, so programmatic\n`focus()` must redirect there — otherwise scripted focus and error\nrecovery land on the demoted host on unsupported engines."
             }
           ],
           "events": [
@@ -6898,12 +6905,36 @@
             {
               "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"
             }
           ],
           "slots": [
             {
               "description": "Custom trigger element. Default: a color swatch button.",
               "name": "trigger"
+            },
+            {
+              "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.",
+              "name": "label"
+            },
+            {
+              "description": "Help text rendered below the trigger and joined into the host's announced description channel.",
+              "name": "help-text"
+            },
+            {
+              "description": "Error message rendered below help text. When present, marks the trigger as aria-invalid and is announced via a polite live region.",
+              "name": "error"
             }
           ],
           "members": [
@@ -7074,13 +7105,55 @@
               "description": "Accessible label for the color picker dialog/panel.",
               "attribute": "label-picker"
             },
+            {
+              "kind": "field",
+              "name": "label",
+              "type": {
+                "text": "string | undefined"
+              },
+              "default": "undefined",
+              "description": "Visible label rendered above the trigger. When set this becomes the\nannounced name of the trigger surface unless a stronger source\n(`aria-labelledby`, `aria-label`, or `accessible-label`) is supplied.",
+              "attribute": "label",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "accessibleLabel",
+              "type": {
+                "text": "string | undefined"
+              },
+              "default": "undefined",
+              "description": "Visually-hidden accessible name. Highest-priority self-naming source —\noutranks `label`, slotted label content, and the generated trigger label,\nbut defers to consumer `aria-labelledby` (effective) and `aria-label`.",
+              "attribute": "accessible-label"
+            },
+            {
+              "kind": "field",
+              "name": "helpText",
+              "type": {
+                "text": "string | undefined"
+              },
+              "default": "undefined",
+              "description": "Help text rendered below the trigger and joined into the host's\nannounced description channel.",
+              "attribute": "help-text"
+            },
+            {
+              "kind": "field",
+              "name": "error",
+              "type": {
+                "text": "string | undefined"
+              },
+              "default": "undefined",
+              "description": "Error message. When non-empty, marks the trigger surface as `aria-invalid`\nand joins the host's announced description channel via a live alert.",
+              "attribute": "error",
+              "reflects": true
+            },
             {
               "kind": "field",
               "name": "labelTrigger",
               "type": {
                 "text": "(color: string) => string"
               },
-              "description": "Generates the accessible label for the trigger button.",
+              "description": "Generates the accessible label for the trigger button when no other\nnaming source is provided.",
               "parameters": [
                 {
                   "description": "current color value string",
@@ -7186,6 +7259,46 @@
               "fieldName": "required",
               "attribute": "required"
             },
+            {
+              "name": "label",
+              "type": {
+                "text": "string | undefined"
+              },
+              "default": "undefined",
+              "description": "Visible label rendered above the trigger. When set this becomes the\nannounced name of the trigger surface unless a stronger source\n(`aria-labelledby`, `aria-label`, or `accessible-label`) is supplied.",
+              "fieldName": "label",
+              "attribute": "label"
+            },
+            {
+              "name": "accessible-label",
+              "type": {
+                "text": "string | undefined"
+              },
+              "default": "undefined",
+              "description": "Visually-hidden accessible name. Highest-priority self-naming source —\noutranks `label`, slotted label content, and the generated trigger label,\nbut defers to consumer `aria-labelledby` (effective) and `aria-label`.",
+              "fieldName": "accessibleLabel",
+              "attribute": "accessible-label"
+            },
+            {
+              "name": "help-text",
+              "type": {
+                "text": "string | undefined"
+              },
+              "default": "undefined",
+              "description": "Help text rendered below the trigger and joined into the host's\nannounced description channel.",
+              "fieldName": "helpText",
+              "attribute": "help-text"
+            },
+            {
+              "name": "error",
+              "type": {
+                "text": "string | undefined"
+              },
+              "default": "undefined",
+              "description": "Error message. When non-empty, marks the trigger surface as `aria-invalid`\nand joins the host's announced description channel via a live alert.",
+              "fieldName": "error",
+              "attribute": "error"
+            },
             {
               "name": "label-gradient",
               "type": {
@@ -7807,7 +7920,7 @@
                 "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.\n\nNote: `mixinDelegatesAria` is not applied to this component because form\ninputs with associated labels delegate accessible naming via `<label>`\nassociation and `aria-labelledby`, not host-level ARIA delegation. The\n`accessible-label` attribute is a fallback for label-free usage. The value is forwarded to the\ninternal input's `aria-label`.",
+              "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.\n\nNote: `mixinDelegatesAria` is not applied to this component because form\ninputs with associated labels delegate accessible naming via `<label>`\nassociation and `aria-labelledby`, not host-level ARIA delegation. The\n`accessible-label` attribute is a fallback for label-free usage. The value is forwarded to the\nhost's `internals.ariaLabel` on the modern path.",
               "attribute": "accessible-label"
             },
             {
@@ -7844,6 +7957,16 @@
                 }
               ]
             },
+            {
+              "kind": "method",
+              "name": "_syncHostAriaSemantics",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
             {
               "kind": "method",
               "name": "focus",
@@ -7861,7 +7984,7 @@
                   }
                 }
               ],
-              "description": "Moves focus to the text input."
+              "description": "Routes programmatic focus to the inner text input. Per W3C APG editable\ncombobox pattern, the inner `<input>` carries `role=\"combobox\"` (replacing\nits implicit textbox role) so it IS the canonical announced + focused\nsurface. Shadow DOM focus causes `document.activeElement` to report the\nhost externally, but the input retains focus inside the shadow root and\nAT announces its role/state."
             }
           ],
           "events": [
@@ -8038,7 +8161,7 @@
                 "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.\n\nNote: `mixinDelegatesAria` is not applied to this component because form\ninputs with associated labels delegate accessible naming via `<label>`\nassociation and `aria-labelledby`, not host-level ARIA delegation. The\n`accessible-label` attribute is a fallback for label-free usage. The value is forwarded to the\ninternal input's `aria-label`.",
+              "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.\n\nNote: `mixinDelegatesAria` is not applied to this component because form\ninputs with associated labels delegate accessible naming via `<label>`\nassociation and `aria-labelledby`, not host-level ARIA delegation. The\n`accessible-label` attribute is a fallback for label-free usage. The value is forwarded to the\nhost's `internals.ariaLabel` on the modern path.",
               "fieldName": "accessibleLabel",
               "attribute": "accessible-label"
             },
@@ -10046,6 +10169,16 @@
               "description": "Accessible label for the next month navigation button.",
               "attribute": "next-month-label"
             },
+            {
+              "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": "_handleDocumentClick",
@@ -10250,6 +10383,16 @@
               "description": "Accessible label for the next month navigation button.",
               "fieldName": "nextMonthLabel",
               "attribute": "next-month-label"
+            },
+            {
+              "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": [
@@ -10315,7 +10458,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "A modal and non-modal dialog component built on the native HTML `<dialog>` element.\nProvides focus trapping, backdrop interaction, keyboard navigation, and full\nARIA labelling for enterprise healthcare accessibility requirements.",
+          "description": "A modal and non-modal dialog component built on the native HTML `<dialog>` element.\nProvides focus trapping, backdrop interaction, keyboard navigation, and full\nARIA labelling for enterprise healthcare accessibility requirements.\n\n## Architecture Note: Host-Canonical ARIA (group-4a round-1, Path A — native-dialog adaptation)\n\nUnlike `hx-drawer` (which uses an inner `<div role=\"dialog\">` and can fully\nhost-canonicalize the role), `hx-dialog` is built on the native\n`<dialog>` HTMLDialogElement. The native element has an **implicit\n`role=\"dialog\"`** baked in by the browser that **cannot be stripped**, so\nfull host-canonical role takeover would create nested-dialog announcements.\n\n**Path A (adopted):** the host owns label / description projection via\n`ElementInternals` (`internals.ariaLabelledByElements`,\n`internals.ariaDescribedByElements`, `internals.ariaLabel`) but **does NOT**\nset `internals.role`. The native inner `<dialog>` continues to be the\nannounced surface. Consumer light-DOM IDREFs project across the shadow\nboundary via `internals.aria*Elements` on the host.\n\n**Hybrid fallback (always-on belt-and-suspenders):** because some assistive\ntechnologies may walk the native `<dialog>` first and ignore host\n`internals.aria*Elements`, the resolved label / description text is **also**\nserialized into `aria-label` / `aria-describedby` on the inner native\n`<dialog>` element. Consumers therefore get name/description on every AT,\nwith the IDL-ref path providing live DOM-text-update tracking when the AT\nhonours it. This forfeits live-text tracking on the inner-dialog fallback\n(the serialized text is recomputed on every sync, which is good enough since\nmutation observers re-fire `_syncHostAriaSemantics` on consumer text edits).\n\nWhy we do NOT set `internals.role = 'alertdialog'` either: setting role on\nthe host while the native `<dialog>` keeps `role=\"dialog\"` would announce\nBOTH a host alertdialog AND an inner dialog. Instead, the alertdialog\nvariant continues to write `role=\"alertdialog\"` directly on the inner\n`<dialog>` element (the platform allows overriding the implicit `dialog`\nrole with the more specific `alertdialog`).\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` (closest scope first, then\n     ancestor shadow hosts, then owner document).\n  2. Consumer `aria-label` on the host.\n  3. `<slot name=\"header\">` 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. `heading` property — explicit author-provided heading text.\n  5. Hard-coded literal `\"Dialog\"` (last-resort accessible name).\n\nDescription channel: the host's `internals.ariaDescribedByElements` carries\nthe resolved IDREF chain on the modern path. The inner native `<dialog>` ALSO\nreceives a serialized `aria-describedby` chain — when a consumer description\nresolves, a synthesized in-shadow `<span id=\"${id}-consumer-desc\">` is\nappended to the existing `description` span (if any) and the inner\n`<dialog>`'s `aria-describedby` references both same-root ids. `aria-description`\nis intentionally NEVER written — W3C AccName ignores it whenever\n`aria-describedby` is also present.\n\nSlot mutation observers track:\n  1. The header 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  4. Authentic consumer `aria-describedby` retraction (oldValue !== null &&\n     newValue === null) via a dedicated `attributeOldValue: true` observer.\n\n**First-paint slot state seeding intentionally omitted:** seeding\n`_hasHeaderSlot` / `_headerSlotText` from `firstUpdated()` would schedule an\nextra Lit re-render that subtly reorders the open-dialog promise chain\n(`updateComplete.then(...) → showModal() → updateComplete.then(...) →\nfocus first focusable`). On Chromium, that reordering interleaves the\nnative dialog's modal activation with the focus-restore step and causes\nfocus-trap test failures. The slotchange handler runs one microtask later\nand `_syncHostAriaSemantics()` from `updated()` picks up the resolved state\non the next paint — close enough that AT never observes the unnamed window.\nMirrors the same intentional decision documented in hx-drawer round-1.\n\nFocus trap, ESC dismiss with `hx-cancel` BEFORE `hx-close`, focus-restore\nvia `_triggerElement`, and native `showModal()` semantics are unchanged\nfrom the pre-host-canonical implementation.",
           "name": "HelixDialog",
           "cssProperties": [
             {
@@ -11034,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": [
             {
@@ -11539,7 +11682,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "A dropdown component — a button that opens a floating panel on click.",
+          "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": [
             {
@@ -11804,7 +11947,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Layout wrapper providing consistent label + input + help text + validation\nmessage structure for any form control. Use this when wrapping non-HELiX\nform controls or native HTML elements in the HELiX form field pattern.\n\nThis component is NOT form-associated — it is a pure visual layout wrapper.\n\n**Light DOM side effect:** This component injects a visually-hidden `<span>`\ninto its light DOM children for ARIA describedby linkage across the shadow\nDOM boundary. This span has `id=\"${fieldId}-desc\"` and is removed on\n`disconnectedCallback`. This is an intentional, documented accessibility\nmechanism.",
+          "description": "Layout wrapper providing consistent label + input + help text + validation\nmessage structure for any form control. Use this when wrapping non-HELiX\nform controls or native HTML elements in the HELiX form field pattern.\n\nThis component is NOT form-associated — it is a pure visual layout wrapper.\n\n**Light DOM side effect:** This component injects a visually-hidden `<span>`\ninto its light DOM children for ARIA describedby linkage across the shadow\nDOM boundary. This span has `id=\"${fieldId}-desc\"` and is removed on\n`disconnectedCallback`. This is an intentional, documented accessibility\nmechanism.\n\n**`aria-label` ownership model:** When `label` is set and no shadow `<label>`\nis rendered, hx-field writes `aria-label` to the slotted control and stamps\na `data-hx-owns-label=\"true\"` ownership marker.\n\nConsumers have two ways to keep their value safe from hx-field's writes:\n  (a) **Suspend** all ARIA bridging by setting `data-aria-managed` on the\n      control. While present, hx-field skips every aria-* mutation and\n      leaves any existing marker/snapshot in place — removing\n      `data-aria-managed` later may resume host ownership of an `aria-label`\n      value that still matches the snapshot.\n  (b) **Release** ownership permanently by overwriting `aria-label` to a\n      different value than the one hx-field last wrote. The mismatch\n      triggers `_releaseHostOwnedAriaLabel`, which strips the marker and\n      clears the snapshot, transferring ownership to the consumer.\n\n**Limitation:** because release detection is snapshot-based, a consumer\nrewrite to the *exact same value* hx-field last wrote is invisible. To\ngenuinely take ownership in that case the consumer must write a different\nvalue (even briefly), or remove the `data-hx-owns-label` marker themselves.",
           "name": "HelixField",
           "cssProperties": [
             {
@@ -14470,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": [
@@ -14532,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",
@@ -14641,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": {
@@ -14672,6 +14840,12 @@
               "attribute": "value"
             }
           ],
+          "mixins": [
+            {
+              "name": "mixinDelegatesAria",
+              "module": "/src/mixins/index.js"
+            }
+          ],
           "superclass": {
             "name": "HelixElement",
             "module": "/src/base/index.js"
@@ -15312,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": [
@@ -15383,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": {
@@ -15442,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": [
             {
@@ -15687,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": [
             {
@@ -15857,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": [
             {
@@ -15907,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": [
             {
@@ -16055,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": [
@@ -16067,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": [
@@ -16167,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": [
             {
@@ -16244,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
             },
@@ -16292,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"
             }
@@ -16362,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": [
             {
@@ -17766,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": [
             {
@@ -17985,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
             },
@@ -18071,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"
             },
@@ -19191,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"
@@ -19469,7 +19664,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "A popover that displays rich floating content attached to a trigger element.",
+          "description": "A popover that displays rich floating content attached to a trigger element.\n\n## Architecture Note: Host-Attribute Label Mirror (group-4 round-1)\n\nUnlike modal dialogs (`hx-dialog` / `hx-drawer`) where the HOST is the\nannounced surface and `ElementInternals` projects consumer IDREFs across\nthe shadow boundary, `hx-popover`'s announced surface is the inner\n`[part=\"body\"]` element which carries `role=\"dialog\"`. The host does not\nclaim a role — it is a structural wrapper around an anchor slot and a\nseparate floating panel.\n\nIDL element references on `internals.ariaLabelledByElements` therefore\ncannot help: AT walks the inner body's accessibility node, and IDL refs\ndeclared on the host are not visible from a shadow-internal descendant\nlooking up. The viable cross-shadow path is the host-attribute mirror:\n\n  1. The host observes `aria-label` / `aria-labelledby` mutations.\n  2. On every sync, `aria-labelledby` IDREFs are resolved via\n     `resolveIdrefTokens` (composed-tree walk: host root → ancestor\n     shadow hosts → owner document) and **text-flattened** via\n     `flattenAccName` (AccName 1.2 §4.3.10 hidden-aware).\n  3. The flattened name is written to the inner body's `aria-label`,\n     overriding the `label` property only when consumer naming is set.\n\nNaming precedence (W3C AccName 1.2 §4.3.1):\n\n  1. Host `aria-labelledby` (resolved IDREFs, text-flattened)\n  2. Host `aria-label`\n  3. `label` property\n  4. Hard-coded literal `\"Popover\"` (last-resort accessible name)\n\nThe text-flatten approach forfeits live IDL-ref tracking (mutating a\nreferenced element's text re-fires through the shared root observer; see\n`installAriaIdrefMirror`). `aria-controls` is intentionally omitted on\nthe trigger — the body lives in shadow DOM and consumer IDREFs cannot\nresolve cross-root from light-DOM (axe-core flags this as a critical\nviolation if attempted; see line documenting this exception below).\n\nSlotted label support (e.g. `<slot name=\"title\">`) is deliberately NOT\nadded in this round — it would expand the public API surface and is\ntracked as a follow-up enhancement.",
           "name": "HelixPopover",
           "cssProperties": [
             {
@@ -20240,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": [
             {
@@ -21477,6 +21672,13 @@
               "description": "Whether this radio is checked. Managed by the parent group.",
               "attribute": "checked",
               "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "_groupedSuppress",
+              "type": {
+                "text": "boolean"
+              }
             }
           ],
           "attributes": [
@@ -22535,7 +22737,7 @@
                   }
                 }
               ],
-              "description": "Moves focus to the visible trigger button."
+              "description": "Moves focus to the host. Round-3 finding 1: the host is the canonical\ncombobox surface (`role=\"combobox\"`, `tabindex=\"0\"`), so programmatic\nfocus must land there to match where AT routes focus and where\n`setValidity()` anchors recovery."
             }
           ],
           "events": [
@@ -22545,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": [
@@ -24283,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": [
             {
@@ -24582,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"
             },
             {
@@ -24669,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"
             },
@@ -25357,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": [
             {
@@ -27336,7 +27545,7 @@
                   }
                 }
               ],
-              "description": "Moves focus to the switch track element."
+              "description": "Moves focus to the announced switch surface. Codex round-1 finding #1\nrelocated the focus target to the host so AT announces a single widget;\nthe host carries the canonical role/state on modern engines. Round-7\nfinding #7 extends that contract to the no-IDL-ref fallback: when the\nhost is demoted (`tabindex=-1`, role/state cleared on `internals`) the\ninner `<button role=switch>` owns the announced semantics and tab order,\nso programmatic `focus()` must redirect there — otherwise scripted focus\nand error recovery land on the demoted host on unsupported engines."
             }
           ],
           "events": [
@@ -27822,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": [
             {
@@ -27882,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"
             }
           ],
@@ -27923,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"
             }
@@ -28011,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": [
             {
@@ -28227,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": [
             {
@@ -28392,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": [
             {
@@ -28482,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": [
             {
@@ -28675,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": [
             {
@@ -28824,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
             },
@@ -28836,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
             },
@@ -28877,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"
             },
@@ -28888,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"
             }
@@ -30985,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"
             }
           ],
@@ -31587,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",
@@ -31722,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": [
@@ -31791,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"
             }
@@ -32683,6 +32924,25 @@
               },
               "description": "Reports validity and shows the browser's constraint validation UI."
             },
+            {
+              "kind": "method",
+              "name": "focus",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "options",
+                  "optional": true,
+                  "type": {
+                    "text": "FocusOptions"
+                  }
+                }
+              ],
+              "description": "Moves focus to the announced toggle-button surface. Codex round-1 finding\n`#1` made the host the canonical focus target on modern engines so AT\nannounces a single widget. Round-7 finding `#9` extends that contract to\nthe no-IDL-ref fallback: when the host is demoted (`tabindex=-1`,\nrole/state cleared on `internals`) the inner `<button>` owns the announced\nsemantics and tab order, so programmatic `focus()` must redirect there —\notherwise scripted focus and error recovery land on the demoted host on\nunsupported engines."
+            },
             {
               "kind": "method",
               "name": "_onFormReset",
@@ -32884,7 +33144,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "A tooltip that displays contextual help text on hover or focus.",
+          "description": "A tooltip that displays contextual help text on hover or focus.\n\n## Architecture Note: Light-DOM Description Shim (group-4 round-1)\n\n`aria-describedby` IDREFs cannot resolve across the Shadow DOM boundary —\nthe trigger lives in the consumer's light DOM and references a tooltip\nwhose body is in this component's shadow root. The tooltip text must\ntherefore be exposed in DOCUMENT scope.\n\nThe shim is a single visually-hidden `<span>` appended to `document.body`\nwith the `_tooltipId` as its `id`. The trigger's `aria-describedby` points\nat this span. The text content is mirrored from the slotted `content`\nslot on every relevant signal:\n\n  1. `firstUpdated` (initial wiring)\n  2. `slotchange` on the default slot AND the `content` slot (the slotted\n     element list changes)\n  3. **Text-content mutations on the assigned `content` slot elements**\n     (round-23 P2 pattern). Without this observer a framework that\n     rewrites the slotted `<span slot=\"content\">` `textContent` IN PLACE\n     (Vue / React keyed text rerender) would leave the shim stale.\n\nCleanup: `disconnectedCallback` removes the shim from `document.body`,\ndisconnects the slot-text observer, and clears the timers. SSR is\nsidestepped by guarding `document` access — the shim is created lazily\nthe first time `_setupTriggerAria()` runs in a browser environment.\n\n`role=\"tooltip\"` is the correct APG role and is NEVER promoted to\n`role=\"dialog\"` — APG explicitly forbids tooltips from holding focus and\nthe tooltip body is not a focus target. No host-canonical `_internals`\nwork is owed: the trigger is the announced surface, and it correctly\nreferences the tooltip via `aria-describedby`.",
           "name": "HelixTooltip",
           "cssProperties": [
             {
@@ -33390,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": [
             {
@@ -33435,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"
             },
             {
@@ -33447,7 +33707,7 @@
               "name": "label"
             },
             {
-              "description": "The children container.",
+              "description": "The children container (always carries role=\"group\").",
               "name": "children"
             }
           ],
@@ -33538,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",
@@ -33548,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": [
@@ -33626,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": [
             {
@@ -33661,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"
             }
           ],
@@ -33679,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
             },
@@ -33711,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"
             },