stimeo-ui 0.1.0-alpha.1

package/dist/controllers/popover_controller.js

@@ -0,0 +1,94 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/popover_controller.ts
+var PopoverController = class _PopoverController extends Controller {
+  static targets = ["trigger", "panel"];
+  static actions = ["close", "open", "toggle"];
+  /** Selector for natively focusable elements used to find the first one. */
+  static #FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+  /** Starts closed and registers the document-level dismissal listeners. */
+  connect() {
+    this.close();
+    document.addEventListener("click", this.#onOutsideClick);
+    document.addEventListener("keydown", this.#onKeydown);
+  }
+  /**
+   * Removes the document-level listeners registered in {@link connect}, plus the
+   * panel's `focusout` listener if the popover is torn down while open (e.g. a
+   * Turbo navigation). `removeEventListener` is a no-op when it was never added,
+   * so this is safe in the closed state too — no listener outlives the element.
+   */
+  disconnect() {
+    document.removeEventListener("click", this.#onOutsideClick);
+    document.removeEventListener("keydown", this.#onKeydown);
+    if (this.hasPanelTarget) this.panelTarget.removeEventListener("focusout", this.#onFocusOut);
+  }
+  /** Toggles the popover. Bound via `data-action` (click on the trigger). */
+  toggle() {
+    if (this.#isOpen) {
+      this.close();
+    } else {
+      this.open();
+    }
+  }
+  /** Opens the panel, reflects state, and moves focus inside it. */
+  open() {
+    if (!this.hasPanelTarget || this.#isOpen) return;
+    this.panelTarget.hidden = false;
+    if (this.hasTriggerTarget) this.triggerTarget.setAttribute("aria-expanded", "true");
+    this.panelTarget.addEventListener("focusout", this.#onFocusOut);
+    this.#focusFirst();
+  }
+  /** Closes the panel and reflects the collapsed state. Bound via `data-action`. */
+  close() {
+    if (!this.hasPanelTarget) return;
+    this.panelTarget.removeEventListener("focusout", this.#onFocusOut);
+    this.panelTarget.hidden = true;
+    if (this.hasTriggerTarget) this.triggerTarget.setAttribute("aria-expanded", "false");
+  }
+  /** Moves focus to the first focusable element in the panel, or the panel itself. */
+  #focusFirst() {
+    const first = this.panelTarget.querySelector(_PopoverController.#FOCUSABLE);
+    if (first) {
+      first.focus();
+      return;
+    }
+    if (!this.panelTarget.hasAttribute("tabindex")) this.panelTarget.tabIndex = -1;
+    this.panelTarget.focus();
+  }
+  /** Closes and restores focus to the trigger (shared by Escape / outside click). */
+  #closeAndRestore() {
+    this.close();
+    if (this.hasTriggerTarget) this.triggerTarget.focus();
+  }
+  /** Closes (restoring focus) when a click lands outside the controller element. */
+  #onOutsideClick = (event) => {
+    if (this.#isOpen && !this.element.contains(event.target)) this.#closeAndRestore();
+  };
+  /** Closes (restoring focus) on `Escape` while open. */
+  #onKeydown = (event) => {
+    if (event.key === "Escape" && this.#isOpen) {
+      event.preventDefault();
+      this.#closeAndRestore();
+    }
+  };
+  /**
+   * Closes when focus leaves the panel for an element outside the controller
+   * (e.g. `Tab` past the last field). Focus is *not* restored — the natural
+   * destination is kept, which is the modeless contract. Moves within the
+   * controller (panel → trigger) keep it open.
+   */
+  #onFocusOut = (event) => {
+    const next = event.relatedTarget;
+    if (next && this.element.contains(next)) return;
+    this.close();
+  };
+  /** Whether the panel is currently visible. */
+  get #isOpen() {
+    return this.hasPanelTarget && !this.panelTarget.hidden;
+  }
+};
+
+export { PopoverController };
+//# sourceMappingURL=popover_controller.js.map
+//# sourceMappingURL=popover_controller.js.map

package/dist/controllers/popover_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/controllers/popover_controller.ts"],"names":[],"mappings":"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","file":"popover_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\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.\n * - An outside click (anywhere off the controller element) closes and restores\n *   focus to the trigger.\n * - Because it is modeless, focus is *not* trapped: when `Tab` moves focus out of\n *   the panel it closes (detected via `focusout`) without yanking focus back, so\n *   the natural tab destination is preserved.\n */\nexport class PopoverController extends Controller<HTMLElement> {\n  static override targets = [\"trigger\", \"panel\"];\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\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 document-level dismissal listeners. */\n  override connect(): void {\n    this.close();\n    document.addEventListener(\"click\", this.#onOutsideClick);\n    document.addEventListener(\"keydown\", this.#onKeydown);\n  }\n\n  /**\n   * Removes the document-level listeners registered in {@link connect}, plus the\n   * panel's `focusout` listener if the popover is torn down while open (e.g. a\n   * Turbo navigation). `removeEventListener` is a no-op when it was never added,\n   * so this is safe in the closed state too — no listener outlives the element.\n   */\n  override disconnect(): void {\n    document.removeEventListener(\"click\", this.#onOutsideClick);\n    document.removeEventListener(\"keydown\", this.#onKeydown);\n    if (this.hasPanelTarget) this.panelTarget.removeEventListener(\"focusout\", this.#onFocusOut);\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    // focusout fires as focus settles; register only once the panel is open so an\n    // initial close()/connect() does not immediately re-close it.\n    this.panelTarget.addEventListener(\"focusout\", this.#onFocusOut);\n    this.#focusFirst();\n  }\n\n  /** Closes the panel and reflects the collapsed state. Bound via `data-action`. */\n  close(): void {\n    if (!this.hasPanelTarget) return;\n    this.panelTarget.removeEventListener(\"focusout\", this.#onFocusOut);\n    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 (shared by Escape / outside click). */\n  #closeAndRestore(): void {\n    this.close();\n    if (this.hasTriggerTarget) this.triggerTarget.focus();\n  }\n\n  /** Closes (restoring focus) when a click lands outside the controller element. */\n  readonly #onOutsideClick = (event: MouseEvent): void => {\n    if (this.#isOpen && !this.element.contains(event.target as Node)) this.#closeAndRestore();\n  };\n\n  /** Closes (restoring focus) on `Escape` while open. */\n  readonly #onKeydown = (event: KeyboardEvent): void => {\n    if (event.key === \"Escape\" && this.#isOpen) {\n      event.preventDefault();\n      this.#closeAndRestore();\n    }\n  };\n\n  /**\n   * Closes when focus leaves the panel for an element outside the controller\n   * (e.g. `Tab` past the last field). Focus is *not* restored — the natural\n   * destination is kept, which is the modeless contract. Moves within the\n   * controller (panel → trigger) keep it open.\n   */\n  readonly #onFocusOut = (event: FocusEvent): void => {\n    const next = event.relatedTarget as Node | null;\n    if (next && 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

@@ -0,0 +1,58 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless **portal / teleport**: moves an element to another place in the DOM (e.g.
+ * directly under `body`) on connect and cleans up on disconnect — the shared substrate
+ * for overlays that must escape an ancestor's `overflow: hidden`, `transform`, or
+ * stacking context (no APG pattern; a DOM utility). Counterpart to Radix `Portal` /
+ * Alpine `x-teleport`.
+ *
+ * Markup contract (identifier: `stimeo--portal`):
+ *   <div data-controller="stimeo--portal" data-stimeo--portal-to-value="body">
+ *     <div data-stimeo--portal-target="content">Teleported content</div>
+ *   </div>
+ *
+ * Moves `content` (or `this.element` when no `content` target) into the first element
+ * matching `to` (default `body`), `append`ed or `prepend`ed per `position`. A comment
+ * placeholder records the original spot so `disconnect()` can return the node there
+ * (when `restore`) — or remove it — leaving no orphan behind. The moved node carries
+ * `data-portaled`.
+ *
+ * @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
+ * the same document does not re-fire connect/disconnect, so the move is safe. For Turbo
+ * compatibility prefer the `content`-target form: the controller then stays on the
+ * in-place source, so its `disconnect()` fires when the original container is replaced
+ * and the teleported node is restored/removed rather than orphaned under `body`. The
+ * move is idempotent (guarded by the placeholder) and reversed on `disconnect()` (Turbo
+ * navigation included).
+ */
+declare class PortalController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        to: {
+            type: StringConstructor;
+            default: string;
+        };
+        position: {
+            type: StringConstructor;
+            default: string;
+        };
+        restore: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+    };
+    static events: readonly ["mount", "unmount"];
+    readonly contentTarget: HTMLElement;
+    readonly hasContentTarget: boolean;
+    toValue: string;
+    positionValue: string;
+    restoreValue: boolean;
+    connect(): void;
+    disconnect(): void;
+}
+
+export { PortalController };

package/dist/controllers/portal_controller.js

@@ -0,0 +1,63 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/portal_controller.ts
+var portalState = /* @__PURE__ */ new WeakMap();
+var PortalController = class extends Controller {
+  static targets = ["content"];
+  static values = {
+    to: { type: String, default: "body" },
+    position: { type: String, default: "append" },
+    restore: { type: Boolean, default: true }
+  };
+  static events = ["mount", "unmount"];
+  connect() {
+    if (portalState.has(this.element)) return;
+    const node = this.hasContentTarget ? this.contentTarget : this.element;
+    const destination = this.#destination();
+    if (!destination || destination === node || node.contains(destination)) return;
+    const placeholder = document.createComment("stimeo--portal");
+    node.parentNode?.insertBefore(placeholder, node);
+    portalState.set(this.element, { node, placeholder });
+    if (this.positionValue === "prepend") {
+      destination.prepend(node);
+    } else {
+      destination.appendChild(node);
+    }
+    node.setAttribute("data-portaled", "true");
+    this.dispatch("mount", { detail: { target: destination } });
+  }
+  disconnect() {
+    if (this.element.isConnected && this.#stillControlled()) return;
+    const state = portalState.get(this.element);
+    if (!state) return;
+    portalState.delete(this.element);
+    const { node, placeholder } = state;
+    node.removeAttribute("data-portaled");
+    if (this.restoreValue && placeholder.parentNode) {
+      placeholder.parentNode.insertBefore(node, placeholder);
+    } else {
+      node.remove();
+    }
+    placeholder.remove();
+    this.dispatch("unmount", { detail: {} });
+  }
+  /** True while `data-controller` still lists this identifier (spurious-churn signal). */
+  #stillControlled() {
+    const tokens = (this.element.getAttribute("data-controller") ?? "").split(/\s+/);
+    return tokens.includes(this.identifier);
+  }
+  /** Resolves the destination for `to`, tolerating an invalid selector. */
+  #destination() {
+    const selector = this.toValue.trim();
+    if (!selector) return null;
+    try {
+      return document.querySelector(selector);
+    } catch {
+      return null;
+    }
+  }
+};
+
+export { PortalController };
+//# sourceMappingURL=portal_controller.js.map
+//# sourceMappingURL=portal_controller.js.map

package/dist/controllers/portal_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/controllers/portal_controller.ts"],"names":[],"mappings":";;;AAQA,IAAM,WAAA,uBAAkB,OAAA,EAA8D;AA8B/E,IAAM,gBAAA,GAAN,cAA+B,UAAA,CAAwB;AAAA,EAC5D,OAAgB,OAAA,GAAU,CAAC,SAAS,CAAA;AAAA,EACpC,OAAgB,MAAA,GAAS;AAAA,IACvB,EAAA,EAAI,EAAE,IAAA,EAAM,MAAA,EAAQ,SAAS,MAAA,EAAO;AAAA,IACpC,QAAA,EAAU,EAAE,IAAA,EAAM,MAAA,EAAQ,SAAS,QAAA,EAAS;AAAA,IAC5C,OAAA,EAAS,EAAE,IAAA,EAAM,OAAA,EAAS,SAAS,IAAA;AAAK,GAC1C;AAAA,EACA,OAAO,MAAA,GAAS,CAAC,OAAA,EAAS,SAAS,CAAA;AAAA,EAS1B,OAAA,GAAgB;AACvB,IAAA,IAAI,WAAA,CAAY,GAAA,CAAI,IAAA,CAAK,OAAO,CAAA,EAAG;AACnC,IAAA,MAAM,IAAA,GAAO,IAAA,CAAK,gBAAA,GAAmB,IAAA,CAAK,gBAAgB,IAAA,CAAK,OAAA;AAC/D,IAAA,MAAM,WAAA,GAAc,KAAK,YAAA,EAAa;AACtC,IAAA,IAAI,CAAC,WAAA,IAAe,WAAA,KAAgB,QAAQ,IAAA,CAAK,QAAA,CAAS,WAAW,CAAA,EAAG;AAExE,IAAA,MAAM,WAAA,GAAc,QAAA,CAAS,aAAA,CAAc,gBAAgB,CAAA;AAC3D,IAAA,IAAA,CAAK,UAAA,EAAY,YAAA,CAAa,WAAA,EAAa,IAAI,CAAA;AAC/C,IAAA,WAAA,CAAY,IAAI,IAAA,CAAK,OAAA,EAAS,EAAE,IAAA,EAAM,aAAa,CAAA;AAEnD,IAAA,IAAI,IAAA,CAAK,kBAAkB,SAAA,EAAW;AACpC,MAAA,WAAA,CAAY,QAAQ,IAAI,CAAA;AAAA,IAC1B,CAAA,MAAO;AACL,MAAA,WAAA,CAAY,YAAY,IAAI,CAAA;AAAA,IAC9B;AACA,IAAA,IAAA,CAAK,YAAA,CAAa,iBAAiB,MAAM,CAAA;AACzC,IAAA,IAAA,CAAK,QAAA,CAAS,SAAS,EAAE,MAAA,EAAQ,EAAE,MAAA,EAAQ,WAAA,IAAe,CAAA;AAAA,EAC5D;AAAA,EAES,UAAA,GAAmB;AAM1B,IAAA,IAAI,IAAA,CAAK,OAAA,CAAQ,WAAA,IAAe,IAAA,CAAK,kBAAiB,EAAG;AACzD,IAAA,MAAM,KAAA,GAAQ,WAAA,CAAY,GAAA,CAAI,IAAA,CAAK,OAAO,CAAA;AAC1C,IAAA,IAAI,CAAC,KAAA,EAAO;AACZ,IAAA,WAAA,CAAY,MAAA,CAAO,KAAK,OAAO,CAAA;AAC/B,IAAA,MAAM,EAAE,IAAA,EAAM,WAAA,EAAY,GAAI,KAAA;AAE9B,IAAA,IAAA,CAAK,gBAAgB,eAAe,CAAA;AACpC,IAAA,IAAI,IAAA,CAAK,YAAA,IAAgB,WAAA,CAAY,UAAA,EAAY;AAC/C,MAAA,WAAA,CAAY,UAAA,CAAW,YAAA,CAAa,IAAA,EAAM,WAAW,CAAA;AAAA,IACvD,CAAA,MAAO;AACL,MAAA,IAAA,CAAK,MAAA,EAAO;AAAA,IACd;AACA,IAAA,WAAA,CAAY,MAAA,EAAO;AACnB,IAAA,IAAA,CAAK,SAAS,SAAA,EAAW,EAAE,MAAA,EAAQ,IAAI,CAAA;AAAA,EACzC;AAAA;AAAA,EAGA,gBAAA,GAA4B;AAC1B,IAAA,MAAM,MAAA,GAAA,CAAU,KAAK,OAAA,CAAQ,YAAA,CAAa,iBAAiB,CAAA,IAAK,EAAA,EAAI,MAAM,KAAK,CAAA;AAC/E,IAAA,OAAO,MAAA,CAAO,QAAA,CAAS,IAAA,CAAK,UAAU,CAAA;AAAA,EACxC;AAAA;AAAA,EAGA,YAAA,GAA+B;AAC7B,IAAA,MAAM,QAAA,GAAW,IAAA,CAAK,OAAA,CAAQ,IAAA,EAAK;AACnC,IAAA,IAAI,CAAC,UAAU,OAAO,IAAA;AACtB,IAAA,IAAI;AACF,MAAA,OAAO,QAAA,CAAS,cAAc,QAAQ,CAAA;AAAA,IACxC,CAAA,CAAA,MAAQ;AACN,MAAA,OAAO,IAAA;AAAA,IACT;AAAA,EACF;AACF","file":"portal_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\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). Counterpart to Radix `Portal` /\n * Alpine `x-teleport`.\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).\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  override connect(): void {\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    // Moving the controller element (the no-`content` form) makes some runtimes re-emit\n    // disconnect/connect. That spurious churn is recognisable: the element is still in the\n    // document AND still carries this identifier (Stimulus will reconnect immediately), so\n    // ignore it. A genuine teardown — the element left the DOM, or `data-controller` no\n    // longer lists us (e.g. a Turbo 8 morph) — must still restore/remove the teleport.\n    if (this.element.isConnected && this.#stillControlled()) return;\n    const state = portalState.get(this.element);\n    if (!state) return;\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  /** True while `data-controller` still lists this identifier (spurious-churn signal). */\n  #stillControlled(): boolean {\n    const tokens = (this.element.getAttribute(\"data-controller\") ?? \"\").split(/\\s+/);\n    return tokens.includes(this.identifier);\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

@@ -0,0 +1,47 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless **preview guard** (Hotwire-specific): hides or placeholders a volatile element
+ * — a balance, a notification count, a live timestamp — *only while Turbo is showing a
+ * preview* (`html[data-turbo-preview]`), so a stale cached snapshot does not briefly flash
+ * the old value on a back/restore visit. No APG pattern; it keeps displayed information
+ * accurate and never moves focus.
+ *
+ * Markup contract (identifier: `stimeo--preview-guard`):
+ *   <span data-controller="stimeo--preview-guard"
+ *         data-stimeo--preview-guard-mode-value="placeholder"
+ *         data-stimeo--preview-guard-placeholder-value="—">¥123,456</span>
+ *
+ * Watches `<html>` for the `data-turbo-preview` attribute with a `MutationObserver`.
+ * While it is present the element is guarded: `mode="hide"` makes it `visibility: hidden`
+ * (its box is kept, so nothing shifts), `mode="placeholder"` swaps its text for
+ * `placeholder`. The element carries `data-preview-hidden` and emits `hide`; when the
+ * preview clears it is restored and `show` fires.
+ *
+ * @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
+ * module-scope state) and the original value is saved on hide and put back on show, so a
+ * guard that connects mid-preview hides immediately and a `disconnect()` (Turbo navigation
+ * included) restores the element and severs the observer. Focus is never moved.
+ */
+declare class PreviewGuardController extends Controller<HTMLElement> {
+    #private;
+    static values: {
+        placeholder: {
+            type: StringConstructor;
+            default: string;
+        };
+        mode: {
+            type: StringConstructor;
+            default: string;
+        };
+    };
+    static events: readonly ["hide", "show"];
+    placeholderValue: string;
+    modeValue: string;
+    connect(): void;
+    disconnect(): void;
+}
+
+export { PreviewGuardController };

package/dist/controllers/preview_guard_controller.js

@@ -0,0 +1,69 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/preview_guard_controller.ts
+var PreviewGuardController = class extends Controller {
+  static values = {
+    placeholder: { type: String, default: "" },
+    mode: { type: String, default: "hide" }
+  };
+  static events = ["hide", "show"];
+  #observer = null;
+  #hidden = false;
+  /** Saved inline visibility (hide mode), restored on show. */
+  #savedVisibility = "";
+  /** Saved text (placeholder mode); non-null marks that text — not visibility — was swapped. */
+  #savedText = null;
+  connect() {
+    if (typeof MutationObserver !== "undefined") {
+      this.#observer = new MutationObserver(() => this.#sync());
+      this.#observer.observe(document.documentElement, {
+        attributes: true,
+        attributeFilter: ["data-turbo-preview"]
+      });
+    }
+    this.#sync();
+  }
+  disconnect() {
+    this.#observer?.disconnect();
+    this.#observer = null;
+    this.#restore();
+  }
+  /** Reflects the current `data-turbo-preview` state onto the element. */
+  #sync() {
+    const previewing = document.documentElement.hasAttribute("data-turbo-preview");
+    if (previewing && !this.#hidden) this.#hide();
+    else if (!previewing && this.#hidden) this.#show();
+  }
+  #hide() {
+    this.#hidden = true;
+    if (this.modeValue === "placeholder") {
+      this.#savedText = this.element.textContent;
+      this.element.textContent = this.placeholderValue;
+    } else {
+      this.#savedVisibility = this.element.style.visibility;
+      this.element.style.visibility = "hidden";
+    }
+    this.element.setAttribute("data-preview-hidden", "true");
+    this.dispatch("hide", { detail: {} });
+  }
+  #show() {
+    this.#restore();
+    this.dispatch("show", { detail: {} });
+  }
+  /** Reverts the guard. Safe to call when not hidden (no-op) — used by show and teardown. */
+  #restore() {
+    if (!this.#hidden) return;
+    this.#hidden = false;
+    if (this.#savedText !== null) {
+      this.element.textContent = this.#savedText;
+      this.#savedText = null;
+    } else {
+      this.element.style.visibility = this.#savedVisibility;
+    }
+    this.element.removeAttribute("data-preview-hidden");
+  }
+};
+
+export { PreviewGuardController };
+//# sourceMappingURL=preview_guard_controller.js.map
+//# sourceMappingURL=preview_guard_controller.js.map

package/dist/controllers/preview_guard_controller.js.map

@@ -0,0 +1 @@
+{"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 * @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

@@ -0,0 +1,85 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Event shape `setValue` accepts: an action param `amount` or a `detail.value`.
+ * Both are typed `number | string` because, while Stimulus coerces numeric action
+ * params to numbers, a `progress:set` CustomEvent (or a non-numeric-looking param)
+ * may carry a string; {@link ProgressController.setValue} normalizes either form.
+ */
+type SetValueEvent = Event & {
+    params?: {
+        amount?: number | string;
+    };
+    detail?: {
+        value?: number | string;
+    };
+};
+/**
+ * Headless progress-bar behavior backed by the WAI-ARIA `progressbar` role.
+ *
+ * Markup contract (identifier: `stimeo--progress`):
+ *   <div data-controller="stimeo--progress" role="progressbar"
+ *        aria-label="Upload" aria-valuemin="0" aria-valuemax="100" aria-valuenow="0"
+ *        data-stimeo--progress-value-value="0"
+ *        data-action="progress:set->stimeo--progress#setValue">
+ *     <div data-stimeo--progress-target="bar"></div>
+ *   </div>
+ *
+ * This is the *progress over time* role (a task advancing toward completion),
+ * deliberately distinct from {@link MeterController}'s point-in-time `meter`. The
+ * controller owns value normalization and ARIA value-attribute synchronization;
+ * the bar's width/animation is the consumer's, driven off the
+ * `--stimeo-progress-ratio` (0–1) custom property and `data-state`.
+ *
+ * @remarks
+ * Behavior only — no styling is emitted. An indeterminate bar drops
+ * `aria-valuenow` (per ARIA) so assistive tech announces "busy" rather than a
+ * stale value; the consumer animates the indeterminate look off
+ * `data-state="indeterminate"`.
+ */
+declare class ProgressController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        value: {
+            type: NumberConstructor;
+            default: number;
+        };
+        min: {
+            type: NumberConstructor;
+            default: number;
+        };
+        max: {
+            type: NumberConstructor;
+            default: number;
+        };
+        indeterminate: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        valueText: {
+            type: StringConstructor;
+            default: string;
+        };
+    };
+    static actions: readonly ["setValue"];
+    static events: readonly ["change", "complete"];
+    readonly barTarget: HTMLElement;
+    readonly hasBarTarget: boolean;
+    valueValue: number;
+    minValue: number;
+    maxValue: number;
+    indeterminateValue: boolean;
+    valueTextValue: string;
+    connect(): void;
+    /**
+     * Updates the progress value from an action param (`amount`) or a
+     * `detail.value` CustomEvent, normalizes it into range, syncs ARIA, and
+     * dispatches `change` (always) plus `complete` when `max` is reached.
+     */
+    setValue(event: SetValueEvent): void;
+    /** Re-render when the indeterminate flag is toggled via its data attribute. */
+    indeterminateValueChanged(): void;
+}
+
+export { ProgressController };

package/dist/controllers/progress_controller.js

@@ -0,0 +1,93 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/progress_controller.ts
+
+// src/utils/coerce.ts
+function toFiniteNumber(raw) {
+  if (raw === null || raw === void 0 || raw === "") return null;
+  const value = typeof raw === "number" ? raw : Number(raw);
+  return Number.isFinite(value) ? value : null;
+}
+
+// src/controllers/progress_controller.ts
+var ProgressController = class extends Controller {
+  static targets = ["bar"];
+  static values = {
+    value: { type: Number, default: 0 },
+    min: { type: Number, default: 0 },
+    max: { type: Number, default: 100 },
+    indeterminate: { type: Boolean, default: false },
+    valueText: { type: String, default: "" }
+  };
+  static actions = ["setValue"];
+  static events = ["change", "complete"];
+  connect() {
+    this.#render();
+  }
+  /**
+   * Updates the progress value from an action param (`amount`) or a
+   * `detail.value` CustomEvent, normalizes it into range, syncs ARIA, and
+   * dispatches `change` (always) plus `complete` when `max` is reached.
+   */
+  setValue(event) {
+    const next = toFiniteNumber(event.params?.amount ?? event.detail?.value);
+    if (next === null) return;
+    const value = this.#clamp(next);
+    this.valueValue = value;
+    this.indeterminateValue = false;
+    this.#render();
+    this.dispatch("change", { detail: { value, ratio: this.#ratio } });
+    if (value >= this.maxValue) {
+      this.dispatch("complete", { detail: { value } });
+    }
+  }
+  /** Re-render when the indeterminate flag is toggled via its data attribute. */
+  indeterminateValueChanged() {
+    this.#render();
+  }
+  /** Clamps `raw` into the configured `[min, max]` range. */
+  #clamp(raw) {
+    return Math.min(this.maxValue, Math.max(this.minValue, raw));
+  }
+  /** Current fraction of the range in `[0, 1]`; `0` when the range is empty. */
+  get #ratio() {
+    const span = this.maxValue - this.minValue;
+    if (span <= 0) return 0;
+    return (this.#clamp(this.valueValue) - this.minValue) / span;
+  }
+  /** Reflects value/range/indeterminate onto ARIA, `data-state`, and the ratio. */
+  #render() {
+    this.element.setAttribute("aria-valuemin", String(this.minValue));
+    this.element.setAttribute("aria-valuemax", String(this.maxValue));
+    if (this.indeterminateValue) {
+      this.element.removeAttribute("aria-valuenow");
+      this.element.removeAttribute("aria-valuetext");
+      this.element.style.removeProperty("--stimeo-progress-ratio");
+      this.element.setAttribute("data-state", "indeterminate");
+      return;
+    }
+    const value = this.#clamp(this.valueValue);
+    this.element.setAttribute("aria-valuenow", String(value));
+    this.element.style.setProperty("--stimeo-progress-ratio", String(this.#ratio));
+    this.element.setAttribute("data-state", "determinate");
+    this.#applyValueText(value);
+  }
+  /**
+   * Sets `aria-valuetext` from the consumer-provided template, substituting
+   * `{value}` and `{percent}`. Left to the consumer so the human-readable text
+   * stays i18n-neutral in the library; cleared when no template is given.
+   */
+  #applyValueText(value) {
+    if (this.valueTextValue.length === 0) {
+      this.element.removeAttribute("aria-valuetext");
+      return;
+    }
+    const percent = Math.round(this.#ratio * 100);
+    const text = this.valueTextValue.replaceAll("{value}", String(value)).replaceAll("{percent}", String(percent));
+    this.element.setAttribute("aria-valuetext", text);
+  }
+};
+
+export { ProgressController };
+//# sourceMappingURL=progress_controller.js.map
+//# sourceMappingURL=progress_controller.js.map

package/dist/controllers/progress_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/coerce.ts","../../src/controllers/progress_controller.ts"],"names":[],"mappings":"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","file":"progress_controller.js","sourcesContent":["/**\n * Numeric coercion shared by the value-bearing status controllers (progress,\n * meter).\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","import { Controller } from \"@hotwired/stimulus\";\nimport { toFiniteNumber } from \"../utils/coerce\";\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 * 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  };\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\n  override connect(): void {\n    this.#render();\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    }\n  }\n\n  /** Re-render when the indeterminate flag is toggled via its data attribute. */\n  indeterminateValueChanged(): void {\n    // Stimulus fires this once during initialization (before `connect`), where\n    // touching the DOM is still safe; guard nothing.\n    this.#render();\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    const span = this.maxValue - this.minValue;\n    if (span <= 0) return 0;\n    // Clamp first so an out-of-range value (e.g. an initial value past `max`)\n    // can never push the ratio — and thus the bar width / percent — outside 0–1.\n    return (this.#clamp(this.valueValue) - this.minValue) / span;\n  }\n\n  /** Reflects value/range/indeterminate onto ARIA, `data-state`, and the ratio. */\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      this.element.removeAttribute(\"aria-valuetext\");\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; cleared when no template is given.\n   */\n  #applyValueText(value: number): void {\n    if (this.valueTextValue.length === 0) {\n      this.element.removeAttribute(\"aria-valuetext\");\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  }\n}\n"]}

package/dist/controllers/radio_group_controller.d.ts

@@ -0,0 +1,49 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless, accessible radio-group behavior for **custom** (non-native) radios.
+ *
+ * Markup contract (identifier: `stimeo--radio-group`):
+ *   <div data-controller="stimeo--radio-group" role="radiogroup" aria-label="Plan">
+ *     <div role="radio" aria-checked="true" tabindex="0" data-value="basic"
+ *          data-stimeo--radio-group-target="radio"
+ *          data-action="click->stimeo--radio-group#select
+ *                       keydown->stimeo--radio-group#onKeydown">Basic</div>
+ *     <!-- more radios; exactly one tabindex=0 -->
+ *     <input type="hidden" data-stimeo--radio-group-target="field" />
+ *   </div>
+ *
+ * Implements the WAI-ARIA APG **Radio Group** pattern. Use this only for custom
+ * radios (e.g. button-styled cards); native `<input type="radio">` already does
+ * this and should be preferred when its look suffices.
+ *
+ * @remarks
+ * Behavior only — selection is exposed through `aria-checked`, the single Tab
+ * stop through roving `tabindex` ({@link RovingTabindex}); the consumer styles
+ * off `[role="radio"][aria-checked="true"]`. Per APG, **selection follows
+ * focus**: arrow keys move focus and select in one step.
+ *
+ * Behavior provided:
+ * - Click selects a radio.
+ * - `ArrowDown`/`ArrowRight` select the next, `ArrowUp`/`ArrowLeft` the previous
+ *   (wrapping); `Home`/`End` the first/last; `Space` selects the focused radio.
+ * - The selected radio's `data-value` is mirrored to the optional hidden `field`,
+ *   and `stimeo--radio-group:change` is dispatched on every change.
+ */
+declare class RadioGroupController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static actions: readonly ["onKeydown", "select"];
+    static events: readonly ["change"];
+    readonly radioTargets: HTMLElement[];
+    readonly fieldTarget: HTMLInputElement;
+    readonly hasFieldTarget: boolean;
+    /** Establishes the roving entry point and reflects the initial selection. */
+    connect(): void;
+    /** Selects the clicked radio. Bound via `data-action` (click). */
+    select(event: Event): void;
+    /** Arrow/Home/End/Space navigation with selection-follows-focus. */
+    onKeydown(event: KeyboardEvent): void;
+}
+
+export { RadioGroupController };