@helixui/library 3.3.1 → 3.4.0

package/dist/components/hx-icon-button/hx-icon-button.d.ts

@@ -1,5 +1,6 @@
-import { nothing } from 'lit';
+import { nothing, TemplateResult } from 'lit';
 import { HelixElement } from '../../base/index.js';
+declare const HelixIconButton_base: typeof HelixElement;
 /**
  * An icon-only button component for compact, accessible actions.
  * Renders a square button or anchor element containing a single icon.
@@ -16,6 +17,7 @@ import { HelixElement } from '../../base/index.js';
  *
  * @csspart button - The native button or anchor element.
  * @csspart icon - The icon container span wrapping the default slot.
+ * @csspart spinner - The loading spinner SVG element shown when `loading` is true.
  *
  * @cssprop [--hx-icon-button-bg=transparent] - Button background color.
  * @cssprop [--hx-icon-button-color=var(--hx-color-primary-500)] - Icon color.
@@ -51,7 +53,7 @@ import { HelixElement } from '../../base/index.js';
  * @cssprop [--hx-color-error-500] - Color.
  * @cssprop [--hx-color-error-600] - Color.
  */
-export declare class HelixIconButton extends HelixElement {
+export declare class HelixIconButton extends HelixIconButton_base {
     static styles: import('lit').CSSResult[];
     /**
      * Accessible name for the button. Required. Rendered as `aria-label` and
@@ -81,6 +83,14 @@ export declare class HelixIconButton extends HelixElement {
      * @attr 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).
+     * @attr loading
+     */
+    loading: boolean;
     /**
      * When set, renders an `<a>` element instead of a `<button>`.
      * @attr href
@@ -107,7 +117,9 @@ export declare class HelixIconButton extends HelixElement {
     private _classes;
     /** @internal */
     private _iconSlot;
-    render(): typeof nothing | import('lit').TemplateResult<1>;
+    /** @internal */
+    private _renderSpinner;
+    render(): typeof nothing | TemplateResult<1>;
 }
 declare global {
     interface HTMLElementTagNameMap {
@@ -119,4 +131,5 @@ declare global {
         }>;
     }
 }
+export {};
 //# sourceMappingURL=hx-icon-button.d.ts.map

package/dist/components/hx-icon-button/hx-icon-button.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hx-icon-button.d.ts","sourceRoot":"","sources":["../../../src/components/hx-icon-button/hx-icon-button.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,OAAO,EAAE,MAAM,KAAK,CAAC;AACpC,OAAO,4CAA4C,CAAC;AAIpD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAKnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,qBACa,eAAgB,SAAQ,YAAY;IAC/C,OAAgB,MAAM,4BAAoD;IAE1E;;;;;OAKG;IAEH,KAAK,SAAM;IAEX;;;OAGG;IAEH,OAAO,EAAE,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAW;IAE7E;;;OAGG;IAEH,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAQ;IAEhC;;;;OAIG;IAEH,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAY;IAE/C;;;OAGG;IAEH,QAAQ,UAAS;IAEjB;;;OAGG;IAEH,IAAI,EAAE,MAAM,GAAG,SAAS,CAAa;IAErC;;;OAGG;IAEH,IAAI,EAAE,MAAM,GAAG,SAAS,CAAa;IAErC;;;OAGG;IAEH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAa;IAItC,oFAAoF;IACpF,OAAgB,cAAc,UAAQ;cAEnB,eAAe,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI;IAM3D,gBAAgB;IAChB,OAAO,CAAC,YAAY;IA+BpB,gBAAgB;IAChB,OAAO,CAAC,gBAAgB;IAIxB,gBAAgB;IAChB,OAAO,CAAC,QAAQ;IAQhB,gBAAgB;IAChB,OAAO,CAAC,SAAS;IAMR,MAAM;CAsDhB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,gBAAgB,EAAE,eAAe,CAAC;KACnC;IACD,UAAU,mBAAmB;QAC3B,UAAU,EAAE,WAAW,CAAC;YAAE,aAAa,EAAE,UAAU,CAAA;SAAE,CAAC,CAAC;KACxD;CACF"}
+{"version":3,"file":"hx-icon-button.d.ts","sourceRoot":"","sources":["../../../src/components/hx-icon-button/hx-icon-button.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AACzD,OAAO,4CAA4C,CAAC;AAIpD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;;AAMnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,qBACa,eAAgB,SAAQ,oBAAgC;IACnE,OAAgB,MAAM,4BAAoD;IAE1E;;;;;OAKG;IAEH,KAAK,SAAM;IAEX;;;OAGG;IAEH,OAAO,EAAE,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAW;IAE7E;;;OAGG;IAEH,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAQ;IAEhC;;;;OAIG;IAEH,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAY;IAE/C;;;OAGG;IAEH,QAAQ,UAAS;IAEjB;;;;;;OAMG;IAEH,OAAO,UAAS;IAEhB;;;OAGG;IAEH,IAAI,EAAE,MAAM,GAAG,SAAS,CAAa;IAErC;;;OAGG;IAEH,IAAI,EAAE,MAAM,GAAG,SAAS,CAAa;IAErC;;;OAGG;IAEH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAa;IAItC,oFAAoF;IACpF,OAAgB,cAAc,UAAQ;cAEnB,eAAe,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI;IAM3D,gBAAgB;IAChB,OAAO,CAAC,YAAY;IA+BpB,gBAAgB;IAChB,OAAO,CAAC,gBAAgB;IAIxB,gBAAgB;IAChB,OAAO,CAAC,QAAQ;IAShB,gBAAgB;IAChB,OAAO,CAAC,SAAS;IAIjB,gBAAgB;IAChB,OAAO,CAAC,cAAc;IA+Bb,MAAM;CAgFhB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,gBAAgB,EAAE,eAAe,CAAC;KACnC;IACD,UAAU,mBAAmB;QAC3B,UAAU,EAAE,WAAW,CAAC;YAAE,aAAa,EAAE,UAAU,CAAA;SAAE,CAAC,CAAC;KACxD;CACF"}

package/dist/components/hx-icon-button/hx-icon-button.styles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hx-icon-button.styles.d.ts","sourceRoot":"","sources":["../../../src/components/hx-icon-button/hx-icon-button.styles.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,qBAAqB,yBA2LjC,CAAC"}
+{"version":3,"file":"hx-icon-button.styles.d.ts","sourceRoot":"","sources":["../../../src/components/hx-icon-button/hx-icon-button.styles.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,qBAAqB,yBAyNjC,CAAC"}

package/dist/components/hx-icon-button/index.js

@@ -1,4 +1,4 @@
-import { H as e } from "../../shared/hx-icon-button-CGNdQSFM.js";
+import { H as e } from "../../shared/hx-icon-button-a6OpeQz5.js";
 export {
   e as HelixIconButton
 };

package/dist/components/hx-link/hx-link.d.ts

@@ -3,6 +3,7 @@ import { HelixElement } from '../../base/index.js';
  * Variant options for the link component.
  */
 export type LinkVariant = 'default' | 'subtle' | 'danger';
+declare const HelixLink_base: typeof HelixElement;
 /**
  * A semantic hyperlink component with accessibility-first design.
  * Renders a native `<a>` element for enabled state and a `<span>` for
@@ -52,7 +53,7 @@ export type LinkVariant = 'default' | 'subtle' | 'danger';
  * @cssprop [--hx-color-error-700] - Color.
  * @cssprop [--hx-color-neutral-400] - Color.
  */
-export declare class HelixLink extends HelixElement {
+export declare class HelixLink extends HelixLink_base {
     static styles: import('lit').CSSResult[];
     /**
      * The URL the link points to.
@@ -90,6 +91,13 @@ export declare class HelixLink extends HelixElement {
      * @attr rel
      */
     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.
+     * @attr external-label
+     */
+    externalLabel: string;
     /** @internal Blocks Enter and Space activation on disabled span. */
     private _handleDisabledKeydown;
     /** @internal */
@@ -105,4 +113,5 @@ declare global {
         'hx-link': HelixLink;
     }
 }
+export {};
 //# sourceMappingURL=hx-link.d.ts.map

package/dist/components/hx-link/hx-link.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hx-link.d.ts","sourceRoot":"","sources":["../../../src/components/hx-link/hx-link.ts"],"names":[],"mappings":"AACA,OAAO,4CAA4C,CAAC;AAIpD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAInD;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,qBACa,SAAU,SAAQ,YAAY;IACzC,OAAgB,MAAM,4BAAuC;IAE7D;;;OAGG;IAEH,IAAI,EAAE,MAAM,GAAG,SAAS,CAAa;IAErC;;;;;OAKG;IAEH,MAAM,EAAE,MAAM,GAAG,SAAS,CAAa;IAEvC;;;OAGG;IAEH,OAAO,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAa;IAErD;;;;;OAKG;IAEH,QAAQ,UAAS;IAEjB;;;;OAIG;IAEH,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAa;IAEzC;;;;OAIG;IAEH,GAAG,EAAE,MAAM,GAAG,SAAS,CAAa;IAIpC,oEAAoE;IACpE,OAAO,CAAC,sBAAsB;IAM9B,gBAAgB;IAChB,OAAO,CAAC,YAAY;IAkBpB,gBAAgB;IAChB,OAAO,CAAC,WAAW;IAMnB,gBAAgB;IAChB,OAAO,CAAC,mBAAmB;IAuBlB,MAAM;CAsChB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,SAAS,EAAE,SAAS,CAAC;KACtB;CACF"}
+{"version":3,"file":"hx-link.d.ts","sourceRoot":"","sources":["../../../src/components/hx-link/hx-link.ts"],"names":[],"mappings":"AACA,OAAO,4CAA4C,CAAC;AAIpD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAKnD;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,qBACa,SAAU,SAAQ,cAAgC;IAC7D,OAAgB,MAAM,4BAAuC;IAE7D;;;OAGG;IAEH,IAAI,EAAE,MAAM,GAAG,SAAS,CAAa;IAErC;;;;;OAKG;IAEH,MAAM,EAAE,MAAM,GAAG,SAAS,CAAa;IAEvC;;;OAGG;IAEH,OAAO,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAa;IAErD;;;;;OAKG;IAEH,QAAQ,UAAS;IAEjB;;;;OAIG;IAEH,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAa;IAEzC;;;;OAIG;IAEH,GAAG,EAAE,MAAM,GAAG,SAAS,CAAa;IAEpC;;;;;OAKG;IAEH,aAAa,EAAE,MAAM,CAAwB;IAI7C,oEAAoE;IACpE,OAAO,CAAC,sBAAsB;IAM9B,gBAAgB;IAChB,OAAO,CAAC,YAAY;IAkBpB,gBAAgB;IAChB,OAAO,CAAC,WAAW;IAMnB,gBAAgB;IAChB,OAAO,CAAC,mBAAmB;IAuBlB,MAAM;CAuDhB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,SAAS,EAAE,SAAS,CAAC;KACtB;CACF"}

package/dist/components/hx-link/index.js

@@ -1,4 +1,4 @@
-import { H as o } from "../../shared/hx-link-C-O6vq0Q.js";
+import { H as o } from "../../shared/hx-link-CMnZRUtQ.js";
 export {
   o as HelixLink
 };

package/dist/components/hx-list/hx-list-item.d.ts

@@ -3,6 +3,14 @@ import { HelixElement } from '../../base/index.js';
 /**
  * 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.
+ *
  * @summary Individual list item with optional prefix, suffix, description, link, and disabled/selected states.
  *
  * @tag hx-list-item
@@ -30,6 +38,12 @@ import { HelixElement } from '../../base/index.js';
  */
 export declare class HelixListItem extends HelixElement {
     static styles: import('lit').CSSResult[];
+    /**
+     * Test seam (Group 7 host-canonical migration): see other Group 7 components.
+     * Production code MUST NOT touch this field.
+     * @internal
+     */
+    static __testSupportsIdrefRefsOverride: boolean | null;
     /**
      * Whether the item is disabled. Prevents interaction.
      * @attr disabled
@@ -61,10 +75,22 @@ export declare class HelixListItem extends HelixElement {
      * @attr type
      */
     type: 'default' | 'term' | 'definition';
+    /** @internal */
+    private _supportsIdrefRefs;
+    /** @internal */
+    private _ariaMirror;
+    /** @internal */
+    private _resolvedAccessibleName;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
     updated(changedProps: PropertyValues<this>): void;
     /**
      * Syncs ARIA attributes to the host element when in interactive (listbox option) mode.
-     * This ensures correct ARIA ownership: ul[role=listbox] > hx-list-item[role=option].
+     * Preserves the prior imperative `setAttribute('role', 'option')` path so existing
+     * consumer queries and tests continue to pass. ALSO mirrors the same surface onto
+     * `internals.role` / `internals.ariaSelected` (modern path) so cross-shadow IDREF
+     * resolution through `internals.ariaLabelledByElements` works on engines that
+     * support it.
      */
     /** @internal */
     private _syncHostAria;

package/dist/components/hx-list/hx-list-item.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hx-list-item.d.ts","sourceRoot":"","sources":["../../../src/components/hx-list/hx-list-item.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AACzD,OAAO,4CAA4C,CAAC;AAIpD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAInD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBACa,aAAc,SAAQ,YAAY;IAC7C,OAAgB,MAAM,4BAA8C;IAEpE;;;OAGG;IAEH,QAAQ,UAAS;IAEjB;;;OAGG;IAEH,QAAQ,UAAS;IAEjB;;;OAGG;IAEH,IAAI,EAAE,MAAM,GAAG,SAAS,CAAa;IAErC;;;OAGG;IAEH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAa;IAEtC;;;;OAIG;IAEH,WAAW,UAAS;IAEpB;;;OAGG;IAEH,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,YAAY,CAAa;IAE3C,OAAO,CAAC,YAAY,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,IAAI;IAW1D;;;OAGG;IACH,gBAAgB;IAChB,OAAO,CAAC,aAAa;IAsBrB,gBAAgB;IAChB,OAAO,CAAC,sBAAsB;IAU9B,gBAAgB;IAChB,OAAO,CAAC,YAAY;IAUpB,gBAAgB;IAChB,OAAO,CAAC,cAAc;IAmBb,MAAM;IAmFf,gBAAgB;IAChB,OAAO,CAAC,cAAc;CAQvB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,cAAc,EAAE,aAAa,CAAC;KAC/B;CACF"}
+{"version":3,"file":"hx-list-item.d.ts","sourceRoot":"","sources":["../../../src/components/hx-list/hx-list-item.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AACzD,OAAO,4CAA4C,CAAC;AAIpD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAWnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBACa,aAAc,SAAQ,YAAY;IAC7C,OAAgB,MAAM,4BAA8C;IAEpE;;;;OAIG;IACH,MAAM,CAAC,+BAA+B,EAAE,OAAO,GAAG,IAAI,CAAQ;IAE9D;;;OAGG;IAEH,QAAQ,UAAS;IAEjB;;;OAGG;IAEH,QAAQ,UAAS;IAEjB;;;OAGG;IAEH,IAAI,EAAE,MAAM,GAAG,SAAS,CAAa;IAErC;;;OAGG;IAEH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAa;IAEtC;;;;OAIG;IAEH,WAAW,UAAS;IAEpB;;;OAGG;IAEH,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,YAAY,CAAa;IAIpD,gBAAgB;IAChB,OAAO,CAAC,kBAAkB,CAAQ;IAElC,gBAAgB;IAChB,OAAO,CAAC,WAAW,CAAsC;IAEzD,gBAAgB;IAChB,OAAO,CAAC,uBAAuB,CAAM;IAE5B,iBAAiB,IAAI,IAAI;IAazB,oBAAoB,IAAI,IAAI;IAM5B,OAAO,CAAC,YAAY,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,IAAI;IAW1D;;;;;;;OAOG;IACH,gBAAgB;IAChB,OAAO,CAAC,aAAa;IAgFrB,gBAAgB;IAChB,OAAO,CAAC,sBAAsB;IAU9B,gBAAgB;IAChB,OAAO,CAAC,YAAY;IAUpB,gBAAgB;IAChB,OAAO,CAAC,cAAc;IAmBb,MAAM;IAmFf,gBAAgB;IAChB,OAAO,CAAC,cAAc;CAQvB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,cAAc,EAAE,aAAa,CAAC;KAC/B;CACF"}

package/dist/components/hx-list/hx-list.d.ts

@@ -3,6 +3,12 @@ import { HelixElement } from '../../base/index.js';
 /**
  * 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.
+ *
  * @summary Container for list items with optional dividers and interactive selection.
  *
  * @tag hx-list
@@ -22,6 +28,12 @@ import { HelixElement } from '../../base/index.js';
  */
 export declare class HelixList extends HelixElement {
     static styles: import('lit').CSSResult[];
+    /**
+     * Test seam (Group 7 host-canonical migration): see other Group 7 components.
+     * Production code MUST NOT touch this field.
+     * @internal
+     */
+    static __testSupportsIdrefRefsOverride: boolean | null;
     /**
      * Visual variant of the list.
      * @attr variant
@@ -37,6 +49,12 @@ export declare class HelixList extends HelixElement {
      * @attr label
      */
     label: string | undefined;
+    /** @internal */
+    private _supportsIdrefRefs;
+    /** @internal */
+    private _ariaMirror;
+    /** @internal */
+    private _resolvedAccessibleName;
     connectedCallback(): void;
     disconnectedCallback(): void;
     updated(changedProps: PropertyValues<this>): void;
@@ -46,6 +64,16 @@ export declare class HelixList extends HelixElement {
      */
     /** @internal */
     private _updateItemStates;
+    /**
+     * Resolve the host's role for the current variant. Description variant
+     * uses native `<dl>` semantics (returns `null` so the host carries no
+     * explicit role). Interactive variant becomes `listbox`. All other
+     * variants are `list`.
+     * @internal
+     */
+    private _hostRole;
+    /** @internal */
+    private _syncHostAriaSemantics;
     /** @internal */
     private _handleSlotChange;
     /** @internal */

package/dist/components/hx-list/hx-list.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hx-list.d.ts","sourceRoot":"","sources":["../../../src/components/hx-list/hx-list.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AACzD,OAAO,4CAA4C,CAAC;AAGpD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAMnD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBACa,SAAU,SAAQ,YAAY;IACzC,OAAgB,MAAM,4BAA0C;IAEhE;;;OAGG;IAEH,OAAO,EAAE,OAAO,GAAG,UAAU,GAAG,UAAU,GAAG,aAAa,GAAG,aAAa,CAAW;IAErF;;;OAGG;IAEH,OAAO,UAAS;IAEhB;;;OAGG;IAEH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAa;IAE7B,iBAAiB,IAAI,IAAI;IAKzB,oBAAoB,IAAI,IAAI;IAK5B,OAAO,CAAC,YAAY,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,IAAI;IAc1D;;;OAGG;IACH,gBAAgB;IAChB,OAAO,CAAC,iBAAiB;IAQzB,gBAAgB;IAChB,OAAO,CAAC,iBAAiB;IAIzB,gBAAgB;IAChB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAiC7B;IAEF,gBAAgB;IAChB,OAAO,CAAC,gBAAgB;IAgBf,MAAM;CA+ChB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,SAAS,EAAE,SAAS,CAAC;KACtB;CACF"}
+{"version":3,"file":"hx-list.d.ts","sourceRoot":"","sources":["../../../src/components/hx-list/hx-list.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AACzD,OAAO,4CAA4C,CAAC;AAGpD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAanD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBACa,SAAU,SAAQ,YAAY;IACzC,OAAgB,MAAM,4BAA0C;IAEhE;;;;OAIG;IACH,MAAM,CAAC,+BAA+B,EAAE,OAAO,GAAG,IAAI,CAAQ;IAE9D;;;OAGG;IAEH,OAAO,EAAE,OAAO,GAAG,UAAU,GAAG,UAAU,GAAG,aAAa,GAAG,aAAa,CAAW;IAErF;;;OAGG;IAEH,OAAO,UAAS;IAEhB;;;OAGG;IAEH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAa;IAItC,gBAAgB;IAChB,OAAO,CAAC,kBAAkB,CAAQ;IAElC,gBAAgB;IAChB,OAAO,CAAC,WAAW,CAAsC;IAEzD,gBAAgB;IAChB,OAAO,CAAC,uBAAuB,CAAM;IAE5B,iBAAiB,IAAI,IAAI;IAczB,oBAAoB,IAAI,IAAI;IAO5B,OAAO,CAAC,YAAY,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,IAAI;IAkB1D;;;OAGG;IACH,gBAAgB;IAChB,OAAO,CAAC,iBAAiB;IAQzB;;;;;;OAMG;IACH,OAAO,CAAC,SAAS;IAMjB,gBAAgB;IAChB,OAAO,CAAC,sBAAsB;IAwE9B,gBAAgB;IAChB,OAAO,CAAC,iBAAiB;IAIzB,gBAAgB;IAChB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAiC7B;IAEF,gBAAgB;IAChB,OAAO,CAAC,gBAAgB;IAgBf,MAAM;CAmDhB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,SAAS,EAAE,SAAS,CAAC;KACtB;CACF"}

package/dist/components/hx-list/index.js

@@ -1,4 +1,4 @@
-import { H as s, a as t } from "../../shared/hx-list-MyEhh8c7.js";
+import { H as s, a as t } from "../../shared/hx-list-De66EtAP.js";
 export {
   s as HelixList,
   t as HelixListItem

package/dist/components/hx-menu/hx-menu-divider.d.ts

@@ -2,6 +2,13 @@ import { HelixElement } from '../../base/index.js';
 /**
  * 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.
+ *
  * @summary Horizontal divider between menu sections.
  *
  * @tag hx-menu-divider
@@ -12,6 +19,9 @@ import { HelixElement } from '../../base/index.js';
  */
 export declare class HelixMenuDivider extends HelixElement {
     static styles: import('lit').CSSResult[];
+    /** @internal */
+    private _supportsIdrefRefs;
+    connectedCallback(): void;
     render(): import('lit').TemplateResult<1>;
 }
 declare global {

package/dist/components/hx-menu/hx-menu-divider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hx-menu-divider.d.ts","sourceRoot":"","sources":["../../../src/components/hx-menu/hx-menu-divider.ts"],"names":[],"mappings":"AACA,OAAO,4CAA4C,CAAC;AAEpD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAInD;;;;;;;;;;GAUG;AACH,qBACa,gBAAiB,SAAQ,YAAY;IAChD,OAAgB,MAAM,4BAAqD;IAElE,MAAM;CAQhB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,iBAAiB,EAAE,gBAAgB,CAAC;KACrC;CACF"}
+{"version":3,"file":"hx-menu-divider.d.ts","sourceRoot":"","sources":["../../../src/components/hx-menu/hx-menu-divider.ts"],"names":[],"mappings":"AACA,OAAO,4CAA4C,CAAC;AAEpD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAKnD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBACa,gBAAiB,SAAQ,YAAY;IAChD,OAAgB,MAAM,4BAAqD;IAE3E,gBAAgB;IAChB,OAAO,CAAC,kBAAkB,CAAQ;IAEzB,iBAAiB,IAAI,IAAI;IAQzB,MAAM;CAehB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,iBAAiB,EAAE,gBAAgB,CAAC;KACrC;CACF"}

package/dist/components/hx-menu/hx-menu-item.d.ts

@@ -1,8 +1,23 @@
+import { PropertyValues } from 'lit';
 import { HelixElement } from '../../base/index.js';
 /**
  * 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).
  *
  * @summary Interactive item within an hx-menu.
  *
@@ -29,6 +44,19 @@ import { HelixElement } from '../../base/index.js';
  */
 export declare class HelixMenuItem extends HelixElement {
     static styles: import('lit').CSSResult[];
+    /**
+     * Test seam (codex push-gate round-1 finding 3 mirror of hx-select
+     * pattern): when set to `true` or `false`, overrides the platform
+     * `supportsIdrefElementReferences` probe before `connectedCallback`
+     * seeds `_supportsIdrefRefs`. Tests that need to exercise the fallback
+     * path must select it BEFORE the host connects so tabindex / role
+     * placement matches a legacy engine for the entire lifecycle.
+     *
+     * Production code MUST NOT touch this field. It is `static` so the test
+     * stub cleanup is global and obvious.
+     * @internal
+     */
+    static __testSupportsIdrefRefsOverride: boolean | null;
     /**
      * @internal Managed by parent hx-menu for roving tabindex.
      * Only the active item in the menu has tabindex=0; all others have -1.
@@ -70,13 +98,82 @@ export declare class HelixMenuItem extends HelixElement {
     private _submenuOpen;
     /** @internal */
     private _menuItemEl;
-    /** Focus the inner interactive element. */
+    /** @internal */
+    private _supportsIdrefRefs;
+    /** @internal */
+    private _ariaMirror;
+    /**
+     * Resolved accessible name for the menu item — read by both
+     * `_syncHostAriaSemantics()` (modern path: host `internals.ariaLabel`)
+     * and the fallback `render()` branch (legacy path: inner
+     * `div[role="menuitem*"]` `aria-label`). Empty string means "no
+     * override" — slotted text content provides the implicit name through
+     * the announced surface (host on modern; inner div on fallback). AccName
+     * 1.2 §4.3.1 precedence: consumer host `aria-labelledby` (flattened) >
+     * consumer host `aria-label` > implicit slotted text.
+     * @internal
+     */
+    private _resolvedAccessibleName;
+    /**
+     * Focus the menu item. On the modern host-canonical path, focus lands on
+     * the host (which carries the roving tabindex and announced role). On the
+     * legacy fallback path, focus delegates to the inner element which still
+     * carries the role.
+     */
     focus(options?: FocusOptions): void;
     connectedCallback(): void;
+    disconnectedCallback(): void;
+    updated(changedProperties: PropertyValues<this>): void;
+    /**
+     * Apply the roving tabindex to the host (modern path) so the host is the
+     * Tab stop. Disabled items are non-tabbable.
+     *
+     * Codex push-gate round-1 finding 3: on the fallback path
+     * (`_supportsIdrefRefs === false`), the inner `.menu-item` element
+     * carries `role="menuitem"` and the roving tabindex via the template
+     * (see `render()`'s legacy branch). If we ALSO assign a non-negative
+     * tabindex to the host, the user gets two focusable surfaces per item —
+     * Tab can land on the host even though the AT-announced role/aria-* live
+     * on the inner element. The host MUST be removed from the tab order on
+     * the fallback path; the inner element is the canonical Tab stop.
+     * @internal
+     */
+    private _applyHostTabIndex;
+    /**
+     * Mirror menuitem semantics onto the host via ElementInternals. Role is
+     * derived from `type` (normal → menuitem, checkbox → menuitemcheckbox,
+     * radio → menuitemradio). aria-disabled, aria-checked, aria-haspopup,
+     * aria-expanded, and aria-busy reactively follow component state.
+     * Consumer-supplied `aria-label` / `aria-labelledby` on the host project
+     * onto `internals.ariaLabel` / `internals.ariaLabelledByElements`.
+     * @internal
+     */
+    private _syncHostAriaSemantics;
     /** @internal */
     private _handleSubmenuSlotChange;
     /** @internal */
     private _activate;
+    /**
+     * Origin guard for host-bound click/keydown handlers. Returns `true` only
+     * when the event originated on THIS host (its shadow tree) and not on a
+     * nested `hx-menu-item` projected into the `submenu` slot.
+     *
+     * Codex push-gate round-5 P1: nested submenu items are slotted descendants
+     * in the parent's light DOM. Click/keydown events from a Child item bubble
+     * through the parent host's listeners — without this guard, selecting Child
+     * also activates Parent (double `hx-item-select`) and Enter/Space/ArrowRight
+     * on Child re-trigger Parent's handlers (wrong-level activation, second
+     * submenu reopen).
+     *
+     * Walks `composedPath()` and returns the closest `hx-menu-item` ancestor of
+     * the original target; the event is "ours" iff that ancestor is `this`.
+     * Mirrors the inner-vs-host origin discipline used by `hx-checkbox`,
+     * `hx-switch`, and `hx-toggle-button`'s host handlers (`path[0] !== this`)
+     * but adapts for hx-menu-item's nested-host case where path[0] is the
+     * deepest inner element of a slotted child's own shadow tree.
+     * @internal
+     */
+    private _isOwnEvent;
     /** @internal */
     private _handleClick;
     /** @internal */

package/dist/components/hx-menu/hx-menu-item.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hx-menu-item.d.ts","sourceRoot":"","sources":["../../../src/components/hx-menu/hx-menu-item.ts"],"names":[],"mappings":"AACA,OAAO,4CAA4C,CAAC;AAGpD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAKnD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBACa,aAAc,SAAQ,YAAY;IAC7C,OAAgB,MAAM,4BAAkD;IAExE;;;OAGG;IAEH,OAAO,CAAC,eAAe,CAAM;IAE7B,yEAAyE;IACzE,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAItC,mGAAmG;IACnG,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;IAInC;;;OAGG;IAEH,KAAK,SAAM;IAEX;;;OAGG;IAEH,QAAQ,UAAS;IAEjB;;;OAGG;IAEH,OAAO,UAAS;IAEhB;;;;OAIG;IAEH,IAAI,EAAE,QAAQ,GAAG,UAAU,GAAG,OAAO,CAAY;IAEjD;;;OAGG;IAEH,OAAO,UAAS;IAEhB,gBAAgB;IAEhB,OAAO,CAAC,WAAW,CAAS;IAE5B,qEAAqE;IAErE,OAAO,CAAC,YAAY,CAAS;IAE7B,gBAAgB;IACK,OAAO,CAAC,WAAW,CAAsB;IAE9D,2CAA2C;IAClC,KAAK,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI;IAInC,iBAAiB,IAAI,IAAI;IAclC,gBAAgB;IAChB,OAAO,CAAC,wBAAwB;IAKhC,gBAAgB;IAChB,OAAO,CAAC,SAAS;IA2BjB,gBAAgB;IAChB,OAAO,CAAC,YAAY;IASpB,gBAAgB;IAChB,OAAO,CAAC,cAAc;IA+BtB,gBAAgB;IAChB,OAAO,CAAC,kBAAkB;IAmB1B,gBAAgB;IAChB,OAAO,CAAC,kBAAkB;IAmB1B,gBAAgB;IAChB,OAAO,CAAC,cAAc;IActB,gBAAgB;IAChB,OAAO,CAAC,QAAQ;IAWP,MAAM;CAsChB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,cAAc,EAAE,aAAa,CAAC;KAC/B;CACF"}
+{"version":3,"file":"hx-menu-item.d.ts","sourceRoot":"","sources":["../../../src/components/hx-menu/hx-menu-item.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AACzD,OAAO,4CAA4C,CAAC;AAGpD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAYnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,qBACa,aAAc,SAAQ,YAAY;IAC7C,OAAgB,MAAM,4BAAkD;IAExE;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,+BAA+B,EAAE,OAAO,GAAG,IAAI,CAAQ;IAE9D;;;OAGG;IAEH,OAAO,CAAC,eAAe,CAAM;IAE7B,yEAAyE;IACzE,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAKtC,mGAAmG;IACnG,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;IAInC;;;OAGG;IAEH,KAAK,SAAM;IAEX;;;OAGG;IAEH,QAAQ,UAAS;IAEjB;;;OAGG;IAEH,OAAO,UAAS;IAEhB;;;;OAIG;IAEH,IAAI,EAAE,QAAQ,GAAG,UAAU,GAAG,OAAO,CAAY;IAEjD;;;OAGG;IAEH,OAAO,UAAS;IAEhB,gBAAgB;IAEhB,OAAO,CAAC,WAAW,CAAS;IAE5B,qEAAqE;IAErE,OAAO,CAAC,YAAY,CAAS;IAE7B,gBAAgB;IACK,OAAO,CAAC,WAAW,CAAsB;IAI9D,gBAAgB;IAChB,OAAO,CAAC,kBAAkB,CAAQ;IAElC,gBAAgB;IAChB,OAAO,CAAC,WAAW,CAAsC;IAEzD;;;;;;;;;;OAUG;IACH,OAAO,CAAC,uBAAuB,CAAM;IAErC;;;;;OAKG;IACM,KAAK,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI;IASnC,iBAAiB,IAAI,IAAI;IAmCzB,oBAAoB,IAAI,IAAI;IAQ5B,OAAO,CAAC,iBAAiB,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,IAAI;IAoB/D;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,kBAAkB;IAc1B;;;;;;;;OAQG;IACH,OAAO,CAAC,sBAAsB;IAqG9B,gBAAgB;IAChB,OAAO,CAAC,wBAAwB;IAKhC,gBAAgB;IAChB,OAAO,CAAC,SAAS;IA2BjB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,WAAW;IAWnB,gBAAgB;IAChB,OAAO,CAAC,YAAY,CAWlB;IAEF,gBAAgB;IAChB,OAAO,CAAC,cAAc,CAyCpB;IAEF,gBAAgB;IAChB,OAAO,CAAC,kBAAkB;IAmB1B,gBAAgB;IAChB,OAAO,CAAC,kBAAkB;IAmB1B,gBAAgB;IAChB,OAAO,CAAC,cAAc;IActB,gBAAgB;IAChB,OAAO,CAAC,QAAQ;IAWP,MAAM;CA8EhB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,cAAc,EAAE,aAAa,CAAC;KAC/B;CACF"}

package/dist/components/hx-menu/hx-menu-item.styles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hx-menu-item.styles.d.ts","sourceRoot":"","sources":["../../../src/components/hx-menu/hx-menu-item.styles.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,mBAAmB,yBA8H/B,CAAC"}
+{"version":3,"file":"hx-menu-item.styles.d.ts","sourceRoot":"","sources":["../../../src/components/hx-menu/hx-menu-item.styles.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,mBAAmB,yBAsJ/B,CAAC"}

package/dist/components/hx-menu/hx-menu.d.ts

@@ -1,8 +1,24 @@
+import { PropertyValues } from 'lit';
 import { HelixElement } from '../../base/index.js';
 /**
  * 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.
+ *
  * @summary Context/action menu with keyboard-navigable items.
  *
  * @tag hx-menu
@@ -30,8 +46,10 @@ import { HelixElement } from '../../base/index.js';
 export declare class HelixMenu extends HelixElement {
     static styles: import('lit').CSSResult[];
     /**
-     * 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.
      * @attr label
      */
     label: string;
@@ -50,7 +68,50 @@ export declare class HelixMenu extends HelixElement {
      * @internal
      */
     private _typeaheadTimer;
+    /**
+     * Test seam (codex push-gate round-2 finding 1): when set to `true` or
+     * `false`, overrides the platform `supportsIdrefElementReferences` probe
+     * before `connectedCallback` seeds `_supportsIdrefRefs`. Mirrors the
+     * hx-select / hx-menu-item seam — required so tests can deterministically
+     * exercise the legacy fallback render branch (where the inner
+     * `div[role="menu"]` is the announced surface and must mirror the
+     * resolved accessible name).
+     *
+     * Production code MUST NOT touch this field. It is `static` so the test
+     * stub cleanup is global and obvious.
+     * @internal
+     */
+    static __testSupportsIdrefRefsOverride: boolean | null;
+    /** @internal */
+    private _supportsIdrefRefs;
     /** @internal */
+    private _ariaMirror;
+    /**
+     * Resolved accessible name for the menu — the single source of truth that
+     * both `_syncHostAriaSemantics()` (modern path: writes to
+     * `internals.ariaLabel`) and the fallback `render()` branch (legacy path:
+     * writes to inner `div[role="menu"]` `aria-label`) read. Recomputed by
+     * `_syncHostAriaSemantics()` whenever host aria-* or `label` changes via
+     * the shared IDREF mirror. AccName 1.2 §4.3.1 precedence: consumer host
+     * `aria-labelledby` (flattened) > consumer host `aria-label` > `label`
+     * property > literal "Menu".
+     * @internal
+     */
+    private _resolvedAccessibleName;
+    /**
+     * Return the menu's enabled, top-level `hx-menu-item` children.
+     *
+     * Codex push-gate round-6 finding 3: `querySelectorAll('hx-menu-item')`
+     * walks the entire descendant tree, which on a parent menuitem
+     * includes the slotted nested `<hx-menu>` and ITS items. Treating
+     * those as top-level options corrupts roving tabindex, ArrowUp/Down
+     * navigation, and typeahead matching (typing the first letter of a
+     * grandchild item lands focus there instead of on the next sibling).
+     * Restrict to direct children of `this` so each menu owns only its
+     * own items.
+     *
+     * @internal
+     */
     private _getItems;
     /**
      * Synchronize roving tabindex across all enabled items.
@@ -70,12 +131,66 @@ export declare class HelixMenu extends HelixElement {
     private _handleKeyDown;
     /** @internal */
     private _handleTypeahead;
+    /**
+     * Read the typeahead label for an item — delegates to the shared
+     * `getMenuItemTypeaheadLabel` util so all four menu-bearing components
+     * (`hx-menu`, `hx-dropdown`, `hx-overflow-menu`, `hx-split-button`)
+     * share one submenu-aware extractor. Codex push-gate round-7 finding 3
+     * extracted this helper from its original home here in `hx-menu.ts`.
+     *
+     * @internal
+     */
+    private _getTypeaheadLabel;
     /** @internal */
     private _handleSlotChange;
     /** @internal */
     private _handleItemSelect;
+    /**
+     * Auto-handle submenu open/close events emitted by child `hx-menu-item`
+     * children. APG-mandated behaviour: ArrowRight on a parent item opens the
+     * nested submenu and focuses its first item; ArrowLeft closes the submenu
+     * and returns focus to the parent item. Consumers that own submenu
+     * lifecycle themselves can `event.preventDefault()` to opt out.
+     * @internal
+     */
+    private _handleSubmenuOpen;
+    /** @internal */
+    private _handleSubmenuClose;
+    connectedCallback(): void;
     disconnectedCallback(): void;
+    /**
+     * Codex push-gate round-7 finding 1: keydown bound on the HOST receives
+     * events that bubble out of nested submenus. When a child submenu is
+     * open and focus lives inside it, ArrowUp/Down/Home/End/Escape on the
+     * inner item bubbles to EVERY enclosing `hx-menu`. Without this guard
+     * the outer menu would run `_focusItem(...)` against its OWN top-level
+     * items and steal focus back out of the child submenu, and Escape would
+     * dispatch one `hx-close` per enclosing menu. Mirrors the
+     * `findClosestMenuAncestor` pattern already used by the submenu
+     * open/close handlers.
+     * @internal
+     */
+    private _handleHostKeyDown;
+    /**
+     * Codex push-gate round-7 finding 2: `hx-item-select` bubbles composed
+     * through every enclosing `hx-menu`. The outer menu would otherwise
+     * (a) corrupt `_focusedIndex` to `-1` because the bubbled item is not
+     * a member of the outer menu's items, and (b) re-emit a duplicate
+     * `hx-select`. Only act when THIS menu is the closest enclosing menu
+     * of the dispatching item.
+     * @internal
+     */
+    private _handleItemSelectHost;
+    updated(changedProperties: PropertyValues<this>): void;
     firstUpdated(): void;
+    /**
+     * Mirror menu semantics onto the host via ElementInternals so consumer-
+     * supplied `aria-label`, `aria-labelledby`, and the `label` property all
+     * reach the announced control. Falls back to a flattened-string label on
+     * engines that do not implement `ariaLabelledByElements`.
+     * @internal
+     */
+    private _syncHostAriaSemantics;
     render(): import('lit').TemplateResult<1>;
 }
 declare global {

package/dist/components/hx-menu/hx-menu.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hx-menu.d.ts","sourceRoot":"","sources":["../../../src/components/hx-menu/hx-menu.ts"],"names":[],"mappings":"AACA,OAAO,4CAA4C,CAAC;AAEpD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAMnD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBACa,SAAU,SAAQ,YAAY;IACzC,OAAgB,MAAM,4BAA8C;IAEpE;;;;OAIG;IAEH,KAAK,SAAM;IAEX;;;OAGG;IACH,OAAO,CAAC,aAAa,CAAM;IAE3B;;;OAGG;IACH,OAAO,CAAC,gBAAgB,CAAM;IAE9B;;;OAGG;IACH,OAAO,CAAC,eAAe,CAA8C;IAErE,gBAAgB;IAChB,OAAO,CAAC,SAAS;IAMjB;;;OAGG;IACH,gBAAgB;IAChB,OAAO,CAAC,mBAAmB;IAQ3B,iCAAiC;IACjC,UAAU,IAAI,IAAI;IAUlB,gCAAgC;IAChC,SAAS,IAAI,IAAI;IAUjB,gBAAgB;IAChB,OAAO,CAAC,UAAU;IASlB,gBAAgB;IAChB,OAAO,CAAC,mBAAmB;IAQ3B,gBAAgB;IAChB,OAAO,CAAC,cAAc;IAkCtB,gBAAgB;IAChB,OAAO,CAAC,gBAAgB;IAqBxB,gBAAgB;IAChB,OAAO,CAAC,iBAAiB;IAiBzB,gBAAgB;IAChB,OAAO,CAAC,iBAAiB;IAehB,oBAAoB,IAAI,IAAI;IAQ5B,YAAY,IAAI,IAAI;IASpB,MAAM;CAchB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,SAAS,EAAE,SAAS,CAAC;KACtB;CACF"}
+{"version":3,"file":"hx-menu.d.ts","sourceRoot":"","sources":["../../../src/components/hx-menu/hx-menu.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AACzD,OAAO,4CAA4C,CAAC;AAEpD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AA2CnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,qBACa,SAAU,SAAQ,YAAY;IACzC,OAAgB,MAAM,4BAA8C;IAEpE;;;;;;OAMG;IAEH,KAAK,SAAM;IAEX;;;OAGG;IACH,OAAO,CAAC,aAAa,CAAM;IAE3B;;;OAGG;IACH,OAAO,CAAC,gBAAgB,CAAM;IAE9B;;;OAGG;IACH,OAAO,CAAC,eAAe,CAA8C;IAIrE;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,+BAA+B,EAAE,OAAO,GAAG,IAAI,CAAQ;IAE9D,gBAAgB;IAChB,OAAO,CAAC,kBAAkB,CAAQ;IAElC,gBAAgB;IAChB,OAAO,CAAC,WAAW,CAAsC;IAEzD;;;;;;;;;;OAUG;IACH,OAAO,CAAC,uBAAuB,CAAM;IAErC;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,SAAS;IASjB;;;OAGG;IACH,gBAAgB;IAChB,OAAO,CAAC,mBAAmB;IAQ3B,iCAAiC;IACjC,UAAU,IAAI,IAAI;IAUlB,gCAAgC;IAChC,SAAS,IAAI,IAAI;IAUjB,gBAAgB;IAChB,OAAO,CAAC,UAAU;IASlB,gBAAgB;IAChB,OAAO,CAAC,mBAAmB;IAQ3B,gBAAgB;IAChB,OAAO,CAAC,cAAc;IAkCtB,gBAAgB;IAChB,OAAO,CAAC,gBAAgB;IAqBxB;;;;;;;;OAQG;IACH,OAAO,CAAC,kBAAkB;IAI1B,gBAAgB;IAChB,OAAO,CAAC,iBAAiB;IAiBzB,gBAAgB;IAChB,OAAO,CAAC,iBAAiB;IAezB;;;;;;;OAOG;IACH,OAAO,CAAC,kBAAkB,CAyBxB;IAEF,gBAAgB;IAChB,OAAO,CAAC,mBAAmB,CA6BzB;IAIO,iBAAiB,IAAI,IAAI;IA0BzB,oBAAoB,IAAI,IAAI;IAcrC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,kBAAkB,CAMxB;IAEF;;;;;;;;OAQG;IACH,OAAO,CAAC,qBAAqB,CAQ3B;IAEO,OAAO,CAAC,iBAAiB,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,IAAI;IAOtD,YAAY,IAAI,IAAI;IAa7B;;;;;;OAMG;IACH,OAAO,CAAC,sBAAsB;IAgFrB,MAAM;CAgChB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,SAAS,EAAE,SAAS,CAAC;KACtB;CACF"}

package/dist/components/hx-menu/index.js

@@ -1,4 +1,4 @@
-import { H as a, a as x, b as H } from "../../shared/hx-menu-divider-C2omnPtj.js";
+import { H as a, a as x, b as H } from "../../shared/hx-menu-divider-BjiRIWKq.js";
 export {
   a as HelixMenu,
   x as HelixMenuDivider,