@helixui/react 3.3.0 → 3.4.0

package/dist/components/HxAccordionItem/HxAccordionItem.d.ts

@@ -3,6 +3,41 @@ import { HxAccordionItemProps } from './types.js';
 export type { HxAccordionItemProps };
 /**
  * An individual accordion item with collapsible content.
+
+## Architecture Note: Slot Projection vs. Host-Canonical (group-4 round-1)
+
+`hx-accordion-item` deliberately does NOT participate in the
+host-canonical / `internals.ariaLabelledByElements` pattern used by every
+other group-2/3/4 component. Rationale:
+
+  1. The trigger label comes from `<slot name="trigger">` — consumer
+     light-DOM projected directly into the `<summary>` element. AT reads
+     the slot-projected text natively because slot projection preserves
+     accessible name (the `<summary>` IS the heading and consumes the
+     slotted text in its own accessible name computation).
+  2. `aria-labelledby="${_uid}-trigger"` on the inner content region and
+     `aria-controls="${_uid}-content"` on the summary BOTH resolve
+     same-shadow-root, which works correctly across every AT — these
+     IDREFs never cross a shadow boundary.
+  3. Pushing these ids through `internals.ariaLabelledByElements` would
+     either duplicate the wiring (heading announced twice) or break the
+     native `<details>/<summary>` toggle semantics (the host carrying
+     `role="heading"` would shadow the summary's own heading projection).
+
+`role="heading"` on `<summary>` (with `aria-level=N`) is the APG-canonical
+Accordion pattern. Per the APG note, `<summary>` MUST be a direct child
+of `<details>` for the native toggle to function — wrapping it in an
+`<h3>` would forfeit native disclosure. The role-on-summary approach is
+the authoritative compromise. NVDA, JAWS, and VoiceOver all announce the
+summary as a heading at the configured level when this pattern is used.
+
+`aria-controls` on the summary points at the shadow-internal content
+region; APG marks the relationship as implicit via the heading + region
+structure, so AT not following the IDREF still announces correctly. The
+IDREF is a hint, not a requirement — and because both ids are in the
+same shadow root, it resolves cleanly when AT does follow it. This
+matches the popover/dropdown intentional `aria-controls` omission for
+the cross-shadow case (see those components' code comments).
  *
  * @example
  * ```tsx

package/dist/components/HxAccordionItem/HxAccordionItem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HxAccordionItem.d.ts","sourceRoot":"","sources":["../../../src/components/HxAccordionItem/HxAccordionItem.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,kBAAkB,EAAE,MAAM,0CAA0C,CAAC;AAE9E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD,YAAY,EAAE,oBAAoB,EAAE,CAAC;AAErC;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe;;;EAS1B,CAAC;AAEH,eAAe,eAAe,CAAC"}
+{"version":3,"file":"HxAccordionItem.d.ts","sourceRoot":"","sources":["../../../src/components/HxAccordionItem/HxAccordionItem.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,kBAAkB,EAAE,MAAM,0CAA0C,CAAC;AAE9E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD,YAAY,EAAE,oBAAoB,EAAE,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,eAAO,MAAM,eAAe;;;EAS1B,CAAC;AAEH,eAAe,eAAe,CAAC"}

package/dist/components/HxColorPicker/types.d.ts

@@ -42,7 +42,22 @@ export interface HxColorPickerProps {
     labelColorValue?: string;
     /** Accessible label for the color picker dialog/panel. */
     labelPicker?: string;
-    /** Generates the accessible label for the trigger button. */
+    /** Visible label rendered above the trigger. When set this becomes the
+  announced name of the trigger surface unless a stronger source
+  (`aria-labelledby`, `aria-label`, or `accessible-label`) is supplied. */
+    label?: string | undefined;
+    /** Visually-hidden accessible name. Highest-priority self-naming source —
+  outranks `label`, slotted label content, and the generated trigger label,
+  but defers to consumer `aria-labelledby` (effective) and `aria-label`. */
+    accessibleLabel?: string | undefined;
+    /** Help text rendered below the trigger and joined into the host's
+  announced description channel. */
+    helpText?: string | undefined;
+    /** Error message. When non-empty, marks the trigger surface as `aria-invalid`
+  and joins the host's announced description channel via a live alert. */
+    error?: string | undefined;
+    /** Generates the accessible label for the trigger button when no other
+  naming source is provided. */
     labelTrigger?: string;
     /** Dispatched while dragging sliders or grid. */
     onHxInput?: (event: Event) => void;

package/dist/components/HxColorPicker/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/components/HxColorPicker/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,MAAM,WAAW,kBAAkB;IACjC,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,qBAAqB;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oBAAoB;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wFAAwF;IACxF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;6BAGyB;IACzB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB;wDACoD;IACpD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,sDAAsD;IACtD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qDAAqD;IACrD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kDAAkD;IAClD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,YAAY,CAAC,EAAE,MAAM,CAAC;IAGtB,iDAAiD;IACjD,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACnC,4CAA4C;IAC5C,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACrC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/components/HxColorPicker/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,MAAM,WAAW,kBAAkB;IACjC,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,qBAAqB;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oBAAoB;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wFAAwF;IACxF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;6BAGyB;IACzB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB;wDACoD;IACpD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,sDAAsD;IACtD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qDAAqD;IACrD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kDAAkD;IAClD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;0EAEsE;IACtE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B;;2EAEuE;IACvE,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC;mCAC+B;IAC/B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B;yEACqE;IACrE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B;+BAC2B;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IAGtB,iDAAiD;IACjD,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACnC,4CAA4C;IAC5C,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACrC"}

package/dist/components/HxCombobox/types.d.ts

@@ -40,7 +40,7 @@ export interface HxComboboxProps {
   inputs with associated labels delegate accessible naming via `<label>`
   association and `aria-labelledby`, not host-level ARIA delegation. The
   `accessible-label` attribute is a fallback for label-free usage. The value is forwarded to the
-  internal input's `aria-label`. */
+  host's `internals.ariaLabel` on the modern path. */
     accessibleLabel?: string | null;
     /** Text shown when no options match the current filter. */
     labelNoOptions?: string;

package/dist/components/HxCombobox/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/components/HxCombobox/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,MAAM,WAAW,eAAe;IAC9B,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,qBAAqB;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oBAAoB;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAC1B,gDAAgD;IAChD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,qEAAqE;IACrE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,kEAAkE;IAClE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iEAAiE;IACjE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;;mCAQ+B;IAC/B,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,2DAA2D;IAC3D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAG3B,yCAAyC;IACzC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAClC,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAClC,sDAAsD;IACtD,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACnC,qDAAqD;IACrD,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACnC,6CAA6C;IAC7C,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACrC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/components/HxCombobox/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,MAAM,WAAW,eAAe;IAC9B,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,qBAAqB;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oBAAoB;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAC1B,gDAAgD;IAChD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,qEAAqE;IACrE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,kEAAkE;IAClE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iEAAiE;IACjE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;;qDAQiD;IACjD,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,2DAA2D;IAC3D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAG3B,yCAAyC;IACzC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAClC,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAClC,sDAAsD;IACtD,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACnC,qDAAqD;IACrD,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACnC,6CAA6C;IAC7C,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACrC"}

package/dist/components/HxDatePicker/types.d.ts

@@ -40,6 +40,10 @@ export interface HxDatePickerProps {
     previousMonthLabel?: string;
     /** Accessible label for the next month navigation button. */
     nextMonthLabel?: string;
+    /** Accessible name for screen readers, if different from the visible label.
+  Uses `accessible-label` attribute instead of `aria-label` to avoid
+  ARIAMixin shadowing on the host element. Highest-precedence naming source. */
+    accessibleLabel?: string | null;
     /** Emitted when the selected date changes. */
     onHxChange?: (event: Event) => void;
 }

package/dist/components/HxDatePicker/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/components/HxDatePicker/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,MAAM,WAAW,iBAAiB;IAChC,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,qBAAqB;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oBAAoB;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gDAAgD;IAChD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oFAAoF;IACpF,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kFAAkF;IAClF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,iEAAiE;IACjE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,6DAA6D;IAC7D,cAAc,CAAC,EAAE,MAAM,CAAC;IAGxB,8CAA8C;IAC9C,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACrC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/components/HxDatePicker/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,MAAM,WAAW,iBAAiB;IAChC,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,qBAAqB;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oBAAoB;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gDAAgD;IAChD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oFAAoF;IACpF,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kFAAkF;IAClF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,iEAAiE;IACjE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,6DAA6D;IAC7D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;+EAE2E;IAC3E,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAGhC,8CAA8C;IAC9C,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACrC"}

package/dist/components/HxDialog/HxDialog.d.ts

@@ -5,6 +5,84 @@ export type { HxDialogProps };
  * A modal and non-modal dialog component built on the native HTML `<dialog>` element.
 Provides focus trapping, backdrop interaction, keyboard navigation, and full
 ARIA labelling for enterprise healthcare accessibility requirements.
+
+## Architecture Note: Host-Canonical ARIA (group-4a round-1, Path A — native-dialog adaptation)
+
+Unlike `hx-drawer` (which uses an inner `<div role="dialog">` and can fully
+host-canonicalize the role), `hx-dialog` is built on the native
+`<dialog>` HTMLDialogElement. The native element has an **implicit
+`role="dialog"`** baked in by the browser that **cannot be stripped**, so
+full host-canonical role takeover would create nested-dialog announcements.
+
+**Path A (adopted):** the host owns label / description projection via
+`ElementInternals` (`internals.ariaLabelledByElements`,
+`internals.ariaDescribedByElements`, `internals.ariaLabel`) but **does NOT**
+set `internals.role`. The native inner `<dialog>` continues to be the
+announced surface. Consumer light-DOM IDREFs project across the shadow
+boundary via `internals.aria*Elements` on the host.
+
+**Hybrid fallback (always-on belt-and-suspenders):** because some assistive
+technologies may walk the native `<dialog>` first and ignore host
+`internals.aria*Elements`, the resolved label / description text is **also**
+serialized into `aria-label` / `aria-describedby` on the inner native
+`<dialog>` element. Consumers therefore get name/description on every AT,
+with the IDL-ref path providing live DOM-text-update tracking when the AT
+honours it. This forfeits live-text tracking on the inner-dialog fallback
+(the serialized text is recomputed on every sync, which is good enough since
+mutation observers re-fire `_syncHostAriaSemantics` on consumer text edits).
+
+Why we do NOT set `internals.role = 'alertdialog'` either: setting role on
+the host while the native `<dialog>` keeps `role="dialog"` would announce
+BOTH a host alertdialog AND an inner dialog. Instead, the alertdialog
+variant continues to write `role="alertdialog"` directly on the inner
+`<dialog>` element (the platform allows overriding the implicit `dialog`
+role with the more specific `alertdialog`).
+
+Naming precedence (W3C AccName 1.2 §4.3.1):
+
+  1. Consumer `aria-labelledby` on the host — IDREFs resolved across the
+     shadow boundary via `resolveIdrefTokens` (closest scope first, then
+     ancestor shadow hosts, then owner document).
+  2. Consumer `aria-label` on the host.
+  3. `<slot name="header">` text content (multi-node aggregation per
+     AccName 1.2 §4.3.10 — decorative `aria-hidden` / `[hidden]` subtrees
+     contribute zero to the name).
+  4. `heading` property — explicit author-provided heading text.
+  5. Hard-coded literal `"Dialog"` (last-resort accessible name).
+
+Description channel: the host's `internals.ariaDescribedByElements` carries
+the resolved IDREF chain on the modern path. The inner native `<dialog>` ALSO
+receives a serialized `aria-describedby` chain — when a consumer description
+resolves, a synthesized in-shadow `<span id="${id}-consumer-desc">` is
+appended to the existing `description` span (if any) and the inner
+`<dialog>`'s `aria-describedby` references both same-root ids. `aria-description`
+is intentionally NEVER written — W3C AccName ignores it whenever
+`aria-describedby` is also present.
+
+Slot mutation observers track:
+  1. The header slot's text content (in-place i18n re-renders).
+  2. Consumer-resolved external IDREF targets (so a consumer mutating
+     `<label id="x">Patient</label>` in place re-flows the name).
+  3. Host attribute mutations (delegated to `installAriaIdrefMirror`,
+     which also catches late-inserted IDREF targets and id renames in
+     every relevant root).
+  4. Authentic consumer `aria-describedby` retraction (oldValue !== null &&
+     newValue === null) via a dedicated `attributeOldValue: true` observer.
+
+**First-paint slot state seeding intentionally omitted:** seeding
+`_hasHeaderSlot` / `_headerSlotText` from `firstUpdated()` would schedule an
+extra Lit re-render that subtly reorders the open-dialog promise chain
+(`updateComplete.then(...) → showModal() → updateComplete.then(...) →
+focus first focusable`). On Chromium, that reordering interleaves the
+native dialog's modal activation with the focus-restore step and causes
+focus-trap test failures. The slotchange handler runs one microtask later
+and `_syncHostAriaSemantics()` from `updated()` picks up the resolved state
+on the next paint — close enough that AT never observes the unnamed window.
+Mirrors the same intentional decision documented in hx-drawer round-1.
+
+Focus trap, ESC dismiss with `hx-cancel` BEFORE `hx-close`, focus-restore
+via `_triggerElement`, and native `showModal()` semantics are unchanged
+from the pre-host-canonical implementation.
  *
  * @example
  * ```tsx

package/dist/components/HxDialog/HxDialog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HxDialog.d.ts","sourceRoot":"","sources":["../../../src/components/HxDialog/HxDialog.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,WAAW,EAAE,MAAM,uCAAuC,CAAC;AAEpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,YAAY,EAAE,aAAa,EAAE,CAAC;AAE9B;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,QAAQ;;;;EAUnB,CAAC;AAEH,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"HxDialog.d.ts","sourceRoot":"","sources":["../../../src/components/HxDialog/HxDialog.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,WAAW,EAAE,MAAM,uCAAuC,CAAC;AAEpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,YAAY,EAAE,aAAa,EAAE,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyFG;AACH,eAAO,MAAM,QAAQ;;;;EAUnB,CAAC;AAEH,eAAe,QAAQ,CAAC"}

package/dist/components/HxDrawer/HxDrawer.d.ts

@@ -6,6 +6,59 @@ export type { HxDrawerProps };
 Supports focus trapping, overlay backdrop, keyboard navigation, and full
 ARIA labelling for enterprise healthcare accessibility requirements.
 
+## Architecture Note: Host-Canonical ARIA (group-4 round-1, Path A)
+
+The host carries the announced dialog semantics via `ElementInternals`:
+
+  - `internals.role = 'dialog'` (the host IS the dialog surface)
+  - `internals.ariaModal = 'true'` (modality declared on host)
+  - `internals.ariaLabelledByElements` / `internals.ariaDescribedByElements`
+    project consumer light-DOM IDREFs across the shadow boundary.
+  - `internals.ariaLabel` carries the resolved fallback name when no
+    IDREF chain or slotted title exists.
+
+The inner `<div part="overlay">` no longer carries `role`, `aria-modal`,
+`aria-labelledby`, or `aria-label` — those would create a nested-dialog
+announcement above the host's canonical surface. Belt-and-suspenders
+fallback: when the runtime does NOT expose IDL element references on
+`ElementInternals` (older Firefox / Safari builds), the resolved label
+text is text-flattened and written to the inner overlay's `aria-label`
+so AT walking down from the host still finds an announceable name.
+
+Naming precedence (W3C AccName 1.2 §4.3.1):
+
+  1. Consumer `aria-labelledby` on the host — IDREFs resolved across the
+     shadow boundary via `resolveIdrefTokens` (same scope walk used by
+     every host-canonical hx-* control: own root → ancestor shadow hosts
+     → owner document → slot owners).
+  2. Consumer `aria-label` on the host.
+  3. `<slot name="label">` text content (multi-node aggregation per
+     AccName 1.2 §4.3.10 — decorative `aria-hidden` / `[hidden]` subtrees
+     contribute zero to the name).
+  4. `label` property — explicit author fallback string.
+  5. Hard-coded literal `"Drawer"` (last-resort accessible name).
+
+Description channel: a synthesized `<span id="${id}-consumer-desc">` is
+rendered inside the shadow root and updated to mirror consumer-resolved
+description text. The host's `internals.ariaDescribedByElements` carries
+the live element references on the modern path; the in-shadow span is the
+fallback target for AT that does not walk IDL refs. `aria-description` is
+intentionally NEVER written — the W3C AccName algorithm ignores it
+whenever `aria-describedby` is also present.
+
+Slot mutation observers track:
+  1. The label slot's text content (in-place i18n re-renders).
+  2. Consumer-resolved external IDREF targets (so a consumer mutating
+     `<label id="x">Patient</label>` in place re-flows the name).
+  3. Host attribute mutations (delegated to `installAriaIdrefMirror`,
+     which also catches late-inserted IDREF targets and id renames in
+     every relevant root).
+
+Focus trap, ESC dismiss, focus-restore, and the inert-outside-content
+sibling-walk are unchanged from the pre-host-canonical implementation —
+they operate against the shadow-internal panel which is still the focus
+target for keyboard users.
+
 ## Architecture Note: Native `<dialog>` Migration
 
 This component currently uses `role="dialog"` + `aria-modal="true"` on a

package/dist/components/HxDrawer/HxDrawer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HxDrawer.d.ts","sourceRoot":"","sources":["../../../src/components/HxDrawer/HxDrawer.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,WAAW,EAAE,MAAM,uCAAuC,CAAC;AAEpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,YAAY,EAAE,aAAa,EAAE,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,QAAQ;;;;;;EAYnB,CAAC;AAEH,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"HxDrawer.d.ts","sourceRoot":"","sources":["../../../src/components/HxDrawer/HxDrawer.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,WAAW,EAAE,MAAM,uCAAuC,CAAC;AAEpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,YAAY,EAAE,aAAa,EAAE,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuFG;AACH,eAAO,MAAM,QAAQ;;;;;;EAYnB,CAAC;AAEH,eAAe,QAAQ,CAAC"}

package/dist/components/HxDropdown/HxDropdown.d.ts

@@ -3,6 +3,51 @@ import { HxDropdownProps } from './types.js';
 export type { HxDropdownProps };
 /**
  * A dropdown component — a button that opens a floating panel on click.
+
+## Architecture Note: Host-Attribute Label Mirror (group-4 round-1)
+
+The announced surface is the inner `[part="panel"]` element, which carries
+`role="menu"`. The host wraps a slotted trigger and the floating panel and
+does NOT claim a role itself (apart from the round-35-style host
+`aria-expanded` fallback used only when the trigger slot is empty).
+
+Because the panel lives in shadow DOM and `ElementInternals` IDL refs on
+the host project semantics OUTWARD (host → AT) rather than INWARD
+(host → shadow descendant), we use the **host-attribute mirror** pattern:
+resolve consumer `aria-labelledby` IDREFs against the host's composed-tree
+roots, text-flatten via `flattenAccName`, and write the result to the
+panel's `aria-label`. Host `aria-label` outranks the `label` property in
+the same precedence used by every host-canonical hx-* control.
+
+Naming precedence (W3C AccName 1.2 §4.3.1):
+  1. Host `aria-labelledby` (resolved IDREFs, text-flattened)
+  2. Host `aria-label`
+  3. `label` property
+  4. Hard-coded literal `"Menu"` (last-resort accessible name)
+
+**Group 4b → Group 5b boundary:** Group 4b added the host-attribute
+label mirror **only** — additive on top of the existing dropdown
+behaviour. Group 5b (this commit) adds the composite-navigation
+portion that 4b explicitly deferred:
+  - **Roving tabindex** inside the panel (`_applyRovingTabIndex` +
+    `_rovingIndex`). Only the focused item carries `tabindex=0`.
+  - **First-character typeahead** with 500ms timeout (`_handleTypeahead`)
+    matching `hx-menu`, `hx-overflow-menu`, `hx-split-button`.
+  - Submenu auto-handling is delegated to slotted `hx-menu` /
+    `hx-menu-item` (whose `hx-item-submenu-open` / `hx-item-submenu-close`
+    events are auto-handled by the parent `hx-menu` after Group 5b).
+
+The panel's inner-div `role="menu"` is intentionally NOT migrated to
+the host: the host wraps a slotted consumer trigger AND the panel,
+so it cannot canonically carry the menu role. Slotted `hx-menu-item`
+children carry `role="menuitem"` on their HOST after Group 5b's menu
+migration, which fixes the cross-shadow walk concern from the
+consumer's perspective.
+
+`aria-controls` is intentionally omitted on the trigger: the panel lives
+in shadow DOM and IDREF values cannot be resolved across shadow
+boundaries by assistive technology (axe-core flags this as a critical
+violation if attempted). See `_setupTriggerAria` for the inline note.
  *
  * @example
  * ```tsx

package/dist/components/HxDropdown/HxDropdown.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HxDropdown.d.ts","sourceRoot":"","sources":["../../../src/components/HxDropdown/HxDropdown.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAC;AAExE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,YAAY,EAAE,eAAe,EAAE,CAAC;AAEhC;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU;;;;EAUrB,CAAC;AAEH,eAAe,UAAU,CAAC"}
+{"version":3,"file":"HxDropdown.d.ts","sourceRoot":"","sources":["../../../src/components/HxDropdown/HxDropdown.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAC;AAExE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,YAAY,EAAE,eAAe,EAAE,CAAC;AAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,eAAO,MAAM,UAAU;;;;EAUrB,CAAC;AAEH,eAAe,UAAU,CAAC"}

package/dist/components/HxField/HxField.d.ts

@@ -13,6 +13,26 @@ into its light DOM children for ARIA describedby linkage across the shadow
 DOM boundary. This span has `id="${fieldId}-desc"` and is removed on
 `disconnectedCallback`. This is an intentional, documented accessibility
 mechanism.
+
+**`aria-label` ownership model:** When `label` is set and no shadow `<label>`
+is rendered, hx-field writes `aria-label` to the slotted control and stamps
+a `data-hx-owns-label="true"` ownership marker.
+
+Consumers have two ways to keep their value safe from hx-field's writes:
+  (a) **Suspend** all ARIA bridging by setting `data-aria-managed` on the
+      control. While present, hx-field skips every aria-* mutation and
+      leaves any existing marker/snapshot in place — removing
+      `data-aria-managed` later may resume host ownership of an `aria-label`
+      value that still matches the snapshot.
+  (b) **Release** ownership permanently by overwriting `aria-label` to a
+      different value than the one hx-field last wrote. The mismatch
+      triggers `_releaseHostOwnedAriaLabel`, which strips the marker and
+      clears the snapshot, transferring ownership to the consumer.
+
+**Limitation:** because release detection is snapshot-based, a consumer
+rewrite to the *exact same value* hx-field last wrote is invisible. To
+genuinely take ownership in that case the consumer must write a different
+value (even briefly), or remove the `data-hx-owns-label` marker themselves.
  *
  * @example
  * ```tsx

package/dist/components/HxField/HxField.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HxField.d.ts","sourceRoot":"","sources":["../../../src/components/HxField/HxField.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,UAAU,EAAE,MAAM,sCAAsC,CAAC;AAElE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,YAAY,EAAE,YAAY,EAAE,CAAC;AAE7B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,OAAO,wDAMlB,CAAC;AAEH,eAAe,OAAO,CAAC"}
+{"version":3,"file":"HxField.d.ts","sourceRoot":"","sources":["../../../src/components/HxField/HxField.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,UAAU,EAAE,MAAM,sCAAsC,CAAC;AAElE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,YAAY,EAAE,YAAY,EAAE,CAAC;AAE7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,OAAO,wDAMlB,CAAC;AAEH,eAAe,OAAO,CAAC"}

package/dist/components/HxIconButton/types.d.ts

@@ -19,6 +19,11 @@ export interface HxIconButtonProps {
     type?: 'button' | 'submit' | 'reset';
     /** Whether the button is disabled. */
     disabled?: boolean;
+    /** Whether the button is in a loading state. Shows the spinner, prevents
+  activation, and sets `aria-busy="true"` on the inner element. Does NOT
+  set the native `disabled` attribute (loading is transient; disabled is
+  persistent, and AT announces them differently). */
+    loading?: boolean;
     /** When set, renders an `<a>` element instead of a `<button>`. */
     href?: string | undefined;
     /** Name submitted with form data. Only applicable when rendering as a button. */

package/dist/components/HxIconButton/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/components/HxIconButton/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,MAAM,WAAW,iBAAiB;IAChC,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,qBAAqB;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oBAAoB;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B;;2EAEuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,OAAO,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAC;IACpE,0BAA0B;IAC1B,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAC1B;sCACkC;IAClC,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;IACrC,sCAAsC;IACtC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAG3B,4DAA4D;IAC5D,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACpC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/components/HxIconButton/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,MAAM,WAAW,iBAAiB;IAChC,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,qBAAqB;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oBAAoB;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B;;2EAEuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,OAAO,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAC;IACpE,0BAA0B;IAC1B,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAC1B;sCACkC;IAClC,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;IACrC,sCAAsC;IACtC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;oDAGgD;IAChD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAG3B,4DAA4D;IAC5D,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACpC"}

package/dist/components/HxLink/types.d.ts

@@ -24,6 +24,10 @@ export interface HxLinkProps {
     /** Relationship between the current document and the linked URL.
   Automatically set to "noopener noreferrer" when target="_blank". */
     rel?: string | undefined;
+    /** Localised announcement text appended (visually hidden) to the link's
+  accessible name when `target="_blank"`. Defaults to English. Override
+  for i18n contexts so AT users hear the new-tab notice in their locale. */
+    externalLabel?: string;
     /** Dispatched when the link is clicked and is not disabled. */
     onHxClick?: (event: Event) => void;
 }

package/dist/components/HxLink/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/components/HxLink/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,MAAM,WAAW,WAAW;IAC1B,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,qBAAqB;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oBAAoB;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B;;0CAEsC;IACtC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,wCAAwC;IACxC,OAAO,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC1C;;0CAEsC;IACtC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;iDAC6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B;qEACiE;IACjE,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAGzB,+DAA+D;IAC/D,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACpC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/components/HxLink/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,MAAM,WAAW,WAAW;IAC1B,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,qBAAqB;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oBAAoB;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B;;0CAEsC;IACtC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,wCAAwC;IACxC,OAAO,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC1C;;0CAEsC;IACtC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;iDAC6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B;qEACiE;IACjE,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB;;2EAEuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAC;IAGvB,+DAA+D;IAC/D,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACpC"}

package/dist/components/HxList/HxList.d.ts

@@ -3,6 +3,12 @@ import { HxListProps } from './types.js';
 export type { HxListProps };
 /**
  * A styled list container supporting plain, bulleted, numbered, description, and interactive variants.
+
+Group 7 host-canonical: `role="list"` (or `role="listbox"` in interactive
+mode) lives on the **host** via `_internals.role`, harmonizing with
+`hx-structured-list` (the gold-standard exemplar for Group 7). The `<dl>`
+description variant keeps native semantics — no host role assigned, since
+`<dl>` IS the semantic surface and AT walks it directly.
  *
  * @example
  * ```tsx

package/dist/components/HxList/HxList.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HxList.d.ts","sourceRoot":"","sources":["../../../src/components/HxList/HxList.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AAEhE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,YAAY,EAAE,WAAW,EAAE,CAAC;AAE5B;;;;;;;;;GASG;AACH,eAAO,MAAM,MAAM;;EAQjB,CAAC;AAEH,eAAe,MAAM,CAAC"}
+{"version":3,"file":"HxList.d.ts","sourceRoot":"","sources":["../../../src/components/HxList/HxList.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AAEhE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,YAAY,EAAE,WAAW,EAAE,CAAC;AAE5B;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,MAAM;;EAQjB,CAAC;AAEH,eAAe,MAAM,CAAC"}

package/dist/components/HxListItem/HxListItem.d.ts

@@ -3,6 +3,14 @@ import { HxListItemProps } from './types.js';
 export type { HxListItemProps };
 /**
  * A rich list item for use inside `hx-list`.
+
+Group 7 host-canonical: `role="option"` (interactive listbox mode) is
+mirrored onto the **host** via `_internals.role` AND the legacy
+setAttribute('role',...) path. The dual-surface pattern preserves the
+existing imperative host-attribute behaviour (so consumers querying
+`host.getAttribute('role')` still work) while adding cross-shadow IDREF
+wiring through `internals.ariaLabelledByElements` for engines that
+support it.
  *
  * @example
  * ```tsx

package/dist/components/HxListItem/HxListItem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HxListItem.d.ts","sourceRoot":"","sources":["../../../src/components/HxListItem/HxListItem.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AAEpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,YAAY,EAAE,eAAe,EAAE,CAAC;AAEhC;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU;;EAQrB,CAAC;AAEH,eAAe,UAAU,CAAC"}
+{"version":3,"file":"HxListItem.d.ts","sourceRoot":"","sources":["../../../src/components/HxListItem/HxListItem.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AAEpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,YAAY,EAAE,eAAe,EAAE,CAAC;AAEhC;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,UAAU;;EAQrB,CAAC;AAEH,eAAe,UAAU,CAAC"}

package/dist/components/HxMenu/HxMenu.d.ts

@@ -4,6 +4,21 @@ export type { HxMenuProps };
 /**
  * A menu container that manages keyboard navigation over a list of menu items.
 Use with `hx-menu-item` and `hx-menu-divider`.
+
+Group 5b host-canonical: `role="menu"` lives on the **host** via
+`_internals.role`. The host carries the announced surface so AT walks
+`<hx-menu>` (role=menu) → slotted `<hx-menu-item>` (role=menuitem on host)
+directly without two layers of indirection. Consumer-supplied
+`aria-label` / `aria-labelledby` on the host are resolved via the shared
+IDREF mirror; cross-shadow naming uses `ariaLabelledByElements` (modern)
+with a flattened-string fallback (legacy).
+
+Submenu coordination: when an `hx-menu-item` emits `hx-item-submenu-open`
+or `hx-item-submenu-close`, the parent menu auto-handles the toggle by
+calling `setSubmenuOpen()` on the item — UNLESS the consumer has called
+`event.preventDefault()` on the bubbled event, signaling that they own the
+submenu lifecycle. This matches APG-mandated behaviour while leaving an
+opt-out for advanced consumers.
  *
  * @example
  * ```tsx

package/dist/components/HxMenu/HxMenu.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HxMenu.d.ts","sourceRoot":"","sources":["../../../src/components/HxMenu/HxMenu.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AAEhE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,YAAY,EAAE,WAAW,EAAE,CAAC;AAE5B;;;;;;;;;;GAUG;AACH,eAAO,MAAM,MAAM;;;EASjB,CAAC;AAEH,eAAe,MAAM,CAAC"}
+{"version":3,"file":"HxMenu.d.ts","sourceRoot":"","sources":["../../../src/components/HxMenu/HxMenu.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AAEhE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,YAAY,EAAE,WAAW,EAAE,CAAC;AAE5B;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,MAAM;;;EASjB,CAAC;AAEH,eAAe,MAAM,CAAC"}

package/dist/components/HxMenu/types.d.ts

@@ -6,8 +6,10 @@ export interface HxMenuProps {
     className?: string;
     /** Inline styles */
     style?: React.CSSProperties;
-    /** Accessible label for the menu. Rendered as `aria-label` on the inner
-  `role="menu"` element when set. */
+    /** Accessible label for the menu. Used as a fallback when no consumer-supplied
+  `aria-label` / `aria-labelledby` is present on the host. On the modern
+  host-canonical path this projects onto `internals.ariaLabel`; on the
+  legacy fallback path it appears as `aria-label` on the inner div. */
     label?: string;
     /** Dispatched when Escape is pressed. */
     onHxClose?: (event: Event) => void;

package/dist/components/HxMenu/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/components/HxMenu/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,MAAM,WAAW,WAAW;IAC1B,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,qBAAqB;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oBAAoB;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B;oCACgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IAGf,yCAAyC;IACzC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACnC,2CAA2C;IAC3C,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACrC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/components/HxMenu/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,MAAM,WAAW,WAAW;IAC1B,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,qBAAqB;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oBAAoB;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B;;;sEAGkE;IAClE,KAAK,CAAC,EAAE,MAAM,CAAC;IAGf,yCAAyC;IACzC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACnC,2CAA2C;IAC3C,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACrC"}

package/dist/components/HxMenuDivider/HxMenuDivider.d.ts

@@ -3,6 +3,13 @@ import { HxMenuDividerProps } from './types.js';
 export type { HxMenuDividerProps };
 /**
  * A visual separator for grouping items within an `hx-menu`.
+
+Group 5b host-canonical: `role="separator"` lives on the **host** via
+`_internals.role` so the parent `<hx-menu>` (`role="menu"`) sees the
+separator as a direct child. `aria-orientation` is mirrored onto the host
+via `internals.ariaOrientation`. The inner div is presentational on the
+modern path and stripped of its role; the legacy fallback keeps the
+inner role for engines without ElementInternals IDL accessors.
  *
  * @example
  * ```tsx

package/dist/components/HxMenuDivider/HxMenuDivider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HxMenuDivider.d.ts","sourceRoot":"","sources":["../../../src/components/HxMenuDivider/HxMenuDivider.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AAEvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,YAAY,EAAE,kBAAkB,EAAE,CAAC;AAEnC;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,8DAMxB,CAAC;AAEH,eAAe,aAAa,CAAC"}
+{"version":3,"file":"HxMenuDivider.d.ts","sourceRoot":"","sources":["../../../src/components/HxMenuDivider/HxMenuDivider.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AAEvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,YAAY,EAAE,kBAAkB,EAAE,CAAC;AAEnC;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,aAAa,8DAMxB,CAAC;AAEH,eAAe,aAAa,CAAC"}

package/dist/components/HxMenuItem/HxMenuItem.d.ts

@@ -4,7 +4,21 @@ export type { HxMenuItemProps };
 /**
  * A single interactive item for use inside `hx-menu`. Supports normal, checkbox,
 and radio types, loading state, prefix/suffix slots, and submenu nesting.
-Use `aria-label` on the parent `hx-menu` to provide an accessible name.
+
+Group 5b host-canonical: `role="menuitem"` (or `menuitemcheckbox` /
+`menuitemradio` based on `type`) lives on the **host** via
+`_internals.role`. The roving tabindex is written to the host, so the host
+is the focusable surface and lands directly under the parent `<hx-menu>`
+(which carries `role="menu"`) in the AT walked tree. The inner element is
+presentational on the modern path — no role, no aria-* attributes — and
+carries only click/keyboard event handlers. Keyboard activation
+(Enter/Space) is owned by the host's `keydown` handler.
+
+Cross-shadow naming: consumer-supplied `aria-label` / `aria-labelledby` on
+the host project to `internals.ariaLabel` / `internals.ariaLabelledByElements`
+via the shared IDREF mirror. The slotted text content is used as the default
+accessible name when no override is set (AT walks slotted children
+automatically through the host's role).
  *
  * @example
  * ```tsx

package/dist/components/HxMenuItem/HxMenuItem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HxMenuItem.d.ts","sourceRoot":"","sources":["../../../src/components/HxMenuItem/HxMenuItem.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AAEpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,YAAY,EAAE,eAAe,EAAE,CAAC;AAEhC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,UAAU;;;;EAUrB,CAAC;AAEH,eAAe,UAAU,CAAC"}
+{"version":3,"file":"HxMenuItem.d.ts","sourceRoot":"","sources":["../../../src/components/HxMenuItem/HxMenuItem.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AAEpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,YAAY,EAAE,eAAe,EAAE,CAAC;AAEhC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,UAAU;;;;EAUrB,CAAC;AAEH,eAAe,UAAU,CAAC"}

package/dist/components/HxMeter/HxMeter.d.ts

@@ -5,6 +5,16 @@ export type { HxMeterProps };
  * A scalar measurement within a known range — e.g., disk usage, health score,
 or any numeric value with defined min/max bounds. Supports low/high/optimum
 threshold markers for semantic color feedback.
+
+Group 7 host-canonical: `role="meter"` is mirrored onto the **host** via
+`_internals.role` AND kept on the inner `[role="meter"]` element. The dual
+surface is the hx-progress-ring pattern (Group 7 gold-standard exemplar):
+the host carries the cross-shadow IDREF wiring (`ariaLabelledByElements`
+resolves through the shared mirror) while the inner element keeps its
+existing role/state surface so legacy AT and consumer queries continue to
+work. AccName 1.2 §4.3.1 precedence is implemented uniformly: consumer
+host `aria-labelledby` (flattened) > consumer host `aria-label` >
+`label` property / slotted label > derived value-text fallback.
  *
  * @example
  * ```tsx

package/dist/components/HxMeter/HxMeter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HxMeter.d.ts","sourceRoot":"","sources":["../../../src/components/HxMeter/HxMeter.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,UAAU,EAAE,MAAM,sCAAsC,CAAC;AAElE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,YAAY,EAAE,YAAY,EAAE,CAAC;AAE7B;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,OAAO,wDAMlB,CAAC;AAEH,eAAe,OAAO,CAAC"}
+{"version":3,"file":"HxMeter.d.ts","sourceRoot":"","sources":["../../../src/components/HxMeter/HxMeter.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,UAAU,EAAE,MAAM,sCAAsC,CAAC;AAElE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,YAAY,EAAE,YAAY,EAAE,CAAC;AAE7B;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,OAAO,wDAMlB,CAAC;AAEH,eAAe,OAAO,CAAC"}

package/dist/components/HxOverflowMenu/HxOverflowMenu.d.ts

@@ -4,6 +4,25 @@ export type { HxOverflowMenuProps };
 /**
  * An overflow menu (kebab/meatball menu) that reveals hidden actions via a
 floating panel. Composed from a trigger button and a slotted menu panel.
+
+## Architecture Note: Host-Attribute Trigger Label Mirror (group-5b)
+
+The composite has TWO ARIA-bearing surfaces inside its shadow DOM: the
+trigger button (`role` defaulted from `<button>`, with `aria-haspopup`,
+`aria-expanded`, `aria-controls`) and the panel (`role="menu"` on the
+inner div). The host wraps both — it cannot carry either canonical role
+itself, so role placement remains on the inner elements.
+
+What Group 5b adds:
+- **Roving tabindex** on slotted menu items (only the focused item has
+  tabindex=0; arrow keys move focus and rewrite tabindex). Closing-Tab
+  path is preserved (Tab moves focus past the menu and closes it).
+- **First-character typeahead** with 500ms timeout matching `hx-menu`.
+- **Host-attribute label mirror**: consumer-supplied `aria-label` /
+  `aria-labelledby` on the host flow to the trigger button's
+  `aria-label` (the trigger is the announced surface of the disclosure
+  pattern; consumer override wins over the `label` property). The panel
+  continues to use `labelMenu` for its own slot label.
  *
  * @example
  * ```tsx

package/dist/components/HxOverflowMenu/HxOverflowMenu.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HxOverflowMenu.d.ts","sourceRoot":"","sources":["../../../src/components/HxOverflowMenu/HxOverflowMenu.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,iBAAiB,EAAE,MAAM,8CAA8C,CAAC;AAEjF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,YAAY,EAAE,mBAAmB,EAAE,CAAC;AAEpC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc;;;;EAUzB,CAAC;AAEH,eAAe,cAAc,CAAC"}
+{"version":3,"file":"HxOverflowMenu.d.ts","sourceRoot":"","sources":["../../../src/components/HxOverflowMenu/HxOverflowMenu.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,iBAAiB,EAAE,MAAM,8CAA8C,CAAC;AAEjF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,YAAY,EAAE,mBAAmB,EAAE,CAAC;AAEpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,cAAc;;;;EAUzB,CAAC;AAEH,eAAe,cAAc,CAAC"}