stimeo-ui 0.6.0 → 0.7.0

package/dist/controllers/popover_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/escape_layer.ts","../../src/utils/scroll_dismiss.ts","../../src/controllers/popover_controller.ts"],"names":[],"mappings":"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","file":"popover_controller.js","sourcesContent":["/**\n * Single resolver for layered Escape dismissal.\n *\n * Every Escape-dismissable overlay layer (modal focus traps, disclosure\n * overlays like dropdown/popover/menu, and hover-triggered transient layers)\n * registers here while it is open. One document-level listener per document\n * resolves each press to exactly one owner and invokes that layer's\n * {@link EscapeLayerOptions.onDismiss} — controllers never listen for a\n * dismissing Escape themselves.\n *\n * @remarks\n * Each document owns an activation-ordered stack. The owner of a press is the\n * **topmost layer whose {@link EscapeLayerOptions.claims} passes**; a layer\n * that declines is transparent, so a background overlay opened behind a modal\n * never blocks it. Because a layer opened from within another is necessarily\n * activated later, LIFO order is also inner-first for nested layers — no DOM\n * inspection is needed.\n *\n * The shared listener runs in the document bubble phase and honors\n * `event.defaultPrevented`, so an element-level widget handler that consumes\n * Escape first (an editor cancelling its edit, a combobox closing its list)\n * always wins over every registered layer — the deepest handler resolves the\n * press. A keydown that is part of an IME composition (`event.isComposing`)\n * cancels the composition, never a layer, and is ignored here for every layer\n * at once.\n *\n * A WeakMap keeps documents collectible; the listener is installed only while\n * a document's stack is non-empty, and controller lifecycle hooks guarantee\n * that disconnected layers never remain registered.\n */\n\n/** Behavior a layer registers when it activates. */\nexport interface EscapeLayerOptions {\n  /**\n   * Dismisses the layer. Called by the shared resolver when this layer owns a\n   * press; the resolver has already consumed the event (`preventDefault()`),\n   * so the callback only needs to close and place focus per the widget's\n   * contract.\n   */\n  onDismiss: () => void;\n  /**\n   * Whether the layer claims the current press. Evaluated per press, so it can\n   * depend on live state (e.g. \"focus is inside me or fell to the body\"). A\n   * declining layer is skipped and the next layer down is consulted; omitting\n   * it means the layer always claims while active.\n   */\n  claims?: () => boolean;\n}\n\n/** A document's stack plus the one shared listener bound to it. */\ninterface EscapeLayerRegistry {\n  stack: EscapeLayer[];\n  onKeydown: (event: KeyboardEvent) => void;\n}\n\n/**\n * Claims predicate shared by the click-opened disclosure overlays (dropdown /\n * popover / navigation-menu / menu / context-menu / menubar): the layer claims\n * a press while focus is inside `element`, or after focus fell to the body —\n * a click on non-focusable overlay content blurs to `<body>`, and Escape must\n * still close the overlay (the \"body-focus rescue\"). A press made after focus\n * moved to another interactive element is declined, so closing never yanks\n * focus away from where the user deliberately went.\n */\nexport function claimsWhileFocusWithin(element: Element): () => boolean {\n  return () => {\n    const active = element.ownerDocument.activeElement;\n    return active === null || active === element.ownerDocument.body || element.contains(active);\n  };\n}\n\nexport class EscapeLayer {\n  static readonly #registries = new WeakMap<Document, EscapeLayerRegistry>();\n\n  #ownerDocument: Document | null = null;\n  /** Dismissal callback while active; `null` when inactive. */\n  #onDismiss: (() => void) | null = null;\n  /** Live predicate deciding whether the layer claims a press; `null` = always. */\n  #claims: (() => boolean) | null = null;\n\n  /**\n   * Activates this layer at the top of its document's Escape stack, installing\n   * the document's shared resolver listener if this is its first layer.\n   * Re-activating an already-active layer moves it to the top.\n   */\n  activate(ownerDocument: Document = document, options: EscapeLayerOptions): void {\n    this.deactivate();\n    let registry = EscapeLayer.#registries.get(ownerDocument);\n    if (!registry) {\n      registry = EscapeLayer.#createRegistry();\n      EscapeLayer.#registries.set(ownerDocument, registry);\n      ownerDocument.addEventListener(\"keydown\", registry.onKeydown);\n    }\n    registry.stack.push(this);\n    this.#ownerDocument = ownerDocument;\n    this.#onDismiss = options.onDismiss;\n    this.#claims = options.claims ?? null;\n  }\n\n  /**\n   * Removes this layer from its document's Escape stack, uninstalling the\n   * shared listener when the stack empties. Safe to call when inactive.\n   */\n  deactivate(): void {\n    const ownerDocument = this.#ownerDocument;\n    if (!ownerDocument) return;\n\n    const registry = EscapeLayer.#registries.get(ownerDocument);\n    if (registry) {\n      const index = registry.stack.lastIndexOf(this);\n      if (index >= 0) registry.stack.splice(index, 1);\n      if (registry.stack.length === 0) {\n        ownerDocument.removeEventListener(\"keydown\", registry.onKeydown);\n        EscapeLayer.#registries.delete(ownerDocument);\n      }\n    }\n    this.#ownerDocument = null;\n    this.#onDismiss = null;\n    this.#claims = null;\n  }\n\n  /**\n   * Whether this active layer would own a press right now: it is the topmost\n   * layer whose {@link EscapeLayerOptions.claims} passes. Exposed for tests\n   * and diagnostics — production dismissal goes through the shared listener.\n   */\n  get ownsEscape(): boolean {\n    const ownerDocument = this.#ownerDocument;\n    if (!ownerDocument) return false;\n    const registry = EscapeLayer.#registries.get(ownerDocument);\n    if (!registry) return false;\n    return EscapeLayer.#resolveOwner(registry.stack) === this;\n  }\n\n  /** Builds a document's registry with its shared resolver listener. */\n  static #createRegistry(): EscapeLayerRegistry {\n    const registry: EscapeLayerRegistry = {\n      stack: [],\n      onKeydown: (event: KeyboardEvent): void => {\n        if (event.key !== \"Escape\" || event.defaultPrevented || event.isComposing) return;\n        const owner = EscapeLayer.#resolveOwner(registry.stack);\n        if (!owner) return;\n        event.preventDefault();\n        owner.#onDismiss?.();\n      },\n    };\n    return registry;\n  }\n\n  /** The topmost stack layer whose claims predicate passes, or `null`. */\n  static #resolveOwner(stack: EscapeLayer[]): EscapeLayer | null {\n    for (let index = stack.length - 1; index >= 0; index--) {\n      const layer = stack[index];\n      if (!layer) continue;\n      if (layer.#claims && !layer.#claims()) continue;\n      return layer;\n    }\n    return null;\n  }\n}\n","/**\n * Invokes `onScroll` when the page — or any scrollable ancestor of `element` —\n * scrolls, returning a cleanup that detaches every listener.\n *\n * `scroll` events do not bubble, and a single capture-phase listener on\n * `window`/`document` is unreliable for descendant scroll containers — so this\n * attaches a `scroll` listener directly to each scroll-parent ancestor (walking\n * `parentElement` and checking `overflow`) plus the window. That mirrors the\n * *intent* of `@floating-ui/dom`'s `autoUpdate` scroll tracking; it is a\n * deliberately simple resolver and does not cross shadow roots. This is precisely\n * the case a consumer cannot cover with `data-action` alone, which is why the\n * surface controllers own it.\n *\n * The listeners are `passive` (the handler never calls `preventDefault`), so they\n * never delay scrolling. Pass the surface's anchor/root so the relevant scroll\n * parents are found even when the floating element is portaled elsewhere.\n */\nexport function observeScrollDismiss(element: Element, onScroll: () => void): () => void {\n  const targets: Array<Element | Window> = [...scrollParents(element), window];\n  const handler = (): void => onScroll();\n  for (const target of targets) {\n    target.addEventListener(\"scroll\", handler, { passive: true });\n  }\n  return () => {\n    for (const target of targets) target.removeEventListener(\"scroll\", handler);\n  };\n}\n\n/** The scrollable ancestors of `element`, nearest first (window excluded). */\nfunction scrollParents(element: Element): Element[] {\n  const parents: Element[] = [];\n  let node = element.parentElement;\n  while (node) {\n    if (isScrollable(node)) parents.push(node);\n    node = node.parentElement;\n  }\n  return parents;\n}\n\n/** Whether `element` is a scroll container (any axis `auto`/`scroll`/`overlay`). */\nfunction isScrollable(element: Element): boolean {\n  const style = getComputedStyle(element);\n  return /auto|scroll|overlay/.test(style.overflow + style.overflowX + style.overflowY);\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { claimsWhileFocusWithin, EscapeLayer } from \"../utils/escape_layer\";\nimport { observeScrollDismiss } from \"../utils/scroll_dismiss\";\n\n/**\n * Headless, accessible **non-modal popover** behavior.\n *\n * Markup contract (identifier: `stimeo--popover`):\n *   <div data-controller=\"stimeo--popover\">\n *     <button data-stimeo--popover-target=\"trigger\"\n *             aria-haspopup=\"dialog\" aria-expanded=\"false\" aria-controls=\"pop\"\n *             data-action=\"click->stimeo--popover#toggle\">Edit profile</button>\n *     <div id=\"pop\" data-stimeo--popover-target=\"panel\"\n *          role=\"dialog\" aria-label=\"Edit profile\" hidden>…</div>\n *   </div>\n *\n * Implements the WAI-ARIA APG **Dialog** pattern run *non-modally* (no\n * `aria-modal`, no focus trap, no `inert`/scroll lock). The background stays\n * fully interactive; this is the modeless counterpart to `stimeo--dialog`. For\n * a roving `role=\"menu\"` of commands use `stimeo--menu`; for decorative-only\n * text use `stimeo--tooltip`.\n *\n * @remarks\n * Behavior only — static placement is the consumer's CSS, and dynamic\n * edge-collision avoidance is delegated to the opt-in `stimeo-ui/positioning`\n * module (this controller never imports it, preserving the zero-dep core). State\n * is exposed via the trigger's `aria-expanded` and the panel's `hidden`.\n *\n * Behavior provided:\n * - Click the trigger to toggle (`aria-expanded` + `hidden` reflect state).\n * - On open, focus moves to the first focusable element inside the panel (or the\n *   panel itself if it has none).\n * - `Escape` closes and restores focus to the trigger. While open the panel is a\n *   layer on the shared {@link EscapeLayer} stack; it claims a press only while\n *   focus is inside the controller or fell to the body (a click on non-focusable\n *   panel content), so a press aimed at another layer is never consumed here,\n *   and one keypress closes exactly one layer.\n * - An outside click (anywhere off the controller element) closes without moving\n *   focus. Focus stays at the clicked element, or falls back to the document body\n *   for a non-focusable destination.\n * - Because it is modeless, focus is *not* trapped: when `Tab` moves focus out of\n *   the controller it closes (detected via bubbling `focusout`) without yanking\n *   focus back, so forward and reverse traversal preserve their natural destination.\n *   A `focusout` with no destination is ignored because it also occurs for clicks\n *   on non-focusable content and when the browser window loses focus.\n * - Opt-in **dismiss on scroll** (`closeOnScroll`): while open, scrolling a tracked\n *   scroll-parent ancestor (or the window) closes the panel, the usual convention for\n *   anchored popups. Closes without restoring focus (like the modeless `focusout` path)\n *   so the close never fights the user's scroll. Off by default.\n */\nexport class PopoverController extends Controller<HTMLElement> {\n  static override targets = [\"trigger\", \"panel\"];\n  static override values = {\n    closeOnScroll: { type: Boolean, default: false },\n  };\n  static actions = [\"close\", \"open\", \"toggle\"] as const;\n\n  declare readonly triggerTarget: HTMLButtonElement;\n  declare readonly panelTarget: HTMLElement;\n  declare readonly hasTriggerTarget: boolean;\n  declare readonly hasPanelTarget: boolean;\n  declare readonly closeOnScrollValue: boolean;\n\n  /** Cleanup for the dismiss-on-scroll listeners while open, or `null`. */\n  #stopScrollDismiss: (() => void) | null = null;\n  /** Escape-stack membership while open; the shared resolver dismisses via it. */\n  readonly #escapeLayer = new EscapeLayer();\n\n  /** Selector for natively focusable elements used to find the first one. */\n  static readonly #FOCUSABLE =\n    'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex=\"-1\"])';\n\n  /** Starts closed and registers the standing dismissal listeners. */\n  override connect(): void {\n    this.close();\n    document.addEventListener(\"click\", this.#onOutsideClick, true);\n    this.element.addEventListener(\"focusout\", this.#onFocusOut);\n  }\n\n  /**\n   * Removes every standing listener registered in {@link connect} plus any active\n   * dismiss-on-scroll observers. `removeEventListener` is a no-op when it was\n   * never added, so this is safe in the closed state too — no listener outlives\n   * the element after a Turbo navigation.\n   */\n  override disconnect(): void {\n    this.#escapeLayer.deactivate();\n    document.removeEventListener(\"click\", this.#onOutsideClick, true);\n    this.element.removeEventListener(\"focusout\", this.#onFocusOut);\n    this.#stopScrollDismiss?.();\n    this.#stopScrollDismiss = null;\n  }\n\n  /** Toggles the popover. Bound via `data-action` (click on the trigger). */\n  toggle(): void {\n    if (this.#isOpen) {\n      this.close();\n    } else {\n      this.open();\n    }\n  }\n\n  /** Opens the panel, reflects state, and moves focus inside it. */\n  open(): void {\n    if (!this.hasPanelTarget || this.#isOpen) return;\n    this.panelTarget.hidden = false;\n    if (this.hasTriggerTarget) this.triggerTarget.setAttribute(\"aria-expanded\", \"true\");\n    this.#escapeLayer.activate(document, {\n      onDismiss: () => this.#closeAndRestore(),\n      claims: claimsWhileFocusWithin(this.element),\n    });\n    if (this.closeOnScrollValue && !this.#stopScrollDismiss) {\n      // Close (no focus restore) so dismissing never fights the user's scroll.\n      this.#stopScrollDismiss = observeScrollDismiss(this.element, () => this.close());\n    }\n    this.#focusFirst();\n  }\n\n  /** Closes the panel and reflects the collapsed state. Bound via `data-action`. */\n  close(): void {\n    // Release listeners first, unconditionally: a consumer may remove the panel\n    // target while it is open, and an early return would leak scroll observers.\n    this.#escapeLayer.deactivate();\n    this.#stopScrollDismiss?.();\n    this.#stopScrollDismiss = null;\n    if (this.hasPanelTarget) this.panelTarget.hidden = true;\n    if (this.hasTriggerTarget) this.triggerTarget.setAttribute(\"aria-expanded\", \"false\");\n  }\n\n  /** Moves focus to the first focusable element in the panel, or the panel itself. */\n  #focusFirst(): void {\n    const first = this.panelTarget.querySelector<HTMLElement>(PopoverController.#FOCUSABLE);\n    if (first) {\n      first.focus();\n      return;\n    }\n    if (!this.panelTarget.hasAttribute(\"tabindex\")) this.panelTarget.tabIndex = -1;\n    this.panelTarget.focus();\n  }\n\n  /** Closes and restores focus to the trigger for explicit keyboard dismissal. */\n  #closeAndRestore(): void {\n    this.close();\n    if (this.hasTriggerTarget) this.triggerTarget.focus();\n  }\n\n  /** Closes without moving focus when a click lands outside the controller element. */\n  readonly #onOutsideClick = (event: MouseEvent): void => {\n    const target = event.target;\n    if (this.#isOpen && target instanceof Node && !this.element.contains(target)) this.close();\n  };\n\n  /**\n   * Closes when focus leaves the controller for a known external destination\n   * (e.g. forward Tab past the panel or reverse Tab past the trigger). Focus is\n   * not restored — the natural destination is kept, which is the modeless\n   * contract. A null/non-Node destination is indeterminate: browsers use it for\n   * clicks on non-focusable content and window deactivation, so the later outside\n   * click handler decides pointer dismissal instead.\n   */\n  readonly #onFocusOut = (event: FocusEvent): void => {\n    if (!this.#isOpen) return;\n    const next = event.relatedTarget;\n    if (!(next instanceof Node) || this.element.contains(next)) return;\n    this.close();\n  };\n\n  /** Whether the panel is currently visible. */\n  get #isOpen(): boolean {\n    return this.hasPanelTarget && !this.panelTarget.hidden;\n  }\n}\n"]}
+{"version":3,"sources":["../../src/utils/escape_layer.ts","../../src/utils/focus_candidate.ts","../../src/utils/scroll_dismiss.ts","../../src/controllers/popover_controller.ts"],"names":[],"mappings":";;;;;AAgEO,SAAS,uBAAuB,OAAA,EAAiC;AACtE,EAAA,OAAO,MAAM;AACX,IAAA,MAAM,MAAA,GAAS,QAAQ,aAAA,CAAc,aAAA;AACrC,IAAA,OAAO,MAAA,KAAW,QAAQ,MAAA,KAAW,OAAA,CAAQ,cAAc,IAAA,IAAQ,OAAA,CAAQ,SAAS,MAAM,CAAA;AAAA,EAC5F,CAAA;AACF;AAEO,IAAM,WAAA,GAAN,MAAM,YAAA,CAAY;AAAA,EACvB,OAAgB,WAAA,mBAAc,IAAI,OAAA,EAAuC;AAAA,EAEzE,cAAA,GAAkC,IAAA;AAAA;AAAA,EAElC,UAAA,GAAkC,IAAA;AAAA;AAAA,EAElC,OAAA,GAAkC,IAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOlC,QAAA,CAAS,aAAA,GAA0B,QAAA,EAAU,OAAA,EAAmC;AAC9E,IAAA,IAAA,CAAK,UAAA,EAAW;AAChB,IAAA,IAAI,QAAA,GAAW,YAAA,CAAY,WAAA,CAAY,GAAA,CAAI,aAAa,CAAA;AACxD,IAAA,IAAI,CAAC,QAAA,EAAU;AACb,MAAA,QAAA,GAAW,aAAY,eAAA,EAAgB;AACvC,MAAA,YAAA,CAAY,WAAA,CAAY,GAAA,CAAI,aAAA,EAAe,QAAQ,CAAA;AACnD,MAAA,aAAA,CAAc,gBAAA,CAAiB,SAAA,EAAW,QAAA,CAAS,SAAS,CAAA;AAAA,IAC9D;AACA,IAAA,QAAA,CAAS,KAAA,CAAM,KAAK,IAAI,CAAA;AACxB,IAAA,IAAA,CAAK,cAAA,GAAiB,aAAA;AACtB,IAAA,IAAA,CAAK,aAAa,OAAA,CAAQ,SAAA;AAC1B,IAAA,IAAA,CAAK,OAAA,GAAU,QAAQ,MAAA,IAAU,IAAA;AAAA,EACnC;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,UAAA,GAAmB;AACjB,IAAA,MAAM,gBAAgB,IAAA,CAAK,cAAA;AAC3B,IAAA,IAAI,CAAC,aAAA,EAAe;AAEpB,IAAA,MAAM,QAAA,GAAW,YAAA,CAAY,WAAA,CAAY,GAAA,CAAI,aAAa,CAAA;AAC1D,IAAA,IAAI,QAAA,EAAU;AACZ,MAAA,MAAM,KAAA,GAAQ,QAAA,CAAS,KAAA,CAAM,WAAA,CAAY,IAAI,CAAA;AAC7C,MAAA,IAAI,SAAS,CAAA,EAAG,QAAA,CAAS,KAAA,CAAM,MAAA,CAAO,OAAO,CAAC,CAAA;AAC9C,MAAA,IAAI,QAAA,CAAS,KAAA,CAAM,MAAA,KAAW,CAAA,EAAG;AAC/B,QAAA,aAAA,CAAc,mBAAA,CAAoB,SAAA,EAAW,QAAA,CAAS,SAAS,CAAA;AAC/D,QAAA,YAAA,CAAY,WAAA,CAAY,OAAO,aAAa,CAAA;AAAA,MAC9C;AAAA,IACF;AACA,IAAA,IAAA,CAAK,cAAA,GAAiB,IAAA;AACtB,IAAA,IAAA,CAAK,UAAA,GAAa,IAAA;AAClB,IAAA,IAAA,CAAK,OAAA,GAAU,IAAA;AAAA,EACjB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,IAAI,UAAA,GAAsB;AACxB,IAAA,MAAM,gBAAgB,IAAA,CAAK,cAAA;AAC3B,IAAA,IAAI,CAAC,eAAe,OAAO,KAAA;AAC3B,IAAA,MAAM,QAAA,GAAW,YAAA,CAAY,WAAA,CAAY,GAAA,CAAI,aAAa,CAAA;AAC1D,IAAA,IAAI,CAAC,UAAU,OAAO,KAAA;AACtB,IAAA,OAAO,YAAA,CAAY,aAAA,CAAc,QAAA,CAAS,KAAK,CAAA,KAAM,IAAA;AAAA,EACvD;AAAA;AAAA,EAGA,OAAO,eAAA,GAAuC;AAC5C,IAAA,MAAM,QAAA,GAAgC;AAAA,MACpC,OAAO,EAAC;AAAA,MACR,SAAA,EAAW,CAAC,KAAA,KAA+B;AACzC,QAAA,IAAI,MAAM,GAAA,KAAQ,QAAA,IAAY,KAAA,CAAM,gBAAA,IAAoB,MAAM,WAAA,EAAa;AAC3E,QAAA,MAAM,KAAA,GAAQ,YAAA,CAAY,aAAA,CAAc,QAAA,CAAS,KAAK,CAAA;AACtD,QAAA,IAAI,CAAC,KAAA,EAAO;AACZ,QAAA,KAAA,CAAM,cAAA,EAAe;AACrB,QAAA,KAAA,CAAM,UAAA,IAAa;AAAA,MACrB;AAAA,KACF;AACA,IAAA,OAAO,QAAA;AAAA,EACT;AAAA;AAAA,EAGA,OAAO,cAAc,KAAA,EAA0C;AAC7D,IAAA,KAAA,IAAS,QAAQ,KAAA,CAAM,MAAA,GAAS,CAAA,EAAG,KAAA,IAAS,GAAG,KAAA,EAAA,EAAS;AACtD,MAAA,MAAM,KAAA,GAAQ,MAAM,KAAK,CAAA;AACzB,MAAA,IAAI,CAAC,KAAA,EAAO;AACZ,MAAA,IAAI,KAAA,CAAM,OAAA,IAAW,CAAC,KAAA,CAAM,SAAQ,EAAG;AACvC,MAAA,OAAO,KAAA;AAAA,IACT;AACA,IAAA,OAAO,IAAA;AAAA,EACT;AACF,CAAA;;;ACpJO,SAAS,yBAAyB,OAAA,EAA+B;AACtE,EAAA,IAAI,QAAA,GAA2B,OAAA,CAAQ,OAAA,CAAQ,oBAAoB,CAAA;AACnE,EAAA,OAAO,QAAA,EAAU;AACf,IAAA,MAAM,MAAA,GAAS,KAAA,CAAM,IAAA,CAAK,QAAA,CAAS,QAAQ,CAAA,CAAE,IAAA,CAAK,CAAC,KAAA,KAAU,KAAA,CAAM,OAAA,KAAY,QAAQ,CAAA;AACvF,IAAA,IAAI,CAAC,MAAA,EAAQ,QAAA,CAAS,OAAO,GAAG,OAAO,IAAA;AACvC,IAAA,QAAA,GAAW,QAAA,CAAS,aAAA,EAAe,OAAA,CAAQ,oBAAoB,CAAA,IAAK,IAAA;AAAA,EACtE;AACA,EAAA,OAAO,KAAA;AACT;AAgDO,SAAS,aAAa,OAAA,EAA+B;AAC1D,EAAA,IAAI,OAAA,CAAQ,OAAA,CAAQ,mBAAmB,CAAA,EAAG,OAAO,KAAA;AACjD,EAAA,IAAI,OAAA,YAAmB,gBAAA,IAAoB,OAAA,CAAQ,IAAA,KAAS,UAAU,OAAO,KAAA;AAC7E,EAAA,IAAI,EAAE,UAAA,IAAc,OAAA,CAAA,EAAU,OAAO,IAAA;AACrC,EAAA,IAAK,OAAA,CAAgD,UAAU,OAAO,KAAA;AACtE,EAAA,OAAO,CAAC,yBAAyB,OAAO,CAAA;AAC1C;AAGO,IAAM,2BAAA,GAA8B;AAAA,EACzC,SAAA;AAAA,EACA,YAAA;AAAA,EACA,QAAA;AAAA,EACA,OAAA;AAAA,EACA,QAAA;AAAA,EACA,UAAA;AAAA,EACA,SAAA;AAAA,EACA,QAAA;AAAA,EACA,iBAAA;AAAA,EACA,iBAAA;AAAA,EACA,YAAA;AAAA,EACA;AACF,CAAA,CAAE,KAAK,GAAG,CAAA;AAQH,SAAS,mBAAmB,OAAA,EAA+B;AAChE,EAAA,MAAM,QAAS,OAAA,CAA8C,eAAA;AAC7D,EAAA,OAAO,OAAO,KAAA,KAAU,UAAA,GAAa,KAAA,CAAM,IAAA,CAAK,SAAS,EAAE,kBAAA,EAAoB,IAAA,EAAM,CAAA,GAAI,IAAA;AAC3F;AAGA,SAAS,iBAAiB,OAAA,EAAqC;AAC7D,EAAA,MAAM,KAAA,GAAQ,OAAA,CAAQ,YAAA,CAAa,UAAU,CAAA;AAC7C,EAAA,IAAI,KAAA,KAAU,QAAQ,CAAC,YAAA,CAAa,KAAK,KAAA,CAAM,IAAA,EAAM,CAAA,EAAG,OAAO,IAAA;AAC/D,EAAA,OAAO,OAAO,KAAK,CAAA;AACrB;AAGA,SAAS,iBAAiB,OAAA,EAA+B;AACvD,EAAA,IAAI,OAAA,YAAmB,iBAAA,IAAqB,OAAA,YAAmB,eAAA,EAAiB;AAC9E,IAAA,OAAO,OAAA,CAAQ,aAAa,MAAM,CAAA;AAAA,EACpC;AACA,EAAA,IACE,OAAA,YAAmB,iBAAA,IACnB,OAAA,YAAmB,iBAAA,IACnB,mBAAmB,mBAAA,EACnB;AACA,IAAA,OAAO,IAAA;AAAA,EACT;AACA,EAAA,IAAI,OAAA,YAAmB,gBAAA,EAAkB,OAAO,OAAA,CAAQ,IAAA,KAAS,QAAA;AACjE,EAAA,IAAI,OAAA,YAAmB,mBAAmB,OAAO,IAAA;AACjD,EAAA,IAAI,OAAA,CAAQ,OAAA,KAAY,OAAA,IAAW,OAAA,CAAQ,YAAY,OAAA,EAAS;AAC9D,IAAA,OAAO,OAAA,CAAQ,aAAa,UAAU,CAAA;AAAA,EACxC;AACA,EAAA,IAAI,OAAA,YAAmB,WAAA,IAAe,OAAA,CAAQ,OAAA,KAAY,SAAA,EAAW;AACnE,IAAA,MAAM,UAAU,OAAA,CAAQ,aAAA;AACxB,IAAA,OACE,OAAA,YAAmB,kBAAA,IACnB,KAAA,CAAM,IAAA,CAAK,OAAA,CAAQ,QAAQ,CAAA,CAAE,IAAA,CAAK,CAAC,KAAA,KAAU,KAAA,CAAM,OAAA,KAAY,SAAS,CAAA,KAAM,OAAA;AAAA,EAElF;AACA,EAAA,OAAO,KAAA;AACT;AAGA,SAAS,mBAAmB,OAAA,EAA+B;AACzD,EAAA,MAAM,KAAA,GAAQ,OAAA,CAAQ,YAAA,CAAa,iBAAiB,GAAG,WAAA,EAAY;AACnE,EAAA,OAAO,KAAA,KAAU,EAAA,IAAM,KAAA,KAAU,MAAA,IAAU,KAAA,KAAU,gBAAA;AACvD;AAUO,SAAS,UAAU,OAAA,EAA+B;AACvD,EAAA,IAAI,CAAC,aAAa,OAAO,CAAA,IAAK,CAAC,kBAAA,CAAmB,OAAO,GAAG,OAAO,KAAA;AAEnE,EAAA,MAAM,QAAA,GAAW,iBAAiB,OAAO,CAAA;AACzC,EAAA,IAAI,QAAA,KAAa,IAAA,EAAM,OAAO,QAAA,IAAY,CAAA;AAC1C,EAAA,OAAO,gBAAA,CAAiB,OAAO,CAAA,IAAK,kBAAA,CAAmB,OAAO,CAAA;AAChE;AAUO,SAAS,aAAa,IAAA,EAAsC;AACjE,EAAA,KAAA,MAAW,SAAA,IAAa,IAAA,CAAK,gBAAA,CAA8B,2BAA2B,CAAA,EAAG;AACvF,IAAA,IAAI,SAAA,CAAU,SAAS,CAAA,EAAG,OAAO,SAAA;AAAA,EACnC;AACA,EAAA,OAAO,IAAA;AACT;;;AC1JO,SAAS,oBAAA,CAAqB,SAAkB,QAAA,EAAkC;AACvF,EAAA,MAAM,UAAmC,CAAC,GAAG,aAAA,CAAc,OAAO,GAAG,MAAM,CAAA;AAC3E,EAAA,MAAM,OAAA,GAAU,MAAY,QAAA,EAAS;AACrC,EAAA,KAAA,MAAW,UAAU,OAAA,EAAS;AAC5B,IAAA,MAAA,CAAO,iBAAiB,QAAA,EAAU,OAAA,EAAS,EAAE,OAAA,EAAS,MAAM,CAAA;AAAA,EAC9D;AACA,EAAA,OAAO,MAAM;AACX,IAAA,KAAA,MAAW,MAAA,IAAU,OAAA,EAAS,MAAA,CAAO,mBAAA,CAAoB,UAAU,OAAO,CAAA;AAAA,EAC5E,CAAA;AACF;AAGA,SAAS,cAAc,OAAA,EAA6B;AAClD,EAAA,MAAM,UAAqB,EAAC;AAC5B,EAAA,IAAI,OAAO,OAAA,CAAQ,aAAA;AACnB,EAAA,OAAO,IAAA,EAAM;AACX,IAAA,IAAI,YAAA,CAAa,IAAI,CAAA,EAAG,OAAA,CAAQ,KAAK,IAAI,CAAA;AACzC,IAAA,IAAA,GAAO,IAAA,CAAK,aAAA;AAAA,EACd;AACA,EAAA,OAAO,OAAA;AACT;AAGA,SAAS,aAAa,OAAA,EAA2B;AAC/C,EAAA,MAAM,KAAA,GAAQ,iBAAiB,OAAO,CAAA;AACtC,EAAA,OAAO,sBAAsB,IAAA,CAAK,KAAA,CAAM,WAAW,KAAA,CAAM,SAAA,GAAY,MAAM,SAAS,CAAA;AACtF;;;ACQO,IAAM,iBAAA,GAAN,cAAgC,UAAA,CAAwB;AAAA,EAC7D,OAAgB,OAAA,GAAU,CAAC,SAAA,EAAW,OAAO,CAAA;AAAA,EAC7C,OAAgB,MAAA,GAAS;AAAA,IACvB,aAAA,EAAe,EAAE,IAAA,EAAM,OAAA,EAAS,SAAS,KAAA;AAAM,GACjD;AAAA,EACA,OAAO,OAAA,GAAU,CAAC,OAAA,EAAS,QAAQ,QAAQ,CAAA;AAAA;AAAA,EAS3C,kBAAA,GAA0C,IAAA;AAAA;AAAA,EAEjC,YAAA,GAAe,IAAI,WAAA,EAAY;AAAA;AAAA,EAG/B,OAAA,GAAgB;AACvB,IAAA,IAAA,CAAK,KAAA,EAAM;AACX,IAAA,QAAA,CAAS,gBAAA,CAAiB,OAAA,EAAS,IAAA,CAAK,eAAA,EAAiB,IAAI,CAAA;AAC7D,IAAA,IAAA,CAAK,OAAA,CAAQ,gBAAA,CAAiB,UAAA,EAAY,IAAA,CAAK,WAAW,CAAA;AAAA,EAC5D;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQS,UAAA,GAAmB;AAC1B,IAAA,IAAA,CAAK,aAAa,UAAA,EAAW;AAC7B,IAAA,QAAA,CAAS,mBAAA,CAAoB,OAAA,EAAS,IAAA,CAAK,eAAA,EAAiB,IAAI,CAAA;AAChE,IAAA,IAAA,CAAK,OAAA,CAAQ,mBAAA,CAAoB,UAAA,EAAY,IAAA,CAAK,WAAW,CAAA;AAC7D,IAAA,IAAA,CAAK,kBAAA,IAAqB;AAC1B,IAAA,IAAA,CAAK,kBAAA,GAAqB,IAAA;AAAA,EAC5B;AAAA;AAAA,EAGA,MAAA,GAAe;AACb,IAAA,IAAI,KAAK,OAAA,EAAS;AAChB,MAAA,IAAA,CAAK,KAAA,EAAM;AAAA,IACb,CAAA,MAAO;AACL,MAAA,IAAA,CAAK,IAAA,EAAK;AAAA,IACZ;AAAA,EACF;AAAA;AAAA,EAGA,IAAA,GAAa;AACX,IAAA,IAAI,CAAC,IAAA,CAAK,cAAA,IAAkB,IAAA,CAAK,OAAA,EAAS;AAC1C,IAAA,IAAA,CAAK,YAAY,MAAA,GAAS,KAAA;AAC1B,IAAA,IAAI,KAAK,gBAAA,EAAkB,IAAA,CAAK,aAAA,CAAc,YAAA,CAAa,iBAAiB,MAAM,CAAA;AAClF,IAAA,IAAA,CAAK,YAAA,CAAa,SAAS,QAAA,EAAU;AAAA,MACnC,SAAA,EAAW,MAAM,IAAA,CAAK,gBAAA,EAAiB;AAAA,MACvC,MAAA,EAAQ,sBAAA,CAAuB,IAAA,CAAK,OAAO;AAAA,KAC5C,CAAA;AACD,IAAA,IAAI,IAAA,CAAK,kBAAA,IAAsB,CAAC,IAAA,CAAK,kBAAA,EAAoB;AAEvD,MAAA,IAAA,CAAK,qBAAqB,oBAAA,CAAqB,IAAA,CAAK,SAAS,MAAM,IAAA,CAAK,OAAO,CAAA;AAAA,IACjF;AACA,IAAA,IAAA,CAAK,WAAA,EAAY;AAAA,EACnB;AAAA;AAAA,EAGA,KAAA,GAAc;AAGZ,IAAA,IAAA,CAAK,aAAa,UAAA,EAAW;AAC7B,IAAA,IAAA,CAAK,kBAAA,IAAqB;AAC1B,IAAA,IAAA,CAAK,kBAAA,GAAqB,IAAA;AAC1B,IAAA,IAAI,IAAA,CAAK,cAAA,EAAgB,IAAA,CAAK,WAAA,CAAY,MAAA,GAAS,IAAA;AACnD,IAAA,IAAI,KAAK,gBAAA,EAAkB,IAAA,CAAK,aAAA,CAAc,YAAA,CAAa,iBAAiB,OAAO,CAAA;AAAA,EACrF;AAAA;AAAA,EAGA,WAAA,GAAoB;AAClB,IAAA,MAAM,KAAA,GAAQ,YAAA,CAAa,IAAA,CAAK,WAAW,CAAA;AAC3C,IAAA,IAAI,KAAA,EAAO;AACT,MAAA,KAAA,CAAM,KAAA,EAAM;AACZ,MAAA;AAAA,IACF;AACA,IAAA,IAAI,CAAC,KAAK,WAAA,CAAY,YAAA,CAAa,UAAU,CAAA,EAAG,IAAA,CAAK,YAAY,QAAA,GAAW,EAAA;AAC5E,IAAA,IAAA,CAAK,YAAY,KAAA,EAAM;AAAA,EACzB;AAAA;AAAA,EAGA,gBAAA,GAAyB;AACvB,IAAA,IAAA,CAAK,KAAA,EAAM;AACX,IAAA,IAAI,IAAA,CAAK,gBAAA,EAAkB,IAAA,CAAK,aAAA,CAAc,KAAA,EAAM;AAAA,EACtD;AAAA;AAAA,EAGS,eAAA,GAAkB,CAAC,KAAA,KAA4B;AACtD,IAAA,MAAM,SAAS,KAAA,CAAM,MAAA;AACrB,IAAA,IAAI,IAAA,CAAK,OAAA,IAAW,MAAA,YAAkB,IAAA,IAAQ,CAAC,IAAA,CAAK,OAAA,CAAQ,QAAA,CAAS,MAAM,CAAA,EAAG,IAAA,CAAK,KAAA,EAAM;AAAA,EAC3F,CAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUS,WAAA,GAAc,CAAC,KAAA,KAA4B;AAClD,IAAA,IAAI,CAAC,KAAK,OAAA,EAAS;AACnB,IAAA,MAAM,OAAO,KAAA,CAAM,aAAA;AACnB,IAAA,IAAI,EAAE,IAAA,YAAgB,IAAA,CAAA,IAAS,KAAK,OAAA,CAAQ,QAAA,CAAS,IAAI,CAAA,EAAG;AAC5D,IAAA,IAAA,CAAK,KAAA,EAAM;AAAA,EACb,CAAA;AAAA;AAAA,EAGA,IAAI,OAAA,GAAmB;AACrB,IAAA,OAAO,IAAA,CAAK,cAAA,IAAkB,CAAC,IAAA,CAAK,WAAA,CAAY,MAAA;AAAA,EAClD;AACF","file":"popover_controller.js","sourcesContent":["/**\n * Single resolver for layered Escape dismissal.\n *\n * Every Escape-dismissable overlay layer (modal focus traps, disclosure\n * overlays like dropdown/popover/menu, and hover-triggered transient layers)\n * registers here while it is open. One document-level listener per document\n * resolves each press to exactly one owner and invokes that layer's\n * {@link EscapeLayerOptions.onDismiss} — controllers never listen for a\n * dismissing Escape themselves.\n *\n * @remarks\n * Each document owns an activation-ordered stack. The owner of a press is the\n * **topmost layer whose {@link EscapeLayerOptions.claims} passes**; a layer\n * that declines is transparent, so a background overlay opened behind a modal\n * never blocks it. Because a layer opened from within another is necessarily\n * activated later, LIFO order is also inner-first for nested layers — no DOM\n * inspection is needed.\n *\n * The shared listener runs in the document bubble phase and honors\n * `event.defaultPrevented`, so an element-level widget handler that consumes\n * Escape first (an editor cancelling its edit, a combobox closing its list)\n * always wins over every registered layer — the deepest handler resolves the\n * press. A keydown that is part of an IME composition (`event.isComposing`)\n * cancels the composition, never a layer, and is ignored here for every layer\n * at once.\n *\n * A WeakMap keeps documents collectible; the listener is installed only while\n * a document's stack is non-empty, and controller lifecycle hooks guarantee\n * that disconnected layers never remain registered.\n */\n\n/** Behavior a layer registers when it activates. */\nexport interface EscapeLayerOptions {\n  /**\n   * Dismisses the layer. Called by the shared resolver when this layer owns a\n   * press; the resolver has already consumed the event (`preventDefault()`),\n   * so the callback only needs to close and place focus per the widget's\n   * contract.\n   */\n  onDismiss: () => void;\n  /**\n   * Whether the layer claims the current press. Evaluated per press, so it can\n   * depend on live state (e.g. \"focus is inside me or fell to the body\"). A\n   * declining layer is skipped and the next layer down is consulted; omitting\n   * it means the layer always claims while active.\n   */\n  claims?: () => boolean;\n}\n\n/** A document's stack plus the one shared listener bound to it. */\ninterface EscapeLayerRegistry {\n  stack: EscapeLayer[];\n  onKeydown: (event: KeyboardEvent) => void;\n}\n\n/**\n * Claims predicate shared by the click-opened disclosure overlays (dropdown /\n * popover / navigation-menu / menu / context-menu / menubar): the layer claims\n * a press while focus is inside `element`, or after focus fell to the body —\n * a click on non-focusable overlay content blurs to `<body>`, and Escape must\n * still close the overlay (the \"body-focus rescue\"). A press made after focus\n * moved to another interactive element is declined, so closing never yanks\n * focus away from where the user deliberately went.\n */\nexport function claimsWhileFocusWithin(element: Element): () => boolean {\n  return () => {\n    const active = element.ownerDocument.activeElement;\n    return active === null || active === element.ownerDocument.body || element.contains(active);\n  };\n}\n\nexport class EscapeLayer {\n  static readonly #registries = new WeakMap<Document, EscapeLayerRegistry>();\n\n  #ownerDocument: Document | null = null;\n  /** Dismissal callback while active; `null` when inactive. */\n  #onDismiss: (() => void) | null = null;\n  /** Live predicate deciding whether the layer claims a press; `null` = always. */\n  #claims: (() => boolean) | null = null;\n\n  /**\n   * Activates this layer at the top of its document's Escape stack, installing\n   * the document's shared resolver listener if this is its first layer.\n   * Re-activating an already-active layer moves it to the top.\n   */\n  activate(ownerDocument: Document = document, options: EscapeLayerOptions): void {\n    this.deactivate();\n    let registry = EscapeLayer.#registries.get(ownerDocument);\n    if (!registry) {\n      registry = EscapeLayer.#createRegistry();\n      EscapeLayer.#registries.set(ownerDocument, registry);\n      ownerDocument.addEventListener(\"keydown\", registry.onKeydown);\n    }\n    registry.stack.push(this);\n    this.#ownerDocument = ownerDocument;\n    this.#onDismiss = options.onDismiss;\n    this.#claims = options.claims ?? null;\n  }\n\n  /**\n   * Removes this layer from its document's Escape stack, uninstalling the\n   * shared listener when the stack empties. Safe to call when inactive.\n   */\n  deactivate(): void {\n    const ownerDocument = this.#ownerDocument;\n    if (!ownerDocument) return;\n\n    const registry = EscapeLayer.#registries.get(ownerDocument);\n    if (registry) {\n      const index = registry.stack.lastIndexOf(this);\n      if (index >= 0) registry.stack.splice(index, 1);\n      if (registry.stack.length === 0) {\n        ownerDocument.removeEventListener(\"keydown\", registry.onKeydown);\n        EscapeLayer.#registries.delete(ownerDocument);\n      }\n    }\n    this.#ownerDocument = null;\n    this.#onDismiss = null;\n    this.#claims = null;\n  }\n\n  /**\n   * Whether this active layer would own a press right now: it is the topmost\n   * layer whose {@link EscapeLayerOptions.claims} passes. Exposed for tests\n   * and diagnostics — production dismissal goes through the shared listener.\n   */\n  get ownsEscape(): boolean {\n    const ownerDocument = this.#ownerDocument;\n    if (!ownerDocument) return false;\n    const registry = EscapeLayer.#registries.get(ownerDocument);\n    if (!registry) return false;\n    return EscapeLayer.#resolveOwner(registry.stack) === this;\n  }\n\n  /** Builds a document's registry with its shared resolver listener. */\n  static #createRegistry(): EscapeLayerRegistry {\n    const registry: EscapeLayerRegistry = {\n      stack: [],\n      onKeydown: (event: KeyboardEvent): void => {\n        if (event.key !== \"Escape\" || event.defaultPrevented || event.isComposing) return;\n        const owner = EscapeLayer.#resolveOwner(registry.stack);\n        if (!owner) return;\n        event.preventDefault();\n        owner.#onDismiss?.();\n      },\n    };\n    return registry;\n  }\n\n  /** The topmost stack layer whose claims predicate passes, or `null`. */\n  static #resolveOwner(stack: EscapeLayer[]): EscapeLayer | null {\n    for (let index = stack.length - 1; index >= 0; index--) {\n      const layer = stack[index];\n      if (!layer) continue;\n      if (layer.#claims && !layer.#claims()) continue;\n      return layer;\n    }\n    return null;\n  }\n}\n","/**\n * Whether a disabled `<fieldset>` ancestor actually reaches `control`.\n *\n * HTML exempts the contents of a fieldset's **first direct-child `<legend>`**, and\n * the exemption is per fieldset — a control legal in one legend can still be\n * disabled by a second, outer fieldset, so the walk continues upward.\n *\n * Exported for the consumer that needs this rule *without* the rest of\n * {@link canTakeFocus}: `toolbar` bounds its own `hidden` walk at the toolbar\n * root, which is a different rule, so it composes the two itself.\n */\nexport function inheritsFieldsetDisabled(control: HTMLElement): boolean {\n  let fieldset: Element | null = control.closest(\"fieldset[disabled]\");\n  while (fieldset) {\n    const legend = Array.from(fieldset.children).find((child) => child.tagName === \"LEGEND\");\n    if (!legend?.contains(control)) return true;\n    fieldset = fieldset.parentElement?.closest(\"fieldset[disabled]\") ?? null;\n  }\n  return false;\n}\n\n/**\n * Whether an element can actually take focus, checked **before** `focus()` runs.\n *\n * A controller that must move focus off a control it is about to disable or hide\n * picks a destination and calls `focus()` on it. If that destination cannot take\n * focus, the call **fails silently**: `hidden` and natively `disabled` elements\n * swallow it, so the caret stays in the subtree that is disappearing and lands on\n * `<body>` a frame later — the exact outcome the rescue exists to prevent, minus\n * any signal that it happened.\n *\n * Testing after the fact is the obvious alternative and is deliberately not the\n * rule. Reading `document.activeElement` back only works in a real browser, and\n * looping over candidates that way performs a real focus move per failure —\n * observable to assistive technology. Checking first costs nothing and catches\n * the cases that actually occur.\n *\n * **`aria-disabled` is not disqualifying.** It is the attribute an author uses\n * for a control that must stay *discoverable*, and the roving contract keeps\n * such items reachable. Only the three conditions that make the platform refuse\n * focus are checked: `hidden` / `inert` (an ancestor's counts),\n * `input[type=\"hidden\"]`, the native `disabled` property, and `disabled`\n * inherited from an ancestor `fieldset`. CSS-only invisibility is handled by\n * {@link isRenderedForFocus} when a consumer needs sequential-focus semantics.\n *\n * Reading `:disabled` instead of walking the fieldset chain would be shorter, but\n * that pseudo-class is not evaluated consistently outside real browsers and this\n * has to be right headlessly too. happy-dom in particular focuses a `<button>`\n * inside a disabled fieldset where a real engine refuses, so the inheritance is\n * spelled out rather than delegated.\n *\n * What a consumer does when nothing survives is its own call: some fall back to\n * their landmark, while a widget whose caret already sits somewhere legitimate\n * refuses the move outright rather than relocating it.\n *\n * @example\n * ```ts\n * const target = candidates.find(canTakeFocus);\n * if (target) target.focus();\n * else {\n *   this.#tabindex.lend(this.element); // nothing left: fall back to the landmark\n *   this.element.focus();\n * }\n * ```\n *\n * @param element - the candidate destination\n */\nexport function canTakeFocus(element: HTMLElement): boolean {\n  if (element.closest(\"[hidden], [inert]\")) return false;\n  if (element instanceof HTMLInputElement && element.type === \"hidden\") return false;\n  if (!(\"disabled\" in element)) return true;\n  if ((element as HTMLElement & { disabled: boolean }).disabled) return false;\n  return !inheritsFieldsetDisabled(element);\n}\n\n/** Elements whose semantics or authored attributes can place them in sequential focus order. */\nexport const TAB_STOP_CANDIDATE_SELECTOR = [\n  \"a[href]\",\n  \"area[href]\",\n  \"button\",\n  \"input\",\n  \"select\",\n  \"textarea\",\n  \"summary\",\n  \"iframe\",\n  \"audio[controls]\",\n  \"video[controls]\",\n  \"[tabindex]\",\n  \"[contenteditable]\",\n].join(\",\");\n\n/** Optional browser visibility API used to exclude CSS-hidden candidates. */\ninterface VisibilityCheckable {\n  checkVisibility?: (options?: { visibilityProperty?: boolean }) => boolean;\n}\n\n/** Whether CSS visibility allows an otherwise eligible element to participate in focus order. */\nexport function isRenderedForFocus(element: HTMLElement): boolean {\n  const check = (element as HTMLElement & VisibilityCheckable).checkVisibility;\n  return typeof check === \"function\" ? check.call(element, { visibilityProperty: true }) : true;\n}\n\n/** Parses an authored `tabindex`; invalid syntax has no explicit focus-order meaning. */\nfunction authoredTabindex(element: HTMLElement): number | null {\n  const value = element.getAttribute(\"tabindex\");\n  if (value === null || !/^[+-]?\\d+$/.test(value.trim())) return null;\n  return Number(value);\n}\n\n/** Whether the element's native semantics place it in sequential focus order. */\nfunction hasNativeTabStop(element: HTMLElement): boolean {\n  if (element instanceof HTMLAnchorElement || element instanceof HTMLAreaElement) {\n    return element.hasAttribute(\"href\");\n  }\n  if (\n    element instanceof HTMLButtonElement ||\n    element instanceof HTMLSelectElement ||\n    element instanceof HTMLTextAreaElement\n  ) {\n    return true;\n  }\n  if (element instanceof HTMLInputElement) return element.type !== \"hidden\";\n  if (element instanceof HTMLIFrameElement) return true;\n  if (element.tagName === \"AUDIO\" || element.tagName === \"VIDEO\") {\n    return element.hasAttribute(\"controls\");\n  }\n  if (element instanceof HTMLElement && element.tagName === \"SUMMARY\") {\n    const details = element.parentElement;\n    return (\n      details instanceof HTMLDetailsElement &&\n      Array.from(details.children).find((child) => child.tagName === \"SUMMARY\") === element\n    );\n  }\n  return false;\n}\n\n/** Whether an explicit `contenteditable` value creates an editable tab stop. */\nfunction hasEditableTabStop(element: HTMLElement): boolean {\n  const value = element.getAttribute(\"contenteditable\")?.toLowerCase();\n  return value === \"\" || value === \"true\" || value === \"plaintext-only\";\n}\n\n/**\n * Whether an element is a usable sequential Tab stop right now.\n *\n * Native semantics, authored `tabindex`, editable hosts, inherited disabled state,\n * HTML `hidden`/`inert`, and CSS visibility are evaluated together. `aria-disabled`\n * remains focusable because it communicates unavailability without removing the\n * control from discovery order.\n */\nexport function isTabStop(element: HTMLElement): boolean {\n  if (!canTakeFocus(element) || !isRenderedForFocus(element)) return false;\n\n  const tabindex = authoredTabindex(element);\n  if (tabindex !== null) return tabindex >= 0;\n  return hasNativeTabStop(element) || hasEditableTabStop(element);\n}\n\n/** Returns every usable sequential Tab stop below `root` in document order. */\nexport function tabStopsWithin(root: ParentNode): HTMLElement[] {\n  return Array.from(root.querySelectorAll<HTMLElement>(TAB_STOP_CANDIDATE_SELECTOR)).filter(\n    isTabStop,\n  );\n}\n\n/** Returns the first usable sequential Tab stop below `root`, if one exists. */\nexport function firstTabStop(root: ParentNode): HTMLElement | null {\n  for (const candidate of root.querySelectorAll<HTMLElement>(TAB_STOP_CANDIDATE_SELECTOR)) {\n    if (isTabStop(candidate)) return candidate;\n  }\n  return null;\n}\n\n/** Whether `root` contains at least one usable sequential Tab stop. */\nexport function hasTabStop(root: ParentNode): boolean {\n  return firstTabStop(root) !== null;\n}\n","/**\n * Invokes `onScroll` when the page — or any scrollable ancestor of `element` —\n * scrolls, returning a cleanup that detaches every listener.\n *\n * `scroll` events do not bubble, and a single capture-phase listener on\n * `window`/`document` is unreliable for descendant scroll containers — so this\n * attaches a `scroll` listener directly to each scroll-parent ancestor (walking\n * `parentElement` and checking `overflow`) plus the window. That mirrors the\n * *intent* of `@floating-ui/dom`'s `autoUpdate` scroll tracking; it is a\n * deliberately simple resolver and does not cross shadow roots. This is precisely\n * the case a consumer cannot cover with `data-action` alone, which is why the\n * surface controllers own it.\n *\n * The listeners are `passive` (the handler never calls `preventDefault`), so they\n * never delay scrolling. Pass the surface's anchor/root so the relevant scroll\n * parents are found even when the floating element is portaled elsewhere.\n */\nexport function observeScrollDismiss(element: Element, onScroll: () => void): () => void {\n  const targets: Array<Element | Window> = [...scrollParents(element), window];\n  const handler = (): void => onScroll();\n  for (const target of targets) {\n    target.addEventListener(\"scroll\", handler, { passive: true });\n  }\n  return () => {\n    for (const target of targets) target.removeEventListener(\"scroll\", handler);\n  };\n}\n\n/** The scrollable ancestors of `element`, nearest first (window excluded). */\nfunction scrollParents(element: Element): Element[] {\n  const parents: Element[] = [];\n  let node = element.parentElement;\n  while (node) {\n    if (isScrollable(node)) parents.push(node);\n    node = node.parentElement;\n  }\n  return parents;\n}\n\n/** Whether `element` is a scroll container (any axis `auto`/`scroll`/`overlay`). */\nfunction isScrollable(element: Element): boolean {\n  const style = getComputedStyle(element);\n  return /auto|scroll|overlay/.test(style.overflow + style.overflowX + style.overflowY);\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { claimsWhileFocusWithin, EscapeLayer } from \"../utils/escape_layer\";\nimport { firstTabStop } from \"../utils/focus_candidate\";\nimport { observeScrollDismiss } from \"../utils/scroll_dismiss\";\n\n/**\n * Headless, accessible **non-modal popover** behavior.\n *\n * Markup contract (identifier: `stimeo--popover`):\n *   <div data-controller=\"stimeo--popover\">\n *     <button data-stimeo--popover-target=\"trigger\"\n *             aria-haspopup=\"dialog\" aria-expanded=\"false\" aria-controls=\"pop\"\n *             data-action=\"click->stimeo--popover#toggle\">Edit profile</button>\n *     <div id=\"pop\" data-stimeo--popover-target=\"panel\"\n *          role=\"dialog\" aria-label=\"Edit profile\" hidden>…</div>\n *   </div>\n *\n * Implements the WAI-ARIA APG **Dialog** pattern run *non-modally* (no\n * `aria-modal`, no focus trap, no `inert`/scroll lock). The background stays\n * fully interactive; this is the modeless counterpart to `stimeo--dialog`. For\n * a roving `role=\"menu\"` of commands use `stimeo--menu`; for decorative-only\n * text use `stimeo--tooltip`.\n *\n * @remarks\n * Behavior only — static placement is the consumer's CSS, and dynamic\n * edge-collision avoidance is delegated to the opt-in `stimeo-ui/positioning`\n * module (this controller never imports it, preserving the zero-dep core). State\n * is exposed via the trigger's `aria-expanded` and the panel's `hidden`.\n *\n * Behavior provided:\n * - Click the trigger to toggle (`aria-expanded` + `hidden` reflect state).\n * - On open, focus moves to the first focusable element inside the panel (or the\n *   panel itself if it has none).\n * - `Escape` closes and restores focus to the trigger. While open the panel is a\n *   layer on the shared {@link EscapeLayer} stack; it claims a press only while\n *   focus is inside the controller or fell to the body (a click on non-focusable\n *   panel content), so a press aimed at another layer is never consumed here,\n *   and one keypress closes exactly one layer.\n * - An outside click (anywhere off the controller element) closes without moving\n *   focus. Focus stays at the clicked element, or falls back to the document body\n *   for a non-focusable destination.\n * - Because it is modeless, focus is *not* trapped: when `Tab` moves focus out of\n *   the controller it closes (detected via bubbling `focusout`) without yanking\n *   focus back, so forward and reverse traversal preserve their natural destination.\n *   A `focusout` with no destination is ignored because it also occurs for clicks\n *   on non-focusable content and when the browser window loses focus.\n * - Opt-in **dismiss on scroll** (`closeOnScroll`): while open, scrolling a tracked\n *   scroll-parent ancestor (or the window) closes the panel, the usual convention for\n *   anchored popups. Closes without restoring focus (like the modeless `focusout` path)\n *   so the close never fights the user's scroll. Off by default.\n */\nexport class PopoverController extends Controller<HTMLElement> {\n  static override targets = [\"trigger\", \"panel\"];\n  static override values = {\n    closeOnScroll: { type: Boolean, default: false },\n  };\n  static actions = [\"close\", \"open\", \"toggle\"] as const;\n\n  declare readonly triggerTarget: HTMLButtonElement;\n  declare readonly panelTarget: HTMLElement;\n  declare readonly hasTriggerTarget: boolean;\n  declare readonly hasPanelTarget: boolean;\n  declare readonly closeOnScrollValue: boolean;\n\n  /** Cleanup for the dismiss-on-scroll listeners while open, or `null`. */\n  #stopScrollDismiss: (() => void) | null = null;\n  /** Escape-stack membership while open; the shared resolver dismisses via it. */\n  readonly #escapeLayer = new EscapeLayer();\n\n  /** Starts closed and registers the standing dismissal listeners. */\n  override connect(): void {\n    this.close();\n    document.addEventListener(\"click\", this.#onOutsideClick, true);\n    this.element.addEventListener(\"focusout\", this.#onFocusOut);\n  }\n\n  /**\n   * Removes every standing listener registered in {@link connect} plus any active\n   * dismiss-on-scroll observers. `removeEventListener` is a no-op when it was\n   * never added, so this is safe in the closed state too — no listener outlives\n   * the element after a Turbo navigation.\n   */\n  override disconnect(): void {\n    this.#escapeLayer.deactivate();\n    document.removeEventListener(\"click\", this.#onOutsideClick, true);\n    this.element.removeEventListener(\"focusout\", this.#onFocusOut);\n    this.#stopScrollDismiss?.();\n    this.#stopScrollDismiss = null;\n  }\n\n  /** Toggles the popover. Bound via `data-action` (click on the trigger). */\n  toggle(): void {\n    if (this.#isOpen) {\n      this.close();\n    } else {\n      this.open();\n    }\n  }\n\n  /** Opens the panel, reflects state, and moves focus inside it. */\n  open(): void {\n    if (!this.hasPanelTarget || this.#isOpen) return;\n    this.panelTarget.hidden = false;\n    if (this.hasTriggerTarget) this.triggerTarget.setAttribute(\"aria-expanded\", \"true\");\n    this.#escapeLayer.activate(document, {\n      onDismiss: () => this.#closeAndRestore(),\n      claims: claimsWhileFocusWithin(this.element),\n    });\n    if (this.closeOnScrollValue && !this.#stopScrollDismiss) {\n      // Close (no focus restore) so dismissing never fights the user's scroll.\n      this.#stopScrollDismiss = observeScrollDismiss(this.element, () => this.close());\n    }\n    this.#focusFirst();\n  }\n\n  /** Closes the panel and reflects the collapsed state. Bound via `data-action`. */\n  close(): void {\n    // Release listeners first, unconditionally: a consumer may remove the panel\n    // target while it is open, and an early return would leak scroll observers.\n    this.#escapeLayer.deactivate();\n    this.#stopScrollDismiss?.();\n    this.#stopScrollDismiss = null;\n    if (this.hasPanelTarget) this.panelTarget.hidden = true;\n    if (this.hasTriggerTarget) this.triggerTarget.setAttribute(\"aria-expanded\", \"false\");\n  }\n\n  /** Moves focus to the first focusable element in the panel, or the panel itself. */\n  #focusFirst(): void {\n    const first = firstTabStop(this.panelTarget);\n    if (first) {\n      first.focus();\n      return;\n    }\n    if (!this.panelTarget.hasAttribute(\"tabindex\")) this.panelTarget.tabIndex = -1;\n    this.panelTarget.focus();\n  }\n\n  /** Closes and restores focus to the trigger for explicit keyboard dismissal. */\n  #closeAndRestore(): void {\n    this.close();\n    if (this.hasTriggerTarget) this.triggerTarget.focus();\n  }\n\n  /** Closes without moving focus when a click lands outside the controller element. */\n  readonly #onOutsideClick = (event: MouseEvent): void => {\n    const target = event.target;\n    if (this.#isOpen && target instanceof Node && !this.element.contains(target)) this.close();\n  };\n\n  /**\n   * Closes when focus leaves the controller for a known external destination\n   * (e.g. forward Tab past the panel or reverse Tab past the trigger). Focus is\n   * not restored — the natural destination is kept, which is the modeless\n   * contract. A null/non-Node destination is indeterminate: browsers use it for\n   * clicks on non-focusable content and window deactivation, so the later outside\n   * click handler decides pointer dismissal instead.\n   */\n  readonly #onFocusOut = (event: FocusEvent): void => {\n    if (!this.#isOpen) return;\n    const next = event.relatedTarget;\n    if (!(next instanceof Node) || this.element.contains(next)) return;\n    this.close();\n  };\n\n  /** Whether the panel is currently visible. */\n  get #isOpen(): boolean {\n    return this.hasPanelTarget && !this.panelTarget.hidden;\n  }\n}\n"]}

package/dist/controllers/portal_controller.d.ts

@@ -17,6 +17,8 @@ import { Controller } from '@hotwired/stimulus';
  * (when `restore`) — or remove it — leaving no orphan behind. The moved node carries
  * `data-portaled`.
  *
+ * `mount` dispatches `{ target }`; `unmount` dispatches `{}`.
+ *
  * @remarks
  * Behavior only — no positioning (pair with `stimeo-ui/positioning`) and no focus
  * trapping (pair with a Focus Scope / the overlay). Moving a Stimulus element within

package/dist/controllers/portal_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/detach_gate.ts","../../src/controllers/portal_controller.ts"],"names":[],"mappings":"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","file":"portal_controller.js","sourcesContent":["/**\n * Shared \"in-page move vs real detach\" discriminator for `disconnect()`.\n *\n * A mid-session `disconnect()` whose element is still in the document is\n * ambiguous. It can be:\n *\n * - an **in-page move** — a consumer (sortable, a teleport) re-inserted the\n *   element; Stimulus reconnects the SAME instance in the same mutation batch\n *   and the controller's runtime state must survive;\n * - a **detach that keeps the element** — `data-controller` no longer lists the\n *   identifier (a Turbo 8 morph), or the element moved outside the observed\n *   root (a scoped `Application.start(root)`, a shadow root); no reconnect will\n *   ever come and the controller must tear down or it leaks its sessions,\n *   document listeners, and moved nodes.\n *\n * Neither available signal decides this alone. A synchronous `data-controller`\n * token check catches the morph case but misses an observed-root exit (the\n * token stays, the reconnect never comes). Deferring teardown one microtask and\n * letting `connect()` cancel it catches the root exit, but leans on Stimulus\n * reconnecting moved elements within the same mutation batch — internal\n * behavior, not a public contract. {@link DetachGate} composes both: the token\n * check is the synchronous fast path (no probe, no reliance on batching), the\n * microtask probe is the fallback for the genuinely ambiguous remainder.\n *\n * Policy stays with the consumer (the `SafeTimeout` / `FocusTrap` lineage —\n * this util owns the discrimination only):\n *\n * - **Probe** ({@link disconnected}) when the teardown must eventually happen —\n *   live drag sessions, document listeners, teleported *content*. Call\n *   {@link cancel} from `connect()` (a reconnect means in-page move) and from\n *   the head of any direct teardown path (see below).\n * - **Keep** (bare {@link DetachGate.isDetached}) when undoing the ambiguous\n *   case would fight the controller's own effect: a controller that moves its\n *   OWN element (portal's no-`content` form) exits a scoped observed root as\n *   its normal job — a probe-driven teardown would restore the element into\n *   the root, reconnect, re-teleport, and disconnect again, forever. Such\n *   controllers keep their state on an ambiguous disconnect and tear down only\n *   on {@link DetachGate.isDetached}.\n *\n * Event convention for probe consumers: teardown into a dead (detached) tree is\n * silent — consumers restore from their own `connect()`; a detach that keeps the\n * tree alive must end an in-flight session with a `cancel` event, or composing\n * consumers strand their session bookkeeping.\n */\n\n/** The slice of a Stimulus controller the gate inspects. */\nexport interface DetachGateHost {\n  readonly element: Element;\n  readonly identifier: string;\n}\n\n/**\n * Per-controller-instance gate deciding whether a `disconnect()` is a real\n * detach. Hold one per controller (`#gate = new DetachGate()`) — Stimulus\n * reuses the instance across reconnects, so the pending probe state carries\n * over exactly as the protocol needs.\n *\n * @example\n * ```ts\n * #gate = new DetachGate();\n *\n * connect(): void {\n *   this.#gate.cancel(); // a reconnect: the element moved in-page\n *   // …\n * }\n *\n * disconnect(): void {\n *   this.#gate.disconnected(this, () => this.#teardown());\n * }\n *\n * #teardown(): void {\n *   this.#gate.cancel(); // disarm a still-queued probe (double-run guard)\n *   // …\n * }\n * ```\n */\nexport class DetachGate {\n  /** Set while a probe is queued, waiting for a reconnect to cancel it. */\n  #pending = false;\n\n  /**\n   * True while a probe is queued — the last disconnect was ambiguous and no\n   * reconnect has cancelled it yet. Read it from `connect()` to tell the\n   * reconnect half of an in-page move from a first connect: a controller whose\n   * initialisation restarts a measurement (a min-duration floor, an elapsed\n   * counter) must skip it for the move, where nothing actually restarted.\n   */\n  get pending(): boolean {\n    return this.#pending;\n  }\n\n  /**\n   * True when the disconnect is definitely a real detach — the element left\n   * the document, or `data-controller` no longer lists the identifier. False\n   * means ambiguous (in-page move or observed-root exit), NOT \"alive\".\n   */\n  static isDetached(host: DetachGateHost): boolean {\n    if (!host.element.isConnected) return true;\n    const tokens = (host.element.getAttribute(\"data-controller\") ?? \"\").split(/\\s+/);\n    return !tokens.includes(host.identifier);\n  }\n\n  /**\n   * Call from `disconnect()`: runs `teardown` synchronously on a definite\n   * detach (fast path), otherwise defers it one microtask — a reconnect\n   * ({@link cancel} from `connect()`) keeps the state, no reconnect runs it.\n   * One microtask is the whole probe window: Stimulus reconnects a moved\n   * element within the same mutation batch, before the checkpoint drains.\n   */\n  disconnected(host: DetachGateHost, teardown: () => void): void {\n    if (DetachGate.isDetached(host)) {\n      // Also disarms a probe a previous ambiguous disconnect left queued\n      // (defer, element removed, disconnect again) — exactly one teardown.\n      this.#pending = false;\n      teardown();\n      return;\n    }\n    this.#pending = true;\n    queueMicrotask(() => {\n      if (!this.#pending) return;\n      this.#pending = false;\n      teardown();\n    });\n  }\n\n  /**\n   * Disarms a pending probe. Call from `connect()` (the reconnect that proves\n   * an in-page move) and from the head of any teardown path not routed through\n   * {@link disconnected} (disabled-toggle, Escape), so an orphaned probe can\n   * never run the teardown a second time.\n   */\n  cancel(): void {\n    this.#pending = false;\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { DetachGate } from \"../utils/detach_gate\";\n\n/**\n * Teleport bookkeeping keyed by the controller element (stable across the\n * connect/disconnect churn some DOM runtimes emit when an observed element is moved).\n * Holds the moved node and its placeholder so any controller instance for that element\n * can finish the teardown.\n */\nconst portalState = new WeakMap<Element, { node: HTMLElement; placeholder: Comment }>();\n\n/**\n * Headless **portal / teleport**: moves an element to another place in the DOM (e.g.\n * directly under `body`) on connect and cleans up on disconnect — the shared substrate\n * for overlays that must escape an ancestor's `overflow: hidden`, `transform`, or\n * stacking context (no APG pattern; a DOM utility).\n *\n * Markup contract (identifier: `stimeo--portal`):\n *   <div data-controller=\"stimeo--portal\" data-stimeo--portal-to-value=\"body\">\n *     <div data-stimeo--portal-target=\"content\">Teleported content</div>\n *   </div>\n *\n * Moves `content` (or `this.element` when no `content` target) into the first element\n * matching `to` (default `body`), `append`ed or `prepend`ed per `position`. A comment\n * placeholder records the original spot so `disconnect()` can return the node there\n * (when `restore`) — or remove it — leaving no orphan behind. The moved node carries\n * `data-portaled`.\n *\n * @remarks\n * Behavior only — no positioning (pair with `stimeo-ui/positioning`) and no focus\n * trapping (pair with a Focus Scope / the overlay). Moving a Stimulus element within\n * the same document does not re-fire connect/disconnect, so the move is safe. For Turbo\n * compatibility prefer the `content`-target form: the controller then stays on the\n * in-place source, so its `disconnect()` fires when the original container is replaced\n * and the teleported node is restored/removed rather than orphaned under `body`. The\n * move is idempotent (guarded by the placeholder) and reversed on `disconnect()` (Turbo\n * navigation included). The \"in-page move vs real detach\" split on `disconnect()` is\n * {@link DetachGate}; in the `content` form the source element may even leave a\n * scoped application's observed root and the content is still restored, while the\n * no-`content` form teleporting itself out of the observed root is fire-and-forget\n * by design (see `disconnect()`).\n */\nexport class PortalController extends Controller<HTMLElement> {\n  static override targets = [\"content\"];\n  static override values = {\n    to: { type: String, default: \"body\" },\n    position: { type: String, default: \"append\" },\n    restore: { type: Boolean, default: true },\n  };\n  static events = [\"mount\", \"unmount\"] as const;\n\n  declare readonly contentTarget: HTMLElement;\n  declare readonly hasContentTarget: boolean;\n\n  declare toValue: string;\n  declare positionValue: string;\n  declare restoreValue: boolean;\n\n  /** Decides whether a `disconnect()` is an in-page move or a real detach. */\n  readonly #gate = new DetachGate();\n\n  override connect(): void {\n    // A reconnect proves an in-page move of the source element: disarm the\n    // probe the mid-move disconnect() deferred (see disconnect).\n    this.#gate.cancel();\n    if (portalState.has(this.element)) return; // already portaled here (idempotent)\n    const node = this.hasContentTarget ? this.contentTarget : this.element;\n    const destination = this.#destination();\n    if (!destination || destination === node || node.contains(destination)) return;\n\n    const placeholder = document.createComment(\"stimeo--portal\");\n    node.parentNode?.insertBefore(placeholder, node);\n    portalState.set(this.element, { node, placeholder });\n\n    if (this.positionValue === \"prepend\") {\n      destination.prepend(node);\n    } else {\n      destination.appendChild(node);\n    }\n    node.setAttribute(\"data-portaled\", \"true\");\n    this.dispatch(\"mount\", { detail: { target: destination } });\n  }\n\n  override disconnect(): void {\n    const state = portalState.get(this.element);\n    if (!state) return;\n    if (state.node === this.element) {\n      // No-`content` form: the teleported node IS the controller element, so the\n      // teleport itself may exit a scoped application's observed root — the controller\n      // doing its job, not a detach. A probe-driven restore would re-enter the root,\n      // reconnect, re-teleport and disconnect again, forever. So an ambiguous\n      // disconnect (in the document, identifier still listed — also the churn a\n      // self-move emits in some runtimes) KEEPS the teleport, and only a definite\n      // detach — the element left the DOM, or `data-controller` no longer lists us\n      // (a Turbo 8 morph) — restores. The cost, by design: a teleport that left the\n      // observed root is fire-and-forget (Stimulus never fires for it again).\n      if (!DetachGate.isDetached(this)) return;\n      this.#restore(state);\n      return;\n    }\n    // `content` form: the controller element stays put, so its own teleport emits no\n    // churn — an ambiguous disconnect means the SOURCE element moved. In-page, the\n    // same-batch reconnect cancels the probe and the teleport survives; out of the\n    // observed root, no reconnect comes and the probe restores, so the content is\n    // never stranded at the destination with a dead owner.\n    this.#gate.disconnected(this, () => {\n      const current = portalState.get(this.element);\n      if (current) this.#restore(current);\n    });\n  }\n\n  /** Returns the node to its placeholder (or removes it) and clears the bookkeeping. */\n  #restore(state: { node: HTMLElement; placeholder: Comment }): void {\n    portalState.delete(this.element);\n    const { node, placeholder } = state;\n\n    node.removeAttribute(\"data-portaled\");\n    if (this.restoreValue && placeholder.parentNode) {\n      placeholder.parentNode.insertBefore(node, placeholder);\n    } else {\n      node.remove();\n    }\n    placeholder.remove();\n    this.dispatch(\"unmount\", { detail: {} });\n  }\n\n  /** Resolves the destination for `to`, tolerating an invalid selector. */\n  #destination(): Element | null {\n    const selector = this.toValue.trim();\n    if (!selector) return null;\n    try {\n      return document.querySelector(selector);\n    } catch {\n      return null;\n    }\n  }\n}\n"]}
+{"version":3,"sources":["../../src/utils/detach_gate.ts","../../src/controllers/portal_controller.ts"],"names":[],"mappings":"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","file":"portal_controller.js","sourcesContent":["/**\n * Shared \"in-page move vs real detach\" discriminator for `disconnect()`.\n *\n * A mid-session `disconnect()` whose element is still in the document is\n * ambiguous. It can be:\n *\n * - an **in-page move** — a consumer (sortable, a teleport) re-inserted the\n *   element; Stimulus reconnects the SAME instance in the same mutation batch\n *   and the controller's runtime state must survive;\n * - a **detach that keeps the element** — `data-controller` no longer lists the\n *   identifier (a Turbo 8 morph), or the element moved outside the observed\n *   root (a scoped `Application.start(root)`, a shadow root); no reconnect will\n *   ever come and the controller must tear down or it leaks its sessions,\n *   document listeners, and moved nodes.\n *\n * Neither available signal decides this alone. A synchronous `data-controller`\n * token check catches the morph case but misses an observed-root exit (the\n * token stays, the reconnect never comes). Deferring teardown one microtask and\n * letting `connect()` cancel it catches the root exit, but leans on Stimulus\n * reconnecting moved elements within the same mutation batch — internal\n * behavior, not a public contract. {@link DetachGate} composes both: the token\n * check is the synchronous fast path (no probe, no reliance on batching), the\n * microtask probe is the fallback for the genuinely ambiguous remainder.\n *\n * Policy stays with the consumer (the `SafeTimeout` / `FocusTrap` lineage —\n * this util owns the discrimination only):\n *\n * - **Probe** ({@link disconnected}) when the teardown must eventually happen —\n *   live drag sessions, document listeners, teleported *content*. Call\n *   {@link cancel} from `connect()` (a reconnect means in-page move) and from\n *   the head of any direct teardown path (see below).\n * - **Keep** (bare {@link DetachGate.isDetached}) when undoing the ambiguous\n *   case would fight the controller's own effect: a controller that moves its\n *   OWN element (portal's no-`content` form) exits a scoped observed root as\n *   its normal job — a probe-driven teardown would restore the element into\n *   the root, reconnect, re-teleport, and disconnect again, forever. Such\n *   controllers keep their state on an ambiguous disconnect and tear down only\n *   on {@link DetachGate.isDetached}.\n *\n * Event convention for probe consumers: teardown into a dead (detached) tree is\n * silent — consumers restore from their own `connect()`; a detach that keeps the\n * tree alive must end an in-flight session with a `cancel` event, or composing\n * consumers strand their session bookkeeping.\n */\n\n/** The slice of a Stimulus controller the gate inspects. */\nexport interface DetachGateHost {\n  readonly element: Element;\n  readonly identifier: string;\n}\n\n/**\n * Per-controller-instance gate deciding whether a `disconnect()` is a real\n * detach. Hold one per controller (`#gate = new DetachGate()`) — Stimulus\n * reuses the instance across reconnects, so the pending probe state carries\n * over exactly as the protocol needs.\n *\n * @example\n * ```ts\n * #gate = new DetachGate();\n *\n * connect(): void {\n *   this.#gate.cancel(); // a reconnect: the element moved in-page\n *   // …\n * }\n *\n * disconnect(): void {\n *   this.#gate.disconnected(this, () => this.#teardown());\n * }\n *\n * #teardown(): void {\n *   this.#gate.cancel(); // disarm a still-queued probe (double-run guard)\n *   // …\n * }\n * ```\n */\nexport class DetachGate {\n  /** Set while a probe is queued, waiting for a reconnect to cancel it. */\n  #pending = false;\n\n  /**\n   * True while a probe is queued — the last disconnect was ambiguous and no\n   * reconnect has cancelled it yet. Read it from `connect()` to tell the\n   * reconnect half of an in-page move from a first connect: a controller whose\n   * initialisation restarts a measurement (a min-duration floor, an elapsed\n   * counter) must skip it for the move, where nothing actually restarted.\n   */\n  get pending(): boolean {\n    return this.#pending;\n  }\n\n  /**\n   * True when the disconnect is definitely a real detach — the element left\n   * the document, or `data-controller` no longer lists the identifier. False\n   * means ambiguous (in-page move or observed-root exit), NOT \"alive\".\n   */\n  static isDetached(host: DetachGateHost): boolean {\n    if (!host.element.isConnected) return true;\n    const tokens = (host.element.getAttribute(\"data-controller\") ?? \"\").split(/\\s+/);\n    return !tokens.includes(host.identifier);\n  }\n\n  /**\n   * Call from `disconnect()`: runs `teardown` synchronously on a definite\n   * detach (fast path), otherwise defers it one microtask — a reconnect\n   * ({@link cancel} from `connect()`) keeps the state, no reconnect runs it.\n   * One microtask is the whole probe window: Stimulus reconnects a moved\n   * element within the same mutation batch, before the checkpoint drains.\n   */\n  disconnected(host: DetachGateHost, teardown: () => void): void {\n    if (DetachGate.isDetached(host)) {\n      // Also disarms a probe a previous ambiguous disconnect left queued\n      // (defer, element removed, disconnect again) — exactly one teardown.\n      this.#pending = false;\n      teardown();\n      return;\n    }\n    this.#pending = true;\n    queueMicrotask(() => {\n      if (!this.#pending) return;\n      this.#pending = false;\n      teardown();\n    });\n  }\n\n  /**\n   * Disarms a pending probe. Call from `connect()` (the reconnect that proves\n   * an in-page move) and from the head of any teardown path not routed through\n   * {@link disconnected} (disabled-toggle, Escape), so an orphaned probe can\n   * never run the teardown a second time.\n   */\n  cancel(): void {\n    this.#pending = false;\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { DetachGate } from \"../utils/detach_gate\";\n\n/**\n * Teleport bookkeeping keyed by the controller element (stable across the\n * connect/disconnect churn some DOM runtimes emit when an observed element is moved).\n * Holds the moved node and its placeholder so any controller instance for that element\n * can finish the teardown.\n */\nconst portalState = new WeakMap<Element, { node: HTMLElement; placeholder: Comment }>();\n\n/**\n * Headless **portal / teleport**: moves an element to another place in the DOM (e.g.\n * directly under `body`) on connect and cleans up on disconnect — the shared substrate\n * for overlays that must escape an ancestor's `overflow: hidden`, `transform`, or\n * stacking context (no APG pattern; a DOM utility).\n *\n * Markup contract (identifier: `stimeo--portal`):\n *   <div data-controller=\"stimeo--portal\" data-stimeo--portal-to-value=\"body\">\n *     <div data-stimeo--portal-target=\"content\">Teleported content</div>\n *   </div>\n *\n * Moves `content` (or `this.element` when no `content` target) into the first element\n * matching `to` (default `body`), `append`ed or `prepend`ed per `position`. A comment\n * placeholder records the original spot so `disconnect()` can return the node there\n * (when `restore`) — or remove it — leaving no orphan behind. The moved node carries\n * `data-portaled`.\n *\n * `mount` dispatches `{ target }`; `unmount` dispatches `{}`.\n *\n * @remarks\n * Behavior only — no positioning (pair with `stimeo-ui/positioning`) and no focus\n * trapping (pair with a Focus Scope / the overlay). Moving a Stimulus element within\n * the same document does not re-fire connect/disconnect, so the move is safe. For Turbo\n * compatibility prefer the `content`-target form: the controller then stays on the\n * in-place source, so its `disconnect()` fires when the original container is replaced\n * and the teleported node is restored/removed rather than orphaned under `body`. The\n * move is idempotent (guarded by the placeholder) and reversed on `disconnect()` (Turbo\n * navigation included). The \"in-page move vs real detach\" split on `disconnect()` is\n * {@link DetachGate}; in the `content` form the source element may even leave a\n * scoped application's observed root and the content is still restored, while the\n * no-`content` form teleporting itself out of the observed root is fire-and-forget\n * by design (see `disconnect()`).\n */\nexport class PortalController extends Controller<HTMLElement> {\n  static override targets = [\"content\"];\n  static override values = {\n    to: { type: String, default: \"body\" },\n    position: { type: String, default: \"append\" },\n    restore: { type: Boolean, default: true },\n  };\n  static events = [\"mount\", \"unmount\"] as const;\n\n  declare readonly contentTarget: HTMLElement;\n  declare readonly hasContentTarget: boolean;\n\n  declare toValue: string;\n  declare positionValue: string;\n  declare restoreValue: boolean;\n\n  /** Decides whether a `disconnect()` is an in-page move or a real detach. */\n  readonly #gate = new DetachGate();\n\n  override connect(): void {\n    // A reconnect proves an in-page move of the source element: disarm the\n    // probe the mid-move disconnect() deferred (see disconnect).\n    this.#gate.cancel();\n    if (portalState.has(this.element)) return; // already portaled here (idempotent)\n    const node = this.hasContentTarget ? this.contentTarget : this.element;\n    const destination = this.#destination();\n    if (!destination || destination === node || node.contains(destination)) return;\n\n    const placeholder = document.createComment(\"stimeo--portal\");\n    node.parentNode?.insertBefore(placeholder, node);\n    portalState.set(this.element, { node, placeholder });\n\n    if (this.positionValue === \"prepend\") {\n      destination.prepend(node);\n    } else {\n      destination.appendChild(node);\n    }\n    node.setAttribute(\"data-portaled\", \"true\");\n    this.dispatch(\"mount\", { detail: { target: destination } });\n  }\n\n  override disconnect(): void {\n    const state = portalState.get(this.element);\n    if (!state) return;\n    if (state.node === this.element) {\n      // No-`content` form: the teleported node IS the controller element, so the\n      // teleport itself may exit a scoped application's observed root — the controller\n      // doing its job, not a detach. A probe-driven restore would re-enter the root,\n      // reconnect, re-teleport and disconnect again, forever. So an ambiguous\n      // disconnect (in the document, identifier still listed — also the churn a\n      // self-move emits in some runtimes) KEEPS the teleport, and only a definite\n      // detach — the element left the DOM, or `data-controller` no longer lists us\n      // (a Turbo 8 morph) — restores. The cost, by design: a teleport that left the\n      // observed root is fire-and-forget (Stimulus never fires for it again).\n      if (!DetachGate.isDetached(this)) return;\n      this.#restore(state);\n      return;\n    }\n    // `content` form: the controller element stays put, so its own teleport emits no\n    // churn — an ambiguous disconnect means the SOURCE element moved. In-page, the\n    // same-batch reconnect cancels the probe and the teleport survives; out of the\n    // observed root, no reconnect comes and the probe restores, so the content is\n    // never stranded at the destination with a dead owner.\n    this.#gate.disconnected(this, () => {\n      const current = portalState.get(this.element);\n      if (current) this.#restore(current);\n    });\n  }\n\n  /** Returns the node to its placeholder (or removes it) and clears the bookkeeping. */\n  #restore(state: { node: HTMLElement; placeholder: Comment }): void {\n    portalState.delete(this.element);\n    const { node, placeholder } = state;\n\n    node.removeAttribute(\"data-portaled\");\n    if (this.restoreValue && placeholder.parentNode) {\n      placeholder.parentNode.insertBefore(node, placeholder);\n    } else {\n      node.remove();\n    }\n    placeholder.remove();\n    this.dispatch(\"unmount\", { detail: {} });\n  }\n\n  /** Resolves the destination for `to`, tolerating an invalid selector. */\n  #destination(): Element | null {\n    const selector = this.toValue.trim();\n    if (!selector) return null;\n    try {\n      return document.querySelector(selector);\n    } catch {\n      return null;\n    }\n  }\n}\n"]}

package/dist/controllers/preview_guard_controller.d.ts

@@ -18,6 +18,8 @@ import { Controller } from '@hotwired/stimulus';
  * `placeholder`. The element carries `data-preview-hidden` and emits `hide`; when the
  * preview clears it is restored and `show` fires.
  *
+ * `hide` and `show` dispatch `{}`.
+ *
  * @remarks
  * Behavior only — restoring the *fresh* value is the normal render's job, not this
  * controller's (it just un-hides what was there). State is derived from the DOM (no

package/dist/controllers/preview_guard_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/controllers/preview_guard_controller.ts"],"names":[],"mappings":";;;AA2BO,IAAM,sBAAA,GAAN,cAAqC,UAAA,CAAwB;AAAA,EAClE,OAAgB,MAAA,GAAS;AAAA,IACvB,WAAA,EAAa,EAAE,IAAA,EAAM,MAAA,EAAQ,SAAS,EAAA,EAAG;AAAA,IACzC,IAAA,EAAM,EAAE,IAAA,EAAM,MAAA,EAAQ,SAAS,MAAA;AAAO,GACxC;AAAA,EACA,OAAO,MAAA,GAAS,CAAC,MAAA,EAAQ,MAAM,CAAA;AAAA,EAK/B,SAAA,GAAqC,IAAA;AAAA,EACrC,OAAA,GAAU,KAAA;AAAA;AAAA,EAEV,gBAAA,GAAmB,EAAA;AAAA;AAAA,EAEnB,UAAA,GAA4B,IAAA;AAAA,EAEnB,OAAA,GAAgB;AACvB,IAAA,IAAI,OAAO,qBAAqB,WAAA,EAAa;AAC3C,MAAA,IAAA,CAAK,YAAY,IAAI,gBAAA,CAAiB,MAAM,IAAA,CAAK,OAAO,CAAA;AACxD,MAAA,IAAA,CAAK,SAAA,CAAU,OAAA,CAAQ,QAAA,CAAS,eAAA,EAAiB;AAAA,QAC/C,UAAA,EAAY,IAAA;AAAA,QACZ,eAAA,EAAiB,CAAC,oBAAoB;AAAA,OACvC,CAAA;AAAA,IACH;AAEA,IAAA,IAAA,CAAK,KAAA,EAAM;AAAA,EACb;AAAA,EAES,UAAA,GAAmB;AAC1B,IAAA,IAAA,CAAK,WAAW,UAAA,EAAW;AAC3B,IAAA,IAAA,CAAK,SAAA,GAAY,IAAA;AACjB,IAAA,IAAA,CAAK,QAAA,EAAS;AAAA,EAChB;AAAA;AAAA,EAGA,KAAA,GAAc;AACZ,IAAA,MAAM,UAAA,GAAa,QAAA,CAAS,eAAA,CAAgB,YAAA,CAAa,oBAAoB,CAAA;AAC7E,IAAA,IAAI,UAAA,IAAc,CAAC,IAAA,CAAK,OAAA,OAAc,KAAA,EAAM;AAAA,SAAA,IACnC,CAAC,UAAA,IAAc,IAAA,CAAK,OAAA,OAAc,KAAA,EAAM;AAAA,EACnD;AAAA,EAEA,KAAA,GAAc;AACZ,IAAA,IAAA,CAAK,OAAA,GAAU,IAAA;AACf,IAAA,IAAI,IAAA,CAAK,cAAc,aAAA,EAAe;AACpC,MAAA,IAAA,CAAK,UAAA,GAAa,KAAK,OAAA,CAAQ,WAAA;AAC/B,MAAA,IAAA,CAAK,OAAA,CAAQ,cAAc,IAAA,CAAK,gBAAA;AAAA,IAClC,CAAA,MAAO;AACL,MAAA,IAAA,CAAK,gBAAA,GAAmB,IAAA,CAAK,OAAA,CAAQ,KAAA,CAAM,UAAA;AAC3C,MAAA,IAAA,CAAK,OAAA,CAAQ,MAAM,UAAA,GAAa,QAAA;AAAA,IAClC;AACA,IAAA,IAAA,CAAK,OAAA,CAAQ,YAAA,CAAa,qBAAA,EAAuB,MAAM,CAAA;AACvD,IAAA,IAAA,CAAK,SAAS,MAAA,EAAQ,EAAE,MAAA,EAAQ,IAAI,CAAA;AAAA,EACtC;AAAA,EAEA,KAAA,GAAc;AACZ,IAAA,IAAA,CAAK,QAAA,EAAS;AACd,IAAA,IAAA,CAAK,SAAS,MAAA,EAAQ,EAAE,MAAA,EAAQ,IAAI,CAAA;AAAA,EACtC;AAAA;AAAA,EAGA,QAAA,GAAiB;AACf,IAAA,IAAI,CAAC,KAAK,OAAA,EAAS;AACnB,IAAA,IAAA,CAAK,OAAA,GAAU,KAAA;AACf,IAAA,IAAI,IAAA,CAAK,eAAe,IAAA,EAAM;AAC5B,MAAA,IAAA,CAAK,OAAA,CAAQ,cAAc,IAAA,CAAK,UAAA;AAChC,MAAA,IAAA,CAAK,UAAA,GAAa,IAAA;AAAA,IACpB,CAAA,MAAO;AACL,MAAA,IAAA,CAAK,OAAA,CAAQ,KAAA,CAAM,UAAA,GAAa,IAAA,CAAK,gBAAA;AAAA,IACvC;AACA,IAAA,IAAA,CAAK,OAAA,CAAQ,gBAAgB,qBAAqB,CAAA;AAAA,EACpD;AACF","file":"preview_guard_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\n\n/**\n * Headless **preview guard** (Hotwire-specific): hides or placeholders a volatile element\n * — a balance, a notification count, a live timestamp — *only while Turbo is showing a\n * preview* (`html[data-turbo-preview]`), so a stale cached snapshot does not briefly flash\n * the old value on a back/restore visit. No APG pattern; it keeps displayed information\n * accurate and never moves focus.\n *\n * Markup contract (identifier: `stimeo--preview-guard`):\n *   <span data-controller=\"stimeo--preview-guard\"\n *         data-stimeo--preview-guard-mode-value=\"placeholder\"\n *         data-stimeo--preview-guard-placeholder-value=\"—\">¥123,456</span>\n *\n * Watches `<html>` for the `data-turbo-preview` attribute with a `MutationObserver`.\n * While it is present the element is guarded: `mode=\"hide\"` makes it `visibility: hidden`\n * (its box is kept, so nothing shifts), `mode=\"placeholder\"` swaps its text for\n * `placeholder`. The element carries `data-preview-hidden` and emits `hide`; when the\n * preview clears it is restored and `show` fires.\n *\n * @remarks\n * Behavior only — restoring the *fresh* value is the normal render's job, not this\n * controller's (it just un-hides what was there). State is derived from the DOM (no\n * module-scope state) and the original value is saved on hide and put back on show, so a\n * guard that connects mid-preview hides immediately and a `disconnect()` (Turbo navigation\n * included) restores the element and severs the observer. Focus is never moved.\n */\nexport class PreviewGuardController extends Controller<HTMLElement> {\n  static override values = {\n    placeholder: { type: String, default: \"\" },\n    mode: { type: String, default: \"hide\" },\n  };\n  static events = [\"hide\", \"show\"] as const;\n\n  declare placeholderValue: string;\n  declare modeValue: string;\n\n  #observer: MutationObserver | null = null;\n  #hidden = false;\n  /** Saved inline visibility (hide mode), restored on show. */\n  #savedVisibility = \"\";\n  /** Saved text (placeholder mode); non-null marks that text — not visibility — was swapped. */\n  #savedText: string | null = null;\n\n  override connect(): void {\n    if (typeof MutationObserver !== \"undefined\") {\n      this.#observer = new MutationObserver(() => this.#sync());\n      this.#observer.observe(document.documentElement, {\n        attributes: true,\n        attributeFilter: [\"data-turbo-preview\"],\n      });\n    }\n    // Sync once in case we connect while a preview is already on screen.\n    this.#sync();\n  }\n\n  override disconnect(): void {\n    this.#observer?.disconnect();\n    this.#observer = null;\n    this.#restore(); // never leave the element guarded after teardown\n  }\n\n  /** Reflects the current `data-turbo-preview` state onto the element. */\n  #sync(): void {\n    const previewing = document.documentElement.hasAttribute(\"data-turbo-preview\");\n    if (previewing && !this.#hidden) this.#hide();\n    else if (!previewing && this.#hidden) this.#show();\n  }\n\n  #hide(): void {\n    this.#hidden = true;\n    if (this.modeValue === \"placeholder\") {\n      this.#savedText = this.element.textContent;\n      this.element.textContent = this.placeholderValue;\n    } else {\n      this.#savedVisibility = this.element.style.visibility;\n      this.element.style.visibility = \"hidden\";\n    }\n    this.element.setAttribute(\"data-preview-hidden\", \"true\");\n    this.dispatch(\"hide\", { detail: {} });\n  }\n\n  #show(): void {\n    this.#restore();\n    this.dispatch(\"show\", { detail: {} });\n  }\n\n  /** Reverts the guard. Safe to call when not hidden (no-op) — used by show and teardown. */\n  #restore(): void {\n    if (!this.#hidden) return;\n    this.#hidden = false;\n    if (this.#savedText !== null) {\n      this.element.textContent = this.#savedText;\n      this.#savedText = null;\n    } else {\n      this.element.style.visibility = this.#savedVisibility;\n    }\n    this.element.removeAttribute(\"data-preview-hidden\");\n  }\n}\n"]}
+{"version":3,"sources":["../../src/controllers/preview_guard_controller.ts"],"names":[],"mappings":"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","file":"preview_guard_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\n\n/**\n * Headless **preview guard** (Hotwire-specific): hides or placeholders a volatile element\n * — a balance, a notification count, a live timestamp — *only while Turbo is showing a\n * preview* (`html[data-turbo-preview]`), so a stale cached snapshot does not briefly flash\n * the old value on a back/restore visit. No APG pattern; it keeps displayed information\n * accurate and never moves focus.\n *\n * Markup contract (identifier: `stimeo--preview-guard`):\n *   <span data-controller=\"stimeo--preview-guard\"\n *         data-stimeo--preview-guard-mode-value=\"placeholder\"\n *         data-stimeo--preview-guard-placeholder-value=\"—\">¥123,456</span>\n *\n * Watches `<html>` for the `data-turbo-preview` attribute with a `MutationObserver`.\n * While it is present the element is guarded: `mode=\"hide\"` makes it `visibility: hidden`\n * (its box is kept, so nothing shifts), `mode=\"placeholder\"` swaps its text for\n * `placeholder`. The element carries `data-preview-hidden` and emits `hide`; when the\n * preview clears it is restored and `show` fires.\n *\n * `hide` and `show` dispatch `{}`.\n *\n * @remarks\n * Behavior only — restoring the *fresh* value is the normal render's job, not this\n * controller's (it just un-hides what was there). State is derived from the DOM (no\n * module-scope state) and the original value is saved on hide and put back on show, so a\n * guard that connects mid-preview hides immediately and a `disconnect()` (Turbo navigation\n * included) restores the element and severs the observer. Focus is never moved.\n */\nexport class PreviewGuardController extends Controller<HTMLElement> {\n  static override values = {\n    placeholder: { type: String, default: \"\" },\n    mode: { type: String, default: \"hide\" },\n  };\n  static events = [\"hide\", \"show\"] as const;\n\n  declare placeholderValue: string;\n  declare modeValue: string;\n\n  #observer: MutationObserver | null = null;\n  #hidden = false;\n  /** Saved inline visibility (hide mode), restored on show. */\n  #savedVisibility = \"\";\n  /** Saved text (placeholder mode); non-null marks that text — not visibility — was swapped. */\n  #savedText: string | null = null;\n\n  override connect(): void {\n    if (typeof MutationObserver !== \"undefined\") {\n      this.#observer = new MutationObserver(() => this.#sync());\n      this.#observer.observe(document.documentElement, {\n        attributes: true,\n        attributeFilter: [\"data-turbo-preview\"],\n      });\n    }\n    // Sync once in case we connect while a preview is already on screen.\n    this.#sync();\n  }\n\n  override disconnect(): void {\n    this.#observer?.disconnect();\n    this.#observer = null;\n    this.#restore(); // never leave the element guarded after teardown\n  }\n\n  /** Reflects the current `data-turbo-preview` state onto the element. */\n  #sync(): void {\n    const previewing = document.documentElement.hasAttribute(\"data-turbo-preview\");\n    if (previewing && !this.#hidden) this.#hide();\n    else if (!previewing && this.#hidden) this.#show();\n  }\n\n  #hide(): void {\n    this.#hidden = true;\n    if (this.modeValue === \"placeholder\") {\n      this.#savedText = this.element.textContent;\n      this.element.textContent = this.placeholderValue;\n    } else {\n      this.#savedVisibility = this.element.style.visibility;\n      this.element.style.visibility = \"hidden\";\n    }\n    this.element.setAttribute(\"data-preview-hidden\", \"true\");\n    this.dispatch(\"hide\", { detail: {} });\n  }\n\n  #show(): void {\n    this.#restore();\n    this.dispatch(\"show\", { detail: {} });\n  }\n\n  /** Reverts the guard. Safe to call when not hidden (no-op) — used by show and teardown. */\n  #restore(): void {\n    if (!this.#hidden) return;\n    this.#hidden = false;\n    if (this.#savedText !== null) {\n      this.element.textContent = this.#savedText;\n      this.#savedText = null;\n    } else {\n      this.element.style.visibility = this.#savedVisibility;\n    }\n    this.element.removeAttribute(\"data-preview-hidden\");\n  }\n}\n"]}

package/dist/controllers/progress_controller.d.ts

@@ -31,6 +31,9 @@ type SetValueEvent = Event & {
  * the bar's width/animation is the consumer's, driven off the
  * `--stimeo--progress-ratio` (0–1) custom property and `data-state`.
  *
+ * `change` dispatches `{ value: number, ratio: number }`; `complete` dispatches
+ * `{ value: number }`.
+ *
  * @remarks
  * Behavior only — no styling is emitted. An indeterminate bar drops
  * `aria-valuenow` (per ARIA) so assistive tech announces "busy" rather than a

package/dist/controllers/progress_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/announce.ts","../../src/utils/coerce.ts","../../src/utils/microtask_coalescer.ts","../../src/utils/range.ts","../../src/controllers/progress_controller.ts"],"names":[],"mappings":"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","file":"progress_controller.js","sourcesContent":["/**\n * Sends one message to the page's shared `stimeo--announcer`.\n *\n * A component that has to reach assistive tech does not carry a live region of its\n * own: a region only announces what changes *after* assistive tech already knows\n * about it, which a region that appears (or is un-hidden) with its message cannot\n * satisfy. The one region that can is the announcer sitting in the page from the\n * start, so state changes are handed to it as an event and it does the reading.\n *\n * The event goes to `window` because the announcer is usually a sibling high in the\n * document rather than an ancestor of the component dispatching it.\n *\n * Wording comes from the consumer — the library ships no English strings — so an\n * empty message is silently dropped and nothing is announced.\n *\n * @example\n * ```ts\n * announce(this.announceTextValue, { assertive: false });\n * ```\n */\nexport function announce(message: string, options: { assertive?: boolean } = {}): void {\n  const text = message.trim();\n  if (text.length === 0) return;\n  window.dispatchEvent(\n    new CustomEvent(\"stimeo--announcer:announce\", {\n      detail: { message: text, assertive: options.assertive === true },\n    }),\n  );\n}\n\n/**\n * Fills `{name}` placeholders in an announcement template from `values`.\n *\n * The same substitution the value-text templates use, so a consumer writes\n * `\"{percent}% complete\"` in one attribute and gets the same rules everywhere. A\n * placeholder with no matching entry is left as authored rather than blanked, which\n * keeps a typo visible instead of silently swallowing the word.\n */\nexport function fillTemplate(template: string, values: Record<string, string | number>): string {\n  return template.replace(/\\{([a-zA-Z][a-zA-Z0-9]*)\\}/g, (match, name: string) => {\n    const replacement = values[name];\n    return replacement === undefined ? match : String(replacement);\n  });\n}\n","/**\n * Numeric coercion shared by the value-bearing controllers (progress, meter,\n * color-picker).\n *\n * Stimulus already coerces numeric action params to numbers, but a value can also\n * arrive as a string — via a `*:set` CustomEvent `detail`, or an action param\n * whose attribute does not look numeric. Centralizing the parse keeps `setValue`\n * tolerant of either form while rejecting anything that is not a finite number.\n */\n\n/**\n * Coerces `raw` to a finite number, or returns `null` when it is absent, empty,\n * or not parseable. Empty strings are treated as \"no value\" rather than `0`, so a\n * stray blank param cannot silently reset the value.\n */\nexport function toFiniteNumber(raw: number | string | null | undefined): number | null {\n  if (raw === null || raw === undefined || raw === \"\") return null;\n  const value = typeof raw === \"number\" ? raw : Number(raw);\n  return Number.isFinite(value) ? value : null;\n}\n","/**\n * Collapses many Stimulus lifecycle callbacks from one DOM mutation into a\n * single pass.\n *\n * Stimulus fires `<name>TargetConnected` / `Disconnected` once per element and\n * `<name>ValueChanged` once per changed attribute. Replacing a list of N options\n * or morphing several render Values therefore delivers N callbacks — but the\n * useful unit of work is \"reconcile against the resulting declarative input\",\n * once, after the batch has settled. Every controller with reconcilable targets\n * or render Values needs the same shape: a `queued` flag plus `queueMicrotask`.\n *\n * **A microtask is the right horizon, and the reason is specific.** Stimulus\n * drives these callbacks from a `MutationObserver`, whose own callback already\n * runs as a microtask with the whole batch in hand; scheduling one more lands\n * after the last sibling callback of that batch and still before paint or any\n * event handler. A timer would be later than it needs to be, and reconciling\n * synchronously would run once per element against a half-applied DOM.\n *\n * **The two guards are not the same guard.** Scheduling is refused before the\n * controller connects, and running is refused after it disconnects:\n *\n * - **Before `connect()`** — Stimulus delivers initial target and Value callbacks\n *   ahead of `connect()`. Reconciling there would compute output against a\n *   controller whose own state has not been initialised, and `connect()` is\n *   about to do a full pass anyway.\n * - **After `disconnect()`** — Stimulus fires a callback for **every** target\n *   during teardown, and a microtask queued just before it would otherwise run\n *   against a detached tree. {@link MicrotaskCoalescer.cancel} exists for the\n *   teardown path to drop the pending pass outright.\n *\n * Both guards are part of one contract here rather than something each consumer\n * has to remember separately.\n *\n * Scope is the scheduling only. *What* to reconcile — keep the surviving active\n * option, fall back to the next / previous / first visible one, rebuild derived\n * chips or hidden fields — stays in the controller, because no two consumers\n * answer it the same way.\n *\n * This file's own doc block is dropped from `dist`, but every member comment is\n * inlined into each consumer entry (`tsup` builds with `splitting: false`), so\n * rationale belongs here and only the contract belongs on the members.\n *\n * @example\n * ```ts\n * readonly #reconcile = new MicrotaskCoalescer(() => this.#reconcileOptions());\n *\n * connect()    { this.#reconcile.activate(); }\n * disconnect() { this.#reconcile.cancel(); }\n *\n * optionTargetConnected()    { this.#reconcile.schedule(); }\n * optionTargetDisconnected() { this.#reconcile.schedule(); }\n * ```\n */\nexport class MicrotaskCoalescer {\n  readonly #run: () => void;\n  #queued = false;\n  #active = false;\n  #generation = 0;\n\n  /** @param run - the single reconciliation pass, invoked at most once per batch. */\n  constructor(run: () => void) {\n    this.#run = run;\n  }\n\n  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */\n  activate(): void {\n    this.#active = true;\n  }\n\n  /** Closes the window and drops any pending pass; call from `disconnect()`. */\n  cancel(): void {\n    this.#active = false;\n    this.#queued = false;\n    this.#generation += 1;\n  }\n\n  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */\n  schedule(): void {\n    if (!this.#active || this.#queued) return;\n    this.#queued = true;\n    const generation = this.#generation;\n    queueMicrotask(() => {\n      // A cancelled callback must not consume a pass queued after reconnect.\n      if (generation !== this.#generation || !this.#queued || !this.#active) return;\n      this.#queued = false;\n      this.#run();\n    });\n  }\n}\n","/**\n * Range normalization shared by the value-bearing controllers (progress, meter,\n * slider, range-slider).\n *\n * Each of them publishes \"where the value sits inside `[min, max]`\" as a CSS\n * custom property the consumer multiplies a track by, and each has to answer the\n * same degenerate cases: empty and inverted ranges cannot express progress, and\n * malformed Number Values can produce `NaN`. Keeping the rule in one place is\n * what makes those answers identical across the four.\n */\n\n/**\n * Fraction of `[min, max]` that `value` occupies, always within `[0, 1]`.\n *\n * `value` is clamped into the range first, so a value outside it reports a full\n * or empty track rather than pushing the fraction past the ends.\n *\n * An empty, inverted, or non-numeric range yields `0`. That is a deliberate\n * floor rather than a computed result: `min === max` would produce `NaN`, and\n * `min > max` would report a full track for a value that is really out of range.\n * Non-finite results are floored for the same reason. These results reach\n * assistive tech, because the same fraction drives the percentage substituted\n * into `aria-valuetext`.\n */\nexport function rangeFraction(value: number, min: number, max: number): number {\n  const span = max - min;\n  if (!(span > 0)) return 0;\n\n  const clamped = Math.min(max, Math.max(min, value));\n  let fraction: number;\n  if (Number.isFinite(span)) {\n    fraction = (clamped - min) / span;\n  } else {\n    // Scaling preserves the ratio when two finite endpoints straddle zero so\n    // widely that their subtraction overflows to Infinity.\n    const scale = Math.max(Math.abs(min), Math.abs(max));\n    fraction = (clamped / scale - min / scale) / (max / scale - min / scale);\n  }\n\n  if (!Number.isFinite(fraction)) return 0;\n  return Math.min(1, Math.max(0, fraction));\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { announce, fillTemplate } from \"../utils/announce\";\nimport { toFiniteNumber } from \"../utils/coerce\";\nimport { MicrotaskCoalescer } from \"../utils/microtask_coalescer\";\nimport { rangeFraction } from \"../utils/range\";\n\n/**\n * Event shape `setValue` accepts: an action param `amount` or a `detail.value`.\n * Both are typed `number | string` because, while Stimulus coerces numeric action\n * params to numbers, a `progress:set` CustomEvent (or a non-numeric-looking param)\n * may carry a string; {@link ProgressController.setValue} normalizes either form.\n */\ntype SetValueEvent = Event & {\n  params?: { amount?: number | string };\n  detail?: { value?: number | string };\n};\n\n/**\n * Marks an `aria-valuetext` this controller wrote, so a render takes back only\n * its own text. `aria-valuetext` is shared: a consumer may author it instead of\n * supplying a template, and that text is theirs to keep across renders.\n */\nconst OWNED_VALUE_TEXT = \"data-stimeo--progress-owns-valuetext\";\n\n/**\n * Headless progress-bar behavior backed by the WAI-ARIA `progressbar` role.\n *\n * Markup contract (identifier: `stimeo--progress`):\n *   <div data-controller=\"stimeo--progress\" role=\"progressbar\"\n *        aria-label=\"Upload\" aria-valuemin=\"0\" aria-valuemax=\"100\" aria-valuenow=\"0\"\n *        data-stimeo--progress-value-value=\"0\"\n *        data-action=\"progress:set->stimeo--progress#setValue\">\n *     <div data-stimeo--progress-target=\"bar\"></div>\n *   </div>\n *\n * This is the *progress over time* role (a task advancing toward completion),\n * deliberately distinct from {@link MeterController}'s point-in-time `meter`. The\n * controller owns value normalization and ARIA value-attribute synchronization;\n * the bar's width/animation is the consumer's, driven off the\n * `--stimeo--progress-ratio` (0–1) custom property and `data-state`.\n *\n * @remarks\n * Behavior only — no styling is emitted. An indeterminate bar drops\n * `aria-valuenow` (per ARIA) so assistive tech announces \"busy\" rather than a\n * stale value; the consumer animates the indeterminate look off\n * `data-state=\"indeterminate\"`.\n */\nexport class ProgressController extends Controller<HTMLElement> {\n  static override targets = [\"bar\"];\n  static override values = {\n    value: { type: Number, default: 0 },\n    min: { type: Number, default: 0 },\n    max: { type: Number, default: 100 },\n    indeterminate: { type: Boolean, default: false },\n    valueText: { type: String, default: \"\" },\n    announceText: { type: String, default: \"\" },\n  };\n  static actions = [\"setValue\"] as const;\n  static events = [\"change\", \"complete\"] as const;\n\n  declare readonly barTarget: HTMLElement;\n  declare readonly hasBarTarget: boolean;\n\n  declare valueValue: number;\n  declare minValue: number;\n  declare maxValue: number;\n  declare indeterminateValue: boolean;\n  declare valueTextValue: string;\n  declare announceTextValue: string;\n\n  /**\n   * Collapses a morph that swaps several render inputs at once into one repaint.\n   * A single update usually rewrites the whole set, and each Value would otherwise\n   * repaint on its own.\n   */\n  readonly #repaint = new MicrotaskCoalescer(() => {\n    this.#render();\n  });\n\n  override connect(): void {\n    this.#repaint.activate();\n    this.#render();\n  }\n\n  /** Closes the window in which a queued repaint may still run. */\n  override disconnect(): void {\n    this.#repaint.cancel();\n  }\n\n  /**\n   * Updates the progress value from an action param (`amount`) or a\n   * `detail.value` CustomEvent, normalizes it into range, syncs ARIA, and\n   * dispatches `change` (always) plus `complete` when `max` is reached.\n   */\n  setValue(event: SetValueEvent): void {\n    const next = toFiniteNumber(event.params?.amount ?? event.detail?.value);\n    if (next === null) return;\n    const value = this.#clamp(next);\n    this.valueValue = value;\n    this.indeterminateValue = false;\n    this.#render();\n    this.dispatch(\"change\", { detail: { value, ratio: this.#ratio } });\n    if (value >= this.maxValue) {\n      this.dispatch(\"complete\", { detail: { value } });\n      // Reaching the end is the transition worth reading out; the running numbers in\n      // between are state the consumer can see, not news.\n      announce(\n        fillTemplate(this.announceTextValue, { value, percent: Math.round(this.#ratio * 100) }),\n      );\n    }\n  }\n\n  /** Repaints when application code (or a Turbo morph) changes `indeterminate` at runtime. */\n  indeterminateValueChanged(): void {\n    this.#repaint.schedule();\n  }\n\n  /** Repaints when application code (or a Turbo morph) changes `value` at runtime. */\n  valueValueChanged(): void {\n    this.#repaint.schedule();\n  }\n\n  /** Repaints when application code (or a Turbo morph) changes `min` at runtime. */\n  minValueChanged(): void {\n    this.#repaint.schedule();\n  }\n\n  /** Repaints when application code (or a Turbo morph) changes `max` at runtime. */\n  maxValueChanged(): void {\n    this.#repaint.schedule();\n  }\n\n  /** Repaints when application code (or a Turbo morph) changes `valueText` at runtime. */\n  valueTextValueChanged(): void {\n    this.#repaint.schedule();\n  }\n\n  /** Clamps `raw` into the configured `[min, max]` range. */\n  #clamp(raw: number): number {\n    return Math.min(this.maxValue, Math.max(this.minValue, raw));\n  }\n\n  /** Current fraction of the range in `[0, 1]`; `0` when the range is empty. */\n  get #ratio(): number {\n    return rangeFraction(this.valueValue, this.minValue, this.maxValue);\n  }\n\n  /**\n   * Reflects value/range/indeterminate onto ARIA, `data-state`, and the ratio.\n   *\n   * @stimeoRenderRoot\n   */\n  #render(): void {\n    this.element.setAttribute(\"aria-valuemin\", String(this.minValue));\n    this.element.setAttribute(\"aria-valuemax\", String(this.maxValue));\n\n    if (this.indeterminateValue) {\n      this.element.removeAttribute(\"aria-valuenow\");\n      // `aria-valuetext` outranks `aria-valuenow` for assistive tech, so a text\n      // this controller derived from a value would announce the very number the\n      // indeterminate state drops.\n      this.#clearOwnValueText();\n      this.element.style.removeProperty(\"--stimeo--progress-ratio\");\n      this.element.setAttribute(\"data-state\", \"indeterminate\");\n      return;\n    }\n\n    const value = this.#clamp(this.valueValue);\n    this.element.setAttribute(\"aria-valuenow\", String(value));\n    this.element.style.setProperty(\"--stimeo--progress-ratio\", String(this.#ratio));\n    this.element.setAttribute(\"data-state\", \"determinate\");\n    this.#applyValueText(value);\n  }\n\n  /**\n   * Sets `aria-valuetext` from the consumer-provided template, substituting\n   * `{value}` and `{percent}`. Left to the consumer so the human-readable text\n   * stays i18n-neutral in the library. With no template the attribute belongs to\n   * the consumer, so only a text this controller wrote is taken back\n   * ({@link OWNED_VALUE_TEXT}).\n   */\n  #applyValueText(value: number): void {\n    if (this.valueTextValue.length === 0) {\n      this.#clearOwnValueText();\n      return;\n    }\n    const percent = Math.round(this.#ratio * 100);\n    const text = this.valueTextValue\n      .replaceAll(\"{value}\", String(value))\n      .replaceAll(\"{percent}\", String(percent));\n    this.element.setAttribute(\"aria-valuetext\", text);\n    this.element.setAttribute(OWNED_VALUE_TEXT, \"\");\n  }\n\n  /** Removes `aria-valuetext` only when this controller is the one that wrote it. */\n  #clearOwnValueText(): void {\n    if (!this.element.hasAttribute(OWNED_VALUE_TEXT)) return;\n    this.element.removeAttribute(\"aria-valuetext\");\n    this.element.removeAttribute(OWNED_VALUE_TEXT);\n  }\n}\n"]}
+{"version":3,"sources":["../../src/utils/announce.ts","../../src/utils/coerce.ts","../../src/utils/microtask_coalescer.ts","../../src/utils/range.ts","../../src/controllers/progress_controller.ts"],"names":[],"mappings":"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","file":"progress_controller.js","sourcesContent":["/**\n * Sends one message to the page's shared `stimeo--announcer`.\n *\n * A component that has to reach assistive tech does not carry a live region of its\n * own: a region only announces what changes *after* assistive tech already knows\n * about it, which a region that appears (or is un-hidden) with its message cannot\n * satisfy. The one region that can is the announcer sitting in the page from the\n * start, so state changes are handed to it as an event and it does the reading.\n *\n * The event goes to `window` because the announcer is usually a sibling high in the\n * document rather than an ancestor of the component dispatching it.\n *\n * Wording comes from the consumer — the library ships no English strings — so an\n * empty message is silently dropped and nothing is announced.\n *\n * @example\n * ```ts\n * announce(this.announceTextValue, { assertive: false });\n * ```\n */\nexport function announce(message: string, options: { assertive?: boolean } = {}): void {\n  const text = message.trim();\n  if (text.length === 0) return;\n  window.dispatchEvent(\n    new CustomEvent(\"stimeo--announcer:announce\", {\n      detail: { message: text, assertive: options.assertive === true },\n    }),\n  );\n}\n\n/**\n * Fills `{name}` placeholders in an announcement template from `values`.\n *\n * The same substitution the value-text templates use, so a consumer writes\n * `\"{percent}% complete\"` in one attribute and gets the same rules everywhere. A\n * placeholder with no matching entry is left as authored rather than blanked, which\n * keeps a typo visible instead of silently swallowing the word.\n */\nexport function fillTemplate(template: string, values: Record<string, string | number>): string {\n  return template.replace(/\\{([a-zA-Z][a-zA-Z0-9]*)\\}/g, (match, name: string) => {\n    const replacement = values[name];\n    return replacement === undefined ? match : String(replacement);\n  });\n}\n","/**\n * Numeric coercion shared by the value-bearing controllers (progress, meter,\n * color-picker).\n *\n * Stimulus already coerces numeric action params to numbers, but a value can also\n * arrive as a string — via a `*:set` CustomEvent `detail`, or an action param\n * whose attribute does not look numeric. Centralizing the parse keeps `setValue`\n * tolerant of either form while rejecting anything that is not a finite number.\n */\n\n/**\n * Coerces `raw` to a finite number, or returns `null` when it is absent, empty,\n * or not parseable. Empty strings are treated as \"no value\" rather than `0`, so a\n * stray blank param cannot silently reset the value.\n */\nexport function toFiniteNumber(raw: number | string | null | undefined): number | null {\n  if (raw === null || raw === undefined || raw === \"\") return null;\n  const value = typeof raw === \"number\" ? raw : Number(raw);\n  return Number.isFinite(value) ? value : null;\n}\n","/**\n * Collapses many Stimulus lifecycle callbacks from one DOM mutation into a\n * single pass.\n *\n * Stimulus fires `<name>TargetConnected` / `Disconnected` once per element and\n * `<name>ValueChanged` once per changed attribute. Replacing a list of N options\n * or morphing several render Values therefore delivers N callbacks — but the\n * useful unit of work is \"reconcile against the resulting declarative input\",\n * once, after the batch has settled. Every controller with reconcilable targets\n * or render Values needs the same shape: a `queued` flag plus `queueMicrotask`.\n *\n * **A microtask is the right horizon, and the reason is specific.** Stimulus\n * drives these callbacks from a `MutationObserver`, whose own callback already\n * runs as a microtask with the whole batch in hand; scheduling one more lands\n * after the last sibling callback of that batch and still before paint or any\n * event handler. A timer would be later than it needs to be, and reconciling\n * synchronously would run once per element against a half-applied DOM.\n *\n * **The two guards are not the same guard.** Scheduling is refused before the\n * controller connects, and running is refused after it disconnects:\n *\n * - **Before `connect()`** — Stimulus delivers initial target and Value callbacks\n *   ahead of `connect()`. Reconciling there would compute output against a\n *   controller whose own state has not been initialised, and `connect()` is\n *   about to do a full pass anyway.\n * - **After `disconnect()`** — Stimulus fires a callback for **every** target\n *   during teardown, and a microtask queued just before it would otherwise run\n *   against a detached tree. {@link MicrotaskCoalescer.cancel} exists for the\n *   teardown path to drop the pending pass outright.\n *\n * Both guards are part of one contract here rather than something each consumer\n * has to remember separately.\n *\n * Scope is the scheduling only. *What* to reconcile — keep the surviving active\n * option, fall back to the next / previous / first visible one, rebuild derived\n * chips or hidden fields — stays in the controller, because no two consumers\n * answer it the same way.\n *\n * This file's own doc block is dropped from `dist`, but every member comment is\n * inlined into each consumer entry (`tsup` builds with `splitting: false`), so\n * rationale belongs here and only the contract belongs on the members.\n *\n * @example\n * ```ts\n * readonly #reconcile = new MicrotaskCoalescer(() => this.#reconcileOptions());\n *\n * connect()    { this.#reconcile.activate(); }\n * disconnect() { this.#reconcile.cancel(); }\n *\n * optionTargetConnected()    { this.#reconcile.schedule(); }\n * optionTargetDisconnected() { this.#reconcile.schedule(); }\n * ```\n */\nexport class MicrotaskCoalescer {\n  readonly #run: () => void;\n  #queued = false;\n  #active = false;\n  #generation = 0;\n\n  /** @param run - the single reconciliation pass, invoked at most once per batch. */\n  constructor(run: () => void) {\n    this.#run = run;\n  }\n\n  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */\n  activate(): void {\n    this.#active = true;\n  }\n\n  /** Closes the window and drops any pending pass; call from `disconnect()`. */\n  cancel(): void {\n    this.#active = false;\n    this.#queued = false;\n    this.#generation += 1;\n  }\n\n  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */\n  schedule(): void {\n    if (!this.#active || this.#queued) return;\n    this.#queued = true;\n    const generation = this.#generation;\n    queueMicrotask(() => {\n      // A cancelled callback must not consume a pass queued after reconnect.\n      if (generation !== this.#generation || !this.#queued || !this.#active) return;\n      this.#queued = false;\n      this.#run();\n    });\n  }\n}\n","/**\n * Range normalization shared by the value-bearing controllers (progress, meter,\n * slider, range-slider).\n *\n * Each of them publishes \"where the value sits inside `[min, max]`\" as a CSS\n * custom property the consumer multiplies a track by, and each has to answer the\n * same degenerate cases: empty and inverted ranges cannot express progress, and\n * malformed Number Values can produce `NaN`. Keeping the rule in one place is\n * what makes those answers identical across the four.\n */\n\n/**\n * Fraction of `[min, max]` that `value` occupies, always within `[0, 1]`.\n *\n * `value` is clamped into the range first, so a value outside it reports a full\n * or empty track rather than pushing the fraction past the ends.\n *\n * An empty, inverted, or non-numeric range yields `0`. That is a deliberate\n * floor rather than a computed result: `min === max` would produce `NaN`, and\n * `min > max` would report a full track for a value that is really out of range.\n * Non-finite results are floored for the same reason. These results reach\n * assistive tech, because the same fraction drives the percentage substituted\n * into `aria-valuetext`.\n */\nexport function rangeFraction(value: number, min: number, max: number): number {\n  const span = max - min;\n  if (!(span > 0)) return 0;\n\n  const clamped = Math.min(max, Math.max(min, value));\n  let fraction: number;\n  if (Number.isFinite(span)) {\n    fraction = (clamped - min) / span;\n  } else {\n    // Scaling preserves the ratio when two finite endpoints straddle zero so\n    // widely that their subtraction overflows to Infinity.\n    const scale = Math.max(Math.abs(min), Math.abs(max));\n    fraction = (clamped / scale - min / scale) / (max / scale - min / scale);\n  }\n\n  if (!Number.isFinite(fraction)) return 0;\n  return Math.min(1, Math.max(0, fraction));\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { announce, fillTemplate } from \"../utils/announce\";\nimport { toFiniteNumber } from \"../utils/coerce\";\nimport { MicrotaskCoalescer } from \"../utils/microtask_coalescer\";\nimport { rangeFraction } from \"../utils/range\";\n\n/**\n * Event shape `setValue` accepts: an action param `amount` or a `detail.value`.\n * Both are typed `number | string` because, while Stimulus coerces numeric action\n * params to numbers, a `progress:set` CustomEvent (or a non-numeric-looking param)\n * may carry a string; {@link ProgressController.setValue} normalizes either form.\n */\ntype SetValueEvent = Event & {\n  params?: { amount?: number | string };\n  detail?: { value?: number | string };\n};\n\n/**\n * Marks an `aria-valuetext` this controller wrote, so a render takes back only\n * its own text. `aria-valuetext` is shared: a consumer may author it instead of\n * supplying a template, and that text is theirs to keep across renders.\n */\nconst OWNED_VALUE_TEXT = \"data-stimeo--progress-owns-valuetext\";\n\n/**\n * Headless progress-bar behavior backed by the WAI-ARIA `progressbar` role.\n *\n * Markup contract (identifier: `stimeo--progress`):\n *   <div data-controller=\"stimeo--progress\" role=\"progressbar\"\n *        aria-label=\"Upload\" aria-valuemin=\"0\" aria-valuemax=\"100\" aria-valuenow=\"0\"\n *        data-stimeo--progress-value-value=\"0\"\n *        data-action=\"progress:set->stimeo--progress#setValue\">\n *     <div data-stimeo--progress-target=\"bar\"></div>\n *   </div>\n *\n * This is the *progress over time* role (a task advancing toward completion),\n * deliberately distinct from {@link MeterController}'s point-in-time `meter`. The\n * controller owns value normalization and ARIA value-attribute synchronization;\n * the bar's width/animation is the consumer's, driven off the\n * `--stimeo--progress-ratio` (0–1) custom property and `data-state`.\n *\n * `change` dispatches `{ value: number, ratio: number }`; `complete` dispatches\n * `{ value: number }`.\n *\n * @remarks\n * Behavior only — no styling is emitted. An indeterminate bar drops\n * `aria-valuenow` (per ARIA) so assistive tech announces \"busy\" rather than a\n * stale value; the consumer animates the indeterminate look off\n * `data-state=\"indeterminate\"`.\n */\nexport class ProgressController extends Controller<HTMLElement> {\n  static override targets = [\"bar\"];\n  static override values = {\n    value: { type: Number, default: 0 },\n    min: { type: Number, default: 0 },\n    max: { type: Number, default: 100 },\n    indeterminate: { type: Boolean, default: false },\n    valueText: { type: String, default: \"\" },\n    announceText: { type: String, default: \"\" },\n  };\n  static actions = [\"setValue\"] as const;\n  static events = [\"change\", \"complete\"] as const;\n\n  declare readonly barTarget: HTMLElement;\n  declare readonly hasBarTarget: boolean;\n\n  declare valueValue: number;\n  declare minValue: number;\n  declare maxValue: number;\n  declare indeterminateValue: boolean;\n  declare valueTextValue: string;\n  declare announceTextValue: string;\n\n  /**\n   * Collapses a morph that swaps several render inputs at once into one repaint.\n   * A single update usually rewrites the whole set, and each Value would otherwise\n   * repaint on its own.\n   */\n  readonly #repaint = new MicrotaskCoalescer(() => {\n    this.#render();\n  });\n\n  override connect(): void {\n    this.#repaint.activate();\n    this.#render();\n  }\n\n  /** Closes the window in which a queued repaint may still run. */\n  override disconnect(): void {\n    this.#repaint.cancel();\n  }\n\n  /**\n   * Updates the progress value from an action param (`amount`) or a\n   * `detail.value` CustomEvent, normalizes it into range, syncs ARIA, and\n   * dispatches `change` (always) plus `complete` when `max` is reached.\n   */\n  setValue(event: SetValueEvent): void {\n    const next = toFiniteNumber(event.params?.amount ?? event.detail?.value);\n    if (next === null) return;\n    const value = this.#clamp(next);\n    this.valueValue = value;\n    this.indeterminateValue = false;\n    this.#render();\n    this.dispatch(\"change\", { detail: { value, ratio: this.#ratio } });\n    if (value >= this.maxValue) {\n      this.dispatch(\"complete\", { detail: { value } });\n      // Reaching the end is the transition worth reading out; the running numbers in\n      // between are state the consumer can see, not news.\n      announce(\n        fillTemplate(this.announceTextValue, { value, percent: Math.round(this.#ratio * 100) }),\n      );\n    }\n  }\n\n  /** Repaints when application code (or a Turbo morph) changes `indeterminate` at runtime. */\n  indeterminateValueChanged(): void {\n    this.#repaint.schedule();\n  }\n\n  /** Repaints when application code (or a Turbo morph) changes `value` at runtime. */\n  valueValueChanged(): void {\n    this.#repaint.schedule();\n  }\n\n  /** Repaints when application code (or a Turbo morph) changes `min` at runtime. */\n  minValueChanged(): void {\n    this.#repaint.schedule();\n  }\n\n  /** Repaints when application code (or a Turbo morph) changes `max` at runtime. */\n  maxValueChanged(): void {\n    this.#repaint.schedule();\n  }\n\n  /** Repaints when application code (or a Turbo morph) changes `valueText` at runtime. */\n  valueTextValueChanged(): void {\n    this.#repaint.schedule();\n  }\n\n  /** Clamps `raw` into the configured `[min, max]` range. */\n  #clamp(raw: number): number {\n    return Math.min(this.maxValue, Math.max(this.minValue, raw));\n  }\n\n  /** Current fraction of the range in `[0, 1]`; `0` when the range is empty. */\n  get #ratio(): number {\n    return rangeFraction(this.valueValue, this.minValue, this.maxValue);\n  }\n\n  /**\n   * Reflects value/range/indeterminate onto ARIA, `data-state`, and the ratio.\n   *\n   * @stimeoRenderRoot\n   */\n  #render(): void {\n    this.element.setAttribute(\"aria-valuemin\", String(this.minValue));\n    this.element.setAttribute(\"aria-valuemax\", String(this.maxValue));\n\n    if (this.indeterminateValue) {\n      this.element.removeAttribute(\"aria-valuenow\");\n      // `aria-valuetext` outranks `aria-valuenow` for assistive tech, so a text\n      // this controller derived from a value would announce the very number the\n      // indeterminate state drops.\n      this.#clearOwnValueText();\n      this.element.style.removeProperty(\"--stimeo--progress-ratio\");\n      this.element.setAttribute(\"data-state\", \"indeterminate\");\n      return;\n    }\n\n    const value = this.#clamp(this.valueValue);\n    this.element.setAttribute(\"aria-valuenow\", String(value));\n    this.element.style.setProperty(\"--stimeo--progress-ratio\", String(this.#ratio));\n    this.element.setAttribute(\"data-state\", \"determinate\");\n    this.#applyValueText(value);\n  }\n\n  /**\n   * Sets `aria-valuetext` from the consumer-provided template, substituting\n   * `{value}` and `{percent}`. Left to the consumer so the human-readable text\n   * stays i18n-neutral in the library. With no template the attribute belongs to\n   * the consumer, so only a text this controller wrote is taken back\n   * ({@link OWNED_VALUE_TEXT}).\n   */\n  #applyValueText(value: number): void {\n    if (this.valueTextValue.length === 0) {\n      this.#clearOwnValueText();\n      return;\n    }\n    const percent = Math.round(this.#ratio * 100);\n    const text = this.valueTextValue\n      .replaceAll(\"{value}\", String(value))\n      .replaceAll(\"{percent}\", String(percent));\n    this.element.setAttribute(\"aria-valuetext\", text);\n    this.element.setAttribute(OWNED_VALUE_TEXT, \"\");\n  }\n\n  /** Removes `aria-valuetext` only when this controller is the one that wrote it. */\n  #clearOwnValueText(): void {\n    if (!this.element.hasAttribute(OWNED_VALUE_TEXT)) return;\n    this.element.removeAttribute(\"aria-valuetext\");\n    this.element.removeAttribute(OWNED_VALUE_TEXT);\n  }\n}\n"]}

package/dist/controllers/radio_group_controller.d.ts

@@ -15,6 +15,9 @@ import { Controller } from '@hotwired/stimulus';
  * radios; native `<input type="radio">` already owns its activation and form
  * semantics and should be preferred when its appearance is sufficient.
  *
+ * `change` dispatches `{ value: string, radio: HTMLElement }`; `reconcile` dispatches
+ * `{ value: string, radio: HTMLElement | null }`.
+ *
  * @remarks
  * Behavior only — selection is exposed through `aria-checked`, the single Tab
  * stop through roving `tabindex` ({@link RovingTabindex}); the consumer styles