stimeo-ui 0.1.0-alpha.1

package/dist/controllers/stick_to_bottom_controller.js

@@ -0,0 +1,100 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/stick_to_bottom_controller.ts
+var countElements = (nodes) => {
+  let n = 0;
+  for (const node of nodes) if (node.nodeType === Node.ELEMENT_NODE) n += 1;
+  return n;
+};
+var StickToBottomController = class extends Controller {
+  static targets = ["content"];
+  static values = {
+    threshold: { type: Number, default: 80 },
+    behavior: { type: String, default: "auto" }
+  };
+  static actions = ["scrollToBottom"];
+  static events = ["pin", "new"];
+  #observer = null;
+  #pinned = false;
+  #onScroll = () => this.#updatePinned();
+  connect() {
+    this.#pinned = this.#isPinned();
+    this.#reflectPinned();
+    this.element.addEventListener("scroll", this.#onScroll, { passive: true });
+    if (typeof MutationObserver !== "undefined") {
+      this.#observer = new MutationObserver((mutations) => this.#onMutations(mutations));
+      this.#observer.observe(this.#watched(), { childList: true });
+    }
+  }
+  disconnect() {
+    this.element.removeEventListener("scroll", this.#onScroll);
+    this.#observer?.disconnect();
+    this.#observer = null;
+  }
+  /** Jumps to the bottom and re-pins (wired to a "new messages" button). */
+  scrollToBottom() {
+    this.#scrollToBottom();
+    this.element.removeAttribute("data-has-new");
+    if (!this.#pinned) {
+      this.#pinned = true;
+      this.element.setAttribute("data-pinned", "true");
+      this.dispatch("pin", { detail: { pinned: true } });
+    }
+  }
+  /** Follows appended children while pinned; otherwise flags new content. */
+  #onMutations(mutations) {
+    let added = 0;
+    for (const mutation of mutations) added += countElements(mutation.addedNodes);
+    if (added === 0) return;
+    if (this.#pinned) {
+      this.#scrollToBottom();
+    } else {
+      this.element.setAttribute("data-has-new", "true");
+      this.dispatch("new", { detail: { count: added } });
+    }
+  }
+  /** Recomputes pinned from the scroll position and reflects it on a transition. */
+  #updatePinned() {
+    const pinned = this.#isPinned();
+    if (pinned === this.#pinned) return;
+    this.#pinned = pinned;
+    this.#reflectPinned();
+    this.dispatch("pin", { detail: { pinned } });
+  }
+  /** Mirrors the current `#pinned` onto the state hooks (clearing has-new once pinned). */
+  #reflectPinned() {
+    if (this.#pinned) {
+      this.element.setAttribute("data-pinned", "true");
+      this.element.removeAttribute("data-has-new");
+    } else {
+      this.element.removeAttribute("data-pinned");
+    }
+  }
+  #isPinned() {
+    const el = this.element;
+    return el.scrollHeight - el.clientHeight - el.scrollTop <= this.thresholdValue;
+  }
+  #scrollToBottom() {
+    const top = this.element.scrollHeight;
+    if (typeof this.element.scrollTo === "function") {
+      this.element.scrollTo({ top, behavior: this.#behavior() });
+    } else {
+      this.element.scrollTop = top;
+    }
+  }
+  /** The append-watched element: the `content` target, or the container itself. */
+  #watched() {
+    return this.hasContentTarget ? this.contentTarget : this.element;
+  }
+  #behavior() {
+    if (this.#prefersReducedMotion()) return "auto";
+    return this.behaviorValue === "smooth" ? "smooth" : "auto";
+  }
+  #prefersReducedMotion() {
+    return typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  }
+};
+
+export { StickToBottomController };
+//# sourceMappingURL=stick_to_bottom_controller.js.map
+//# sourceMappingURL=stick_to_bottom_controller.js.map

package/dist/controllers/stick_to_bottom_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/controllers/stick_to_bottom_controller.ts"],"names":[],"mappings":"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","file":"stick_to_bottom_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\n\n/** Counts the element nodes in an added-node list (text nodes are ignored). */\nconst countElements = (nodes: NodeList): number => {\n  let n = 0;\n  for (const node of nodes) if (node.nodeType === Node.ELEMENT_NODE) n += 1;\n  return n;\n};\n\n/**\n * Headless **stick-to-bottom**: auto-follows new content to the bottom of a scroll\n * container (a chat log, a live console) — but only while the user is already near the\n * bottom; if they have scrolled up to read, it holds position and flags that new content\n * arrived instead (no APG pattern; honors WCAG 2.3.3 via `prefers-reduced-motion` and\n * never steals focus).\n *\n * Markup contract (identifier: `stimeo--stick-to-bottom`):\n *   <div data-controller=\"stimeo--stick-to-bottom\"\n *        data-stimeo--stick-to-bottom-threshold-value=\"80\" style=\"overflow:auto\">\n *     <ul data-stimeo--stick-to-bottom-target=\"content\"><!-- Turbo Stream appends --></ul>\n *   </div>\n *\n * The container is \"pinned\" while its distance from the bottom is within `threshold`. A\n * `MutationObserver` on `content` (or the element) reacts to appended children: while\n * pinned it scrolls to the bottom; while unpinned it sets `data-has-new` and emits `new`.\n * Scrolling recomputes pinned and reflects `data-pinned`, emitting `pin` on change; the\n * `scrollToBottom` action jumps back down (a \"new messages\" button).\n *\n * @remarks\n * The `MutationObserver` watches `childList` only (not `subtree`), so it follows\n * direct appends to `content` (or the element). Appends made deeper inside a nested\n * wrapper are not detected — keep messages as direct children, or call the public\n * `scrollToBottom` action after such inserts.\n *\n * Behavior only — it does not add content (Turbo Stream / the consumer does) and is the\n * minimal follow primitive, not a full chat UI (no virtualization / message input). It is\n * the lightweight member of the scroll family. State is derived from the scroll position\n * each pass (no module-scope state), so `connect()` re-syncs after a Turbo Stream insert;\n * `behavior` falls back to `auto` under reduced motion; auto-scroll never moves focus; the\n * observer and the passive scroll listener are released on `disconnect()` (Turbo\n * navigation included).\n */\nexport class StickToBottomController extends Controller<HTMLElement> {\n  static override targets = [\"content\"];\n  static override values = {\n    threshold: { type: Number, default: 80 },\n    behavior: { type: String, default: \"auto\" },\n  };\n  static actions = [\"scrollToBottom\"] as const;\n  static events = [\"pin\", \"new\"] as const;\n\n  declare readonly contentTarget: HTMLElement;\n  declare readonly hasContentTarget: boolean;\n\n  declare thresholdValue: number;\n  declare behaviorValue: string;\n\n  #observer: MutationObserver | null = null;\n  #pinned = false;\n\n  readonly #onScroll = (): void => this.#updatePinned();\n\n  override connect(): void {\n    this.#pinned = this.#isPinned();\n    // Re-sync the hooks from the current geometry — a Turbo cache restore may bring back a\n    // stale data-pinned / data-has-new that no longer matches the scroll position.\n    this.#reflectPinned();\n\n    this.element.addEventListener(\"scroll\", this.#onScroll, { passive: true });\n    if (typeof MutationObserver !== \"undefined\") {\n      this.#observer = new MutationObserver((mutations) => this.#onMutations(mutations));\n      this.#observer.observe(this.#watched(), { childList: true });\n    }\n  }\n\n  override disconnect(): void {\n    this.element.removeEventListener(\"scroll\", this.#onScroll);\n    this.#observer?.disconnect();\n    this.#observer = null;\n  }\n\n  /** Jumps to the bottom and re-pins (wired to a \"new messages\" button). */\n  scrollToBottom(): void {\n    this.#scrollToBottom();\n    this.element.removeAttribute(\"data-has-new\");\n    if (!this.#pinned) {\n      this.#pinned = true;\n      this.element.setAttribute(\"data-pinned\", \"true\");\n      this.dispatch(\"pin\", { detail: { pinned: true } });\n    }\n  }\n\n  /** Follows appended children while pinned; otherwise flags new content. */\n  #onMutations(mutations: MutationRecord[]): void {\n    let added = 0;\n    for (const mutation of mutations) added += countElements(mutation.addedNodes);\n    if (added === 0) return;\n\n    if (this.#pinned) {\n      this.#scrollToBottom();\n    } else {\n      this.element.setAttribute(\"data-has-new\", \"true\");\n      this.dispatch(\"new\", { detail: { count: added } });\n    }\n  }\n\n  /** Recomputes pinned from the scroll position and reflects it on a transition. */\n  #updatePinned(): void {\n    const pinned = this.#isPinned();\n    if (pinned === this.#pinned) return;\n    this.#pinned = pinned;\n    this.#reflectPinned();\n    this.dispatch(\"pin\", { detail: { pinned } });\n  }\n\n  /** Mirrors the current `#pinned` onto the state hooks (clearing has-new once pinned). */\n  #reflectPinned(): void {\n    if (this.#pinned) {\n      this.element.setAttribute(\"data-pinned\", \"true\");\n      this.element.removeAttribute(\"data-has-new\"); // caught up with the bottom\n    } else {\n      this.element.removeAttribute(\"data-pinned\");\n    }\n  }\n\n  #isPinned(): boolean {\n    const el = this.element;\n    return el.scrollHeight - el.clientHeight - el.scrollTop <= this.thresholdValue;\n  }\n\n  #scrollToBottom(): void {\n    const top = this.element.scrollHeight;\n    if (typeof this.element.scrollTo === \"function\") {\n      this.element.scrollTo({ top, behavior: this.#behavior() });\n    } else {\n      this.element.scrollTop = top;\n    }\n  }\n\n  /** The append-watched element: the `content` target, or the container itself. */\n  #watched(): HTMLElement {\n    return this.hasContentTarget ? this.contentTarget : this.element;\n  }\n\n  #behavior(): ScrollBehavior {\n    if (this.#prefersReducedMotion()) return \"auto\";\n    return this.behaviorValue === \"smooth\" ? \"smooth\" : \"auto\";\n  }\n\n  #prefersReducedMotion(): boolean {\n    return (\n      typeof window.matchMedia === \"function\" &&\n      window.matchMedia(\"(prefers-reduced-motion: reduce)\").matches\n    );\n  }\n}\n"]}

package/dist/controllers/sticky_observer_controller.d.ts

@@ -0,0 +1,54 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless **Sticky State Observer**: detects whether a `position: sticky`
+ * element is currently stuck and publishes it as `data-stuck`. No APG widget — a
+ * pure state-detection utility. Detection uses an {@link IntersectionObserver}
+ * and a sentinel placed just before the sticky element, avoiding per-frame scroll
+ * math.
+ *
+ * Markup contract (identifier: `stimeo--sticky-observer`):
+ *   <div data-controller="stimeo--sticky-observer">
+ *     <div data-stimeo--sticky-observer-target="sentinel"
+ *          aria-hidden="true" style="height: 1px;"></div>
+ *     <header data-stimeo--sticky-observer-target="element"
+ *             style="position: sticky; top: 0;">Site heading</header>
+ *     <main>…</main>
+ *   </div>
+ *
+ * When the sentinel scrolls out past the top of the viewport (or `rootSelector`
+ * container), the sticky element is considered stuck and `data-stuck="true"` is
+ * set; otherwise `false`. The `change` event fires on each transition.
+ *
+ * @remarks
+ * Behavior only — `position: sticky`, shadows, and shrink effects are the
+ * consumer's CSS (`[data-stuck="true"] { … }`). `data-stuck` is a visual hook
+ * only: it carries no ARIA role/state. `offset` feeds a negative top `rootMargin`
+ * and must match the sticky element's CSS `top`. The observer is disconnected on
+ * `disconnect()` (Turbo navigation included).
+ */
+declare class StickyObserverController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        rootSelector: {
+            type: StringConstructor;
+            default: string;
+        };
+        offset: {
+            type: NumberConstructor;
+            default: number;
+        };
+    };
+    static events: readonly ["change"];
+    readonly sentinelTarget: HTMLElement;
+    readonly elementTarget: HTMLElement;
+    readonly hasSentinelTarget: boolean;
+    readonly hasElementTarget: boolean;
+    rootSelectorValue: string;
+    offsetValue: number;
+    connect(): void;
+    disconnect(): void;
+}
+
+export { StickyObserverController };

package/dist/controllers/sticky_observer_controller.js

@@ -0,0 +1,53 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/sticky_observer_controller.ts
+var StickyObserverController = class extends Controller {
+  static targets = ["sentinel", "element"];
+  static values = {
+    rootSelector: { type: String, default: "" },
+    offset: { type: Number, default: 0 }
+  };
+  static events = ["change"];
+  #observer = null;
+  /** Guards against a queued callback mutating state after teardown. */
+  #active = false;
+  /** Last reported stuck state, so `change` fires only on transitions. */
+  #stuck = null;
+  #onIntersect = (entries) => {
+    if (!this.#active) return;
+    const entry = entries[entries.length - 1];
+    if (!entry) return;
+    this.#setStuck(!entry.isIntersecting);
+  };
+  connect() {
+    if (!this.hasSentinelTarget) return;
+    this.#active = true;
+    if (typeof IntersectionObserver === "undefined") return;
+    const root = this.rootSelectorValue ? document.querySelector(this.rootSelectorValue) : null;
+    this.#observer = new IntersectionObserver(this.#onIntersect, {
+      root,
+      rootMargin: `-${this.offsetValue}px 0px 0px 0px`,
+      threshold: [0]
+    });
+    this.#observer.observe(this.sentinelTarget);
+  }
+  disconnect() {
+    this.#active = false;
+    this.#observer?.disconnect();
+    this.#observer = null;
+    this.#stuck = null;
+  }
+  /** Reflects the stuck state onto the sticky element and emits `change`. */
+  #setStuck(next) {
+    if (next === this.#stuck) return;
+    this.#stuck = next;
+    if (this.hasElementTarget) {
+      this.elementTarget.setAttribute("data-stuck", next ? "true" : "false");
+    }
+    this.dispatch("change", { detail: { stuck: next } });
+  }
+};
+
+export { StickyObserverController };
+//# sourceMappingURL=sticky_observer_controller.js.map
+//# sourceMappingURL=sticky_observer_controller.js.map

package/dist/controllers/sticky_observer_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/controllers/sticky_observer_controller.ts"],"names":[],"mappings":";;;AA6BO,IAAM,wBAAA,GAAN,cAAuC,UAAA,CAAwB;AAAA,EACpE,OAAgB,OAAA,GAAU,CAAC,UAAA,EAAY,SAAS,CAAA;AAAA,EAChD,OAAgB,MAAA,GAAS;AAAA,IACvB,YAAA,EAAc,EAAE,IAAA,EAAM,MAAA,EAAQ,SAAS,EAAA,EAAG;AAAA,IAC1C,MAAA,EAAQ,EAAE,IAAA,EAAM,MAAA,EAAQ,SAAS,CAAA;AAAE,GACrC;AAAA,EACA,OAAO,MAAA,GAAS,CAAC,QAAQ,CAAA;AAAA,EAUzB,SAAA,GAAyC,IAAA;AAAA;AAAA,EAEzC,OAAA,GAAU,KAAA;AAAA;AAAA,EAEV,MAAA,GAAyB,IAAA;AAAA,EAEhB,YAAA,GAAe,CAAC,OAAA,KAA+C;AACtE,IAAA,IAAI,CAAC,KAAK,OAAA,EAAS;AACnB,IAAA,MAAM,KAAA,GAAQ,OAAA,CAAQ,OAAA,CAAQ,MAAA,GAAS,CAAC,CAAA;AACxC,IAAA,IAAI,CAAC,KAAA,EAAO;AAGZ,IAAA,IAAA,CAAK,SAAA,CAAU,CAAC,KAAA,CAAM,cAAc,CAAA;AAAA,EACtC,CAAA;AAAA,EAES,OAAA,GAAgB;AACvB,IAAA,IAAI,CAAC,KAAK,iBAAA,EAAmB;AAC7B,IAAA,IAAA,CAAK,OAAA,GAAU,IAAA;AAEf,IAAA,IAAI,OAAO,yBAAyB,WAAA,EAAa;AACjD,IAAA,MAAM,OAAO,IAAA,CAAK,iBAAA,GACd,SAAS,aAAA,CAA2B,IAAA,CAAK,iBAAiB,CAAA,GAC1D,IAAA;AAEJ,IAAA,IAAA,CAAK,SAAA,GAAY,IAAI,oBAAA,CAAqB,IAAA,CAAK,YAAA,EAAc;AAAA,MAC3D,IAAA;AAAA,MACA,UAAA,EAAY,CAAA,CAAA,EAAI,IAAA,CAAK,WAAW,CAAA,cAAA,CAAA;AAAA,MAChC,SAAA,EAAW,CAAC,CAAC;AAAA,KACd,CAAA;AACD,IAAA,IAAA,CAAK,SAAA,CAAU,OAAA,CAAQ,IAAA,CAAK,cAAc,CAAA;AAAA,EAC5C;AAAA,EAES,UAAA,GAAmB;AAC1B,IAAA,IAAA,CAAK,OAAA,GAAU,KAAA;AACf,IAAA,IAAA,CAAK,WAAW,UAAA,EAAW;AAC3B,IAAA,IAAA,CAAK,SAAA,GAAY,IAAA;AACjB,IAAA,IAAA,CAAK,MAAA,GAAS,IAAA;AAAA,EAChB;AAAA;AAAA,EAGA,UAAU,IAAA,EAAqB;AAC7B,IAAA,IAAI,IAAA,KAAS,KAAK,MAAA,EAAQ;AAC1B,IAAA,IAAA,CAAK,MAAA,GAAS,IAAA;AACd,IAAA,IAAI,KAAK,gBAAA,EAAkB;AACzB,MAAA,IAAA,CAAK,aAAA,CAAc,YAAA,CAAa,YAAA,EAAc,IAAA,GAAO,SAAS,OAAO,CAAA;AAAA,IACvE;AACA,IAAA,IAAA,CAAK,QAAA,CAAS,UAAU,EAAE,MAAA,EAAQ,EAAE,KAAA,EAAO,IAAA,IAAQ,CAAA;AAAA,EACrD;AACF","file":"sticky_observer_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\n\n/**\n * Headless **Sticky State Observer**: detects whether a `position: sticky`\n * element is currently stuck and publishes it as `data-stuck`. No APG widget — a\n * pure state-detection utility. Detection uses an {@link IntersectionObserver}\n * and a sentinel placed just before the sticky element, avoiding per-frame scroll\n * math.\n *\n * Markup contract (identifier: `stimeo--sticky-observer`):\n *   <div data-controller=\"stimeo--sticky-observer\">\n *     <div data-stimeo--sticky-observer-target=\"sentinel\"\n *          aria-hidden=\"true\" style=\"height: 1px;\"></div>\n *     <header data-stimeo--sticky-observer-target=\"element\"\n *             style=\"position: sticky; top: 0;\">Site heading</header>\n *     <main>…</main>\n *   </div>\n *\n * When the sentinel scrolls out past the top of the viewport (or `rootSelector`\n * container), the sticky element is considered stuck and `data-stuck=\"true\"` is\n * set; otherwise `false`. The `change` event fires on each transition.\n *\n * @remarks\n * Behavior only — `position: sticky`, shadows, and shrink effects are the\n * consumer's CSS (`[data-stuck=\"true\"] { … }`). `data-stuck` is a visual hook\n * only: it carries no ARIA role/state. `offset` feeds a negative top `rootMargin`\n * and must match the sticky element's CSS `top`. The observer is disconnected on\n * `disconnect()` (Turbo navigation included).\n */\nexport class StickyObserverController extends Controller<HTMLElement> {\n  static override targets = [\"sentinel\", \"element\"];\n  static override values = {\n    rootSelector: { type: String, default: \"\" },\n    offset: { type: Number, default: 0 },\n  };\n  static events = [\"change\"] as const;\n\n  declare readonly sentinelTarget: HTMLElement;\n  declare readonly elementTarget: HTMLElement;\n  declare readonly hasSentinelTarget: boolean;\n  declare readonly hasElementTarget: boolean;\n\n  declare rootSelectorValue: string;\n  declare offsetValue: number;\n\n  #observer: IntersectionObserver | null = null;\n  /** Guards against a queued callback mutating state after teardown. */\n  #active = false;\n  /** Last reported stuck state, so `change` fires only on transitions. */\n  #stuck: boolean | null = null;\n\n  readonly #onIntersect = (entries: IntersectionObserverEntry[]): void => {\n    if (!this.#active) return;\n    const entry = entries[entries.length - 1];\n    if (!entry) return;\n    // The sentinel sits above the sticky element; once it is no longer\n    // intersecting the (top-inset) root, the sticky element has stuck.\n    this.#setStuck(!entry.isIntersecting);\n  };\n\n  override connect(): void {\n    if (!this.hasSentinelTarget) return;\n    this.#active = true;\n\n    if (typeof IntersectionObserver === \"undefined\") return;\n    const root = this.rootSelectorValue\n      ? document.querySelector<HTMLElement>(this.rootSelectorValue)\n      : null;\n\n    this.#observer = new IntersectionObserver(this.#onIntersect, {\n      root,\n      rootMargin: `-${this.offsetValue}px 0px 0px 0px`,\n      threshold: [0],\n    });\n    this.#observer.observe(this.sentinelTarget);\n  }\n\n  override disconnect(): void {\n    this.#active = false;\n    this.#observer?.disconnect();\n    this.#observer = null;\n    this.#stuck = null;\n  }\n\n  /** Reflects the stuck state onto the sticky element and emits `change`. */\n  #setStuck(next: boolean): void {\n    if (next === this.#stuck) return;\n    this.#stuck = next;\n    if (this.hasElementTarget) {\n      this.elementTarget.setAttribute(\"data-stuck\", next ? \"true\" : \"false\");\n    }\n    this.dispatch(\"change\", { detail: { stuck: next } });\n  }\n}\n"]}

package/dist/controllers/submit_once_controller.d.ts

@@ -0,0 +1,66 @@
+import { Controller } from '@hotwired/stimulus';
+
+/** Submit-capable controls this controller can disable. */
+type SubmitButton = HTMLButtonElement | HTMLInputElement;
+/**
+ * Headless "submit once" behavior: disables the form's submit button(s) on submit
+ * to prevent a double submission, optionally swaps in a busy label, and restores
+ * on completion. The Headless superset of Rails' `disable_with` (no dedicated APG
+ * pattern; follows the WCAG "status messages" practice via `aria-busy`).
+ *
+ * Markup contract (identifier: `stimeo--submit-once`):
+ *   <form data-controller="stimeo--submit-once"
+ *         data-stimeo--submit-once-busy-label-value="Submitting…"
+ *         data-action="submit->stimeo--submit-once#start">
+ *     <button type="submit" data-stimeo--submit-once-target="submit">Send</button>
+ *   </form>
+ *
+ * On submit it disables every `submit` target (or, with none, the form's native
+ * `button[type=submit]` / `input[type=submit]`), sets `aria-busy` on them and
+ * `data-submitting` on the form, and swaps the **triggering** button's visible
+ * label for the busy label (per-button `data-submit-once-busy-label` overrides the
+ * form's `busyLabel` Value). It restores on Turbo's `turbo:submit-end`, or after
+ * `timeout` ms, re-enabling the buttons and putting the labels back.
+ *
+ * @remarks
+ * Behavior only — no spinner is drawn (pair with {@link "spinner"}). The submit-end
+ * listener and the timeout are torn down on `disconnect()` (Turbo navigation
+ * included), and `connect()` clears any stale busy state parked in a restored cache
+ * snapshot so a button is never left disabled. Non-Turbo caveat: the buttons are
+ * disabled synchronously inside the `submit` handler, and a plain HTML submission
+ * builds its entry list *after* that event — so a disabled submitter's `name`/`value`
+ * is excluded from the payload. Turbo is unaffected (it appends the submitter's
+ * name/value from attributes when building `FormData`); mirror the value into a
+ * hidden field when a non-Turbo form depends on it.
+ */
+declare class SubmitOnceController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        busyLabel: {
+            type: StringConstructor;
+            default: string;
+        };
+        timeout: {
+            type: NumberConstructor;
+            default: number;
+        };
+        restoreFocus: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+    };
+    static actions: readonly ["start"];
+    static events: readonly ["start", "end"];
+    readonly submitTargets: SubmitButton[];
+    readonly hasSubmitTarget: boolean;
+    busyLabelValue: string;
+    timeoutValue: number;
+    restoreFocusValue: boolean;
+    connect(): void;
+    disconnect(): void;
+    /** Enters the busy state for the submission started by `event`. */
+    start(event: SubmitEvent): void;
+}
+
+export { SubmitOnceController };

package/dist/controllers/submit_once_controller.js

@@ -0,0 +1,206 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/submit_once_controller.ts
+
+// src/utils/safe_timeout.ts
+var TimerRegistry = class {
+  /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
+  ids = /* @__PURE__ */ new Set();
+  /**
+   * Cancels a single tracked timer.
+   *
+   * No-ops if the id is unknown (already cleared, fired, or never owned by this
+   * registry), so callers can clear defensively without guarding.
+   */
+  clear(id) {
+    if (this.ids.delete(id)) {
+      this.cancel(id);
+    }
+  }
+  /**
+   * Cancels every tracked timer. Call this from a controller's `disconnect()`
+   * to guarantee no timer outlives the element.
+   */
+  clearAll() {
+    for (const id of this.ids) {
+      this.cancel(id);
+    }
+    this.ids.clear();
+  }
+  /** Number of timers currently tracked (pending). */
+  get size() {
+    return this.ids.size;
+  }
+};
+var SafeTimeout = class extends TimerRegistry {
+  /**
+   * Schedules `callback` after `delay` ms and returns the timer id.
+   *
+   * The id is removed from the registry automatically when the timeout fires,
+   * so {@link TimerRegistry.size | size} reflects only still-pending timers.
+   */
+  set(callback, delay) {
+    const id = this.schedule(() => {
+      this.ids.delete(id);
+      callback();
+    }, delay);
+    this.ids.add(id);
+    return id;
+  }
+  schedule(callback, delay) {
+    return window.setTimeout(callback, delay);
+  }
+  cancel(id) {
+    window.clearTimeout(id);
+  }
+};
+
+// src/controllers/submit_once_controller.ts
+var ORIGINAL_LABEL = "data-submit-once-original-label";
+var DISABLED_MARKER = "data-submit-once-disabled";
+var BUTTON_BUSY_LABEL = "data-submit-once-busy-label";
+var SubmitOnceController = class extends Controller {
+  static targets = ["submit"];
+  static values = {
+    busyLabel: { type: String, default: "" },
+    timeout: { type: Number, default: 0 },
+    restoreFocus: { type: Boolean, default: false }
+  };
+  static actions = ["start"];
+  static events = ["start", "end"];
+  #timeouts = new SafeTimeout();
+  #timeoutId = null;
+  #busy = false;
+  #submitter = null;
+  #onSubmitEnd = (event) => {
+    const success = event.detail?.success;
+    this.#restore(success);
+  };
+  connect() {
+    this.element.addEventListener("turbo:submit-end", this.#onSubmitEnd);
+    this.#clearStaleBusy();
+  }
+  disconnect() {
+    this.element.removeEventListener("turbo:submit-end", this.#onSubmitEnd);
+    this.#clearTimeout();
+  }
+  /** Enters the busy state for the submission started by `event`. */
+  start(event) {
+    if (this.#busy) return;
+    this.#busy = true;
+    const buttons = this.#buttons;
+    const submitter = this.#resolveSubmitter(event, buttons);
+    this.#submitter = submitter;
+    for (const button of buttons) {
+      this.#enterBusy(button, button === submitter);
+    }
+    this.element.setAttribute("data-submitting", "true");
+    this.element.setAttribute("aria-busy", "true");
+    this.dispatch("start", { detail: {} });
+    if (this.timeoutValue > 0) {
+      this.#timeoutId = this.#timeouts.set(() => this.#restore(false), this.timeoutValue);
+    }
+  }
+  /** Restores the non-busy state, re-enabling buttons and putting labels back. */
+  #restore(success) {
+    if (!this.#busy) return;
+    this.#busy = false;
+    this.#clearTimeout();
+    for (const button of this.#buttons) {
+      this.#exitBusy(button);
+    }
+    this.element.removeAttribute("data-submitting");
+    this.element.removeAttribute("aria-busy");
+    this.dispatch("end", { detail: { success } });
+    if (this.restoreFocusValue && this.#submitter) {
+      this.#submitter.focus();
+    }
+    this.#submitter = null;
+  }
+  /** Disables a button, marks it busy, and swaps the trigger's label. */
+  #enterBusy(button, isTrigger) {
+    if (!button.disabled) {
+      button.disabled = true;
+      button.setAttribute(DISABLED_MARKER, "true");
+      button.setAttribute("aria-busy", "true");
+    }
+    if (!isTrigger) return;
+    const label = button.getAttribute(BUTTON_BUSY_LABEL) ?? this.busyLabelValue;
+    if (label.length === 0) return;
+    if (!button.hasAttribute(ORIGINAL_LABEL)) {
+      button.setAttribute(ORIGINAL_LABEL, this.#getLabel(button));
+    }
+    this.#setLabel(button, label);
+  }
+  /** Re-enables a button we disabled and restores its parked label, if any. */
+  #exitBusy(button) {
+    if (button.hasAttribute(DISABLED_MARKER)) {
+      button.disabled = false;
+      button.removeAttribute(DISABLED_MARKER);
+      button.removeAttribute("aria-busy");
+    }
+    const original = button.getAttribute(ORIGINAL_LABEL);
+    if (original !== null) {
+      this.#setLabel(button, original);
+      button.removeAttribute(ORIGINAL_LABEL);
+    }
+  }
+  /** Resets busy state left in a restored cache snapshot without firing events. */
+  #clearStaleBusy() {
+    this.#busy = false;
+    if (this.element.hasAttribute("data-submitting")) {
+      this.element.removeAttribute("data-submitting");
+      this.element.removeAttribute("aria-busy");
+    }
+    for (const button of this.#buttons) {
+      this.#exitBusy(button);
+    }
+  }
+  /** The triggering button: the event's submitter when ours, else the first button. */
+  #resolveSubmitter(event, buttons) {
+    const submitter = event.submitter;
+    if (submitter && this.#isSubmitButton(submitter) && buttons.includes(submitter)) {
+      return submitter;
+    }
+    return buttons[0] ?? null;
+  }
+  /** The controlled buttons: `submit` targets, or the form's native submit controls. */
+  get #buttons() {
+    if (this.hasSubmitTarget) return this.submitTargets;
+    return Array.from(
+      this.element.querySelectorAll('button[type="submit"], input[type="submit"]')
+    );
+  }
+  #isSubmitButton(el) {
+    return el instanceof HTMLButtonElement || el instanceof HTMLInputElement;
+  }
+  /** Reads a button's visible label (input value, aria-label, or text). */
+  #getLabel(button) {
+    if (button instanceof HTMLInputElement) return button.value;
+    const aria = button.getAttribute("aria-label");
+    if (aria !== null) return aria;
+    return button.textContent ?? "";
+  }
+  /** Writes a button's visible label through the same channel it was read from. */
+  #setLabel(button, text) {
+    if (button instanceof HTMLInputElement) {
+      button.value = text;
+      return;
+    }
+    if (button.hasAttribute("aria-label")) {
+      button.setAttribute("aria-label", text);
+      return;
+    }
+    button.textContent = text;
+  }
+  #clearTimeout() {
+    if (this.#timeoutId !== null) {
+      this.#timeouts.clear(this.#timeoutId);
+      this.#timeoutId = null;
+    }
+  }
+};
+
+export { SubmitOnceController };
+//# sourceMappingURL=submit_once_controller.js.map
+//# sourceMappingURL=submit_once_controller.js.map

package/dist/controllers/submit_once_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/safe_timeout.ts","../../src/controllers/submit_once_controller.ts"],"names":[],"mappings":"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","file":"submit_once_controller.js","sourcesContent":["/**\n * Self-cleaning timer registries shared by Stimeo controllers.\n *\n * Stimulus controllers frequently schedule `setTimeout` / `setInterval` work\n * (auto-dismiss, debouncing, polling). When the element leaves the DOM — a\n * Turbo Drive navigation, a Turbo Stream replacement, or any `disconnect()` —\n * orphaned timers keep firing against a detached controller, leaking memory and\n * mutating stale state. {@link SafeTimeout} and {@link SafeInterval} track every\n * timer they create so a single {@link TimerRegistry.clearAll | clearAll()} call\n * in `disconnect()` tears them all down.\n *\n * These are intentionally low-level primitives: they own *registration and\n * cleanup only*. Higher-level policy (pause/resume, remaining-time accounting)\n * stays in the individual controllers so per-widget semantics are not flattened\n * into a lowest-common-denominator helper.\n */\n\n/**\n * Shared registry bookkeeping for the timeout/interval variants.\n *\n * Subclasses provide the scheduling primitive ({@link schedule}) and its matching\n * canceller ({@link cancel}); this base owns the set of live ids plus the\n * per-id and bulk teardown shared by both.\n */\nabstract class TimerRegistry {\n  /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */\n  protected readonly ids = new Set<number>();\n\n  /** Schedules the underlying platform timer and returns its id. */\n  protected abstract schedule(callback: () => void, delay: number): number;\n\n  /** Cancels the underlying platform timer for `id`. */\n  protected abstract cancel(id: number): void;\n\n  /**\n   * Cancels a single tracked timer.\n   *\n   * No-ops if the id is unknown (already cleared, fired, or never owned by this\n   * registry), so callers can clear defensively without guarding.\n   */\n  clear(id: number): void {\n    if (this.ids.delete(id)) {\n      this.cancel(id);\n    }\n  }\n\n  /**\n   * Cancels every tracked timer. Call this from a controller's `disconnect()`\n   * to guarantee no timer outlives the element.\n   */\n  clearAll(): void {\n    for (const id of this.ids) {\n      this.cancel(id);\n    }\n    this.ids.clear();\n  }\n\n  /** Number of timers currently tracked (pending). */\n  get size(): number {\n    return this.ids.size;\n  }\n}\n\n/**\n * `setTimeout` wrapper that auto-forgets each timer once it fires and supports\n * bulk teardown on disconnect.\n *\n * @example\n * ```ts\n * #timers = new SafeTimeout();\n *\n * connect() {\n *   this.#timers.set(() => this.dismiss(), 5000);\n * }\n *\n * disconnect() {\n *   this.#timers.clearAll();\n * }\n * ```\n */\nexport class SafeTimeout extends TimerRegistry {\n  /**\n   * Schedules `callback` after `delay` ms and returns the timer id.\n   *\n   * The id is removed from the registry automatically when the timeout fires,\n   * so {@link TimerRegistry.size | size} reflects only still-pending timers.\n   */\n  set(callback: () => void, delay: number): number {\n    const id = this.schedule(() => {\n      this.ids.delete(id);\n      callback();\n    }, delay);\n    this.ids.add(id);\n    return id;\n  }\n\n  protected schedule(callback: () => void, delay: number): number {\n    return window.setTimeout(callback, delay);\n  }\n\n  protected cancel(id: number): void {\n    window.clearTimeout(id);\n  }\n}\n\n/**\n * `setInterval` wrapper that tracks every interval for bulk teardown on\n * disconnect. Unlike {@link SafeTimeout}, intervals are retained until they are\n * explicitly cleared because they fire repeatedly.\n *\n * @example\n * ```ts\n * #intervals = new SafeInterval();\n *\n * connect() {\n *   this.#intervals.set(() => this.tick(), 1000);\n * }\n *\n * disconnect() {\n *   this.#intervals.clearAll();\n * }\n * ```\n */\nexport class SafeInterval extends TimerRegistry {\n  /** Schedules a repeating `callback` every `delay` ms and returns the timer id. */\n  set(callback: () => void, delay: number): number {\n    const id = this.schedule(callback, delay);\n    this.ids.add(id);\n    return id;\n  }\n\n  protected schedule(callback: () => void, delay: number): number {\n    return window.setInterval(callback, delay);\n  }\n\n  protected cancel(id: number): void {\n    window.clearInterval(id);\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { SafeTimeout } from \"../utils/safe_timeout\";\n\n/** Submit-capable controls this controller can disable. */\ntype SubmitButton = HTMLButtonElement | HTMLInputElement;\n\n/** Attribute the original label is parked in while busy (survives a cache restore). */\nconst ORIGINAL_LABEL = \"data-submit-once-original-label\";\n/** Marker on buttons this controller disabled (so we never re-enable authored-disabled ones). */\nconst DISABLED_MARKER = \"data-submit-once-disabled\";\n/** Per-button override for the busy label (a plain attribute, not a Stimulus Value). */\nconst BUTTON_BUSY_LABEL = \"data-submit-once-busy-label\";\n\n/**\n * Headless \"submit once\" behavior: disables the form's submit button(s) on submit\n * to prevent a double submission, optionally swaps in a busy label, and restores\n * on completion. The Headless superset of Rails' `disable_with` (no dedicated APG\n * pattern; follows the WCAG \"status messages\" practice via `aria-busy`).\n *\n * Markup contract (identifier: `stimeo--submit-once`):\n *   <form data-controller=\"stimeo--submit-once\"\n *         data-stimeo--submit-once-busy-label-value=\"Submitting…\"\n *         data-action=\"submit->stimeo--submit-once#start\">\n *     <button type=\"submit\" data-stimeo--submit-once-target=\"submit\">Send</button>\n *   </form>\n *\n * On submit it disables every `submit` target (or, with none, the form's native\n * `button[type=submit]` / `input[type=submit]`), sets `aria-busy` on them and\n * `data-submitting` on the form, and swaps the **triggering** button's visible\n * label for the busy label (per-button `data-submit-once-busy-label` overrides the\n * form's `busyLabel` Value). It restores on Turbo's `turbo:submit-end`, or after\n * `timeout` ms, re-enabling the buttons and putting the labels back.\n *\n * @remarks\n * Behavior only — no spinner is drawn (pair with {@link \"spinner\"}). The submit-end\n * listener and the timeout are torn down on `disconnect()` (Turbo navigation\n * included), and `connect()` clears any stale busy state parked in a restored cache\n * snapshot so a button is never left disabled. Non-Turbo caveat: the buttons are\n * disabled synchronously inside the `submit` handler, and a plain HTML submission\n * builds its entry list *after* that event — so a disabled submitter's `name`/`value`\n * is excluded from the payload. Turbo is unaffected (it appends the submitter's\n * name/value from attributes when building `FormData`); mirror the value into a\n * hidden field when a non-Turbo form depends on it.\n */\nexport class SubmitOnceController extends Controller<HTMLElement> {\n  static override targets = [\"submit\"];\n  static override values = {\n    busyLabel: { type: String, default: \"\" },\n    timeout: { type: Number, default: 0 },\n    restoreFocus: { type: Boolean, default: false },\n  };\n  static actions = [\"start\"] as const;\n  static events = [\"start\", \"end\"] as const;\n\n  declare readonly submitTargets: SubmitButton[];\n  declare readonly hasSubmitTarget: boolean;\n\n  declare busyLabelValue: string;\n  declare timeoutValue: number;\n  declare restoreFocusValue: boolean;\n\n  readonly #timeouts = new SafeTimeout();\n  #timeoutId: number | null = null;\n  #busy = false;\n  #submitter: SubmitButton | null = null;\n\n  readonly #onSubmitEnd = (event: Event): void => {\n    const success = (event as CustomEvent<{ success?: boolean }>).detail?.success;\n    this.#restore(success);\n  };\n\n  override connect(): void {\n    this.element.addEventListener(\"turbo:submit-end\", this.#onSubmitEnd);\n    // Idempotent: drop any busy state carried over in a restored snapshot so a\n    // cached, disabled button does not stay stuck.\n    this.#clearStaleBusy();\n  }\n\n  override disconnect(): void {\n    this.element.removeEventListener(\"turbo:submit-end\", this.#onSubmitEnd);\n    this.#clearTimeout();\n  }\n\n  /** Enters the busy state for the submission started by `event`. */\n  start(event: SubmitEvent): void {\n    if (this.#busy) return;\n    this.#busy = true;\n    const buttons = this.#buttons;\n    const submitter = this.#resolveSubmitter(event, buttons);\n    this.#submitter = submitter;\n    for (const button of buttons) {\n      this.#enterBusy(button, button === submitter);\n    }\n    this.element.setAttribute(\"data-submitting\", \"true\");\n    this.element.setAttribute(\"aria-busy\", \"true\");\n    this.dispatch(\"start\", { detail: {} });\n    if (this.timeoutValue > 0) {\n      this.#timeoutId = this.#timeouts.set(() => this.#restore(false), this.timeoutValue);\n    }\n  }\n\n  /** Restores the non-busy state, re-enabling buttons and putting labels back. */\n  #restore(success?: boolean): void {\n    if (!this.#busy) return;\n    this.#busy = false;\n    this.#clearTimeout();\n    for (const button of this.#buttons) {\n      this.#exitBusy(button);\n    }\n    this.element.removeAttribute(\"data-submitting\");\n    this.element.removeAttribute(\"aria-busy\");\n    this.dispatch(\"end\", { detail: { success } });\n    if (this.restoreFocusValue && this.#submitter) {\n      this.#submitter.focus();\n    }\n    this.#submitter = null;\n  }\n\n  /** Disables a button, marks it busy, and swaps the trigger's label. */\n  #enterBusy(button: SubmitButton, isTrigger: boolean): void {\n    // Only disable (and mark) buttons that were enabled, so an authored-disabled\n    // submit button — e.g. \"disabled until valid\" — is left untouched and is never\n    // re-enabled by us on restore.\n    if (!button.disabled) {\n      button.disabled = true;\n      button.setAttribute(DISABLED_MARKER, \"true\");\n      button.setAttribute(\"aria-busy\", \"true\");\n    }\n    if (!isTrigger) return;\n    const label = button.getAttribute(BUTTON_BUSY_LABEL) ?? this.busyLabelValue;\n    if (label.length === 0) return;\n    if (!button.hasAttribute(ORIGINAL_LABEL)) {\n      button.setAttribute(ORIGINAL_LABEL, this.#getLabel(button));\n    }\n    this.#setLabel(button, label);\n  }\n\n  /** Re-enables a button we disabled and restores its parked label, if any. */\n  #exitBusy(button: SubmitButton): void {\n    if (button.hasAttribute(DISABLED_MARKER)) {\n      button.disabled = false;\n      button.removeAttribute(DISABLED_MARKER);\n      button.removeAttribute(\"aria-busy\");\n    }\n    const original = button.getAttribute(ORIGINAL_LABEL);\n    if (original !== null) {\n      this.#setLabel(button, original);\n      button.removeAttribute(ORIGINAL_LABEL);\n    }\n  }\n\n  /** Resets busy state left in a restored cache snapshot without firing events. */\n  #clearStaleBusy(): void {\n    this.#busy = false;\n    if (this.element.hasAttribute(\"data-submitting\")) {\n      this.element.removeAttribute(\"data-submitting\");\n      this.element.removeAttribute(\"aria-busy\");\n    }\n    for (const button of this.#buttons) {\n      this.#exitBusy(button);\n    }\n  }\n\n  /** The triggering button: the event's submitter when ours, else the first button. */\n  #resolveSubmitter(event: SubmitEvent, buttons: SubmitButton[]): SubmitButton | null {\n    const submitter = event.submitter;\n    if (submitter && this.#isSubmitButton(submitter) && buttons.includes(submitter)) {\n      return submitter;\n    }\n    return buttons[0] ?? null;\n  }\n\n  /** The controlled buttons: `submit` targets, or the form's native submit controls. */\n  get #buttons(): SubmitButton[] {\n    if (this.hasSubmitTarget) return this.submitTargets;\n    return Array.from(\n      this.element.querySelectorAll<SubmitButton>('button[type=\"submit\"], input[type=\"submit\"]'),\n    );\n  }\n\n  #isSubmitButton(el: HTMLElement): el is SubmitButton {\n    return el instanceof HTMLButtonElement || el instanceof HTMLInputElement;\n  }\n\n  /** Reads a button's visible label (input value, aria-label, or text). */\n  #getLabel(button: SubmitButton): string {\n    if (button instanceof HTMLInputElement) return button.value;\n    const aria = button.getAttribute(\"aria-label\");\n    if (aria !== null) return aria;\n    return button.textContent ?? \"\";\n  }\n\n  /** Writes a button's visible label through the same channel it was read from. */\n  #setLabel(button: SubmitButton, text: string): void {\n    if (button instanceof HTMLInputElement) {\n      button.value = text;\n      return;\n    }\n    if (button.hasAttribute(\"aria-label\")) {\n      button.setAttribute(\"aria-label\", text);\n      return;\n    }\n    button.textContent = text;\n  }\n\n  #clearTimeout(): void {\n    if (this.#timeoutId !== null) {\n      this.#timeouts.clear(this.#timeoutId);\n      this.#timeoutId = null;\n    }\n  }\n}\n"]}

package/dist/controllers/switch_controller.d.ts

@@ -0,0 +1,43 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless, accessible switch (toggle) behavior.
+ *
+ * Markup contract (identifier: `stimeo--switch`):
+ *   <button data-controller="stimeo--switch"
+ *           data-action="stimeo--switch#toggle keydown->stimeo--switch#onKeydown"
+ *           role="switch" aria-checked="false">…</button>
+ *
+ * Implements the WAI-ARIA APG **Switch** pattern. The controller element is the
+ * switch itself; its on/off state is reflected solely through `aria-checked`.
+ *
+ * @remarks
+ * Behavior only — the consumer owns all styling (typically keyed off the
+ * `[aria-checked="true"]` attribute). On a native `<button>` host, the browser
+ * already synthesizes a click for Space/Enter, so {@link onKeydown} deliberately
+ * does nothing there (to avoid a double toggle) and only drives non-button hosts
+ * such as `<div role="switch" tabindex="0">`.
+ *
+ * Behavior provided:
+ * - Click (or Space/Enter) toggles `aria-checked` between `"true"` and `"false"`.
+ * - A `stimeo--switch:changed` event is dispatched on every toggle so the
+ *   consumer can react (its `detail.checked` carries the new boolean state).
+ */
+declare class SwitchController extends Controller<HTMLElement> {
+    #private;
+    static actions: readonly ["onKeydown", "toggle"];
+    static events: readonly ["changed"];
+    /** Ensures the switch exposes a role and is keyboard-reachable. */
+    connect(): void;
+    /** Toggles the checked state. Bound via `data-action` (click). */
+    toggle(): void;
+    /**
+     * Activates the switch on Space/Enter for non-native hosts and prevents the
+     * default Space scroll. Bound via `data-action` (keydown). Native `<button>`
+     * hosts are skipped because the browser already turns Space/Enter into a click,
+     * which would otherwise toggle the switch twice.
+     */
+    onKeydown(event: KeyboardEvent): void;
+}
+
+export { SwitchController };

package/dist/controllers/switch_controller.js

@@ -0,0 +1,50 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/switch_controller.ts
+var SwitchController = class extends Controller {
+  static actions = ["onKeydown", "toggle"];
+  static events = ["changed"];
+  /** Ensures the switch exposes a role and is keyboard-reachable. */
+  connect() {
+    if (!this.element.hasAttribute("role")) {
+      this.element.setAttribute("role", "switch");
+    }
+    if (!this.element.hasAttribute("aria-checked")) {
+      this.element.setAttribute("aria-checked", "false");
+    }
+    if (!(this.element instanceof HTMLButtonElement) && !this.element.hasAttribute("tabindex")) {
+      this.element.setAttribute("tabindex", "0");
+    }
+  }
+  /** Toggles the checked state. Bound via `data-action` (click). */
+  toggle() {
+    this.#checked = !this.#checked;
+  }
+  /**
+   * Activates the switch on Space/Enter for non-native hosts and prevents the
+   * default Space scroll. Bound via `data-action` (keydown). Native `<button>`
+   * hosts are skipped because the browser already turns Space/Enter into a click,
+   * which would otherwise toggle the switch twice.
+   */
+  onKeydown(event) {
+    if (this.element instanceof HTMLButtonElement) return;
+    if (event.repeat) return;
+    if (event.key === " " || event.key === "Enter") {
+      event.preventDefault();
+      this.toggle();
+    }
+  }
+  /** Whether the switch is currently on. */
+  get #checked() {
+    return this.element.getAttribute("aria-checked") === "true";
+  }
+  /** Reflects the new state on `aria-checked` and notifies listeners. */
+  set #checked(value) {
+    this.element.setAttribute("aria-checked", value ? "true" : "false");
+    this.dispatch("changed", { detail: { checked: value } });
+  }
+};
+
+export { SwitchController };
+//# sourceMappingURL=switch_controller.js.map
+//# sourceMappingURL=switch_controller.js.map