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

package/dist/shared/{hx-tooltip-nYOv9OLu.js → hx-tooltip-DVqtKPCD.js}

@@ -1,9 +1,9 @@
-import { css as g, html as y } from "lit";
-import { property as d, state as b, query as p, customElement as w } from "lit/decorators.js";
+import { css as g, html as b } from "lit";
+import { property as d, state as y, query as p, customElement as w } from "lit/decorators.js";
 import { a as T } from "./forced-colors-CTEDFRGa.js";
 import { H as D } from "./helix-element-BNEYeiys.js";
-import { c as C } from "./id-counter-DuX8vsui.js";
-const E = g`
+import { c as S } from "./id-counter-DuX8vsui.js";
+const C = g`
   :host {
     display: inline-block;
   }
@@ -68,15 +68,15 @@ const E = g`
     }
   }
 `;
-var S = Object.defineProperty, $ = Object.getOwnPropertyDescriptor, r = (t, e, i, a) => {
-  for (var s = a > 1 ? void 0 : a ? $(e, i) : e, n = t.length - 1, h; n >= 0; n--)
-    (h = t[n]) && (s = (a ? h(e, i, s) : h(s)) || s);
-  return a && s && S(e, i, s), s;
+var E = Object.defineProperty, O = Object.getOwnPropertyDescriptor, n = (t, e, i, o) => {
+  for (var s = o > 1 ? void 0 : o ? O(e, i) : e, l = t.length - 1, h; l >= 0; l--)
+    (h = t[l]) && (s = (o ? h(e, i, s) : h(s)) || s);
+  return o && s && E(e, i, s), s;
 };
-const H = C("hx-tooltip");
-let o = class extends D {
+const $ = S("hx-tooltip");
+let r = class extends D {
   constructor() {
-    super(...arguments), this.placement = "top", this.showDelay = 300, this.hideDelay = 100, this._visible = !1, this._showTimer = null, this._hideTimer = null, this._tooltipId = H(), this._lightDomDescription = null, this._handleKeydown = (t) => {
+    super(...arguments), this.placement = "top", this.showDelay = 300, this.hideDelay = 100, this._visible = !1, this._showTimer = null, this._hideTimer = null, this._tooltipId = $(), this._lightDomDescription = null, this._contentSlotTextObserver = null, this._handleKeydown = (t) => {
       t instanceof KeyboardEvent && t.key === "Escape" && this._visible && (this._clearTimers(), this._hide());
     };
   }
@@ -85,8 +85,8 @@ let o = class extends D {
     super.connectedCallback(), this.addEventListener("keydown", this._handleKeydown), this.hasUpdated && this._setupTriggerAria();
   }
   disconnectedCallback() {
-    var t;
-    super.disconnectedCallback(), this.removeEventListener("keydown", this._handleKeydown), this._clearTimers(), (t = this._lightDomDescription) == null || t.remove(), this._lightDomDescription = null;
+    var t, e;
+    super.disconnectedCallback(), this.removeEventListener("keydown", this._handleKeydown), this._clearTimers(), (t = this._lightDomDescription) == null || t.remove(), this._lightDomDescription = null, (e = this._contentSlotTextObserver) == null || e.disconnect(), this._contentSlotTextObserver = null;
   }
   firstUpdated() {
     this._setupTriggerAria();
@@ -96,8 +96,30 @@ let o = class extends D {
   _setupTriggerAria() {
     const t = this._defaultSlot;
     if (!t) return;
-    const e = t.assignedElements()[0], i = this._contentSlot, a = (i == null ? void 0 : i.assignedElements().map((s) => s.textContent).join(" ").trim()) ?? "";
-    !this._lightDomDescription && typeof document < "u" && (this._lightDomDescription = document.createElement("span"), this._lightDomDescription.id = this._tooltipId, this._lightDomDescription.style.cssText = "position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0", document.body.appendChild(this._lightDomDescription)), this._lightDomDescription && (this._lightDomDescription.textContent = a), e && e.setAttribute("aria-describedby", this._tooltipId);
+    const e = t.assignedElements()[0], i = this._contentSlot, o = (i == null ? void 0 : i.assignedElements()) ?? [], s = o.map((l) => l.textContent).join(" ").trim();
+    !this._lightDomDescription && typeof document < "u" && (this._lightDomDescription = document.createElement("span"), this._lightDomDescription.id = this._tooltipId, this._lightDomDescription.style.cssText = "position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0", document.body.appendChild(this._lightDomDescription)), this._lightDomDescription && (this._lightDomDescription.textContent = s), e && e.setAttribute("aria-describedby", this._tooltipId), this._installContentSlotTextObserver(o);
+  }
+  /**
+   * (Re-)installs the slotted-content text observer over the deduped union
+   * of assigned `content` slot elements. Disconnects any previous observer
+   * before re-attaching so observer count is bounded by component lifetime,
+   * not by `slotchange` event count.
+   * @internal
+   */
+  _installContentSlotTextObserver(t) {
+    if (this._contentSlotTextObserver && (this._contentSlotTextObserver.disconnect(), this._contentSlotTextObserver = null), t.length === 0 || typeof MutationObserver > "u") return;
+    const e = new Set(t), i = new MutationObserver(() => {
+      if (!this._lightDomDescription) return;
+      const o = this._contentSlot, s = (o == null ? void 0 : o.assignedElements().map((l) => l.textContent).join(" ").trim()) ?? "";
+      this._lightDomDescription.textContent !== s && (this._lightDomDescription.textContent = s);
+    });
+    for (const o of e)
+      i.observe(o, {
+        characterData: !0,
+        subtree: !0,
+        childList: !0
+      });
+    this._contentSlotTextObserver = i;
   }
   // ─── Show/Hide ───
   /** @internal */
@@ -129,24 +151,24 @@ let o = class extends D {
   async _updatePosition() {
     const t = this._triggerWrapper, e = this._tooltipEl, i = this._arrowEl;
     if (!t || !e || !i) return;
-    const { computePosition: a, flip: s, shift: n, offset: h, arrow: c } = await import("@floating-ui/dom"), { x: m, y: u, placement: _, middlewareData: f } = await a(t, e, {
+    const { computePosition: o, flip: s, shift: l, offset: h, arrow: c } = await import("@floating-ui/dom"), { x: m, y: u, placement: _, middlewareData: v } = await o(t, e, {
       placement: this.placement,
       strategy: "fixed",
-      middleware: [h(8), s(), n({ padding: 8 }), c({ element: i })]
+      middleware: [h(8), s(), l({ padding: 8 }), c({ element: i })]
     });
     Object.assign(e.style, {
       left: `${m}px`,
       top: `${u}px`
     });
-    const l = f.arrow, v = _.split("-")[0] ?? "top", x = {
+    const a = v.arrow, f = _.split("-")[0] ?? "top", x = {
       top: "bottom",
       right: "left",
       bottom: "top",
       left: "right"
-    }[v] ?? "bottom";
+    }[f] ?? "bottom";
     Object.assign(i.style, {
-      left: (l == null ? void 0 : l.x) != null ? `${l.x}px` : "",
-      top: (l == null ? void 0 : l.y) != null ? `${l.y}px` : "",
+      left: (a == null ? void 0 : a.x) != null ? `${a.x}px` : "",
+      top: (a == null ? void 0 : a.y) != null ? `${a.y}px` : "",
       right: "",
       bottom: "",
       [x]: `${-(i.offsetWidth / 2)}px`
@@ -165,7 +187,7 @@ let o = class extends D {
   }
   // ─── Render ───
   render() {
-    return y`
+    return b`
       <div
         class="trigger-wrapper"
         @mouseenter=${this._scheduleShow}
@@ -190,38 +212,38 @@ let o = class extends D {
     `;
   }
 };
-o.styles = [E, T];
-r([
+r.styles = [C, T];
+n([
   d({ type: String, reflect: !0 })
-], o.prototype, "placement", 2);
-r([
+], r.prototype, "placement", 2);
+n([
   d({ type: Number, attribute: "show-delay" })
-], o.prototype, "showDelay", 2);
-r([
+], r.prototype, "showDelay", 2);
+n([
   d({ type: Number, attribute: "hide-delay" })
-], o.prototype, "hideDelay", 2);
-r([
-  b()
-], o.prototype, "_visible", 2);
-r([
+], r.prototype, "hideDelay", 2);
+n([
+  y()
+], r.prototype, "_visible", 2);
+n([
   p("slot:not([name])")
-], o.prototype, "_defaultSlot", 2);
-r([
+], r.prototype, "_defaultSlot", 2);
+n([
   p('slot[name="content"]')
-], o.prototype, "_contentSlot", 2);
-r([
+], r.prototype, "_contentSlot", 2);
+n([
   p(".trigger-wrapper")
-], o.prototype, "_triggerWrapper", 2);
-r([
+], r.prototype, "_triggerWrapper", 2);
+n([
   p('[part="tooltip"]')
-], o.prototype, "_tooltipEl", 2);
-r([
+], r.prototype, "_tooltipEl", 2);
+n([
   p('[part="arrow"]')
-], o.prototype, "_arrowEl", 2);
-o = r([
+], r.prototype, "_arrowEl", 2);
+r = n([
   w("hx-tooltip")
-], o);
+], r);
 export {
-  o as H
+  r as H
 };
-//# sourceMappingURL=hx-tooltip-nYOv9OLu.js.map
+//# sourceMappingURL=hx-tooltip-DVqtKPCD.js.map

package/dist/shared/hx-tooltip-DVqtKPCD.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hx-tooltip-DVqtKPCD.js","sources":["../../src/components/hx-tooltip/hx-tooltip.styles.ts","../../src/components/hx-tooltip/hx-tooltip.ts"],"sourcesContent":["import { css } from 'lit';\n\n/**\n * hx-tooltip styles.\n *\n * Component-tier tokens with two-level var() fallback:\n *   var(--hx-tooltip-{prop}, var(--hx-color-{semantic}, #hex))\n * Inner hex fallbacks track the \"precision cool\" palette (3.2.0):\n *   neutral-0 = #FFFFFF, neutral-900 = #0D1825 (surface-inverse anchor).\n */\nexport const helixTooltipStyles = css`\n  :host {\n    display: inline-block;\n  }\n\n  .trigger-wrapper {\n    display: inline-block;\n  }\n\n  [part='tooltip'] {\n    position: fixed;\n    z-index: var(--hx-tooltip-z-index, var(--hx-z-index-tooltip, 1600));\n    max-width: var(--hx-tooltip-max-width, 280px);\n    padding: var(--hx-tooltip-padding, var(--hx-space-1, 0.25rem) var(--hx-space-2, 0.5rem));\n    background: var(--hx-tooltip-bg, var(--hx-color-surface-inverse, #0d1825));\n    color: var(--hx-tooltip-color, var(--hx-color-text-inverse, #ffffff));\n    font-family: var(--hx-tooltip-font-family, var(--hx-font-family-sans, sans-serif));\n    font-size: var(--hx-tooltip-font-size, var(--hx-font-size-xs, 0.75rem));\n    line-height: var(--hx-line-height-normal, 1.5);\n    border-radius: var(--hx-tooltip-border-radius, var(--hx-border-radius-sm, 0.25rem));\n    box-shadow: var(\n      --hx-tooltip-shadow,\n      var(--hx-shadow-sm, 0 2px 8px var(--hx-overlay-black-20, rgba(0, 0, 0, 0.2)))\n    );\n    visibility: hidden;\n    opacity: 0;\n    transition:\n      opacity var(--hx-tooltip-transition-duration, var(--hx-transition-fast, 150ms ease)),\n      visibility var(--hx-tooltip-transition-duration, var(--hx-transition-fast, 150ms ease));\n    overflow-wrap: break-word;\n  }\n\n  [part='tooltip'].visible {\n    visibility: visible;\n    opacity: 1;\n  }\n\n  [part='arrow'] {\n    position: absolute;\n    width: var(--hx-tooltip-arrow-size, 8px);\n    height: var(--hx-tooltip-arrow-size, 8px);\n    background: var(--hx-tooltip-bg, var(--hx-color-surface-inverse, #0d1825));\n    transform: rotate(45deg);\n    pointer-events: none;\n  }\n\n  @media (prefers-reduced-motion: reduce) {\n    [part='tooltip'] {\n      transition: none;\n    }\n  }\n\n  /* ─── Forced Colors (Windows High Contrast) ─── */\n  /* Belt-and-suspenders: rich per-class HC overrides PLUS the forcedColorsSurface mixin. */\n\n  @media (forced-colors: active) {\n    [part='tooltip'] {\n      border: 1px solid CanvasText;\n    }\n\n    [part='arrow'] {\n      border: 1px solid CanvasText;\n    }\n  }\n`;\n","import { html } from 'lit';\nimport '../../utilities/document-token-adoption.js';\nimport { customElement, property, query, state } from 'lit/decorators.js';\n\nimport { HelixElement, createIdCounter } from '../../base/index.js';\nimport { helixTooltipStyles } from './hx-tooltip.styles.js';\nimport { forcedColorsSurface } from '../../styles/forced-colors.js';\n\nconst _nextTooltipId = createIdCounter('hx-tooltip');\n\n/**\n * A tooltip that displays contextual help text on hover or focus.\n *\n * ## Architecture Note: Light-DOM Description Shim (group-4 round-1)\n *\n * `aria-describedby` IDREFs cannot resolve across the Shadow DOM boundary —\n * the trigger lives in the consumer's light DOM and references a tooltip\n * whose body is in this component's shadow root. The tooltip text must\n * therefore be exposed in DOCUMENT scope.\n *\n * The shim is a single visually-hidden `<span>` appended to `document.body`\n * with the `_tooltipId` as its `id`. The trigger's `aria-describedby` points\n * at this span. The text content is mirrored from the slotted `content`\n * slot on every relevant signal:\n *\n *   1. `firstUpdated` (initial wiring)\n *   2. `slotchange` on the default slot AND the `content` slot (the slotted\n *      element list changes)\n *   3. **Text-content mutations on the assigned `content` slot elements**\n *      (round-23 P2 pattern). Without this observer a framework that\n *      rewrites the slotted `<span slot=\"content\">` `textContent` IN PLACE\n *      (Vue / React keyed text rerender) would leave the shim stale.\n *\n * Cleanup: `disconnectedCallback` removes the shim from `document.body`,\n * disconnects the slot-text observer, and clears the timers. SSR is\n * sidestepped by guarding `document` access — the shim is created lazily\n * the first time `_setupTriggerAria()` runs in a browser environment.\n *\n * `role=\"tooltip\"` is the correct APG role and is NEVER promoted to\n * `role=\"dialog\"` — APG explicitly forbids tooltips from holding focus and\n * the tooltip body is not a focus target. No host-canonical `_internals`\n * work is owed: the trigger is the announced surface, and it correctly\n * references the tooltip via `aria-describedby`.\n *\n * @summary Contextual help text and abbreviations with smart positioning.\n *\n * @tag hx-tooltip\n *\n * @slot - Default slot for the trigger element.\n * @slot content - Tooltip content to display.\n *\n * @csspart tooltip - The tooltip container element.\n * @csspart arrow - The arrow indicator element.\n *\n * @cssprop [--hx-tooltip-bg=var(--hx-color-neutral-900)] - Tooltip background color.\n * @cssprop [--hx-tooltip-color=var(--hx-color-neutral-50)] - Tooltip text color.\n * @cssprop [--hx-tooltip-font-size=var(--hx-font-size-xs)] - Tooltip font size.\n * @cssprop [--hx-tooltip-max-width=280px] - Maximum tooltip width.\n * @cssprop [--hx-tooltip-padding] - Tooltip padding.\n * @cssprop [--hx-tooltip-border-radius=var(--hx-border-radius-sm)] - Tooltip border radius.\n * @cssprop [--hx-tooltip-shadow] - Tooltip box shadow.\n * @cssprop [--hx-tooltip-z-index=9999] - Tooltip z-index.\n * @cssprop [--hx-tooltip-transition-duration=0.15s] - Show/hide transition duration.\n * @cssprop [--hx-tooltip-arrow-size=8px] - Size of the arrow indicator.\n *\n * @example\n * ```html\n * <hx-tooltip>\n *   <button>Hover me</button>\n *   <span slot=\"content\">Helpful context here</span>\n * </hx-tooltip>\n * ```\n *\n * @example Drupal/Twig usage\n * ```twig\n * <hx-tooltip>\n *   <button type=\"button\">{{ trigger_label }}</button>\n *   <span slot=\"content\">{{ tooltip_text }}</span>\n * </hx-tooltip>\n * ```\n * @cssprop [--hx-tooltip-font-family=var(--hx-font-family-sans)] - CSS custom property.\n * @cssprop [--hx-z-index-tooltip] - Z-index layer.\n * @cssprop [--hx-space-1] - Spacing token.\n * @cssprop [--hx-space-2] - Spacing token.\n * @cssprop [--hx-color-neutral-900] - Color.\n * @cssprop [--hx-color-neutral-50] - Color.\n * @cssprop [--hx-font-family-sans] - Font family.\n * @cssprop [--hx-font-size-xs] - Font size.\n * @cssprop [--hx-line-height-normal] - Line height.\n * @cssprop [--hx-border-radius-sm] - CSS custom property.\n * @cssprop [--hx-shadow-sm] - Box shadow.\n * @cssprop [--hx-overlay-black-20] - Overlay color.\n * @cssprop [--hx-transition-fast] - Transition timing.\n */\n\n@customElement('hx-tooltip')\nexport class HelixTooltip extends HelixElement {\n  static override styles = [helixTooltipStyles, forcedColorsSurface];\n\n  /**\n   * Preferred placement of the tooltip relative to the trigger.\n   * Supports all Floating UI placement values including alignment variants\n   * (e.g. 'top-start', 'bottom-end') and 'auto'.\n   * @attr placement\n   */\n  @property({ type: String, reflect: true })\n  placement:\n    | 'top'\n    | 'top-start'\n    | 'top-end'\n    | 'right'\n    | 'right-start'\n    | 'right-end'\n    | 'bottom'\n    | 'bottom-start'\n    | 'bottom-end'\n    | 'left'\n    | 'left-start'\n    | 'left-end' = 'top';\n\n  /**\n   * Delay in milliseconds before the tooltip is shown.\n   * @attr show-delay\n   */\n  @property({ type: Number, attribute: 'show-delay' })\n  showDelay = 300;\n\n  /**\n   * Delay in milliseconds before the tooltip is hidden.\n   * @attr hide-delay\n   */\n  @property({ type: Number, attribute: 'hide-delay' })\n  hideDelay = 100;\n\n  /** @internal */\n  @state() private _visible = false;\n\n  /** @internal */\n  private _showTimer: ReturnType<typeof setTimeout> | null = null;\n  /** @internal */\n  private _hideTimer: ReturnType<typeof setTimeout> | null = null;\n\n  /** @internal */\n  private readonly _tooltipId = _nextTooltipId();\n\n  /** @internal */\n  @query('slot:not([name])') private _defaultSlot!: HTMLSlotElement | null;\n  /** @internal */\n  @query('slot[name=\"content\"]') private _contentSlot!: HTMLSlotElement | null;\n  /** @internal */\n  @query('.trigger-wrapper') private _triggerWrapper!: HTMLElement | null;\n  /** @internal */\n  @query('[part=\"tooltip\"]') private _tooltipEl!: HTMLElement | null;\n  /** @internal */\n  @query('[part=\"arrow\"]') private _arrowEl!: HTMLElement | null;\n\n  /**\n   * Visually-hidden description element in light DOM.\n   * Necessary because aria-describedby cannot cross Shadow DOM boundaries —\n   * ARIA ID references are scoped to the element's root node. This element\n   * lives in the document scope so the trigger's aria-describedby resolves correctly.\n   * @internal\n   */\n  private _lightDomDescription: HTMLSpanElement | null = null;\n\n  /**\n   * Watches in-place text mutations on the elements assigned to the\n   * `<slot name=\"content\">`. Without this observer, a framework that\n   * rewrites the slotted `<span slot=\"content\">` `textContent` in place\n   * would leave the document-scope shim stale — the `slotchange` event\n   * does NOT fire on descendant text mutations.\n   *\n   * The observer is reinstalled on every `_setupTriggerAria()` call against\n   * the deduped current set of assigned elements; it is fully torn down in\n   * `disconnectedCallback` to prevent leaks on SSR teardown.\n   * @internal\n   */\n  private _contentSlotTextObserver: MutationObserver | null = null;\n\n  // ─── Lifecycle ───\n\n  override connectedCallback(): void {\n    super.connectedCallback();\n    this.addEventListener('keydown', this._handleKeydown);\n    // Re-run ARIA setup on reconnection (firstUpdated does not re-run).\n    // hasUpdated is true after the first update cycle completes.\n    if (this.hasUpdated) {\n      this._setupTriggerAria();\n    }\n  }\n\n  override disconnectedCallback(): void {\n    super.disconnectedCallback();\n    this.removeEventListener('keydown', this._handleKeydown);\n    this._clearTimers();\n    this._lightDomDescription?.remove();\n    this._lightDomDescription = null;\n    // Round-23 P2: tear down the slotted-content text observer so a\n    // disconnect-then-reconnect cycle never leaks observers and the\n    // observed light-DOM nodes do not retain a reference to this host.\n    this._contentSlotTextObserver?.disconnect();\n    this._contentSlotTextObserver = null;\n  }\n\n  override firstUpdated(): void {\n    this._setupTriggerAria();\n  }\n\n  // ─── ARIA setup ───\n\n  /** @internal */\n  private _setupTriggerAria(): void {\n    const slot = this._defaultSlot;\n    if (!slot) return;\n    const trigger = slot.assignedElements()[0] as HTMLElement | undefined;\n\n    // Sync content from the content slot into a visually-hidden light DOM element.\n    // aria-describedby cannot cross Shadow DOM boundaries, so the referenced element\n    // must live in the document scope (light DOM), not inside the shadow root.\n    const contentSlot = this._contentSlot;\n    const contentEls = contentSlot?.assignedElements() ?? [];\n    const contentText = contentEls\n      .map((el) => el.textContent)\n      .join(' ')\n      .trim();\n\n    // Guard for SSR — document is unavailable server-side\n    if (!this._lightDomDescription && typeof document !== 'undefined') {\n      this._lightDomDescription = document.createElement('span');\n      this._lightDomDescription.id = this._tooltipId;\n      // Visually hidden but accessible to screen readers via aria-describedby.\n      // Appended to document.body (not this element) so that the ID is in the\n      // document scope and resolves correctly across shadow DOM boundaries.\n      // Web components must not mutate their own light DOM children.\n      this._lightDomDescription.style.cssText =\n        'position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0';\n      document.body.appendChild(this._lightDomDescription);\n    }\n    if (this._lightDomDescription) {\n      this._lightDomDescription.textContent = contentText;\n    }\n\n    if (trigger) {\n      trigger.setAttribute('aria-describedby', this._tooltipId);\n    }\n\n    // Round-23 P2 pattern: observe in-place text mutations on the assigned\n    // content elements so a framework-driven `textContent` rewrite re-syncs\n    // the document-scope shim. `slotchange` fires only on the assignment\n    // list itself, never on descendant text/attribute mutations.\n    this._installContentSlotTextObserver(contentEls);\n  }\n\n  /**\n   * (Re-)installs the slotted-content text observer over the deduped union\n   * of assigned `content` slot elements. Disconnects any previous observer\n   * before re-attaching so observer count is bounded by component lifetime,\n   * not by `slotchange` event count.\n   * @internal\n   */\n  private _installContentSlotTextObserver(elements: Element[]): void {\n    if (this._contentSlotTextObserver) {\n      this._contentSlotTextObserver.disconnect();\n      this._contentSlotTextObserver = null;\n    }\n    if (elements.length === 0) return;\n    if (typeof MutationObserver === 'undefined') return;\n    const unique = new Set<Element>(elements);\n    const observer = new MutationObserver(() => {\n      // Re-flatten the current assignment and write the fresh text into the\n      // shim. We deliberately do NOT call `_setupTriggerAria()` here — that\n      // would reinstall this very observer in a tight loop. The trigger's\n      // `aria-describedby` and the shim element are already wired; only the\n      // text mirror needs to be refreshed.\n      if (!this._lightDomDescription) return;\n      const contentSlot = this._contentSlot;\n      const fresh =\n        contentSlot\n          ?.assignedElements()\n          .map((el) => el.textContent)\n          .join(' ')\n          .trim() ?? '';\n      if (this._lightDomDescription.textContent !== fresh) {\n        this._lightDomDescription.textContent = fresh;\n      }\n    });\n    for (const el of unique) {\n      observer.observe(el, {\n        characterData: true,\n        subtree: true,\n        childList: true,\n      });\n    }\n    this._contentSlotTextObserver = observer;\n  }\n\n  // ─── Show/Hide ───\n\n  /** @internal */\n  private _scheduleShow(): void {\n    this._clearTimers();\n    this._showTimer = setTimeout(() => {\n      void this._show();\n    }, this.showDelay);\n  }\n\n  /** @internal */\n  private _scheduleHide(): void {\n    this._clearTimers();\n    this._hideTimer = setTimeout(() => {\n      this._hide();\n    }, this.hideDelay);\n  }\n\n  /** @internal */\n  private async _show(): Promise<void> {\n    this._visible = true;\n    await this.updateComplete;\n    await this._updatePosition();\n  }\n\n  /** @internal */\n  private _hide(): void {\n    this._visible = false;\n  }\n\n  /** @internal */\n  private _clearTimers(): void {\n    if (this._showTimer !== null) {\n      clearTimeout(this._showTimer);\n      this._showTimer = null;\n    }\n    if (this._hideTimer !== null) {\n      clearTimeout(this._hideTimer);\n      this._hideTimer = null;\n    }\n  }\n\n  // ─── Positioning ───\n\n  /** @internal */\n  private async _updatePosition(): Promise<void> {\n    const reference = this._triggerWrapper;\n    const tooltipEl = this._tooltipEl;\n    const arrowEl = this._arrowEl;\n\n    if (!reference || !tooltipEl || !arrowEl) return;\n\n    const { computePosition, flip, shift, offset, arrow } = await import('@floating-ui/dom');\n    const { x, y, placement, middlewareData } = await computePosition(reference, tooltipEl, {\n      placement: this.placement,\n      strategy: 'fixed',\n      middleware: [offset(8), flip(), shift({ padding: 8 }), arrow({ element: arrowEl })],\n    });\n\n    Object.assign(tooltipEl.style, {\n      left: `${x}px`,\n      top: `${y}px`,\n    });\n\n    const arrowData = middlewareData.arrow;\n    const basePlacement = placement.split('-')[0] ?? 'top';\n    const oppositeSide: Record<string, string> = {\n      top: 'bottom',\n      right: 'left',\n      bottom: 'top',\n      left: 'right',\n    };\n    const staticSide = oppositeSide[basePlacement] ?? 'bottom';\n\n    // Offset is derived from the arrow element's actual size so that custom\n    // --hx-tooltip-arrow-size values position the arrow correctly.\n    Object.assign(arrowEl.style, {\n      left: arrowData?.x != null ? `${arrowData.x}px` : '',\n      top: arrowData?.y != null ? `${arrowData.y}px` : '',\n      right: '',\n      bottom: '',\n      [staticSide]: `${-(arrowEl.offsetWidth / 2)}px`,\n    });\n  }\n\n  // ─── Events ───\n\n  /** @internal */\n  private _handleKeydown = (e: Event): void => {\n    if (!(e instanceof KeyboardEvent)) return;\n    if (e.key === 'Escape' && this._visible) {\n      this._clearTimers();\n      this._hide();\n    }\n  };\n\n  /**\n   * Handle mouseleave on the trigger wrapper.\n   * Does not schedule hide if keyboard focus is still on the trigger element,\n   * preventing mixed keyboard+mouse interactions from dismissing the tooltip\n   * while the user is still navigating by keyboard.\n   * @internal\n   */\n  private _handleTriggerMouseleave(): void {\n    const slot = this._defaultSlot;\n    const trigger = slot?.assignedElements()[0] as HTMLElement | undefined;\n    // Guard for SSR — document is unavailable server-side\n    const active = typeof document !== 'undefined' ? document.activeElement : null;\n    if (trigger && (trigger === active || trigger.contains(active))) {\n      return;\n    }\n    this._scheduleHide();\n  }\n\n  // ─── Render ───\n\n  override render() {\n    return html`\n      <div\n        class=\"trigger-wrapper\"\n        @mouseenter=${this._scheduleShow}\n        @mouseleave=${this._handleTriggerMouseleave}\n        @focusin=${this._scheduleShow}\n        @focusout=${this._scheduleHide}\n      >\n        <slot @slotchange=${this._setupTriggerAria}></slot>\n      </div>\n      <div\n        part=\"tooltip\"\n        id=${this._tooltipId}\n        role=\"tooltip\"\n        aria-hidden=${String(!this._visible)}\n        class=${this._visible ? 'visible' : ''}\n        @mouseenter=${this._clearTimers}\n        @mouseleave=${this._scheduleHide}\n      >\n        <slot name=\"content\" @slotchange=${this._setupTriggerAria}></slot>\n        <div part=\"arrow\"></div>\n      </div>\n    `;\n  }\n}\n\ndeclare global {\n  interface HTMLElementTagNameMap {\n    'hx-tooltip': HelixTooltip;\n  }\n}\n"],"names":["helixTooltipStyles","css","_nextTooltipId","createIdCounter","HelixTooltip","HelixElement","e","_a","_b","slot","trigger","contentSlot","contentEls","contentText","el","elements","unique","observer","fresh","reference","tooltipEl","arrowEl","computePosition","flip","shift","offset","arrow","x","y","placement","middlewareData","arrowData","basePlacement","staticSide","active","html","forcedColorsSurface","__decorateClass","property","state","query","customElement"],"mappings":"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"}

package/dist/utils/aria-flatten.d.ts

@@ -0,0 +1,56 @@
+/**
+ * AccName-aware text flattener. Walks the subtree of `root` and concatenates
+ * text-node content, REJECTING any element subtree carrying `aria-hidden="true"`
+ * or the `hidden` attribute per W3C AccName 1.2 §4.3.10. Used by host-canonical
+ * components for both external IDREF flatten (host aria-labelledby/aria-describedby
+ * targets) and slotted-label aggregation, so nested decorative content like
+ * `<svg aria-hidden="true"><title>icon</title></svg>` does not leak into the
+ * announced name/description.
+ *
+ * The TreeWalker filter only inspects elements VISITED during the walk — it
+ * never tests the root itself, so a hidden ROOT (e.g. `<span slot="label" hidden>`)
+ * would still contribute its descendants' text. Per AccName 1.2 §4.3.10, a
+ * hidden root contributes the empty string. Gate the walk here so every caller
+ * honors the rule symmetrically.
+ *
+ * ## Intentional divergence from AccName 1.2 §4.3.7 (LabelledBy Recursion)
+ *
+ * The AccName 1.2 spec (§4.3.7 + "Hidden Not Referenced") states that when an
+ * element is DIRECTLY referenced by `aria-labelledby` / `aria-describedby`,
+ * that referenced element's subtree contributes to the computed name even when
+ * the element itself is hidden via `hidden` / `aria-hidden="true"`. The author's
+ * explicit IDREF is treated as intent to use that subtree as the name.
+ *
+ * This helper deliberately diverges from §4.3.7 by applying the §4.3.10 hidden
+ * gate uniformly to ALL callers, including the IDREF-target path. Rationale:
+ *
+ *   1. **Predictability across consumer mental models.** Consumers expect
+ *      "visually hidden via `[hidden]` / `aria-hidden=true`" to mean
+ *      "semantically removed", full stop. A label that disappears visually but
+ *      keeps announcing creates a debugging trap, especially in CMS / Twig
+ *      contexts where visibility toggles are often driven by template logic.
+ *   2. **Standard accessible-hide pattern is already supported.** Authors who
+ *      want a label that is visually hidden but contributes its text via
+ *      `aria-labelledby` should use the established `.sr-only` / `.visually-hidden`
+ *      pattern (clip-path / position:absolute / width:1px), which neither
+ *      attribute affects. That pattern correctly contributes here.
+ *   3. **Fail-safe for stale references.** A hidden referenced element is more
+ *      often a stale or accidentally-toggled reference than an intentional
+ *      hidden-name source. Returning the empty string lets the host fall back
+ *      to its next AccName step (aria-label, slotted label, placeholder) rather
+ *      than announcing surprising stale content.
+ *
+ * If a future component genuinely needs strict §4.3.7 behavior, add a second
+ * entry point (e.g. `flattenAccNameForIdRef`) that skips the root-level gate
+ * and reuses the TreeWalker logic; do not relax this gate globally.
+ *
+ * Single source of truth for accessible-name flattening across the library.
+ * Used by hx-time-picker, hx-date-picker, hx-toggle-button, and any future
+ * host-canonical component that aggregates slotted text into an accessible name.
+ *
+ * @param root - The element whose subtree text content should be flattened.
+ * @returns The concatenated, whitespace-collapsed text content with hidden
+ *   subtrees excluded.
+ */
+export declare function flattenAccName(root: Element): string;
+//# sourceMappingURL=aria-flatten.d.ts.map

package/dist/utils/aria-flatten.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aria-flatten.d.ts","sourceRoot":"","sources":["../../src/utils/aria-flatten.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CA6BpD"}

package/dist/utils/aria-idref.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Shared utilities for resolving `aria-labelledby` and `aria-describedby`
+ * IDREF token lists across the Shadow DOM boundary.
+ *
+ * Selection-control components (`hx-checkbox`, `hx-radio-group`, `hx-switch`,
+ * etc.) elevate their semantic surface to the host via `ElementInternals` so
+ * that consumer-supplied `aria-labelledby` / `aria-describedby` on the host
+ * resolves to light-DOM elements rather than being trapped on inner shadow
+ * nodes.
+ *
+ * Modern Chromium 134+ and Safari 17.4+ expose the IDL element-references API
+ * (`internals.ariaLabelledByElements`, `internals.ariaDescribedByElements`).
+ * For those engines we resolve token IDs against the host's root node (a
+ * Document or ShadowRoot) and assign the resulting elements directly.
+ *
+ * Older engines fall back to the host-attribute path: the ARIA delegation
+ * mixin keeps the original token list in `data-aria-labelledby`/
+ * `data-aria-describedby`, which assistive technology cannot follow into the
+ * shadow root, but that is the same surface area as the pre-fix code and is
+ * not a regression.
+ *
+ * Component authors do NOT need to wire this directly — see
+ * `installAriaIdrefMirror()` for an installable observer that keeps an inner
+ * node's `aria-*` attributes in sync with the token list across mutations.
+ */
+/**
+ * Resolves a whitespace-separated IDREF token list to live element references.
+ *
+ * Searches the host's containing root first (Document or ShadowRoot), then
+ * walks up through enclosing shadow hosts, and finally falls back to the
+ * top-level Document. Codex round-15 P1: hx-* controls embedded inside an
+ * outer component's shadow tree often legitimately reference labels/descriptions
+ * declared in the outer document or in an ancestor shadow tree. Restricting
+ * resolution to a single root left those controls anonymous on the
+ * `ariaLabelledByElements` / `ariaDescribedByElements` path. The IDL
+ * element-references API accepts any element regardless of root, so widening
+ * the search closes that gap.
+ *
+ * Codex round-16 P1: when the host is **slotted into** another component
+ * (light-DOM child of a shadow-root-bearing element), `host.getRootNode()`
+ * is still the document, so IDREF targets declared in the slot owner's
+ * shadow root are unreachable through the ancestor-shadow-host chain. We
+ * additionally walk `host.assignedSlot.getRootNode()` — that resolves to
+ * the slot owner's shadow root — and continue up that root's host chain so
+ * cross-shadow IDREF resolution works for the composed-tree slotting
+ * pattern. The walk is recursive: a slot owner that is itself slotted into
+ * another shadow tree contributes its own ancestor chain too.
+ *
+ * Tokens that fail to resolve at every level are silently dropped — matching
+ * native attribute-string platform behaviour where unresolved tokens are
+ * ignored.
+ */
+export declare function resolveIdrefTokens(host: Element, tokens: string | null): Element[];
+/**
+ * True when the runtime exposes the IDL element-references API on
+ * `ElementInternals`. Older Firefox / Safari builds return `undefined`
+ * for these accessors.
+ */
+export declare function supportsIdrefElementReferences(internals: ElementInternals): boolean;
+/**
+ * Mirror snapshot describing what should be applied to inner ARIA-bearing
+ * shadow nodes. Components consume this to project the correct attributes
+ * onto whichever inner element owns the announced semantic role.
+ */
+export interface AriaIdrefSnapshot {
+    /** Computed `aria-labelledby` token list, or `null` to omit. */
+    labelledBy: string | null;
+    /** Computed `aria-describedby` token list, or `null` to omit. */
+    describedBy: string | null;
+}
+/**
+ * Merges two whitespace-separated token lists, preserving order and removing
+ * duplicates. `null`/empty inputs are skipped. Returns `null` when the merged
+ * list is empty.
+ */
+export declare function mergeTokenLists(...lists: Array<string | null | undefined>): string | null;
+/**
+ * Options accepted by `installAriaIdrefMirror()`.
+ */
+export interface AriaIdrefMirrorOptions {
+    /**
+     * Attribute names on the host whose mutations should trigger a resync.
+     * Defaults to `['aria-labelledby', 'aria-describedby', 'aria-label']` plus
+     * the `data-aria-*` mirrors used by `mixinDelegatesAria`.
+     */
+    observedAttributes?: string[];
+    /**
+     * Whether to observe the resolved root for `id` attribute and `childList`
+     * mutations so that late-inserted IDREF targets and id renames trigger a
+     * resync. Defaults to `true`.
+     */
+    observeRoot?: boolean;
+}
+/**
+ * Handle returned by `installAriaIdrefMirror()`. Call `disconnect()` from
+ * `disconnectedCallback()` to tear the observers down. `resync()` forces an
+ * immediate sync — useful from `connectedCallback()` after the host has been
+ * re-attached to a new root.
+ */
+export interface AriaIdrefMirrorHandle {
+    /** Force an immediate sync. */
+    resync(): void;
+    /** Tear down all observers and listeners. */
+    disconnect(): void;
+}
+/**
+ * Installs a `MutationObserver` pair that keeps host ARIA semantics in sync
+ * with mutations to consumer-supplied attributes AND late-target / id
+ * mutations in the host's resolved root.
+ *
+ * The `sync` callback is invoked on:
+ *   1. Initial install (synchronously)
+ *   2. Any change to one of the observed host attributes
+ *   3. Any `id` attribute mutation, child insertion, or child removal in the
+ *      resolved root (Document or ShadowRoot containing the host)
+ *
+ * Components should call this from `connectedCallback()` and call
+ * `handle.disconnect()` from `disconnectedCallback()`. The handle's
+ * `resync()` method is safe to call from any lifecycle hook.
+ *
+ * Costs are bounded: the host observer touches one element; the root
+ * observer is shared per `Document`/`ShadowRoot` (codex round-7 #11) so every
+ * subscribing host pays a single attach cost regardless of how many other
+ * IDREF-aware controls share the root.
+ */
+export declare function installAriaIdrefMirror(host: Element, sync: () => void, options?: AriaIdrefMirrorOptions): AriaIdrefMirrorHandle;
+//# sourceMappingURL=aria-idref.d.ts.map

package/dist/utils/aria-idref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aria-idref.d.ts","sourceRoot":"","sources":["../../src/utils/aria-idref.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,EAAE,CA6BlF;AA0ED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAOnF;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,gEAAgE;IAChE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,iEAAiE;IACjE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,KAAK,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,MAAM,GAAG,IAAI,CAazF;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,+BAA+B;IAC/B,MAAM,IAAI,IAAI,CAAC;IACf,6CAA6C;IAC7C,UAAU,IAAI,IAAI,CAAC;CACpB;AAsED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,MAAM,IAAI,EAChB,OAAO,GAAE,sBAA2B,GACnC,qBAAqB,CAmFvB"}

package/figma-inventory.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-05-03T13:42:50.577Z",
+  "generatedAt": "2026-05-05T12:24:24.560Z",
   "sourceCem": "custom-elements.json",
   "helixVersion": "3.3.1",
   "tokensVersion": "3.3.1",
@@ -5519,6 +5519,30 @@
           "type": "text",
           "defaultValue": ""
         },
+        {
+          "figmaPropertyName": "label",
+          "cemAttribute": "label",
+          "type": "text",
+          "defaultValue": "undefined"
+        },
+        {
+          "figmaPropertyName": "accessibleLabel",
+          "cemAttribute": "accessible-label",
+          "type": "text",
+          "defaultValue": "undefined"
+        },
+        {
+          "figmaPropertyName": "helpText",
+          "cemAttribute": "help-text",
+          "type": "text",
+          "defaultValue": "undefined"
+        },
+        {
+          "figmaPropertyName": "error",
+          "cemAttribute": "error",
+          "type": "text",
+          "defaultValue": "undefined"
+        },
         {
           "figmaPropertyName": "labelGradient",
           "cemAttribute": "label-gradient",
@@ -5569,6 +5593,27 @@
           "type": "instance-swap",
           "default": null,
           "description": "Custom trigger element. Default: a color swatch button."
+        },
+        {
+          "figmaPropertyName": "label",
+          "cemSlot": "label",
+          "type": "instance-swap",
+          "default": null,
+          "description": "Visible label projected above the trigger; aggregated text contributes to the host's accessible name when no stronger naming source (aria-labelledby/aria-label/accessible-label/label) is supplied."
+        },
+        {
+          "figmaPropertyName": "help-text",
+          "cemSlot": "help-text",
+          "type": "instance-swap",
+          "default": null,
+          "description": "Help text rendered below the trigger and joined into the host's announced description channel."
+        },
+        {
+          "figmaPropertyName": "error",
+          "cemSlot": "error",
+          "type": "instance-swap",
+          "default": null,
+          "description": "Error message rendered below help text. When present, marks the trigger as aria-invalid and is announced via a polite live region."
         }
       ],
       "cssParts": [
@@ -5599,6 +5644,18 @@
         {
           "description": "The text input area.",
           "name": "input"
+        },
+        {
+          "description": "The visible label container above the trigger.",
+          "name": "label"
+        },
+        {
+          "description": "The help-text container rendered below the trigger.",
+          "name": "help-text"
+        },
+        {
+          "description": "The error-message container rendered below help text.",
+          "name": "error"
         }
       ],
       "events": [
@@ -7808,6 +7865,12 @@
           "cemAttribute": "next-month-label",
           "type": "text",
           "defaultValue": "Next month"
+        },
+        {
+          "figmaPropertyName": "accessibleLabel",
+          "cemAttribute": "accessible-label",
+          "type": "text",
+          "defaultValue": "null"
         }
       ],
       "slots": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helixui/library",
-  "version": "3.3.1-next.115",
+  "version": "3.3.1-next.118",
   "description": "Enterprise Web Component Library built with Lit 3.x",
   "type": "module",
   "sideEffects": [
@@ -59,7 +59,7 @@
   "customElements": "custom-elements.json",
   "dependencies": {
     "lit": "^3.3.2",
-    "@helixui/tokens": "3.3.1-next.115"
+    "@helixui/tokens": "3.3.1-next.118"
   },
   "peerDependencies": {
     "@floating-ui/dom": "^1.7.6"