stimeo-ui 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stimeo Labs (taiyaky)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# Stimeo UI
+
+**Headless Stimulus UI framework for Ruby on Rails.** Stimeo UI ships *behavior*
+— ARIA state, keyboard interaction, focus management, Turbo resilience — as
+`data-*`-driven Stimulus controllers. It does **not** ship CSS: the consuming app
+owns the look entirely.
+
+- Lean by design: the **core** needs only `@hotwired/stimulus` at runtime (kept
+  external in the build). The opt-in `stimeo-ui/positioning` module is the one
+  exception — it uses `@floating-ui/dom` (an optional **peer dependency**; see the
+  Peer dependencies note below).
+- Accessibility first: every controller follows the relevant WAI-ARIA APG pattern
+  and the related WCAG 2.2 AA criteria.
+- Public controller identifiers use the `stimeo--` namespace (e.g.
+  `stimeo--dropdown`).
+
+> Status: **alpha** (`0.x`). The `stimeo--*` attribute API may still change before
+> 1.0 — pin your version.
+
+## Install
+
+### Rails with importmap (recommended)
+
+```bash
+bundle add stimeo-ui
+bin/rails generate stimeo:install
+```
+
+The generator vendors the prebuilt JS into `vendor/javascript/stimeo/`, pins
+`stimeo-ui` in `config/importmap.rb`, and registers all controllers with your
+Stimulus application. Then drive components from HTML alone:
+
+```erb
+<div data-controller="stimeo--dropdown">
+  <button data-stimeo--dropdown-target="trigger"
+          data-action="click->stimeo--dropdown#toggle">Menu</button>
+  <div data-stimeo--dropdown-target="menu" hidden>…</div>
+</div>
+```
+
+### npm (jsbundling or any bundler)
+
+```bash
+npm install stimeo-ui @hotwired/stimulus
+```
+
+```js
+import { Application } from "@hotwired/stimulus";
+import { registerStimeo } from "stimeo-ui";
+
+const application = Application.start();
+registerStimeo(application); // registers every stimeo--* controller
+```
+
+Need only a few controllers? Import them individually from
+`stimeo-ui/controllers/*` and register them under your own identifiers.
+
+- **Peer dependencies:** `@hotwired/stimulus` (always), `@floating-ui/dom` (only
+  if you use the opt-in `stimeo-ui/positioning` module — tooltips, popovers, etc.
+  work without it via the default flow layout).
+- **No CSS is shipped.** Style the components yourself; controllers only toggle
+  ARIA state and `data-*` hooks.
+
+## Contributing
+
+Bug reports and feature requests are very welcome — please open a GitHub issue.
+For code changes, open an issue first to discuss direction; see
+[`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+## License
+
+Released under the [MIT License](LICENSE) © Stimeo Labs.

package/dist/controllers/accordion_controller.d.ts

@@ -0,0 +1,59 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless, accessible accordion behavior.
+ *
+ * Markup contract (identifier: `stimeo--accordion`):
+ *   <div data-controller="stimeo--accordion">
+ *     <h3>
+ *       <button data-stimeo--accordion-target="trigger"
+ *               data-action="stimeo--accordion#toggle
+ *                            keydown->stimeo--accordion#onKeydown"
+ *               aria-expanded="false" aria-controls="panel-1">Section 1</button>
+ *     </h3>
+ *     <div id="panel-1" data-stimeo--accordion-target="panel"
+ *          role="region" hidden>…</div>
+ *     <!-- repeat header/panel pairs -->
+ *   </div>
+ *
+ * Implements the WAI-ARIA APG **Accordion** pattern. Each header button is
+ * associated with its panel through `aria-controls`; the panel's `id` is the
+ * single source of truth for the pairing, so headers and panels need not be
+ * adjacent siblings.
+ *
+ * @remarks
+ * Multiple panels may be open at once (this is the APG-allowed default). State
+ * is reflected through `aria-expanded` on the header and the `hidden` attribute
+ * on the panel — never through visual styling, which the consumer owns.
+ *
+ * Behavior provided:
+ * - Click a header to toggle its panel (`aria-expanded` + `hidden` reflect state).
+ * - `ArrowDown`/`ArrowUp` move focus between headers; `Home`/`End` jump to the
+ *   first/last header. Hidden headers (including those inside a hidden subtree,
+ *   e.g. a section a filter collapsed) are skipped so focus stays perceivable.
+ * - {@link expandAll} / {@link collapseAll} open or close every panel at once,
+ *   for an optional "expand all / collapse all" control pair anywhere in scope.
+ */
+declare class AccordionController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static actions: readonly ["collapseAll", "expandAll", "onKeydown", "toggle"];
+    readonly triggerTargets: HTMLButtonElement[];
+    readonly panelTargets: HTMLElement[];
+    /** Toggles the panel controlled by the activated header. */
+    toggle(event: Event): void;
+    /** Opens every panel. Bound via `data-action` on an "expand all" control. */
+    expandAll(): void;
+    /** Closes every panel. Bound via `data-action` on a "collapse all" control. */
+    collapseAll(): void;
+    /**
+     * Moves focus between headers per the APG keyboard model, skipping any header
+     * that is hidden or nested in a hidden subtree. A consumer may hide whole
+     * sections (e.g. an `stimeo--filter` that collapses empty groups), and an
+     * unperceivable header must never become an arrow-key target — otherwise
+     * `.focus()` lands on nothing and navigation appears to stall.
+     */
+    onKeydown(event: KeyboardEvent): void;
+}
+
+export { AccordionController };

package/dist/controllers/accordion_controller.js

@@ -0,0 +1,76 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/accordion_controller.ts
+var AccordionController = class extends Controller {
+  static targets = ["trigger", "panel"];
+  static actions = ["collapseAll", "expandAll", "onKeydown", "toggle"];
+  /** Toggles the panel controlled by the activated header. */
+  toggle(event) {
+    const trigger = event.currentTarget;
+    const panel = this.#panelFor(trigger);
+    if (!panel) return;
+    this.#setExpanded(trigger, panel, trigger.getAttribute("aria-expanded") !== "true");
+  }
+  /** Opens every panel. Bound via `data-action` on an "expand all" control. */
+  expandAll() {
+    this.#setAll(true);
+  }
+  /** Closes every panel. Bound via `data-action` on a "collapse all" control. */
+  collapseAll() {
+    this.#setAll(false);
+  }
+  /** Drives every header/panel pair to the same expanded state. */
+  #setAll(open) {
+    for (const trigger of this.triggerTargets) {
+      const panel = this.#panelFor(trigger);
+      if (panel) this.#setExpanded(trigger, panel, open);
+    }
+  }
+  /** Reflects one header/panel pair's state through `aria-expanded` + `hidden`. */
+  #setExpanded(trigger, panel, open) {
+    trigger.setAttribute("aria-expanded", open ? "true" : "false");
+    panel.hidden = !open;
+  }
+  /**
+   * Moves focus between headers per the APG keyboard model, skipping any header
+   * that is hidden or nested in a hidden subtree. A consumer may hide whole
+   * sections (e.g. an `stimeo--filter` that collapses empty groups), and an
+   * unperceivable header must never become an arrow-key target — otherwise
+   * `.focus()` lands on nothing and navigation appears to stall.
+   */
+  onKeydown(event) {
+    const current = event.currentTarget;
+    if (this.triggerTargets.indexOf(current) === -1) return;
+    const navigable = this.triggerTargets.filter((trigger) => trigger.closest("[hidden]") === null);
+    const here = navigable.indexOf(current);
+    if (here === -1) return;
+    let next;
+    switch (event.key) {
+      case "ArrowDown":
+        next = navigable[(here + 1) % navigable.length];
+        break;
+      case "ArrowUp":
+        next = navigable[(here - 1 + navigable.length) % navigable.length];
+        break;
+      case "Home":
+        next = navigable[0];
+        break;
+      case "End":
+        next = navigable[navigable.length - 1];
+        break;
+      default:
+        return;
+    }
+    event.preventDefault();
+    next?.focus();
+  }
+  /** Resolves the panel a header controls via its `aria-controls` reference. */
+  #panelFor(trigger) {
+    const id = trigger.getAttribute("aria-controls");
+    return id ? this.panelTargets.find((panel) => panel.id === id) ?? null : null;
+  }
+};
+
+export { AccordionController };
+//# sourceMappingURL=accordion_controller.js.map
+//# sourceMappingURL=accordion_controller.js.map

package/dist/controllers/accordion_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/controllers/accordion_controller.ts"],"names":[],"mappings":"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","file":"accordion_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\n\n/**\n * Headless, accessible accordion behavior.\n *\n * Markup contract (identifier: `stimeo--accordion`):\n *   <div data-controller=\"stimeo--accordion\">\n *     <h3>\n *       <button data-stimeo--accordion-target=\"trigger\"\n *               data-action=\"stimeo--accordion#toggle\n *                            keydown->stimeo--accordion#onKeydown\"\n *               aria-expanded=\"false\" aria-controls=\"panel-1\">Section 1</button>\n *     </h3>\n *     <div id=\"panel-1\" data-stimeo--accordion-target=\"panel\"\n *          role=\"region\" hidden>…</div>\n *     <!-- repeat header/panel pairs -->\n *   </div>\n *\n * Implements the WAI-ARIA APG **Accordion** pattern. Each header button is\n * associated with its panel through `aria-controls`; the panel's `id` is the\n * single source of truth for the pairing, so headers and panels need not be\n * adjacent siblings.\n *\n * @remarks\n * Multiple panels may be open at once (this is the APG-allowed default). State\n * is reflected through `aria-expanded` on the header and the `hidden` attribute\n * on the panel — never through visual styling, which the consumer owns.\n *\n * Behavior provided:\n * - Click a header to toggle its panel (`aria-expanded` + `hidden` reflect state).\n * - `ArrowDown`/`ArrowUp` move focus between headers; `Home`/`End` jump to the\n *   first/last header. Hidden headers (including those inside a hidden subtree,\n *   e.g. a section a filter collapsed) are skipped so focus stays perceivable.\n * - {@link expandAll} / {@link collapseAll} open or close every panel at once,\n *   for an optional \"expand all / collapse all\" control pair anywhere in scope.\n */\nexport class AccordionController extends Controller<HTMLElement> {\n  static override targets = [\"trigger\", \"panel\"];\n  static actions = [\"collapseAll\", \"expandAll\", \"onKeydown\", \"toggle\"] as const;\n\n  declare readonly triggerTargets: HTMLButtonElement[];\n  declare readonly panelTargets: HTMLElement[];\n\n  /** Toggles the panel controlled by the activated header. */\n  toggle(event: Event): void {\n    const trigger = event.currentTarget as HTMLButtonElement;\n    const panel = this.#panelFor(trigger);\n    if (!panel) return;\n\n    this.#setExpanded(trigger, panel, trigger.getAttribute(\"aria-expanded\") !== \"true\");\n  }\n\n  /** Opens every panel. Bound via `data-action` on an \"expand all\" control. */\n  expandAll(): void {\n    this.#setAll(true);\n  }\n\n  /** Closes every panel. Bound via `data-action` on a \"collapse all\" control. */\n  collapseAll(): void {\n    this.#setAll(false);\n  }\n\n  /** Drives every header/panel pair to the same expanded state. */\n  #setAll(open: boolean): void {\n    for (const trigger of this.triggerTargets) {\n      const panel = this.#panelFor(trigger);\n      if (panel) this.#setExpanded(trigger, panel, open);\n    }\n  }\n\n  /** Reflects one header/panel pair's state through `aria-expanded` + `hidden`. */\n  #setExpanded(trigger: HTMLButtonElement, panel: HTMLElement, open: boolean): void {\n    trigger.setAttribute(\"aria-expanded\", open ? \"true\" : \"false\");\n    panel.hidden = !open;\n  }\n\n  /**\n   * Moves focus between headers per the APG keyboard model, skipping any header\n   * that is hidden or nested in a hidden subtree. A consumer may hide whole\n   * sections (e.g. an `stimeo--filter` that collapses empty groups), and an\n   * unperceivable header must never become an arrow-key target — otherwise\n   * `.focus()` lands on nothing and navigation appears to stall.\n   */\n  onKeydown(event: KeyboardEvent): void {\n    const current = event.currentTarget as HTMLButtonElement;\n    if (this.triggerTargets.indexOf(current) === -1) return;\n\n    // `closest(\"[hidden]\")` catches both a directly-hidden header and one inside a\n    // hidden ancestor (the filter-group case); navigate over the visible set only.\n    const navigable = this.triggerTargets.filter((trigger) => trigger.closest(\"[hidden]\") === null);\n    const here = navigable.indexOf(current);\n    if (here === -1) return;\n\n    let next: HTMLButtonElement | undefined;\n    switch (event.key) {\n      case \"ArrowDown\":\n        next = navigable[(here + 1) % navigable.length];\n        break;\n      case \"ArrowUp\":\n        next = navigable[(here - 1 + navigable.length) % navigable.length];\n        break;\n      case \"Home\":\n        next = navigable[0];\n        break;\n      case \"End\":\n        next = navigable[navigable.length - 1];\n        break;\n      default:\n        return;\n    }\n\n    event.preventDefault();\n    next?.focus();\n  }\n\n  /** Resolves the panel a header controls via its `aria-controls` reference. */\n  #panelFor(trigger: HTMLButtonElement): HTMLElement | null {\n    const id = trigger.getAttribute(\"aria-controls\");\n    return id ? (this.panelTargets.find((panel) => panel.id === id) ?? null) : null;\n  }\n}\n"]}

package/dist/controllers/announcer_controller.d.ts

@@ -0,0 +1,78 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless, shared **live-region announcer** — a polite/assertive screen-reader
+ * announcement base (no dedicated APG pattern; follows the WAI-ARIA "Alert" /
+ * "Status" live-region guidance and WCAG 2.2 **4.1.3 Status Messages**).
+ *
+ * Markup contract (identifier: `stimeo--announcer`):
+ *   <!-- Place once per page; the consumer visually hides the regions in CSS. -->
+ *   <div data-controller="stimeo--announcer">
+ *     <div data-stimeo--announcer-target="polite" aria-live="polite" aria-atomic="true"></div>
+ *     <div data-stimeo--announcer-target="assertive" aria-live="assertive" aria-atomic="true"></div>
+ *   </div>
+ *
+ *   <!-- Attribute-only trigger: declare the activation event explicitly. -->
+ *   <button data-action="click->stimeo--announcer#announce"
+ *           data-stimeo--announcer-message-param="Saved"
+ *           data-stimeo--announcer-assertive-param="false">Save</button>
+ *
+ *   <!-- Programmatic trigger (e.g. from another controller / Turbo Stream). -->
+ *   window.dispatchEvent(new CustomEvent("stimeo--announcer:announce", {
+ *     detail: { message: "12 results", assertive: false },
+ *   }))
+ *
+ * The announcer is the shared substrate other controllers (Auto-Submit, Flash,
+ * Bulk Select, …) lean on instead of each carrying their own live region.
+ *
+ * @remarks
+ * Behavior only, with **one deliberate exception**: when a `polite`/`assertive`
+ * target is absent the controller *generates* the missing region and applies the
+ * canonical visually-hidden inline style (see {@link visuallyHide}). A live region
+ * must exist and be visually hidden to do its job, and a generated node has no
+ * consumer CSS hook to hide it; consumers who want to own styling supply their own
+ * targets. The controller never moves focus — announcements must not steal it
+ * (WCAG 2.2 4.1.3). Listeners and clear timers are torn down on `disconnect()`
+ * (Turbo included), and any generated regions are removed.
+ */
+declare class AnnouncerController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        clearAfter: {
+            type: NumberConstructor;
+            default: number;
+        };
+        dedupeReannounce: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+    };
+    static actions: readonly ["announce"];
+    readonly politeTarget: HTMLElement;
+    readonly assertiveTarget: HTMLElement;
+    readonly hasPoliteTarget: boolean;
+    readonly hasAssertiveTarget: boolean;
+    clearAfterValue: number;
+    dedupeReannounceValue: boolean;
+    connect(): void;
+    disconnect(): void;
+    /**
+     * Announces a message. Reads the text from a Stimulus action param
+     * (`message`, plus optional `assertive`) for attribute-only triggers, falling
+     * back to a CustomEvent `detail` when the same handler is wired to an event.
+     * An empty/non-string message is ignored so untrusted payloads cannot blank
+     * the region.
+     */
+    announce(event: Event): void;
+}
+/**
+ * Applies the canonical visually-hidden ("sr-only") inline style to a generated
+ * live region so its text is announced without being seen. Inline so the library
+ * stays self-contained when the consumer provides no target/CSS of its own.
+ *
+ * Pure (no `this`); exported for direct unit testing.
+ */
+declare function visuallyHide(node: HTMLElement): void;
+
+export { AnnouncerController, visuallyHide };

package/dist/controllers/announcer_controller.js

@@ -0,0 +1,184 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/announcer_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/announcer_controller.ts
+var AnnouncerController = class extends Controller {
+  static targets = ["polite", "assertive"];
+  static values = {
+    clearAfter: { type: Number, default: 1e3 },
+    dedupeReannounce: { type: Boolean, default: true }
+  };
+  static actions = ["announce"];
+  /** Clear/re-announce timers; one `clearAll()` in disconnect tears them all down. */
+  #timers = new SafeTimeout();
+  /** Live regions generated to stand in for absent targets, for teardown. */
+  #generated = /* @__PURE__ */ new Map();
+  /**
+   * Guards against handling the same CustomEvent twice. An event dispatched on
+   * the controller element with `bubbles: true` reaches both the element and the
+   * `window` listener; this WeakSet ensures it announces only once.
+   */
+  #handled = /* @__PURE__ */ new WeakSet();
+  /** Receives programmatic announcements at the element or bubbled to `window`. */
+  #onAnnounceEvent = (event) => {
+    if (this.#handled.has(event)) return;
+    this.#handled.add(event);
+    const detail = event.detail;
+    const message = this.#messageFromDetail(detail);
+    if (!message) return;
+    this.#announce(message, this.#assertiveFromDetail(detail));
+  };
+  connect() {
+    this.element.addEventListener("stimeo--announcer:announce", this.#onAnnounceEvent);
+    window.addEventListener("stimeo--announcer:announce", this.#onAnnounceEvent);
+  }
+  disconnect() {
+    this.element.removeEventListener("stimeo--announcer:announce", this.#onAnnounceEvent);
+    window.removeEventListener("stimeo--announcer:announce", this.#onAnnounceEvent);
+    this.#timers.clearAll();
+    for (const region of this.#generated.values()) {
+      region.remove();
+    }
+    this.#generated.clear();
+  }
+  /**
+   * Announces a message. Reads the text from a Stimulus action param
+   * (`message`, plus optional `assertive`) for attribute-only triggers, falling
+   * back to a CustomEvent `detail` when the same handler is wired to an event.
+   * An empty/non-string message is ignored so untrusted payloads cannot blank
+   * the region.
+   */
+  announce(event) {
+    const params = event.params;
+    const fromParam = params?.message;
+    const message = typeof fromParam === "string" && fromParam.length > 0 ? fromParam : this.#messageFromDetail(event.detail);
+    if (!message) return;
+    const assertive = params?.assertive === true || this.#assertiveFromDetail(event.detail);
+    this.#announce(message, assertive);
+  }
+  /**
+   * Writes `message` into the matching live region and schedules its clear.
+   *
+   * When the region already holds the same text, an aria-atomic region is not
+   * re-read by assistive tech (the node did not change). If `dedupeReannounce`
+   * is on, the text is cleared and re-set on a later task so the mutation is
+   * observed and announced again.
+   */
+  #announce(message, assertive) {
+    const region = this.#regionFor(assertive ? "assertive" : "polite");
+    if (this.dedupeReannounceValue && region.textContent === message) {
+      region.textContent = "";
+      this.#timers.set(() => {
+        region.textContent = message;
+        this.#scheduleClear(region, message);
+      }, 0);
+      return;
+    }
+    region.textContent = message;
+    this.#scheduleClear(region, message);
+  }
+  /** Clears the region after `clearAfter` ms, unless a newer message replaced it. */
+  #scheduleClear(region, message) {
+    if (this.clearAfterValue <= 0) return;
+    this.#timers.set(() => {
+      if (region.textContent === message) region.textContent = "";
+    }, this.clearAfterValue);
+  }
+  /** Resolves the live region for a politeness level, generating it if absent. */
+  #regionFor(level) {
+    if (level === "assertive" && this.hasAssertiveTarget) return this.assertiveTarget;
+    if (level === "polite" && this.hasPoliteTarget) return this.politeTarget;
+    const existing = this.#generated.get(level);
+    if (existing) return existing;
+    const region = document.createElement("div");
+    region.setAttribute("aria-live", level);
+    region.setAttribute("aria-atomic", "true");
+    visuallyHide(region);
+    this.element.appendChild(region);
+    this.#generated.set(level, region);
+    return region;
+  }
+  /** Extracts a non-empty string `message` from a CustomEvent detail, else null. */
+  #messageFromDetail(detail) {
+    if (detail && typeof detail === "object" && "message" in detail) {
+      const value = detail.message;
+      if (typeof value === "string" && value.length > 0) return value;
+    }
+    return null;
+  }
+  /** Reads an `assertive === true` flag from a CustomEvent detail (default polite). */
+  #assertiveFromDetail(detail) {
+    return !!detail && typeof detail === "object" && detail.assertive === true;
+  }
+};
+function visuallyHide(node) {
+  const { style } = node;
+  style.position = "absolute";
+  style.width = "1px";
+  style.height = "1px";
+  style.margin = "-1px";
+  style.padding = "0";
+  style.border = "0";
+  style.overflow = "hidden";
+  style.clip = "rect(0 0 0 0)";
+  style.clipPath = "inset(50%)";
+  style.whiteSpace = "nowrap";
+}
+
+export { AnnouncerController, visuallyHide };
+//# sourceMappingURL=announcer_controller.js.map
+//# sourceMappingURL=announcer_controller.js.map

package/dist/controllers/announcer_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/safe_timeout.ts","../../src/controllers/announcer_controller.ts"],"names":[],"mappings":"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","file":"announcer_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/**\n * Headless, shared **live-region announcer** — a polite/assertive screen-reader\n * announcement base (no dedicated APG pattern; follows the WAI-ARIA \"Alert\" /\n * \"Status\" live-region guidance and WCAG 2.2 **4.1.3 Status Messages**).\n *\n * Markup contract (identifier: `stimeo--announcer`):\n *   <!-- Place once per page; the consumer visually hides the regions in CSS. -->\n *   <div data-controller=\"stimeo--announcer\">\n *     <div data-stimeo--announcer-target=\"polite\" aria-live=\"polite\" aria-atomic=\"true\"></div>\n *     <div data-stimeo--announcer-target=\"assertive\" aria-live=\"assertive\" aria-atomic=\"true\"></div>\n *   </div>\n *\n *   <!-- Attribute-only trigger: declare the activation event explicitly. -->\n *   <button data-action=\"click->stimeo--announcer#announce\"\n *           data-stimeo--announcer-message-param=\"Saved\"\n *           data-stimeo--announcer-assertive-param=\"false\">Save</button>\n *\n *   <!-- Programmatic trigger (e.g. from another controller / Turbo Stream). -->\n *   window.dispatchEvent(new CustomEvent(\"stimeo--announcer:announce\", {\n *     detail: { message: \"12 results\", assertive: false },\n *   }))\n *\n * The announcer is the shared substrate other controllers (Auto-Submit, Flash,\n * Bulk Select, …) lean on instead of each carrying their own live region.\n *\n * @remarks\n * Behavior only, with **one deliberate exception**: when a `polite`/`assertive`\n * target is absent the controller *generates* the missing region and applies the\n * canonical visually-hidden inline style (see {@link visuallyHide}). A live region\n * must exist and be visually hidden to do its job, and a generated node has no\n * consumer CSS hook to hide it; consumers who want to own styling supply their own\n * targets. The controller never moves focus — announcements must not steal it\n * (WCAG 2.2 4.1.3). Listeners and clear timers are torn down on `disconnect()`\n * (Turbo included), and any generated regions are removed.\n */\nexport class AnnouncerController extends Controller<HTMLElement> {\n  static override targets = [\"polite\", \"assertive\"];\n  static override values = {\n    clearAfter: { type: Number, default: 1000 },\n    dedupeReannounce: { type: Boolean, default: true },\n  };\n  static actions = [\"announce\"] as const;\n\n  declare readonly politeTarget: HTMLElement;\n  declare readonly assertiveTarget: HTMLElement;\n  declare readonly hasPoliteTarget: boolean;\n  declare readonly hasAssertiveTarget: boolean;\n\n  declare clearAfterValue: number;\n  declare dedupeReannounceValue: boolean;\n\n  /** Clear/re-announce timers; one `clearAll()` in disconnect tears them all down. */\n  readonly #timers = new SafeTimeout();\n\n  /** Live regions generated to stand in for absent targets, for teardown. */\n  readonly #generated = new Map<\"assertive\" | \"polite\", HTMLElement>();\n\n  /**\n   * Guards against handling the same CustomEvent twice. An event dispatched on\n   * the controller element with `bubbles: true` reaches both the element and the\n   * `window` listener; this WeakSet ensures it announces only once.\n   */\n  readonly #handled = new WeakSet<Event>();\n\n  /** Receives programmatic announcements at the element or bubbled to `window`. */\n  readonly #onAnnounceEvent = (event: Event): void => {\n    if (this.#handled.has(event)) return;\n    this.#handled.add(event);\n    const detail = (event as CustomEvent<unknown>).detail;\n    const message = this.#messageFromDetail(detail);\n    if (!message) return;\n    this.#announce(message, this.#assertiveFromDetail(detail));\n  };\n\n  override connect(): void {\n    this.element.addEventListener(\"stimeo--announcer:announce\", this.#onAnnounceEvent);\n    window.addEventListener(\"stimeo--announcer:announce\", this.#onAnnounceEvent);\n  }\n\n  override disconnect(): void {\n    this.element.removeEventListener(\"stimeo--announcer:announce\", this.#onAnnounceEvent);\n    window.removeEventListener(\"stimeo--announcer:announce\", this.#onAnnounceEvent);\n    this.#timers.clearAll();\n    for (const region of this.#generated.values()) {\n      region.remove();\n    }\n    this.#generated.clear();\n  }\n\n  /**\n   * Announces a message. Reads the text from a Stimulus action param\n   * (`message`, plus optional `assertive`) for attribute-only triggers, falling\n   * back to a CustomEvent `detail` when the same handler is wired to an event.\n   * An empty/non-string message is ignored so untrusted payloads cannot blank\n   * the region.\n   */\n  announce(event: Event): void {\n    const params = (event as { params?: Record<string, unknown> }).params;\n    const fromParam = params?.message;\n    const message =\n      typeof fromParam === \"string\" && fromParam.length > 0\n        ? fromParam\n        : this.#messageFromDetail((event as CustomEvent<unknown>).detail);\n    if (!message) return;\n\n    const assertive =\n      params?.assertive === true ||\n      this.#assertiveFromDetail((event as CustomEvent<unknown>).detail);\n    this.#announce(message, assertive);\n  }\n\n  /**\n   * Writes `message` into the matching live region and schedules its clear.\n   *\n   * When the region already holds the same text, an aria-atomic region is not\n   * re-read by assistive tech (the node did not change). If `dedupeReannounce`\n   * is on, the text is cleared and re-set on a later task so the mutation is\n   * observed and announced again.\n   */\n  #announce(message: string, assertive: boolean): void {\n    const region = this.#regionFor(assertive ? \"assertive\" : \"polite\");\n\n    if (this.dedupeReannounceValue && region.textContent === message) {\n      region.textContent = \"\";\n      this.#timers.set(() => {\n        region.textContent = message;\n        this.#scheduleClear(region, message);\n      }, 0);\n      return;\n    }\n\n    region.textContent = message;\n    this.#scheduleClear(region, message);\n  }\n\n  /** Clears the region after `clearAfter` ms, unless a newer message replaced it. */\n  #scheduleClear(region: HTMLElement, message: string): void {\n    if (this.clearAfterValue <= 0) return;\n    this.#timers.set(() => {\n      if (region.textContent === message) region.textContent = \"\";\n    }, this.clearAfterValue);\n  }\n\n  /** Resolves the live region for a politeness level, generating it if absent. */\n  #regionFor(level: \"assertive\" | \"polite\"): HTMLElement {\n    if (level === \"assertive\" && this.hasAssertiveTarget) return this.assertiveTarget;\n    if (level === \"polite\" && this.hasPoliteTarget) return this.politeTarget;\n\n    const existing = this.#generated.get(level);\n    if (existing) return existing;\n\n    const region = document.createElement(\"div\");\n    region.setAttribute(\"aria-live\", level);\n    region.setAttribute(\"aria-atomic\", \"true\");\n    visuallyHide(region);\n    this.element.appendChild(region);\n    this.#generated.set(level, region);\n    return region;\n  }\n\n  /** Extracts a non-empty string `message` from a CustomEvent detail, else null. */\n  #messageFromDetail(detail: unknown): string | null {\n    if (detail && typeof detail === \"object\" && \"message\" in detail) {\n      const value = (detail as Record<string, unknown>).message;\n      if (typeof value === \"string\" && value.length > 0) return value;\n    }\n    return null;\n  }\n\n  /** Reads an `assertive === true` flag from a CustomEvent detail (default polite). */\n  #assertiveFromDetail(detail: unknown): boolean {\n    return (\n      !!detail &&\n      typeof detail === \"object\" &&\n      (detail as Record<string, unknown>).assertive === true\n    );\n  }\n}\n\n/**\n * Applies the canonical visually-hidden (\"sr-only\") inline style to a generated\n * live region so its text is announced without being seen. Inline so the library\n * stays self-contained when the consumer provides no target/CSS of its own.\n *\n * Pure (no `this`); exported for direct unit testing.\n */\nexport function visuallyHide(node: HTMLElement): void {\n  const { style } = node;\n  style.position = \"absolute\";\n  style.width = \"1px\";\n  style.height = \"1px\";\n  style.margin = \"-1px\";\n  style.padding = \"0\";\n  style.border = \"0\";\n  style.overflow = \"hidden\";\n  style.clip = \"rect(0 0 0 0)\";\n  style.clipPath = \"inset(50%)\";\n  style.whiteSpace = \"nowrap\";\n}\n"]}

package/dist/controllers/aspect_ratio_controller.d.ts

@@ -0,0 +1,39 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless **Aspect Ratio** helper. No APG pattern — a pure layout utility with
+ * no role or state.
+ *
+ * Markup contract (identifier: `stimeo--aspect-ratio`):
+ *   <div data-controller="stimeo--aspect-ratio"
+ *        data-stimeo--aspect-ratio-ratio-value="16/9">
+ *     <img src="/cover.jpg" alt="Cover"
+ *          data-stimeo--aspect-ratio-target="content" />
+ *   </div>
+ *
+ * Supplies the requested ratio as the `--stimeo-aspect-ratio` custom property on
+ * the host so consumer CSS can drive the box (`aspect-ratio: var(--stimeo-aspect-ratio)`)
+ * or a padding-hack fallback. The drawing itself — `aspect-ratio`, `object-fit`,
+ * cropping — stays in the consumer's stylesheet.
+ *
+ * @remarks
+ * Behavior only. The value accepts the CSS `<ratio>` forms `"16/9"` and a bare
+ * number string (`"1.5"`); it is normalized to `"w / h"` (or the number) and an
+ * unparseable value falls back to the default `1 / 1` rather than writing garbage
+ * into the custom property. The reflection re-runs when the value changes.
+ */
+declare class AspectRatioController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        ratio: {
+            type: StringConstructor;
+            default: string;
+        };
+    };
+    ratioValue: string;
+    /** Applies the ratio on connect and whenever the value changes. */
+    ratioValueChanged(): void;
+}
+
+export { AspectRatioController };

package/dist/controllers/aspect_ratio_controller.js

@@ -0,0 +1,36 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/aspect_ratio_controller.ts
+var AspectRatioController = class extends Controller {
+  static targets = ["content"];
+  static values = {
+    ratio: { type: String, default: "1/1" }
+  };
+  /** Applies the ratio on connect and whenever the value changes. */
+  ratioValueChanged() {
+    this.element.style.setProperty("--stimeo-aspect-ratio", this.#normalizeRatio(this.ratioValue));
+  }
+  /**
+   * Normalizes a ratio string to a valid CSS `<ratio>`:
+   * - `"16/9"` / `"16 / 9"` → `"16 / 9"` (both parts must be positive numbers)
+   * - `"1.5"` → `"1.5"` (a bare positive number)
+   * - anything else → `"1 / 1"` (the default), so the custom property is always valid.
+   */
+  #normalizeRatio(raw) {
+    const value = raw.trim();
+    if (value.includes("/")) {
+      const [w, h] = value.split("/").map((part) => Number.parseFloat(part.trim()));
+      if (this.#isPositive(w) && this.#isPositive(h)) return `${w} / ${h}`;
+      return "1 / 1";
+    }
+    const single = Number.parseFloat(value);
+    return this.#isPositive(single) ? String(single) : "1 / 1";
+  }
+  #isPositive(value) {
+    return value !== void 0 && Number.isFinite(value) && value > 0;
+  }
+};
+
+export { AspectRatioController };
+//# sourceMappingURL=aspect_ratio_controller.js.map
+//# sourceMappingURL=aspect_ratio_controller.js.map

package/dist/controllers/aspect_ratio_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/controllers/aspect_ratio_controller.ts"],"names":[],"mappings":";;;AAwBO,IAAM,qBAAA,GAAN,cAAoC,UAAA,CAAwB;AAAA,EACjE,OAAgB,OAAA,GAAU,CAAC,SAAS,CAAA;AAAA,EACpC,OAAgB,MAAA,GAAS;AAAA,IACvB,KAAA,EAAO,EAAE,IAAA,EAAM,MAAA,EAAQ,SAAS,KAAA;AAAM,GACxC;AAAA;AAAA,EAKA,iBAAA,GAA0B;AACxB,IAAA,IAAA,CAAK,OAAA,CAAQ,MAAM,WAAA,CAAY,uBAAA,EAAyB,KAAK,eAAA,CAAgB,IAAA,CAAK,UAAU,CAAC,CAAA;AAAA,EAC/F;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,gBAAgB,GAAA,EAAqB;AACnC,IAAA,MAAM,KAAA,GAAQ,IAAI,IAAA,EAAK;AACvB,IAAA,IAAI,KAAA,CAAM,QAAA,CAAS,GAAG,CAAA,EAAG;AACvB,MAAA,MAAM,CAAC,CAAA,EAAG,CAAC,CAAA,GAAI,KAAA,CAAM,MAAM,GAAG,CAAA,CAAE,GAAA,CAAI,CAAC,SAAS,MAAA,CAAO,UAAA,CAAW,IAAA,CAAK,IAAA,EAAM,CAAC,CAAA;AAC5E,MAAA,IAAI,IAAA,CAAK,WAAA,CAAY,CAAC,CAAA,IAAK,IAAA,CAAK,WAAA,CAAY,CAAC,CAAA,EAAG,OAAO,CAAA,EAAG,CAAC,CAAA,GAAA,EAAM,CAAC,CAAA,CAAA;AAClE,MAAA,OAAO,OAAA;AAAA,IACT;AACA,IAAA,MAAM,MAAA,GAAS,MAAA,CAAO,UAAA,CAAW,KAAK,CAAA;AACtC,IAAA,OAAO,KAAK,WAAA,CAAY,MAAM,CAAA,GAAI,MAAA,CAAO,MAAM,CAAA,GAAI,OAAA;AAAA,EACrD;AAAA,EAEA,YAAY,KAAA,EAA4C;AACtD,IAAA,OAAO,UAAU,MAAA,IAAa,MAAA,CAAO,QAAA,CAAS,KAAK,KAAK,KAAA,GAAQ,CAAA;AAAA,EAClE;AACF","file":"aspect_ratio_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\n\n/**\n * Headless **Aspect Ratio** helper. No APG pattern — a pure layout utility with\n * no role or state.\n *\n * Markup contract (identifier: `stimeo--aspect-ratio`):\n *   <div data-controller=\"stimeo--aspect-ratio\"\n *        data-stimeo--aspect-ratio-ratio-value=\"16/9\">\n *     <img src=\"/cover.jpg\" alt=\"Cover\"\n *          data-stimeo--aspect-ratio-target=\"content\" />\n *   </div>\n *\n * Supplies the requested ratio as the `--stimeo-aspect-ratio` custom property on\n * the host so consumer CSS can drive the box (`aspect-ratio: var(--stimeo-aspect-ratio)`)\n * or a padding-hack fallback. The drawing itself — `aspect-ratio`, `object-fit`,\n * cropping — stays in the consumer's stylesheet.\n *\n * @remarks\n * Behavior only. The value accepts the CSS `<ratio>` forms `\"16/9\"` and a bare\n * number string (`\"1.5\"`); it is normalized to `\"w / h\"` (or the number) and an\n * unparseable value falls back to the default `1 / 1` rather than writing garbage\n * into the custom property. The reflection re-runs when the value changes.\n */\nexport class AspectRatioController extends Controller<HTMLElement> {\n  static override targets = [\"content\"];\n  static override values = {\n    ratio: { type: String, default: \"1/1\" },\n  };\n\n  declare ratioValue: string;\n\n  /** Applies the ratio on connect and whenever the value changes. */\n  ratioValueChanged(): void {\n    this.element.style.setProperty(\"--stimeo-aspect-ratio\", this.#normalizeRatio(this.ratioValue));\n  }\n\n  /**\n   * Normalizes a ratio string to a valid CSS `<ratio>`:\n   * - `\"16/9\"` / `\"16 / 9\"` → `\"16 / 9\"` (both parts must be positive numbers)\n   * - `\"1.5\"` → `\"1.5\"` (a bare positive number)\n   * - anything else → `\"1 / 1\"` (the default), so the custom property is always valid.\n   */\n  #normalizeRatio(raw: string): string {\n    const value = raw.trim();\n    if (value.includes(\"/\")) {\n      const [w, h] = value.split(\"/\").map((part) => Number.parseFloat(part.trim()));\n      if (this.#isPositive(w) && this.#isPositive(h)) return `${w} / ${h}`;\n      return \"1 / 1\";\n    }\n    const single = Number.parseFloat(value);\n    return this.#isPositive(single) ? String(single) : \"1 / 1\";\n  }\n\n  #isPositive(value: number | undefined): value is number {\n    return value !== undefined && Number.isFinite(value) && value > 0;\n  }\n}\n"]}