@helixui/library 3.3.1 → 3.4.0-next.121

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

@@ -5,6 +5,59 @@ import { HelixElement } from '../../base/index.js';
  * 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
@@ -161,7 +214,91 @@ export declare class HelixDrawer extends HelixElement {
      * Unique ID for the title element, used by aria-labelledby to link the dialog to its label.
      * @internal
      */
+    private readonly _id;
+    /** @internal */
     private readonly _titleId;
+    /**
+     * Id of the synthesized in-shadow span that mirrors consumer-resolved
+     * description text. Belt-and-suspenders: the host's
+     * `internals.ariaDescribedByElements` carries the live element references
+     * on the modern path; this in-shadow span is the fallback referenced via
+     * `aria-describedby` on the inner overlay so AT that does not walk IDL refs
+     * still finds an announceable description.
+     * @internal
+     */
+    private readonly _consumerDescId;
+    /**
+     * Test seam: when set to `true` or `false`, overrides the platform
+     * `supportsIdrefElementReferences` probe before `connectedCallback`
+     * seeds `_supportsIdrefRefs`. Mirrors hx-combobox round-3 finding 4 —
+     * tests must select the path BEFORE the host connects so the synthetic
+     * environment matches a legacy engine. Production code MUST NOT touch
+     * this field. It is `static` so the cleanup is global and obvious.
+     * @internal
+     */
+    static __testSupportsIdrefRefsOverride: boolean | null;
+    /**
+     * Whether the runtime exposes IDL element references on ElementInternals.
+     * Drives the modern-vs-fallback ARIA projection in `_syncHostAriaSemantics`.
+     * @internal
+     */
+    private _supportsIdrefRefs;
+    /**
+     * Direct references to ALL labellable elements projected into
+     * `<slot name="label">`. Aggregates every assigned element so composed
+     * labels (e.g. `<svg slot="label" aria-hidden="true">…</svg><span slot="label">Patient</span>`)
+     * project the FULL visible label via `internals.ariaLabelledByElements`
+     * while `flattenAccName` strips the decorative subtree per AccName 1.2.
+     * @internal
+     */
+    private _slottedLabelEls;
+    /**
+     * Flattened text content of the slotted label nodes, used for the no-IDL-ref
+     * fallback `internals.ariaLabel` and the legacy inner-overlay `aria-label`.
+     * @internal
+     */
+    private _labelSlotText;
+    /**
+     * Most recently observed consumer-supplied `aria-labelledby` token list on
+     * the host. Refreshed every sync via `getAttribute()` — the host attribute
+     * IS the live source of truth, so `removeAttribute` is observable on the
+     * next sync (it returns `null`).
+     * @internal
+     */
+    private _consumerLabelledBy;
+    /** @internal — see `_consumerLabelledBy`. */
+    private _consumerDescribedBy;
+    /**
+     * Handle for the shared IDREF mirror. See `installAriaIdrefMirror()`.
+     * @internal
+     */
+    private _ariaMirror;
+    /**
+     * Watches in-place text mutations on the assigned slotted label nodes
+     * (e.g. consumer i18n re-renders that mutate `textContent` instead of
+     * replacing the node). `slotchange` does NOT fire on descendant text
+     * mutations, so this observer is the only signal that keeps the host's
+     * accessible name synchronized with the visible label.
+     * @internal
+     */
+    private _labelSlotTextObserver;
+    /**
+     * Watches in-place text / visibility mutations on consumer light-DOM
+     * elements resolved from host `aria-labelledby` / `aria-describedby`.
+     * Reinstalled on every sync against the deduped union of resolved
+     * elements; disconnects automatically when the consumer retracts both
+     * IDREF chains.
+     * @internal
+     */
+    private _externalRefsObserver;
+    /**
+     * Dedicated host observer scoped to `aria-describedby` with
+     * `attributeOldValue: true`. Catches authentic consumer retraction
+     * (oldValue !== null && newValue === null) so the cached baseline
+     * follows the live attribute.
+     * @internal
+     */
+    private _hostDescribedByObserver;
     /**
      * Controls whether the drawer is open.
      * @attr open
@@ -204,6 +341,7 @@ export declare class HelixDrawer extends HelixElement {
     connectedCallback(): void;
     disconnectedCallback(): void;
     updated(changedProperties: PropertyValues<this>): void;
+    firstUpdated(changedProperties: PropertyValues<this>): void;
     /** Opens the drawer. */
     show(): void;
     /** Closes the drawer. */
@@ -250,6 +388,69 @@ export declare class HelixDrawer extends HelixElement {
     private _handleFooterSlotChange;
     /** @internal */
     private _handleLabelSlotChange;
+    /**
+     * Reads the label slot's assigned nodes and computes the discriminated
+     * naming state. Aggregates ALL assigned elements (not just the first) so
+     * composed labels project the FULL visible label via
+     * `internals.ariaLabelledByElements`. Per AccName 1.2 §4.3.10,
+     * `aria-hidden="true"` / `[hidden]` elements contribute zero to the
+     * accessible name but stay in `elements` so AT walking IDL refs sees the
+     * full visible group. `hasUsefulName` is gated on the flattened text
+     * length: a slot containing only decorative wrappers does NOT name the
+     * dialog, and the host falls through to the next naming source.
+     * @internal
+     */
+    private _readLabelSlotState;
+    /**
+     * (Re-)installs the mutation observer over the current set of slotted label
+     * elements. On any descendant text/visibility mutation we re-flatten and
+     * re-sync so the host's accessible name tracks the visible label.
+     * @internal
+     */
+    private _installLabelSlotTextObserver;
+    /**
+     * (Re-)installs a `MutationObserver` against the deduped union of
+     * consumer-resolved label/description elements. Watches `characterData`,
+     * `childList`, `subtree`, and `aria-hidden` / `hidden` attributes so any
+     * in-place mutation on the referenced light-DOM nodes triggers a fresh
+     * sync — keeping the modern-path IDL refs and the fallback-path text
+     * flatten aligned with the live consumer text.
+     * @internal
+     */
+    private _installExternalRefsObserver;
+    /**
+     * Resolves consumer-supplied label/description IDREFs on the host and
+     * projects the canonical dialog ARIA onto the **host** via
+     * `ElementInternals` (modern path) and onto the inner overlay via attribute
+     * writes (fallback path).
+     *
+     * Cross-shadow naming is belt-and-suspenders:
+     *
+     *   1. **Modern path** (`_supportsIdrefRefs === true`): consumer-resolved
+     *      label/description elements are written onto
+     *      `internals.ariaLabelledByElements` / `internals.ariaDescribedByElements`
+     *      on the host. AT walking the host's accessibility tree finds them
+     *      across the shadow boundary. `internals.ariaLabel` carries the
+     *      flattened text fallback (only when no labelledby resolves) so AT
+     *      that does not walk IDL refs still announces a name.
+     *   2. **Fallback path** (`_supportsIdrefRefs === false`): the resolved
+     *      element text is flattened and written to `internals.ariaLabel` AND
+     *      mirrored to the inner overlay's `aria-label`.
+     *
+     * The synthesized `<span id="${_consumerDescId}">` mirrors the resolved
+     * description text on every sync. The inner overlay's `aria-describedby`
+     * chains the in-shadow span. `aria-description` is intentionally NEVER
+     * written — W3C AccName ignores it whenever `aria-describedby` is set.
+     *
+     * Naming precedence (W3C AccName 1.2 §4.3.1):
+     *   1. Consumer `aria-labelledby` (resolved IDREFs, text-flattened)
+     *   2. Consumer `aria-label`
+     *   3. Slotted `<slot name="label">` text
+     *   4. `label` property
+     *   5. Hard-coded `"Drawer"`
+     * @internal
+     */
+    private _syncHostAriaSemantics;
     /** @internal */
     private _renderHeader;
     /** @internal */

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

@@ -1 +1 @@
-{"version":3,"file":"hx-drawer.d.ts","sourceRoot":"","sources":["../../../src/components/hx-drawer/hx-drawer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AACzD,OAAO,4CAA4C,CAAC;AAMpD,OAAO,EAAE,YAAY,EAAmB,MAAM,qBAAqB,CAAC;AA2BpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqGG;AACH,qBACa,WAAY,SAAQ,YAAY;IAC3C,OAAgB,MAAM,4BAA4C;IAIlE;;;OAGG;IAEH,OAAO,CAAC,UAAU,CAAiC;IAEnD;;;OAGG;IAEH,OAAO,CAAC,QAAQ,CAAiC;IAIjD;;;OAGG;IAEH,OAAO,CAAC,OAAO,CAAS;IAExB;;;OAGG;IAEH,OAAO,CAAC,qBAAqB,CAAS;IAEtC;;;OAGG;IAEH,OAAO,CAAC,cAAc,CAAS;IAE/B;;;OAGG;IAEH,OAAO,CAAC,aAAa,CAAS;IAE9B;;;OAGG;IACH,OAAO,CAAC,wBAAwB,CAAqB;IACrD;;;OAGG;IACH,OAAO,CAAC,eAAe,CAA4B;IACnD;;;OAGG;IACH,OAAO,CAAC,iBAAiB,CAA8C;IACvE,uEAAuE;IACvE,gBAAgB;IAChB,OAAO,CAAC,cAAc,CAAS;IAC/B;;;OAGG;IACH,OAAO,CAAC,0BAA0B,CAAiB;IAEnD;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8B;IAIvD;;;OAGG;IAEH,IAAI,UAAS;IAEb;;;OAGG;IAEH,SAAS,EAAE,OAAO,GAAG,KAAK,GAAG,KAAK,GAAG,QAAQ,CAAS;IAEtD;;;OAGG;IAEH,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,MAAM,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAQ;IAE3E;;;;OAIG;IAEH,SAAS,UAAS;IAElB;;;OAGG;IAEH,QAAQ,UAAS;IAEjB;;;OAGG;IAEH,QAAQ,UAAS;IAEjB;;;;OAIG;IAEH,KAAK,SAAM;IAEX,mFAAmF;IAEnF,UAAU,SAAkB;IAInB,iBAAiB,IAAI,IAAI;IAWzB,oBAAoB,IAAI,IAAI;IAS5B,OAAO,CAAC,iBAAiB,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,IAAI;IAkB/D,wBAAwB;IACxB,IAAI,IAAI,IAAI;IAIZ,yBAAyB;IACzB,IAAI,IAAI,IAAI;IAMZ,gBAAgB;IAChB,OAAO,CAAC,aAAa;IAOrB,gBAAgB;IAChB,OAAO,CAAC,eAAe;IASvB,gBAAgB;IAChB,OAAO,CAAC,kBAAkB;IAM1B,gBAAgB;IAChB,OAAO,CAAC,WAAW;IA2DnB,gBAAgB;IAChB,OAAO,CAAC,YAAY;IA8CpB,gBAAgB;IAChB,OAAO,CAAC,qBAAqB;IAQ7B,gBAAgB;IAChB,OAAO,CAAC,gCAAgC;IAuBxC,gBAAgB;IAChB,OAAO,CAAC,kCAAkC;IAS1C,gBAAgB;IAChB,OAAO,CAAC,aAAa;IAIrB,gBAAgB;IAChB,OAAO,CAAC,gBAAgB;IAMxB;;;OAGG;IACH,OAAO,CAAC,cAAc,CAYpB;IAIF,gBAAgB;IAChB,OAAO,CAAC,gBAAgB;IAkBxB,gBAAgB;IAChB,OAAO,CAAC,qBAAqB;IA0B7B,gBAAgB;IAChB,OAAO,CAAC,UAAU;IAmClB;;;OAGG;IACH,OAAO,CAAC,mBAAmB,CAMzB;IAIF,gBAAgB;IAChB,OAAO,CAAC,8BAA8B;IAKtC,gBAAgB;IAChB,OAAO,CAAC,uBAAuB;IAK/B,gBAAgB;IAChB,OAAO,CAAC,sBAAsB;IAO9B,gBAAgB;IAChB,OAAO,CAAC,aAAa;IA8DrB,gBAAgB;IAChB,OAAO,CAAC,aAAa;IAYZ,MAAM;CAiChB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,WAAW,EAAE,WAAW,CAAC;KAC1B;IACD,UAAU,mBAAmB;QAC3B,SAAS,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC;QAC7B,eAAe,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC;QACnC,SAAS,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC;QAC7B,eAAe,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC;QACnC,kBAAkB,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC;KACvC;CACF"}
+{"version":3,"file":"hx-drawer.d.ts","sourceRoot":"","sources":["../../../src/components/hx-drawer/hx-drawer.ts"],"names":[],"mappings":"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"}

package/dist/components/hx-drawer/hx-drawer.styles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hx-drawer.styles.d.ts","sourceRoot":"","sources":["../../../src/components/hx-drawer/hx-drawer.styles.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,yBA2R7B,CAAC"}
+{"version":3,"file":"hx-drawer.styles.d.ts","sourceRoot":"","sources":["../../../src/components/hx-drawer/hx-drawer.styles.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,yBA4S7B,CAAC"}

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

@@ -1,4 +1,4 @@
-import { H as a } from "../../shared/hx-drawer-Y1Ui2IWJ.js";
+import { H as a } from "../../shared/hx-drawer-DH6CdAN1.js";
 export {
   a as HelixDrawer
 };

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

@@ -4,6 +4,51 @@ export type DropdownPlacement = 'top' | 'top-start' | 'top-end' | 'bottom' | 'bo
 /**
  * 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.
+ *
  * @summary Button that opens a floating menu panel on click.
  *
  * @tag hx-dropdown
@@ -74,6 +119,49 @@ export declare class HelixDropdown extends HelixElement {
      * @internal
      */
     private _panelVisible;
+    /**
+     * Index within the panel's focusable menu items of the item currently
+     * holding the roving tabindex (and thus visual focus). −1 means the
+     * panel has not been keyboard-focused yet.
+     * @internal
+     */
+    private _rovingIndex;
+    /**
+     * Accumulated character buffer for typeahead search within the panel's
+     * menu items. Cleared after 500ms of inactivity.
+     * @internal
+     */
+    private _typeaheadBuffer;
+    /**
+     * Timer handle that clears the typeahead buffer after a period of inactivity.
+     * @internal
+     */
+    private _typeaheadTimer;
+    /**
+     * Resolved accessible name for the menu panel — the value written to the
+     * inner `[part="panel"]` `aria-label`. Recomputed on every sync per
+     * AccName 1.2 §4.3.1 precedence: host `aria-labelledby` (flattened) >
+     * host `aria-label` > `label` property > literal `"Menu"`.
+     * @internal
+     */
+    private _resolvedLabel;
+    /**
+     * Most recently observed consumer-supplied `aria-labelledby` token list on
+     * the host. Refreshed every sync via `getAttribute()`.
+     * @internal
+     */
+    private _consumerLabelledBy;
+    /**
+     * Handle for the shared host attribute / root id observer.
+     * @internal
+     */
+    private _ariaMirror;
+    /**
+     * Watches in-place text / visibility mutations on consumer light-DOM
+     * elements resolved from the host's `aria-labelledby`.
+     * @internal
+     */
+    private _externalRefsObserver;
     /**
      * Guards against accumulating multiple document click listeners when open state
      * changes faster than the microtask queue can process removeEventListener calls.
@@ -111,6 +199,30 @@ export declare class HelixDropdown extends HelixElement {
     private _handleKeydown;
     /** @internal */
     private _handleMenuNavigation;
+    /**
+     * Roving tabindex inside the panel: only the focused item carries
+     * tabindex=0; the rest are tabindex=-1. APG-compliant for the menu
+     * button pattern. Closing-Tab semantics are preserved by the
+     * `_handleKeydown` Tab branch above (which lets focus advance
+     * naturally and closes the panel).
+     *
+     * Group 5b: introduced to align hx-dropdown's panel keyboard contract
+     * with hx-menu / hx-overflow-menu / hx-split-button. Group 4b only
+     * added the host-attribute label mirror (additive); this is the
+     * keyboard portion deferred until Group 5.
+     *
+     * Codex push-gate round-8 finding 2: route through
+     * `writeMenuItemRovingTabIndex` so host-canonical `hx-menu-item` items
+     * land their roving tabindex on the correct surface (host on the
+     * modern path, inner `.menu-item` on the fallback path). A direct
+     * `item.tabIndex = value` write on the host fails on the fallback
+     * path because the host is forced to `tabindex=-1` to keep exactly
+     * one focusable surface per item.
+     * @internal
+     */
+    private _applyRovingTabIndex;
+    /** @internal */
+    private _handleTypeahead;
     /** @internal */
     private _getFocusableMenuItems;
     /** @internal */
@@ -119,6 +231,42 @@ export declare class HelixDropdown extends HelixElement {
     private _handleOutsideClick;
     /** @internal */
     private _handlePanelClick;
+    /**
+     * Bubbled `hx-item-select` from a slotted `hx-menu-item` host. Forwards
+     * the activation through the composite's `hx-select` contract using the
+     * item's `value` property and label text. Disabled items never emit
+     * `hx-item-select`, so no disabled-guard is needed here.
+     * @internal
+     */
+    private _handlePanelItemSelect;
+    /**
+     * Bubbled `hx-item-submenu-open` from a slotted `hx-menu-item` host.
+     * Codex push-gate round-9 P1: when slotted `hx-menu-item`s open / close
+     * a nested submenu inside this composite's panel (no enclosing
+     * `hx-menu`), the events fly past with no handler. Match the round-4
+     * `hx-menu._handleSubmenuOpen` shape so APG behaviour holds.
+     *
+     * If the dispatching item is enclosed by an inner `hx-menu` (a true
+     * nested submenu inside the panel), that menu owns the toggle — defer.
+     * Otherwise this composite's panel is the enclosing menu surface, so
+     * call `setSubmenuOpen(true)` on the item and focus the first child.
+     * @internal
+     */
+    private _handlePanelSubmenuOpen;
+    /**
+     * Bubbled `hx-item-submenu-close` from a slotted `hx-menu-item` host.
+     * Codex push-gate round-9 P1: routes the close to the right surface.
+     *
+     * - Nested submenu close (the dispatching item lives inside an inner
+     *   `hx-menu` slotted into a parent's `slot="submenu"`): defer to that
+     *   inner menu's own handler. The composite's panel must NOT close.
+     * - Top-level item ArrowLeft (no enclosing `hx-menu` between the item
+     *   and this composite): there is no parent submenu to close, so
+     *   collapse the composite's panel and return focus to the trigger,
+     *   matching APG menu-button behaviour.
+     * @internal
+     */
+    private _handlePanelSubmenuClose;
     render(): import('lit').TemplateResult<1>;
     /** @internal */
     private _onPanelSlotChange;
@@ -127,7 +275,27 @@ export declare class HelixDropdown extends HelixElement {
     firstUpdated(): void;
     /** @internal */
     private _setupTriggerAria;
+    willUpdate(changedProperties: PropertyValues<this>): void;
     updated(changedProperties: PropertyValues<this>): void;
+    /**
+     * (Re-)installs a `MutationObserver` over the deduped union of
+     * consumer-resolved label elements, watching for in-place text /
+     * visibility mutations so the panel's `aria-label` tracks live consumer
+     * text. See `hx-popover._installExternalRefsObserver` for the matching
+     * shape used across the host-attribute-mirror family.
+     * @internal
+     */
+    private _installExternalRefsObserver;
+    /**
+     * Resolves the menu panel's accessible name from host attributes and the
+     * `label` property. AccName 1.2 §4.3.1 precedence:
+     *   1. Host `aria-labelledby` (resolved IDREFs, flattened)
+     *   2. Host `aria-label`
+     *   3. `label` property
+     *   4. Literal `"Menu"` (last-resort)
+     * @internal
+     */
+    private _syncResolvedLabel;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

@@ -1 +1 @@
-{"version":3,"file":"hx-dropdown.d.ts","sourceRoot":"","sources":["../../../src/components/hx-dropdown/hx-dropdown.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AACzD,OAAO,4CAA4C,CAAC;AAGpD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAOnD,MAAM,MAAM,iBAAiB,GACzB,KAAK,GACL,WAAW,GACX,SAAS,GACT,QAAQ,GACR,cAAc,GACd,YAAY,GACZ,OAAO,GACP,KAAK,CAAC;AAIV;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,qBACa,aAAc,SAAQ,YAAY;IAC7C,OAAgB,MAAM,4BAAkD;IAIxE;;;OAGG;IAEH,IAAI,UAAS;IAEb;;;OAGG;IAEH,SAAS,EACL,KAAK,GACL,WAAW,GACX,SAAS,GACT,QAAQ,GACR,cAAc,GACd,YAAY,GACZ,OAAO,GACP,KAAK,CAAkB;IAE3B;;;OAGG;IACS,KAAK,SAAU;IAE3B;;;OAGG;IAEH,QAAQ,UAAS;IAEjB;;;OAGG;IAEH,QAAQ,SAAK;IAIb;;;OAGG;IACM,OAAO,CAAC,aAAa,CAAS;IAEvC;;;;OAIG;IACH,OAAO,CAAC,yBAAyB,CAAS;IAG1C;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAgC;IAEhD;;;OAGG;IACsB,OAAO,CAAC,MAAM,CAA0B;IACjE;;;OAGG;IACwB,OAAO,CAAC,eAAe,CAA0B;IAInE,iBAAiB,IAAI,IAAI;IAKzB,oBAAoB,IAAI,IAAI;IAWrC,gBAAgB;YACF,KAAK;IAwBnB,gBAAgB;IAChB,OAAO,CAAC,KAAK;IAkBb,gBAAgB;YACF,eAAe;IAyB7B,gBAAgB;IAChB,OAAO,CAAC,mBAAmB;IAS3B,gBAAgB;IAChB,OAAO,CAAC,qBAAqB;IAO7B,gBAAgB;IAChB,OAAO,CAAC,cAAc,CAepB;IAGF,gBAAgB;IAChB,OAAO,CAAC,qBAAqB;IAkB7B,gBAAgB;IAChB,OAAO,CAAC,sBAAsB;IAkB9B,gBAAgB;IAChB,OAAO,CAAC,sBAAsB;IAgB9B,gBAAgB;IAChB,OAAO,CAAC,mBAAmB,CAKzB;IAEF,gBAAgB;IAChB,OAAO,CAAC,iBAAiB;IAsBhB,MAAM;IA0Bf,gBAAgB;IAChB,OAAO,CAAC,kBAAkB;IAc1B,gBAAgB;IAChB,OAAO,CAAC,oBAAoB;IAInB,YAAY,IAAI,IAAI;IAI7B,gBAAgB;IAChB,OAAO,CAAC,iBAAiB;IAkBhB,OAAO,CAAC,iBAAiB,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,IAAI;CAchE;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,aAAa,EAAE,aAAa,CAAC;KAC9B;IACD,UAAU,mBAAmB;QAC3B,SAAS,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC;QAC7B,SAAS,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC;QAC7B,WAAW,EAAE,WAAW,CAAC;YAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KACnE;CACF"}
+{"version":3,"file":"hx-dropdown.d.ts","sourceRoot":"","sources":["../../../src/components/hx-dropdown/hx-dropdown.ts"],"names":[],"mappings":"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"}

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

@@ -1,4 +1,4 @@
-import { H as e } from "../../shared/hx-dropdown-LyaRc8Rf.js";
+import { H as e } from "../../shared/hx-dropdown-DiLd40Lm.js";
 export {
   e as HelixDropdown
 };

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

@@ -13,6 +13,26 @@ import { HelixElement } from '../../base/index.js';
  * `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.
+ *
  * @summary Layout wrapper for label, control, help text, and error message.
  *
  * @tag hx-field
@@ -150,6 +170,42 @@ export declare class HelixField extends HelixElement {
      * @internal
      */
     private _a11yDescEl;
+    /**
+     * Marker attribute placed on the slotted control whenever hx-field writes
+     * `aria-label` to it. Presence of this marker indicates host ownership of
+     * the attribute; absence means the value belongs to the consumer.
+     *
+     * Ownership is recomputed from the live DOM on every `_syncSlottedControl()`
+     * call rather than cached in a flag — this keeps post-mount mutations
+     * (consumer adds/removes `aria-label`, toggles `data-aria-managed`)
+     * authoritative instead of letting a stale snapshot win.
+     *
+     * See round-13 F2 for context on the precedence hazard.
+     * @internal
+     */
+    private static readonly _ARIA_LABEL_OWNED_ATTR;
+    /**
+     * Last `aria-label` value written by hx-field to the currently adopted
+     * control. Used in combination with the ownership marker to detect a
+     * consumer overwrite: if the marker is present but the live value no
+     * longer matches what we last wrote, the consumer has taken over and we
+     * release the marker so subsequent syncs treat the value as consumer-
+     * owned.
+     * @internal
+     */
+    private _lastWrittenAriaLabel;
+    /**
+     * Tracks whether the dev-time competing-label warning has already been
+     * emitted for the currently adopted slotted control.
+     *
+     * Latch semantics: this fires **once per adopted control**. The latch is
+     * only reset on adoption (`_resolveSlottedControl()`) or disconnection.
+     * Toggling `data-aria-managed` on/off on the same control after the
+     * warning has fired does NOT re-arm the latch — by design, to avoid
+     * console spam from consumers who toggle the attribute repeatedly.
+     * @internal
+     */
+    private _competingLabelWarned;
     connectedCallback(): void;
     disconnectedCallback(): void;
     updated(changedProps: PropertyValues<this>): void;
@@ -162,6 +218,52 @@ export declare class HelixField extends HelixElement {
     /** Tracks the first form control assigned to the default slot. */
     /** @internal */
     private _handleDefaultSlotChange;
+    /**
+     * Adopts a new slotted control and re-syncs ARIA wiring.
+     *
+     * Ownership of `aria-label` is tracked via the
+     * `data-hx-owns-label` marker attribute on the control itself, recomputed
+     * on every `_syncSlottedControl()` call — there is no cached ownership
+     * flag, so post-mount mutations of `aria-label` and `data-aria-managed`
+     * by the consumer are always honored.
+     * @internal
+     */
+    private _resolveSlottedControl;
+    /**
+     * Returns true if hx-field owns the `aria-label` on the given control —
+     * i.e. the host wrote it, the marker attribute is still present, AND the
+     * live value still matches the value the host last wrote.
+     *
+     * Side effect: when the marker is present but the value no longer matches
+     * `_lastWrittenAriaLabel`, the consumer has overwritten the host value
+     * directly. We release the marker (and reset the snapshot) so subsequent
+     * syncs treat the value as consumer-owned. This keeps the marker honest
+     * without a MutationObserver.
+     *
+     * Cross-host migration / pre-mounted marker: if the marker is present but
+     * `_lastWrittenAriaLabel === null`, this host has never written to the
+     * control. Either (a) the control was migrated from a prior hx-field that
+     * stamped the marker, or (b) a consumer pre-mounted the marker themselves.
+     * In both cases this host has no ownership claim, so we strip the orphan
+     * marker and treat the value as consumer-owned. Without this, a fresh host
+     * with `label=""` would silently strip the inherited aria-label.
+     *
+     * Note (snapshot limitation): if the consumer rewrites `aria-label` to the
+     * exact same value we last wrote, we cannot detect the overwrite — to
+     * genuinely take ownership in that case the consumer must either write a
+     * different value or remove the `data-hx-owns-label` marker themselves.
+     *
+     * Absence of the marker (or presence of `data-aria-managed`) means the
+     * consumer owns the value and hx-field must not touch it.
+     * @internal
+     */
+    private _hostOwnsAriaLabel;
+    /**
+     * Removes the host-owned `aria-label` and its ownership marker if (and only
+     * if) hx-field still owns them. Consumer-set values are left untouched.
+     * @internal
+     */
+    private _releaseHostOwnedAriaLabel;
     /**
      * Focuses the slotted form control when the shadow DOM label is clicked.
      * The shadow `<label>` cannot use `for`/`id` to link to a slotted input
@@ -182,6 +284,13 @@ export declare class HelixField extends HelixElement {
      * - `HX-*` elements manage their own ARIA attributes; bridging is skipped.
      * - Elements with `data-aria-managed` attribute opt out of ARIA mutation;
      *   bridging is skipped entirely for those elements.
+     *
+     * **Round-13 F2 ownership model:** `aria-label` ownership is recomputed
+     * from the live DOM on every call. If the marker attribute
+     * `data-hx-owns-label` is present, hx-field owns the value and may
+     * overwrite or remove it. Otherwise the consumer owns it, and hx-field
+     * leaves it alone. This makes post-mount consumer mutations
+     * (add/remove/replace) authoritative without relying on a stale flag.
      */
     /** @internal */
     private _syncSlottedControl;

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

@@ -1 +1 @@
-{"version":3,"file":"hx-field.d.ts","sourceRoot":"","sources":["../../../src/components/hx-field/hx-field.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AACzD,OAAO,4CAA4C,CAAC;AAGpD,OAAO,EAAE,YAAY,EAAmB,MAAM,qBAAqB,CAAC;AAcpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,qBACa,UAAW,SAAQ,YAAY;IAC1C,OAAgB,MAAM,4BAAsB;IAI5C;;;OAGG;IAEH,KAAK,SAAM;IAEX;;;OAGG;IAEH,QAAQ,UAAS;IAEjB;;;OAGG;IAEH,KAAK,SAAM;IAEX;;;OAGG;IAEH,QAAQ,SAAM;IAEd;;;;OAIG;IAEH,QAAQ,UAAS;IAEjB;;;OAGG;IAEH,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAQ;IAEhC;;;OAGG;IAEH,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAY;IAIvC;;;OAGG;IACM,OAAO,CAAC,aAAa,CAAS;IAEvC;;;OAGG;IACM,OAAO,CAAC,aAAa,CAAS;IAEvC;;;OAGG;IACM,OAAO,CAAC,YAAY,CAAS;IAEtC,gBAAgB;IAChB,OAAO,CAAC,sBAAsB;IAK9B,gBAAgB;IAChB,OAAO,CAAC,sBAAsB;IAK9B,gBAAgB;IAChB,OAAO,CAAC,qBAAqB;IAO7B;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAkB;IAElC;;;OAGG;IACH,OAAO,CAAC,WAAW,CAA2B;IAE9C;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAA4B;IAE5C;;;OAGG;IACH,OAAO,CAAC,WAAW,CAA2B;IAI9C;;;;OAIG;IACH,OAAO,CAAC,eAAe,CAA4B;IAEnD;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,WAAW,CAA4B;IAEtC,iBAAiB,IAAI,IAAI;IAKzB,oBAAoB,IAAI,IAAI;IAc5B,OAAO,CAAC,YAAY,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,IAAI;IAkB1D,uFAAuF;IACvF,gBAAgB;IAChB,OAAO,CAAC,iBAAiB;IAazB,qFAAqF;IACrF,gBAAgB;IAChB,OAAO,CAAC,eAAe;IAYvB,kEAAkE;IAClE,gBAAgB;IAChB,OAAO,CAAC,wBAAwB;IAOhC;;;;OAIG;IACH,gBAAgB;IAChB,OAAO,CAAC,iBAAiB;IAIzB;;;;;;;;;;;;;OAaG;IACH,gBAAgB;IAChB,OAAO,CAAC,mBAAmB;IA4ClB,MAAM;CAwEhB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,UAAU,EAAE,UAAU,CAAC;KACxB;CACF"}
+{"version":3,"file":"hx-field.d.ts","sourceRoot":"","sources":["../../../src/components/hx-field/hx-field.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AACzD,OAAO,4CAA4C,CAAC;AAGpD,OAAO,EAAE,YAAY,EAAmB,MAAM,qBAAqB,CAAC;AAcpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH,qBACa,UAAW,SAAQ,YAAY;IAC1C,OAAgB,MAAM,4BAAsB;IAI5C;;;OAGG;IAEH,KAAK,SAAM;IAEX;;;OAGG;IAEH,QAAQ,UAAS;IAEjB;;;OAGG;IAEH,KAAK,SAAM;IAEX;;;OAGG;IAEH,QAAQ,SAAM;IAEd;;;;OAIG;IAEH,QAAQ,UAAS;IAEjB;;;OAGG;IAEH,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAQ;IAEhC;;;OAGG;IAEH,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAY;IAIvC;;;OAGG;IACM,OAAO,CAAC,aAAa,CAAS;IAEvC;;;OAGG;IACM,OAAO,CAAC,aAAa,CAAS;IAEvC;;;OAGG;IACM,OAAO,CAAC,YAAY,CAAS;IAEtC,gBAAgB;IAChB,OAAO,CAAC,sBAAsB;IAK9B,gBAAgB;IAChB,OAAO,CAAC,sBAAsB;IAK9B,gBAAgB;IAChB,OAAO,CAAC,qBAAqB;IAO7B;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAkB;IAElC;;;OAGG;IACH,OAAO,CAAC,WAAW,CAA2B;IAE9C;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAA4B;IAE5C;;;OAGG;IACH,OAAO,CAAC,WAAW,CAA2B;IAI9C;;;;OAIG;IACH,OAAO,CAAC,eAAe,CAA4B;IAEnD;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,WAAW,CAA4B;IAE/C;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,sBAAsB,CAAwB;IAEtE;;;;;;;;OAQG;IACH,OAAO,CAAC,qBAAqB,CAAuB;IAEpD;;;;;;;;;;OAUG;IACH,OAAO,CAAC,qBAAqB,CAAS;IAE7B,iBAAiB,IAAI,IAAI;IAKzB,oBAAoB,IAAI,IAAI;IAiB5B,OAAO,CAAC,YAAY,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,IAAI;IAkB1D,uFAAuF;IACvF,gBAAgB;IAChB,OAAO,CAAC,iBAAiB;IAazB,qFAAqF;IACrF,gBAAgB;IAChB,OAAO,CAAC,eAAe;IAYvB,kEAAkE;IAClE,gBAAgB;IAChB,OAAO,CAAC,wBAAwB;IAOhC;;;;;;;;;OASG;IACH,OAAO,CAAC,sBAAsB;IAyB9B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,OAAO,CAAC,kBAAkB;IAmB1B;;;;OAIG;IACH,OAAO,CAAC,0BAA0B;IAQlC;;;;OAIG;IACH,gBAAgB;IAChB,OAAO,CAAC,iBAAiB;IAIzB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,gBAAgB;IAChB,OAAO,CAAC,mBAAmB;IA2ElB,MAAM;CAwEhB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,UAAU,EAAE,UAAU,CAAC;KACxB;CACF"}

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

@@ -1,4 +1,4 @@
-import { H as l } from "../../shared/hx-field-B3Qo8OLS.js";
+import { H as l } from "../../shared/hx-field-zw0U1KVi.js";
 export {
   l as HelixField
 };