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

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

@@ -102,9 +102,22 @@ declare const HelixSelect_base: typeof HelixElement & (new (...args: any[]) => i
  * @cssprop [--hx-font-size-xs] - Font size.
  */
 export declare class HelixSelect extends HelixSelect_base {
-    static styles: import('lit').CSSResult[];
+    static styles: import('lit').CSSResult;
     /** Marks this element as form-associated for ElementInternals support. @internal */
     static formAssociated: boolean;
+    /**
+     * Test seam (round-3 finding 4): when set to `true` or `false`, overrides
+     * the platform `supportsIdrefElementReferences` probe before
+     * `connectedCallback` seeds `_supportsIdrefRefs`. Mid-life flag flips on a
+     * connected instance allowed stale modern internals (set during connect)
+     * to leak into the fallback branch — 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 a `static` so the test
+     * stub cleanup is global and obvious.
+     * @internal
+     */
+    static __testSupportsIdrefRefsOverride: boolean | null;
     /** @internal */
     private _selectId;
     /** @internal */
@@ -192,16 +205,258 @@ export declare class HelixSelect extends HelixSelect_base {
     private _options;
     /** Whether the named error slot contains projected content. @internal */
     private _hasErrorSlot;
+    /**
+     * Whether the named label slot contributes a useful name. Round-3 finding 3:
+     * the previous boolean tracked `assignedNodes().length > 0`, which is `true`
+     * for whitespace-only slot content. That suppressed the unlabeled devWarn
+     * even when the slot only carried a stray newline. This flag now requires
+     * either a labellable element OR non-empty trimmed text content.
+     * @internal
+     */
+    private _hasLabelSlot;
+    /**
+     * Source of the accessible name. Round-3 finding 8 replaces the magic
+     * sentinel `'*slotted*'` with a discriminated union so a future caller
+     * setting `label="*slotted*"` literally cannot be confused with a slotted
+     * label.
+     * @internal
+     */
+    private _labelSource;
+    /**
+     * Flattened, trimmed text content of any text nodes in the label slot —
+     * used to drive `internals.ariaLabel` when the consumer projects only a
+     * text node (no element to add to `labelEls`). Round-3 finding 3.
+     * @internal
+     */
+    private _labelSlotText;
+    /** Whether the help-text slot contains projected content. @internal */
+    private _hasHelpSlot;
+    /**
+     * Direct reference to the first labellable element projected into the
+     * `<slot name="label">`. Round-3 finding 5 replaces the previous round-trip
+     * through `document.getElementById(this._slottedLabelId)` so we no longer
+     * mutate consumer light-DOM (assigning ids) and the lookup is robust under
+     * nested shadow roots (round-3 finding 6).
+     * @internal
+     */
+    private _slottedLabelEl;
     /** Zero-based index of the keyboard-focused option in the listbox; -1 means none. @internal */
     private _focusedOptionIndex;
+    /**
+     * Whether the platform supports IDL element references on `ElementInternals`.
+     * Drives the cross-shadow naming strategy: modern path uses
+     * `internals.ariaLabelledByElements` / `internals.ariaDescribedByElements`
+     * to bridge consumer light-DOM IDREFs into the host accessible node;
+     * fallback path mirrors the consumer's `aria-labelledby` / `aria-describedby`
+     * tokens onto host attributes and text-mirrors shadow help/error wrappers
+     * via `internals.ariaDescription`.
+     *
+     * ARCHITECTURE — Round-3 host-canonical (overturns scope doc Path A).
+     * Codex round-2 finding 1 demonstrated that the dual-channel approach
+     * (host roleless on modern, host-announced on fallback) creates a "named
+     * surface ≠ focused surface" gap on legacy engines. Round-3 commits to a
+     * single canonical surface — the HOST — on BOTH paths:
+     *
+     * - `internals.role = 'combobox'` on both paths (and `role="combobox"`
+     *   attribute mirror so CSS / `getAttribute` / AT inspecting the DOM see it).
+     * - `tabindex="0"` on the host (so it is the focusable surface).
+     * - Click + keydown listeners on the host (so user input lands on the
+     *   announced surface).
+     * - `focus()` routes to the host (so programmatic focus matches AT focus).
+     * - `setValidity()` anchor = host (so UA validation UI routes to the
+     *   focusable announced surface).
+     * - Inner trigger drops `role`, `tabindex`, and the combobox ARIA mirror
+     *   on both paths so AT does not see a doubled accessible.
+     *
+     * This matches Group 2's host-canonical pattern (PR #1625, validated for
+     * `hx-radio-group` and `hx-checkbox-group`). The scope doc's APG concern
+     * about doubled comboboxes is moot once the inner role is dropped.
+     * @internal
+     */
+    private _supportsIdrefRefs;
+    /**
+     * Deferred copy of `error` driven through reactive state so the persistent
+     * live region can re-announce on transitions without direct DOM mutation.
+     * Aligned with Group 2 round-1 finding #10.
+     * @internal
+     */
+    private _announcedError;
+    /**
+     * Cached invalidity flag derived from `internals.validity.valid` after the
+     * latest `setValidity()` call. Both the modern (`internals.ariaInvalid`)
+     * and fallback (host attribute) writes read from the same source so they
+     * cannot disagree. Round-2 finding 2.
+     * @internal
+     */
+    private _invalid;
     /** Reference to the hidden native select element used for form participation. @internal */
     private _select;
     /** Reference to the visible combobox trigger element that receives keyboard focus. @internal */
     private _trigger;
     /** @internal */
     private get _displayValue();
+    /**
+     * Handle for the shared IDREF observer. See `installAriaIdrefMirror()`.
+     * @internal
+     */
+    private _ariaMirror;
+    /**
+     * Watches assigned `<slot name="help-text">` nodes for in-place text
+     * mutations so the no-IDL-ref fallback `internals.ariaDescription` stays in
+     * sync. Aligned with Group 2 round-23 P2 (Finding C).
+     * @internal
+     */
+    private _helpSlotTextObserver;
+    /**
+     * Watches assigned `<slot name="error">` nodes for in-place text mutations.
+     * Aligned with Group 2 round-23 P2 (Finding C).
+     * @internal
+     */
+    private _errorSlotTextObserver;
+    /**
+     * Round-10 finding 1 (supersedes round-8 counter): dedicated host observer
+     * scoped to `aria-describedby` with `attributeOldValue: true`. The fallback
+     * path strips the host `aria-describedby` attribute on every sync (per
+     * round-6 single-channel design). Once stripped, a subsequent consumer
+     * `removeAttribute('aria-describedby')` causes NO DOM mutation (the
+     * attribute is already absent), so the post-sync `getAttribute()` baseline
+     * diff at the top of `_syncHostAriaSemantics` cannot detect the retraction
+     * — `_consumerDescribedBy` would remain pinned to the originally-cached
+     * string forever and the consumer's external help text would keep
+     * concatenating into `internals.ariaDescription` indefinitely.
+     *
+     * Round-10 architectural lockdown (`.reports/aria-group-3-architecture-
+     * decision-r10.md` section 7.1): the observer is governed by the
+     * **disconnect-during-strip** discipline. Before the fallback strip
+     * `removeAttribute('aria-describedby')` runs, this observer is
+     * `disconnect()`ed; immediately after the strip, it is re-`observe()`d.
+     * Self-mutations are therefore never delivered to the callback, so the
+     * observer only sees consumer-driven mutations. This eliminates the
+     * round-8 pending-strip counter / discriminator entirely and the lockstep
+     * invariant it depended on.
+     *
+     * The observer detects `oldValue !== null && newValue === null`
+     * (consumer authentically retracted the attribute) and clears
+     * `_consumerDescribedBy`. Framework-batched attach-then-detach (Vue /
+     * React / Lit reconciliation flipping `aria-describedby` from a string to
+     * null in one render commit) produces two records in the same callback
+     * batch — the second record's `oldValue` is observable. The bare
+     * `removeAttribute` no-op on an already-absent attribute is unobservable
+     * by design (a null → null DOM operation is not a mutation); see
+     * `hx-select.test.ts` round-10 contract block for the three documented
+     * retraction sequences.
+     *
+     * @internal
+     */
+    private _hostDescribedByObserver;
+    /**
+     * Last value of `aria-labelledby` we wrote to the host. Used to distinguish
+     * external (consumer) attribute mutations from our own internal augmentation
+     * writes. Aligned with Group 2 round-10 P2.
+     * @internal
+     */
+    private _lastWrittenLabelledBy;
+    /** @internal — see `_lastWrittenLabelledBy`. */
+    private _lastWrittenDescribedBy;
+    /**
+     * Last value of `aria-label` we wrote to the host. Used to distinguish
+     * external (consumer) attribute mutations from our own internal mirror
+     * writes on the fallback path. Round-5 finding 1: without this snapshot
+     * the round-3 fallback `aria-label` mirror was self-sealing — sync N
+     * wrote `aria-label="Country"`, sync N+1 read that same string back via
+     * `getAttribute('aria-label')` and treated it as a consumer override,
+     * caching it into `internals.ariaLabel` and short-circuiting
+     * `_writeHostAttributeMirror`. Subsequent label/accessibleLabel/slot
+     * mutations never propagated.
+     * @internal
+     */
+    private _lastWrittenAriaLabel;
+    /**
+     * Most recently observed *consumer-supplied* `aria-labelledby` baseline.
+     * Refreshed only when the host attribute changes via an external write —
+     * internal writes leave the baseline untouched. Cached so consumer tokens
+     * can replay if their target element later attaches to the DOM.
+     * @internal
+     */
+    private _consumerLabelledBy;
+    /** @internal — see `_consumerLabelledBy`. */
+    private _consumerDescribedBy;
+    connectedCallback(): void;
     disconnectedCallback(): void;
     updated(changedProperties: PropertyValues<this>): void;
+    firstUpdated(changedProperties: PropertyValues<this>): void;
+    /**
+     * Reads the label slot's assigned nodes and computes the discriminated
+     * naming state. Round-3 finding 3 + 5 + 8: an empty whitespace-only slot
+     * does NOT count as a useful name; the first labellable element is
+     * captured by reference (no consumer-DOM mutation); the result drives a
+     * discriminated `_labelSource` rather than a magic `'*slotted*'` string.
+     * @internal
+     */
+    private _readLabelSlotState;
+    /**
+     * Mirrors combobox semantics onto the host via ElementInternals so that the
+     * host IS the canonical announced surface on BOTH the modern (IDL element
+     * references) and fallback paths. Round-3 finding 1: codex round-2
+     * demonstrated that putting `role="combobox"` on the host on fallback while
+     * leaving focus/click/keyboard/validity anchored to the inner trigger
+     * created a "named surface ≠ focused surface" gap. Round-3 collapses both
+     * paths to the host-canonical model used by Group 2's `hx-radio-group` /
+     * `hx-checkbox-group` (PR #1625):
+     *
+     * - `internals.role = 'combobox'` so AT advertises the combobox role.
+     * - Host attribute `role="combobox"` mirror so legacy engines, axe-core,
+     *   and `getAttribute('role')` agree with the internals default.
+     * - Host attribute `tabindex="0"` so the host is the focusable surface.
+     * - Host attributes `aria-expanded`, `aria-haspopup`, `aria-controls`,
+     *   `aria-activedescendant`, `aria-required`, `aria-invalid`,
+     *   `aria-disabled` so AT walking the host's attribute graph sees the
+     *   combobox state without depending on internals defaults.
+     * - Modern path additionally sets `internals.ariaLabelledByElements` /
+     *   `internals.ariaDescribedByElements` so consumer light-DOM IDREFs cross
+     *   the shadow boundary into the host's accessible node.
+     * - Fallback path mirrors consumer label/desc tokens onto the host
+     *   attribute and text-mirrors shadow help/error wrappers via
+     *   `internals.ariaDescription`.
+     * @internal
+     */
+    private _syncHostAriaSemantics;
+    /**
+     * Writes host `role="combobox"` and `tabindex` so the host is the
+     * focusable, AT-visible canonical surface. Round-3 finding 1.
+     * @internal
+     */
+    private _writeHostRoleAndTabindex;
+    /**
+     * Writes the host's combobox state attributes (`aria-expanded`,
+     * `aria-haspopup`, `aria-controls`, `aria-activedescendant`,
+     * `aria-required`, `aria-invalid`, `aria-disabled`) on every sync. CSS
+     * selectors and AT inspecting the live attribute graph read these — the
+     * `internals.aria*` defaults are invisible. Round-3 finding 1.
+     * @internal
+     */
+    private _writeHostComboboxStateAttributes;
+    /**
+     * Writes a host `aria-label` attribute mirror on the fallback path so AT
+     * inspecting the live attribute graph sees the resolved name even when
+     * the platform lacks IDL element references. Skip when an effective
+     * `aria-labelledby` is already set on the host (labelledby > label by
+     * ARIA priority). Round-3 finding 1 + round-2 finding 5.
+     * @internal
+     */
+    private _writeHostAttributeMirror;
+    /**
+     * (Re-)installs the mutation observer over the current set of assigned
+     * help-text-slot nodes. Aligned with Group 2 round-23 P2 (Finding C).
+     * @internal
+     */
+    private _installHelpSlotTextObserver;
+    /**
+     * (Re-)installs the mutation observer over the current set of assigned
+     * error-slot nodes. Aligned with Group 2 round-23 P2 (Finding C).
+     * @internal
+     */
+    private _installErrorSlotTextObserver;
     /** @internal */
     private _updateFormValue;
     /** @internal */
@@ -220,10 +475,51 @@ export declare class HelixSelect extends HelixSelect_base {
      */
     /** @internal */
     private _handleSlotChange;
+    /**
+     * Tracks the slotted label so projected `<span slot="label">` content joins
+     * the accessible-name chain without forcing the consumer to also pass the
+     * `label` property.
+     *
+     * Round-3 findings 3, 5, 6, 8:
+     * - 3: count whitespace-only text as "no useful name" (devWarn must fire).
+     * - 5: hold the slotted element by direct reference instead of mutating
+     *   consumer light DOM with a tracked id.
+     * - 6: lookup is by reference, so it survives nested shadow roots without
+     *   the fragile `getElementById` chain.
+     * - 8: discriminated `_labelSource` replaces the magic `'*slotted*'`
+     *   sentinel string.
+     * @internal
+     */
+    private _handleLabelSlotChange;
+    /**
+     * Recomputes the discriminated label source. Round-3 finding 8.
+     *
+     * CodeRabbit F2: slotted label wins over the `label` prop. When a
+     * consumer provides BOTH a `<span slot="label">` AND a `label="..."`
+     * attribute the visible label is the slotted node (rendered by the
+     * named slot's default content branch never firing). Preferring the
+     * string form here would route the accessible name through the prop
+     * and diverge from the rendered text. The slot is the canonical
+     * source whenever it has useful content.
+     * @internal
+     */
+    private _refreshLabelSource;
     /** @internal */
     private _handleErrorSlotChange;
     /** @internal */
+    private _handleHelpSlotChange;
+    /** @internal */
     private _toggleDropdown;
+    /**
+     * Click handler attached to the host. Round-3 finding 1: the host is the
+     * canonical combobox surface, so user input listeners live here. Clicks
+     * inside the open listbox are handled by the per-option `@click` binding
+     * in `_renderOptions()` and stop here only if `composedPath` indicates
+     * the original click target was the open listbox panel (so option clicks
+     * don't double-toggle the dropdown).
+     * @internal
+     */
+    private _handleHostClick;
     /** @internal */
     private _handleKeydown;
     /** @internal */
@@ -234,7 +530,12 @@ export declare class HelixSelect extends HelixSelect_base {
     private _handleNativeChange;
     /** @internal */
     private _handleOutsideClick;
-    /** Moves focus to the visible trigger button. */
+    /**
+     * Moves focus to the host. Round-3 finding 1: the host is the canonical
+     * combobox surface (`role="combobox"`, `tabindex="0"`), so programmatic
+     * focus must land there to match where AT routes focus and where
+     * `setValidity()` anchors recovery.
+     */
     focus(options?: FocusOptions): void;
     /** @internal */
     private _optionId;

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

@@ -1 +1 @@
-{"version":3,"file":"hx-select.d.ts","sourceRoot":"","sources":["../../../src/components/hx-select/hx-select.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"hx-select.d.ts","sourceRoot":"","sources":["../../../src/components/hx-select/hx-select.ts"],"names":[],"mappings":"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"}

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

@@ -1 +1 @@
-{"version":3,"file":"hx-select.styles.d.ts","sourceRoot":"","sources":["../../../src/components/hx-select/hx-select.styles.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,iBAAiB,yBAsX7B,CAAC"}
+{"version":3,"file":"hx-select.styles.d.ts","sourceRoot":"","sources":["../../../src/components/hx-select/hx-select.styles.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,iBAAiB,yBAyY7B,CAAC"}

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

@@ -1,4 +1,4 @@
-import { H as o } from "../../shared/hx-select-C8fEHQhC.js";
+import { H as o } from "../../shared/hx-select-DrcS-YRJ.js";
 export {
   o as HelixSelect
 };

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

@@ -1 +1 @@
-{"version":3,"file":"hx-nav-item.styles.d.ts","sourceRoot":"","sources":["../../../src/components/hx-side-nav/hx-nav-item.styles.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,kBAAkB,yBA6S9B,CAAC"}
+{"version":3,"file":"hx-nav-item.styles.d.ts","sourceRoot":"","sources":["../../../src/components/hx-side-nav/hx-nav-item.styles.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,kBAAkB,yBAiT9B,CAAC"}

package/dist/components/hx-side-nav/index.js

@@ -1,4 +1,4 @@
-import { H as i, a as x } from "../../shared/hx-nav-item-xqRPOCWX.js";
+import { H as i, a as x } from "../../shared/hx-nav-item-CODtUlew.js";
 export {
   i as HelixNavItem,
   x as HelixSideNav

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

@@ -136,7 +136,69 @@ export declare class HelixSwitch extends HelixSwitch_base {
      * @attr required-message
      */
     requiredMessage: string;
+    /**
+     * Handle for the shared IDREF observer. Installed in `connectedCallback()`
+     * so late-mutated `aria-labelledby`/`aria-describedby` and late-inserted
+     * IDREF targets are picked up. See `installAriaIdrefMirror()`.
+     * @internal
+     */
+    private _ariaMirror;
+    /**
+     * No-IDL-ref fallback tokens applied to the inner button so consumer
+     * labelling resolves through the shadow root. Tracked as reactive state
+     * so values flow through the next `render()`.
+     * @internal
+     */
+    private _fallbackAriaLabelledBy;
+    /** @internal */
+    private _fallbackAriaDescribedBy;
+    /** @internal */
+    private _fallbackAriaLabel;
+    /**
+     * Whether the platform supports IDL element references on `ElementInternals`.
+     * Drives the render-time branch between the modern path (host is the
+     * announced surface, inner button is `aria-hidden + tabindex=-1`) and the
+     * fallback path (inner button is the announced surface, host is demoted).
+     * Codex round-2 finding #2.
+     * @internal
+     */
+    private _supportsIdrefRefs;
+    /**
+     * Tracks whether the host's `tabindex` is managed by the component itself
+     * (vs. set explicitly by a consumer). Codex round-14 P2: a consumer-supplied
+     * `tabindex` (e.g. roving-tabindex toolbar pattern with `tabindex="-1"`)
+     * must survive disabled flips and re-renders. Only re-assert tabindex in
+     * `updated()` when the component originally claimed it.
+     * @internal
+     */
+    private _internalTabindexManaged;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * Host-level keydown handler. Active only on the modern path; on the
+     * no-IDL-ref fallback the inner `<button>` owns native activation.
+     * Codex round-2 finding #2.
+     * @internal
+     */
+    private _handleHostKeyDown;
+    /**
+     * Host-level click handler. Active only on the modern path; on the
+     * fallback path AT activation flows directly to the inner button.
+     * Codex round-2 finding #2.
+     * @internal
+     */
+    private _handleHostClick;
     updated(changedProperties: PropertyValues<this>): void;
+    /**
+     * Mirrors switch semantics onto the host via ElementInternals so that
+     * consumer-supplied `aria-label`, `aria-labelledby`, and `aria-describedby`
+     * on `<hx-switch>` reach the announced control. The codex aria-group-2
+     * finding identified that the inner shadow `<button role=switch>` was the
+     * only carrier of switch semantics, leaving host-level IDREF tokens stranded
+     * on the wrong side of the shadow boundary.
+     * @internal
+     */
+    private _syncHostAriaSemantics;
     /** Recalculates and sets the validity state based on required and checked. */
     /** @internal */
     _updateValidity(): void;
@@ -152,12 +214,18 @@ export declare class HelixSwitch extends HelixSwitch_base {
     /** Whether the default slot has assigned content (slotted label). */
     /** @internal */
     private _hasDefaultSlot;
+    /** Whether the help-text slot has assigned content. */
+    /** @internal */
+    private _hasHelpTextSlot;
     /** Updates _hasErrorSlot when error slot content changes. */
     /** @internal */
     private _handleErrorSlotChange;
     /** Updates _hasDefaultSlot when default slot content changes. */
     /** @internal */
     private _handleDefaultSlotChange;
+    /** Updates _hasHelpTextSlot when help-text slot content changes. */
+    /** @internal */
+    private _handleHelpTextSlotChange;
     /** Toggles checked state and dispatches hx-change event. */
     /** @internal */
     private _toggle;
@@ -167,7 +235,16 @@ export declare class HelixSwitch extends HelixSwitch_base {
     /** Handles keydown events — Space toggles the switch per ARIA APG. */
     /** @internal */
     private _handleKeyDown;
-    /** Moves focus to the switch track element. */
+    /**
+     * Moves focus to the announced switch surface. Codex round-1 finding #1
+     * relocated the focus target to the host so AT announces a single widget;
+     * the host carries the canonical role/state on modern engines. Round-7
+     * finding #7 extends that contract to the no-IDL-ref fallback: when the
+     * host is demoted (`tabindex=-1`, role/state cleared on `internals`) the
+     * inner `<button role=switch>` owns the announced semantics and tab order,
+     * so programmatic `focus()` must redirect there — otherwise scripted focus
+     * and error recovery land on the demoted host on unsupported engines.
+     */
     focus(options?: FocusOptions): void;
     /** Unique ID for this switch instance, used for ARIA associations. */
     /** @internal */

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

@@ -1 +1 @@
-{"version":3,"file":"hx-switch.d.ts","sourceRoot":"","sources":["../../../src/components/hx-switch/hx-switch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AACzD,OAAO,4CAA4C,CAAC;AAIpD,OAAO,EAAE,YAAY,EAAmB,MAAM,qBAAqB,CAAC;AAOpE,8DAA8D;AAC9D,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AACH,qBACa,WAAY,SAAQ,gBAAuB;IACtD,OAAgB,MAAM,4BAA0C;IAIhE,gBAAgB;IAChB,OAAgB,cAAc,UAAQ;IAItC;;;OAGG;IAEH,OAAO,UAAS;IAEhB;;;OAGG;IAEH,QAAQ,UAAS;IAEjB;;;OAGG;IAEH,QAAQ,UAAS;IAEjB;;;OAGG;IAEH,IAAI,SAAM;IAEV;;;OAGG;IAEH,KAAK,SAAQ;IAEb;;;OAGG;IAEH,KAAK,SAAM;IAEX;;;OAGG;IAEH,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAQ;IAEhC;;;OAGG;IAEH,KAAK,SAAM;IAEX;;;OAGG;IAEH,QAAQ,SAAM;IAEd;;;OAGG;IAEH,eAAe,SAA6B;IAInC,OAAO,CAAC,iBAAiB,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,IAAI;IAS/D,8EAA8E;IAC9E,gBAAgB;IACP,eAAe,IAAI,IAAI;cAYb,YAAY,IAAI,IAAI;cAMpB,mBAAmB,CACpC,KAAK,EAAE,IAAI,GAAG,MAAM,GAAG,QAAQ,GAAG,IAAI,EACtC,KAAK,EAAE,SAAS,GAAG,cAAc,GAChC,IAAI;cAMY,eAAe,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI;IAI3D;OACG;IAEH,OAAO,CAAC,QAAQ,CAAuC;IAEvD,mDAAmD;IACnD,gBAAgB;IACP,OAAO,CAAC,aAAa,CAAS;IAEvC,qEAAqE;IACrE,gBAAgB;IACP,OAAO,CAAC,eAAe,CAAS;IAIzC,6DAA6D;IAC7D,gBAAgB;IAChB,OAAO,CAAC,sBAAsB;IAK9B,iEAAiE;IACjE,gBAAgB;IAChB,OAAO,CAAC,wBAAwB;IAOhC,4DAA4D;IAC5D,gBAAgB;IAChB,OAAO,CAAC,OAAO;IAcf,yCAAyC;IACzC,gBAAgB;IAChB,OAAO,CAAC,YAAY;IAIpB,sEAAsE;IACtE,gBAAgB;IAChB,OAAO,CAAC,cAAc;IAStB,+CAA+C;IACtC,KAAK,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI;IAM5C,sEAAsE;IACtE,gBAAgB;IAChB,OAAO,CAAC,SAAS,CAAmB;IACpC,+DAA+D;IAC/D,gBAAgB;IAChB,OAAO,CAAC,QAAQ,CAA6B;IAC7C,oEAAoE;IACpE,gBAAgB;IAChB,OAAO,CAAC,WAAW,CAA4B;IAC/C,gEAAgE;IAChE,gBAAgB;IAChB,OAAO,CAAC,QAAQ,CAA6B;IAEpC,MAAM;CAmEhB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,WAAW,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC/D;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,WAAW,EAAE,WAAW,CAAC;KAC1B;CACF;AAED,MAAM,MAAM,QAAQ,GAAG,WAAW,CAAC"}
+{"version":3,"file":"hx-switch.d.ts","sourceRoot":"","sources":["../../../src/components/hx-switch/hx-switch.ts"],"names":[],"mappings":"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"}

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

@@ -1 +1 @@
-{"version":3,"file":"hx-switch.styles.d.ts","sourceRoot":"","sources":["../../../src/components/hx-switch/hx-switch.styles.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,iBAAiB,yBA4O7B,CAAC"}
+{"version":3,"file":"hx-switch.styles.d.ts","sourceRoot":"","sources":["../../../src/components/hx-switch/hx-switch.styles.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,iBAAiB,yBA6P7B,CAAC"}

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

@@ -1,4 +1,4 @@
-import { H as o } from "../../shared/hx-switch-BrZFaRue.js";
+import { H as o } from "../../shared/hx-switch-BX_8uNUs.js";
 export {
   o as HelixSwitch
 };

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

@@ -127,8 +127,118 @@ export declare class HelixToggleButton extends HelixElement {
     checkValidity(): boolean;
     /** Reports validity and shows the browser's constraint validation UI. */
     reportValidity(): boolean;
+    /**
+     * Handle for the shared IDREF observer. See `installAriaIdrefMirror()`.
+     * @internal
+     */
+    private _ariaMirror;
+    /**
+     * Default-slot text content captured for use as the host's accessible name
+     * when no explicit `label`/`aria-label`/`aria-labelledby` is supplied.
+     * Codex round-1 finding #9.
+     * @internal
+     */
+    private _slotLabelText;
+    /** No-IDL-ref fallback tokens applied to the inner button. @internal */
+    private _fallbackAriaLabelledBy;
+    /** @internal */
+    private _fallbackAriaDescribedBy;
+    /** @internal */
+    private _fallbackAriaLabel;
+    /**
+     * Whether the platform supports IDL element references on `ElementInternals`.
+     * Drives the render-time branch between the modern path (host is the
+     * announced surface, inner button is `aria-hidden + tabindex=-1`) and the
+     * fallback path (inner button is the announced surface, host is demoted).
+     * Codex round-2 finding #2.
+     * @internal
+     */
+    private _supportsIdrefRefs;
+    /**
+     * Tracks whether the host's `tabindex` is managed by the component itself
+     * (vs. set explicitly by a consumer). Codex round-14 P2: a consumer-supplied
+     * `tabindex` (e.g. roving-tabindex toolbar pattern with `tabindex="-1"`)
+     * must survive disabled flips and re-renders. Only re-assert tabindex in
+     * `updated()` when the component originally claimed it.
+     * @internal
+     */
+    private _internalTabindexManaged;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * Host-level keydown handler. Active only on the modern path; on the
+     * no-IDL-ref fallback the inner `<button>` owns native Space/Enter
+     * activation. Codex round-2 finding #2.
+     * @internal
+     */
+    private _handleHostKeyDown;
+    /**
+     * Host-level click router. The inner `<button>` is `aria-hidden + tabindex=-1`
+     * on modern browsers but still receives clicks via mouse activation; toggling
+     * is handled by the inner `_handleClick`. Host-level clicks (composed path
+     * origin === host) only come from AT activation or programmatic triggers,
+     * so we route those to the toggle pipeline.
+     *
+     * Codex round-2 finding #2: on no-IDL-ref browsers the inner button is the
+     * announced surface so this host-level routing is a no-op — AT activation
+     * lands on the inner button directly.
+     * @internal
+     */
+    private _handleHostClickRouted;
+    /** @internal */
+    private _invokeToggle;
+    /**
+     * Moves focus to the announced toggle-button surface. Codex round-1 finding
+     * `#1` made the host the canonical focus target on modern engines so AT
+     * announces a single widget. Round-7 finding `#9` extends that contract to
+     * the no-IDL-ref fallback: when the host is demoted (`tabindex=-1`,
+     * role/state cleared on `internals`) the inner `<button>` owns the announced
+     * semantics and tab order, so programmatic `focus()` must redirect there —
+     * otherwise scripted focus and error recovery land on the demoted host on
+     * unsupported engines.
+     */
+    focus(options?: FocusOptions): void;
     firstUpdated(changedProperties: PropertyValues<this>): void;
     updated(changedProperties: PropertyValues<this>): void;
+    /**
+     * Reads the default slot's flattened text content into `_slotLabelText`.
+     * Called from `firstUpdated()` and `slotchange` so host-canonical semantics
+     * pick up slotted label text. Codex round-1 finding #9.
+     * @internal
+     */
+    private _captureSlotLabelText;
+    /**
+     * Watches assigned default-slot nodes for in-place text mutations so the
+     * cached `_slotLabelText` (and thus `internals.ariaLabel`) stays in sync
+     * when a framework rewrites textContent of an already-assigned node without
+     * replacing it. `slotchange` does NOT fire for those mutations, so a
+     * separate observer is required. Codex round-13 P2.
+     * @internal
+     */
+    private _slotTextObserver;
+    /**
+     * (Re-)installs the mutation observer over the current set of assigned
+     * default-slot nodes. Disconnects any prior observer first so detached
+     * nodes stop firing into a torn-down host.
+     * @internal
+     */
+    private _installSlotTextObserver;
+    /** @internal */
+    private _handleDefaultSlotChange;
+    /**
+     * Mirrors toggle-button semantics onto the host via ElementInternals so that
+     * consumer-supplied `aria-label`, `aria-labelledby`, and `aria-describedby`
+     * on `<hx-toggle-button>` reach the announced control. The codex aria-group-2
+     * finding identified that the inner shadow `<button>` was the only carrier of
+     * the toggle role + pressed state, leaving host-level IDREF tokens stranded
+     * across the shadow boundary.
+     *
+     * The shadow `<button>` keeps `aria-pressed`/`aria-label` mirrored for
+     * backwards-compat with existing tests and for browsers without IDL element
+     * references; the host is the canonical announced surface.
+     * @internal
+     */
+    private _syncHostAriaSemantics;
     protected _onFormReset(): void;
     protected _onFormStateRestore(state: string | File | FormData | null, _mode: 'restore' | 'autocomplete'): void;
     protected _onFormDisabled(disabled: boolean): void;

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

@@ -1 +1 @@
-{"version":3,"file":"hx-toggle-button.d.ts","sourceRoot":"","sources":["../../../src/components/hx-toggle-button/hx-toggle-button.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AACzD,OAAO,4CAA4C,CAAC;AAGpD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAInD,qEAAqE;AACrE,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH,qBACa,iBAAkB,SAAQ,YAAY;IACjD,OAAgB,MAAM,4BAAsD;IAI5E,gBAAgB;IAChB,OAAgB,cAAc,UAAQ;IAEtC,gBAAgB;IACW,OAAO,CAAC,YAAY,CAA0B;IAIzE;;;;OAIG;IAEH,OAAO,UAAS;IAEhB;;;OAGG;IAEH,OAAO,EAAE,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,OAAO,GAAG,SAAS,CAAe;IAElF;;;OAGG;IAEH,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAQ;IAEhC;;;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,KAAK,EAAE,MAAM,GAAG,SAAS,CAAa;IAEtC;;;OAGG;IAEH,QAAQ,UAAS;IAIjB,wCAAwC;IACxC,IAAa,QAAQ,IAAI,aAAa,CAErC;IAED,8CAA8C;IAC9C,IAAa,iBAAiB,IAAI,MAAM,CAEvC;IAED,2DAA2D;IAC3D,aAAa,IAAI,OAAO;IAIxB,yEAAyE;IACzE,cAAc,IAAI,OAAO;IAMhB,YAAY,CAAC,iBAAiB,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,IAAI;IAgB3D,OAAO,CAAC,iBAAiB,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,IAAI;cAY5C,YAAY,IAAI,IAAI;cAIpB,mBAAmB,CACpC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,QAAQ,GAAG,IAAI,EACtC,KAAK,EAAE,SAAS,GAAG,cAAc,GAChC,IAAI;cAIY,eAAe,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI;IAM3D,gBAAgB;IAChB,OAAO,CAAC,cAAc;IAUtB,gBAAgB;IAChB,OAAO,CAAC,eAAe;IAcvB,gBAAgB;IAChB,OAAO,CAAC,YAAY;IAyBpB,gBAAgB;IAChB,OAAO,CAAC,YAAY;IAgBX,MAAM;CAsBhB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,kBAAkB,EAAE,iBAAiB,CAAC;KACvC;CACF"}
+{"version":3,"file":"hx-toggle-button.d.ts","sourceRoot":"","sources":["../../../src/components/hx-toggle-button/hx-toggle-button.ts"],"names":[],"mappings":"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"}

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

@@ -1 +1 @@
-{"version":3,"file":"hx-toggle-button.styles.d.ts","sourceRoot":"","sources":["../../../src/components/hx-toggle-button/hx-toggle-button.styles.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,uBAAuB,yBAiQnC,CAAC"}
+{"version":3,"file":"hx-toggle-button.styles.d.ts","sourceRoot":"","sources":["../../../src/components/hx-toggle-button/hx-toggle-button.styles.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,uBAAuB,yBAkRnC,CAAC"}