@helixui/library 3.3.1-next.115 → 3.3.1-next.118

package/custom-elements.json

@@ -2,13 +2,276 @@
   "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",
       "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": [
             {
@@ -322,269 +585,6 @@
         }
       ]
     },
-    {
-      "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",
@@ -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": [
             {
@@ -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 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.",
           "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": [
             {
@@ -19469,7 +19612,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": [
             {
@@ -21477,6 +21620,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 +22685,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": [
@@ -27336,7 +27486,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": [
@@ -32683,6 +32833,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 +33053,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": [
             {