stimeo-ui 0.1.0-alpha.1

package/dist/controllers/dropdown_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/controllers/dropdown_controller.ts"],"names":[],"mappings":";;;AAyBO,IAAM,kBAAA,GAAN,cAAiC,UAAA,CAAwB;AAAA,EAC9D,OAAgB,OAAA,GAAU,CAAC,SAAA,EAAW,MAAM,CAAA;AAAA,EAC5C,OAAO,OAAA,GAAU,CAAC,OAAA,EAAS,QAAQ,QAAQ,CAAA;AAAA;AAAA,EAQlC,eAAA,GAAkB,CAAC,KAAA,KAA4B;AACtD,IAAA,IAAI,CAAC,IAAA,CAAK,OAAA,CAAQ,QAAA,CAAS,KAAA,CAAM,MAAc,CAAA,EAAG;AAChD,MAAA,IAAA,CAAK,KAAA,EAAM;AAAA,IACb;AAAA,EACF,CAAA;AAAA;AAAA,EAGS,UAAA,GAAa,CAAC,KAAA,KAA+B;AACpD,IAAA,IAAI,KAAA,CAAM,GAAA,KAAQ,QAAA,IAAY,IAAA,CAAK,OAAA,EAAS;AAC1C,MAAA,IAAA,CAAK,KAAA,EAAM;AACX,MAAA,IAAI,IAAA,CAAK,gBAAA,EAAkB,IAAA,CAAK,aAAA,CAAc,KAAA,EAAM;AAAA,IACtD;AAAA,EACF,CAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMS,OAAA,GAAgB;AACvB,IAAA,IAAA,CAAK,KAAA,EAAM;AACX,IAAA,QAAA,CAAS,gBAAA,CAAiB,OAAA,EAAS,IAAA,CAAK,eAAe,CAAA;AACvD,IAAA,QAAA,CAAS,gBAAA,CAAiB,SAAA,EAAW,IAAA,CAAK,UAAU,CAAA;AAAA,EACtD;AAAA;AAAA,EAGS,UAAA,GAAmB;AAC1B,IAAA,QAAA,CAAS,mBAAA,CAAoB,OAAA,EAAS,IAAA,CAAK,eAAe,CAAA;AAC1D,IAAA,QAAA,CAAS,mBAAA,CAAoB,SAAA,EAAW,IAAA,CAAK,UAAU,CAAA;AAAA,EACzD;AAAA;AAAA,EAGA,MAAA,GAAe;AACb,IAAA,IAAI,KAAK,OAAA,EAAS;AAChB,MAAA,IAAA,CAAK,KAAA,EAAM;AAAA,IACb,CAAA,MAAO;AACL,MAAA,IAAA,CAAK,IAAA,EAAK;AAAA,IACZ;AAAA,EACF;AAAA;AAAA,EAGA,IAAA,GAAa;AACX,IAAA,IAAI,CAAC,KAAK,aAAA,EAAe;AACzB,IAAA,IAAA,CAAK,WAAW,MAAA,GAAS,KAAA;AACzB,IAAA,IAAI,KAAK,gBAAA,EAAkB;AACzB,MAAA,IAAA,CAAK,aAAA,CAAc,YAAA,CAAa,eAAA,EAAiB,MAAM,CAAA;AAAA,IACzD;AAAA,EACF;AAAA;AAAA,EAGA,KAAA,GAAc;AACZ,IAAA,IAAI,CAAC,KAAK,aAAA,EAAe;AACzB,IAAA,IAAA,CAAK,WAAW,MAAA,GAAS,IAAA;AACzB,IAAA,IAAI,KAAK,gBAAA,EAAkB;AACzB,MAAA,IAAA,CAAK,aAAA,CAAc,YAAA,CAAa,eAAA,EAAiB,OAAO,CAAA;AAAA,IAC1D;AAAA,EACF;AAAA;AAAA,EAGA,IAAI,OAAA,GAAmB;AACrB,IAAA,OAAO,IAAA,CAAK,aAAA,IAAiB,CAAC,IAAA,CAAK,UAAA,CAAW,MAAA;AAAA,EAChD;AACF","file":"dropdown_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\n\n/**\n * Headless, accessible dropdown menu behavior.\n *\n * Markup contract (identifier: `stimeo--dropdown`):\n *   <div data-controller=\"stimeo--dropdown\">\n *     <button data-stimeo--dropdown-target=\"trigger\"\n *             data-action=\"stimeo--dropdown#toggle\">Menu</button>\n *     <div data-stimeo--dropdown-target=\"menu\">...</div>\n *   </div>\n *\n * This is a **disclosure** pattern (WAI-ARIA APG): a button toggles the\n * visibility of an adjacent region. It is intentionally *not* a full APG\n * \"menu\" widget — there is no roving-tabindex arrow-key navigation.\n *\n * @remarks\n * The library owns behavior only (ARIA state, keyboard, focus, outside-click).\n * Visual styling is left entirely to the consumer's CSS.\n *\n * Behavior provided:\n * - Click the trigger to toggle the menu (`aria-expanded` + `hidden` reflect state).\n * - `Escape` closes the menu and returns focus to the trigger.\n * - A click outside the controller element closes the menu.\n */\nexport class DropdownController extends Controller<HTMLElement> {\n  static override targets = [\"trigger\", \"menu\"];\n  static actions = [\"close\", \"open\", \"toggle\"] as const;\n\n  declare readonly triggerTarget: HTMLButtonElement;\n  declare readonly menuTarget: HTMLElement;\n  declare readonly hasMenuTarget: boolean;\n  declare readonly hasTriggerTarget: boolean;\n\n  /** Closes the menu when a click lands outside the controller's element. */\n  readonly #onOutsideClick = (event: MouseEvent): void => {\n    if (!this.element.contains(event.target as Node)) {\n      this.close();\n    }\n  };\n\n  /** Closes the menu on `Escape` and restores focus to the trigger. */\n  readonly #onKeydown = (event: KeyboardEvent): void => {\n    if (event.key === \"Escape\" && this.#isOpen) {\n      this.close();\n      if (this.hasTriggerTarget) this.triggerTarget.focus();\n    }\n  };\n\n  /**\n   * Starts in the closed state and registers the document-level listeners that\n   * power outside-click and `Escape` handling.\n   */\n  override connect(): void {\n    this.close();\n    document.addEventListener(\"click\", this.#onOutsideClick);\n    document.addEventListener(\"keydown\", this.#onKeydown);\n  }\n\n  /** Removes the document-level listeners registered in {@link connect}. */\n  override disconnect(): void {\n    document.removeEventListener(\"click\", this.#onOutsideClick);\n    document.removeEventListener(\"keydown\", this.#onKeydown);\n  }\n\n  /** Toggles the menu between open and closed. Bound via `data-action`. */\n  toggle(): void {\n    if (this.#isOpen) {\n      this.close();\n    } else {\n      this.open();\n    }\n  }\n\n  /** Reveals the menu and reflects the open state on the trigger. */\n  open(): void {\n    if (!this.hasMenuTarget) return;\n    this.menuTarget.hidden = false;\n    if (this.hasTriggerTarget) {\n      this.triggerTarget.setAttribute(\"aria-expanded\", \"true\");\n    }\n  }\n\n  /** Hides the menu and reflects the closed state on the trigger. */\n  close(): void {\n    if (!this.hasMenuTarget) return;\n    this.menuTarget.hidden = true;\n    if (this.hasTriggerTarget) {\n      this.triggerTarget.setAttribute(\"aria-expanded\", \"false\");\n    }\n  }\n\n  /** Whether the menu is currently visible. */\n  get #isOpen(): boolean {\n    return this.hasMenuTarget && !this.menuTarget.hidden;\n  }\n}\n"]}

package/dist/controllers/empty_state_controller.d.ts

@@ -0,0 +1,60 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless empty-state behavior: shows an "empty" placeholder when a list has no
+ * items and hides it once one arrives (and vice-versa), watching the list with a
+ * `MutationObserver` (no dedicated APG pattern; follows the WCAG "status messages"
+ * practice when announcing).
+ *
+ * Markup contract (identifier: `stimeo--empty-state`):
+ *   <div data-controller="stimeo--empty-state">
+ *     <ul data-stimeo--empty-state-target="list"><!-- Turbo Stream rows --></ul>
+ *     <p data-stimeo--empty-state-target="empty" hidden>No items</p>
+ *   </div>
+ *
+ * Counts `list`'s child items (all element children, or those matching
+ * `itemSelector`) on connect and on every childList mutation, toggles `hidden` on
+ * `list` / `empty` at the 0 ↔ 1+ boundary, and reflects `data-empty` / `data-count`
+ * on the controller element. Crossing the boundary dispatches `change`.
+ *
+ * @remarks
+ * Behavior only — the placeholder's look/copy is the consumer's. State is derived
+ * from the DOM (no module-scope state), so `connect()` re-syncs after a Turbo
+ * Stream insertion. The `MutationObserver` is severed on `disconnect()` (Turbo
+ * navigation included). With `announce`, the `empty` target is made a polite live
+ * region (only if the author hasn't already), so showing it is announced — SR
+ * support for unhiding a live region varies; pair with Announcer for a guarantee.
+ *
+ * Ownership note: this controller deliberately owns `hidden` on the `list` / `empty`
+ * targets as its single source of truth for which one is shown, rather than only
+ * emitting `data-empty` and delegating visibility to consumer CSS. The toggle is
+ * unconditional (set every sync), so there is nothing to save/restore and no
+ * authored `hidden` to preserve — the displayed half is always a pure function of
+ * the item count. Consumers wanting CSS-driven visibility should not also set
+ * `hidden` on these targets themselves.
+ */
+declare class EmptyStateController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        itemSelector: {
+            type: StringConstructor;
+            default: string;
+        };
+        announce: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+    };
+    static events: readonly ["change"];
+    readonly listTarget: HTMLElement;
+    readonly emptyTarget: HTMLElement;
+    readonly hasListTarget: boolean;
+    readonly hasEmptyTarget: boolean;
+    itemSelectorValue: string;
+    announceValue: boolean;
+    connect(): void;
+    disconnect(): void;
+}
+
+export { EmptyStateController };

package/dist/controllers/empty_state_controller.js

@@ -0,0 +1,67 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/empty_state_controller.ts
+var EmptyStateController = class extends Controller {
+  static targets = ["list", "empty"];
+  static values = {
+    itemSelector: { type: String, default: "" },
+    announce: { type: Boolean, default: false }
+  };
+  static events = ["change"];
+  #observer = null;
+  /** Last applied empty state; `null` until the first sync so connect emits nothing. */
+  #empty = null;
+  connect() {
+    if (!this.hasListTarget) return;
+    if (this.announceValue && this.hasEmptyTarget && !this.#isLiveRegion(this.emptyTarget)) {
+      this.emptyTarget.setAttribute("role", "status");
+      this.emptyTarget.setAttribute("aria-live", "polite");
+    }
+    if (typeof MutationObserver !== "undefined") {
+      this.#observer = new MutationObserver(() => this.#apply());
+      this.#observer.observe(this.listTarget, { childList: true });
+    }
+    this.#apply();
+  }
+  disconnect() {
+    this.#observer?.disconnect();
+    this.#observer = null;
+  }
+  /** Recomputes the count and syncs visibility, hooks, and the change event. */
+  #apply() {
+    if (!this.hasListTarget) return;
+    const count = this.#count();
+    const empty = count === 0;
+    this.element.setAttribute("data-count", String(count));
+    if (empty) {
+      this.element.setAttribute("data-empty", "true");
+    } else {
+      this.element.removeAttribute("data-empty");
+    }
+    this.listTarget.hidden = empty;
+    if (this.hasEmptyTarget) this.emptyTarget.hidden = !empty;
+    if (this.#empty !== null && empty !== this.#empty) {
+      this.dispatch("change", { detail: { count, empty } });
+    }
+    this.#empty = empty;
+  }
+  /** Item count: element children matching `itemSelector`, or all element children. */
+  #count() {
+    const selector = this.itemSelectorValue;
+    if (selector.length === 0) return this.listTarget.childElementCount;
+    try {
+      return Array.from(this.listTarget.children).filter((child) => child.matches(selector)).length;
+    } catch {
+      return this.listTarget.childElementCount;
+    }
+  }
+  #isLiveRegion(el) {
+    if (el.hasAttribute("aria-live")) return true;
+    const role = el.getAttribute("role");
+    return role === "status" || role === "alert";
+  }
+};
+
+export { EmptyStateController };
+//# sourceMappingURL=empty_state_controller.js.map
+//# sourceMappingURL=empty_state_controller.js.map

package/dist/controllers/empty_state_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/controllers/empty_state_controller.ts"],"names":[],"mappings":"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","file":"empty_state_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\n\n/**\n * Headless empty-state behavior: shows an \"empty\" placeholder when a list has no\n * items and hides it once one arrives (and vice-versa), watching the list with a\n * `MutationObserver` (no dedicated APG pattern; follows the WCAG \"status messages\"\n * practice when announcing).\n *\n * Markup contract (identifier: `stimeo--empty-state`):\n *   <div data-controller=\"stimeo--empty-state\">\n *     <ul data-stimeo--empty-state-target=\"list\"><!-- Turbo Stream rows --></ul>\n *     <p data-stimeo--empty-state-target=\"empty\" hidden>No items</p>\n *   </div>\n *\n * Counts `list`'s child items (all element children, or those matching\n * `itemSelector`) on connect and on every childList mutation, toggles `hidden` on\n * `list` / `empty` at the 0 ↔ 1+ boundary, and reflects `data-empty` / `data-count`\n * on the controller element. Crossing the boundary dispatches `change`.\n *\n * @remarks\n * Behavior only — the placeholder's look/copy is the consumer's. State is derived\n * from the DOM (no module-scope state), so `connect()` re-syncs after a Turbo\n * Stream insertion. The `MutationObserver` is severed on `disconnect()` (Turbo\n * navigation included). With `announce`, the `empty` target is made a polite live\n * region (only if the author hasn't already), so showing it is announced — SR\n * support for unhiding a live region varies; pair with Announcer for a guarantee.\n *\n * Ownership note: this controller deliberately owns `hidden` on the `list` / `empty`\n * targets as its single source of truth for which one is shown, rather than only\n * emitting `data-empty` and delegating visibility to consumer CSS. The toggle is\n * unconditional (set every sync), so there is nothing to save/restore and no\n * authored `hidden` to preserve — the displayed half is always a pure function of\n * the item count. Consumers wanting CSS-driven visibility should not also set\n * `hidden` on these targets themselves.\n */\nexport class EmptyStateController extends Controller<HTMLElement> {\n  static override targets = [\"list\", \"empty\"];\n  static override values = {\n    itemSelector: { type: String, default: \"\" },\n    announce: { type: Boolean, default: false },\n  };\n  static events = [\"change\"] as const;\n\n  declare readonly listTarget: HTMLElement;\n  declare readonly emptyTarget: HTMLElement;\n  declare readonly hasListTarget: boolean;\n  declare readonly hasEmptyTarget: boolean;\n\n  declare itemSelectorValue: string;\n  declare announceValue: boolean;\n\n  #observer: MutationObserver | null = null;\n  /** Last applied empty state; `null` until the first sync so connect emits nothing. */\n  #empty: boolean | null = null;\n\n  override connect(): void {\n    if (!this.hasListTarget) return;\n    if (this.announceValue && this.hasEmptyTarget && !this.#isLiveRegion(this.emptyTarget)) {\n      this.emptyTarget.setAttribute(\"role\", \"status\");\n      this.emptyTarget.setAttribute(\"aria-live\", \"polite\");\n    }\n    if (typeof MutationObserver !== \"undefined\") {\n      this.#observer = new MutationObserver(() => this.#apply());\n      this.#observer.observe(this.listTarget, { childList: true });\n    }\n    this.#apply();\n  }\n\n  override disconnect(): void {\n    this.#observer?.disconnect();\n    this.#observer = null;\n  }\n\n  /** Recomputes the count and syncs visibility, hooks, and the change event. */\n  #apply(): void {\n    if (!this.hasListTarget) return;\n    const count = this.#count();\n    const empty = count === 0;\n\n    this.element.setAttribute(\"data-count\", String(count));\n    if (empty) {\n      this.element.setAttribute(\"data-empty\", \"true\");\n    } else {\n      this.element.removeAttribute(\"data-empty\");\n    }\n    this.listTarget.hidden = empty;\n    if (this.hasEmptyTarget) this.emptyTarget.hidden = !empty;\n\n    // Emit only when the 0 ↔ 1+ boundary is crossed (not on the initial sync, and\n    // not for count changes that stay non-empty, e.g. 2 → 3).\n    if (this.#empty !== null && empty !== this.#empty) {\n      this.dispatch(\"change\", { detail: { count, empty } });\n    }\n    this.#empty = empty;\n  }\n\n  /** Item count: element children matching `itemSelector`, or all element children. */\n  #count(): number {\n    const selector = this.itemSelectorValue;\n    if (selector.length === 0) return this.listTarget.childElementCount;\n    try {\n      return Array.from(this.listTarget.children).filter((child) => child.matches(selector)).length;\n    } catch {\n      // An invalid selector (author typo) must not crash the controller — count all.\n      return this.listTarget.childElementCount;\n    }\n  }\n\n  #isLiveRegion(el: HTMLElement): boolean {\n    if (el.hasAttribute(\"aria-live\")) return true;\n    const role = el.getAttribute(\"role\");\n    return role === \"status\" || role === \"alert\";\n  }\n}\n"]}

package/dist/controllers/flash_controller.d.ts

@@ -0,0 +1,63 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless **Rails flash bridge**: turns server-rendered (and Turbo Stream-inserted)
+ * `flash` elements into live-region announcements with auto-dismiss and a stacking
+ * cap (no dedicated APG pattern; follows the WAI-ARIA status/alert guidance and WCAG
+ * 2.2 **4.1.3 Status Messages**). The general-purpose sibling is Toast; this one is
+ * specialized to the Rails `flash` convention.
+ *
+ * Markup contract (identifier: `stimeo--flash`):
+ *   <div data-controller="stimeo--flash" data-stimeo--flash-target="region">
+ *     <!-- server-rendered or Turbo Stream-inserted -->
+ *     <div data-stimeo--flash-target="message" data-flash-type="notice">Saved</div>
+ *   </div>
+ *
+ * Each message is mapped by `data-flash-type` to `role="status"` (notice) or
+ * `role="alert"` (alert/error), flagged `data-flash-state="visible"`, auto-dismissed
+ * after `duration` (paused while hovered/focused when `pauseOnHover`), and capped at
+ * `max` simultaneous messages. A close button wired to the `dismiss` action removes
+ * one manually.
+ *
+ * @remarks
+ * Reading is **delegated to the shared Announcer** — but only for the *initial*,
+ * page-loaded messages: an in-place live region present at load is not announced by
+ * assistive tech, so the controller bridges those via an `stimeo--announcer:announce`
+ * event. Messages inserted *later* (Turbo Stream) are announced by their own freshly
+ * inserted `role`, exactly like Toast, so they are not bridged again (no double
+ * announcement). Behavior only — no styling; `data-flash-state="leaving"` lets CSS
+ * animate removal. Focus is never moved (WCAG 2.2 4.1.3). The observer, timers, and
+ * per-message listeners are torn down on `disconnect()` (Turbo navigation included).
+ */
+declare class FlashController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        duration: {
+            type: NumberConstructor;
+            default: number;
+        };
+        pauseOnHover: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        max: {
+            type: NumberConstructor;
+            default: number;
+        };
+    };
+    static actions: readonly ["dismiss"];
+    static events: readonly ["show", "dismiss"];
+    readonly regionTarget: HTMLElement;
+    readonly messageTargets: HTMLElement[];
+    readonly hasRegionTarget: boolean;
+    durationValue: number;
+    pauseOnHoverValue: boolean;
+    maxValue: number;
+    connect(): void;
+    disconnect(): void;
+    /** Dismisses the flash whose close control fired the event. */
+    dismiss(event: Event): void;
+}
+
+export { FlashController };

package/dist/controllers/flash_controller.js

@@ -0,0 +1,221 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/flash_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/flash_controller.ts
+var ASSERTIVE_TYPES = /* @__PURE__ */ new Set(["alert", "error"]);
+var MESSAGE_SELECTOR = '[data-stimeo--flash-target="message"]';
+var FlashController = class extends Controller {
+  static targets = ["region", "message"];
+  static values = {
+    duration: { type: Number, default: 5e3 },
+    pauseOnHover: { type: Boolean, default: true },
+    max: { type: Number, default: 0 }
+  };
+  static actions = ["dismiss"];
+  static events = ["show", "dismiss"];
+  #timers = new SafeTimeout();
+  #observer = null;
+  /** Auto-dismiss timer state keyed by message element. */
+  #state = /* @__PURE__ */ new Map();
+  /** Messages already processed, in insertion order, to enforce `max` and avoid double work. */
+  #order = [];
+  #onEnter = (event) => this.#pause(event.currentTarget);
+  #onLeave = (event) => this.#resume(event.currentTarget);
+  connect() {
+    if (!this.hasRegionTarget) return;
+    for (const message of this.messageTargets) {
+      this.#process(message, true);
+    }
+    if (typeof MutationObserver !== "undefined") {
+      this.#observer = new MutationObserver((mutations) => this.#onMutations(mutations));
+      this.#observer.observe(this.regionTarget, { childList: true, subtree: true });
+    }
+  }
+  disconnect() {
+    this.#observer?.disconnect();
+    this.#observer = null;
+    this.#timers.clearAll();
+    for (const message of this.#order) this.#unbindPause(message);
+    this.#state.clear();
+    this.#order.length = 0;
+  }
+  /**
+   * Pause-on-hover/focus listeners, bound and unbound as a pair so the two sides
+   * stay in sync. Binding is gated by `pauseOnHover`; unbinding is unconditional
+   * and idempotent (a no-op when nothing was bound), which keeps teardown correct
+   * even if `pauseOnHover` were ever toggled during a message's life.
+   */
+  #bindPause(message) {
+    if (!this.pauseOnHoverValue) return;
+    message.addEventListener("mouseenter", this.#onEnter);
+    message.addEventListener("mouseleave", this.#onLeave);
+    message.addEventListener("focusin", this.#onEnter);
+    message.addEventListener("focusout", this.#onLeave);
+  }
+  #unbindPause(message) {
+    message.removeEventListener("mouseenter", this.#onEnter);
+    message.removeEventListener("mouseleave", this.#onLeave);
+    message.removeEventListener("focusin", this.#onEnter);
+    message.removeEventListener("focusout", this.#onLeave);
+  }
+  /** Dismisses the flash whose close control fired the event. */
+  dismiss(event) {
+    const target = event.currentTarget || event.target;
+    const message = target?.closest(MESSAGE_SELECTOR);
+    if (message) this.#beginDismiss(message, "user");
+  }
+  /** Processes messages added after connect (Turbo Stream); their own role announces them. */
+  #onMutations(mutations) {
+    for (const mutation of mutations) {
+      for (const node of mutation.addedNodes) {
+        if (!(node instanceof HTMLElement)) continue;
+        if (node.matches(MESSAGE_SELECTOR)) this.#process(node, false);
+        for (const message of node.querySelectorAll(MESSAGE_SELECTOR)) {
+          this.#process(message, false);
+        }
+      }
+    }
+  }
+  /**
+   * Applies role/state, wires pause listeners, schedules auto-dismiss, and either
+   * bridges to the Announcer (`bridge`, for initial flashes) or leaves the message's
+   * own role to do the announcing (dynamic inserts). Idempotent per message.
+   */
+  #process(message, bridge) {
+    if (this.#state.has(message) || this.#order.includes(message)) return;
+    const type = message.getAttribute("data-flash-type") ?? "";
+    const assertive = ASSERTIVE_TYPES.has(type);
+    if (!message.hasAttribute("role")) {
+      message.setAttribute("role", assertive ? "alert" : "status");
+    }
+    message.setAttribute("data-flash-state", "visible");
+    this.#order.push(message);
+    this.#bindPause(message);
+    const text = message.textContent?.trim() ?? "";
+    this.dispatch("show", { target: message, detail: { type, message: text } });
+    if (bridge && text) {
+      window.dispatchEvent(
+        new CustomEvent("stimeo--announcer:announce", { detail: { message: text, assertive } })
+      );
+    }
+    this.#startTimer(message);
+    this.#enforceMax();
+  }
+  /** Removes the oldest visible flashes once the count exceeds `max` (0 = unlimited). */
+  #enforceMax() {
+    if (this.maxValue <= 0) return;
+    while (this.#order.length > this.maxValue) {
+      const oldest = this.#order[0];
+      if (!oldest) break;
+      this.#beginDismiss(oldest, "limit");
+    }
+  }
+  #startTimer(message, duration = this.durationValue) {
+    if (duration <= 0) return;
+    const existing = this.#state.get(message);
+    if (existing?.id) this.#timers.clear(existing.id);
+    const id = this.#timers.set(() => this.#beginDismiss(message, "timeout"), duration);
+    this.#state.set(message, { id, startedAt: Date.now(), remaining: duration });
+  }
+  /** Pauses a message's auto-dismiss, banking the time left (hover/focus, WCAG 2.2.1). */
+  #pause(message) {
+    const timer = this.#state.get(message);
+    if (!timer || timer.id === 0) return;
+    this.#timers.clear(timer.id);
+    const remaining = Math.max(0, timer.remaining - (Date.now() - timer.startedAt));
+    this.#state.set(message, { id: 0, startedAt: 0, remaining });
+  }
+  /** Resumes a paused message's auto-dismiss with the banked time. */
+  #resume(message) {
+    const timer = this.#state.get(message);
+    if (!timer) return;
+    if (timer.id !== 0 || timer.remaining <= 0) return;
+    this.#startTimer(message, timer.remaining);
+  }
+  /** Marks a message leaving, then removes it after its CSS transition and emits dismiss. */
+  #beginDismiss(message, reason) {
+    const timer = this.#state.get(message);
+    if (timer?.id) this.#timers.clear(timer.id);
+    this.#state.delete(message);
+    const index = this.#order.indexOf(message);
+    if (index !== -1) this.#order.splice(index, 1);
+    message.setAttribute("data-flash-state", "leaving");
+    const finalize = () => {
+      this.#unbindPause(message);
+      message.remove();
+      this.dispatch("dismiss", { detail: { element: message, reason } });
+    };
+    const transition = this.#transitionMs(message);
+    if (transition > 0) {
+      this.#timers.set(finalize, transition);
+    } else {
+      finalize();
+    }
+  }
+  /** First `transition-duration` of `el` in ms (0 when none / unsupported). */
+  #transitionMs(el) {
+    if (typeof window.getComputedStyle !== "function") return 0;
+    const first = window.getComputedStyle(el).transitionDuration.split(",")[0]?.trim() ?? "";
+    const amount = Number.parseFloat(first);
+    if (Number.isNaN(amount)) return 0;
+    return first.endsWith("ms") ? amount : amount * 1e3;
+  }
+};
+
+export { FlashController };
+//# sourceMappingURL=flash_controller.js.map
+//# sourceMappingURL=flash_controller.js.map

package/dist/controllers/flash_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/safe_timeout.ts","../../src/controllers/flash_controller.ts"],"names":[],"mappings":"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","file":"flash_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/** Flash types that map to an assertive `alert` (everything else is a polite `status`). */\nconst ASSERTIVE_TYPES = new Set([\"alert\", \"error\"]);\n\n/** Selector for message targets, used by the MutationObserver to spot dynamic inserts. */\nconst MESSAGE_SELECTOR = '[data-stimeo--flash-target=\"message\"]';\n\n/** Per-message auto-dismiss timer bookkeeping (id 0 means paused). */\ninterface FlashTimer {\n  id: number;\n  startedAt: number;\n  remaining: number;\n}\n\n/**\n * Headless **Rails flash bridge**: turns server-rendered (and Turbo Stream-inserted)\n * `flash` elements into live-region announcements with auto-dismiss and a stacking\n * cap (no dedicated APG pattern; follows the WAI-ARIA status/alert guidance and WCAG\n * 2.2 **4.1.3 Status Messages**). The general-purpose sibling is Toast; this one is\n * specialized to the Rails `flash` convention.\n *\n * Markup contract (identifier: `stimeo--flash`):\n *   <div data-controller=\"stimeo--flash\" data-stimeo--flash-target=\"region\">\n *     <!-- server-rendered or Turbo Stream-inserted -->\n *     <div data-stimeo--flash-target=\"message\" data-flash-type=\"notice\">Saved</div>\n *   </div>\n *\n * Each message is mapped by `data-flash-type` to `role=\"status\"` (notice) or\n * `role=\"alert\"` (alert/error), flagged `data-flash-state=\"visible\"`, auto-dismissed\n * after `duration` (paused while hovered/focused when `pauseOnHover`), and capped at\n * `max` simultaneous messages. A close button wired to the `dismiss` action removes\n * one manually.\n *\n * @remarks\n * Reading is **delegated to the shared Announcer** — but only for the *initial*,\n * page-loaded messages: an in-place live region present at load is not announced by\n * assistive tech, so the controller bridges those via an `stimeo--announcer:announce`\n * event. Messages inserted *later* (Turbo Stream) are announced by their own freshly\n * inserted `role`, exactly like Toast, so they are not bridged again (no double\n * announcement). Behavior only — no styling; `data-flash-state=\"leaving\"` lets CSS\n * animate removal. Focus is never moved (WCAG 2.2 4.1.3). The observer, timers, and\n * per-message listeners are torn down on `disconnect()` (Turbo navigation included).\n */\nexport class FlashController extends Controller<HTMLElement> {\n  static override targets = [\"region\", \"message\"];\n  static override values = {\n    duration: { type: Number, default: 5000 },\n    pauseOnHover: { type: Boolean, default: true },\n    max: { type: Number, default: 0 },\n  };\n  static actions = [\"dismiss\"] as const;\n  static events = [\"show\", \"dismiss\"] as const;\n\n  declare readonly regionTarget: HTMLElement;\n  declare readonly messageTargets: HTMLElement[];\n  declare readonly hasRegionTarget: boolean;\n\n  declare durationValue: number;\n  declare pauseOnHoverValue: boolean;\n  declare maxValue: number;\n\n  readonly #timers = new SafeTimeout();\n  #observer: MutationObserver | null = null;\n  /** Auto-dismiss timer state keyed by message element. */\n  readonly #state = new Map<HTMLElement, FlashTimer>();\n  /** Messages already processed, in insertion order, to enforce `max` and avoid double work. */\n  readonly #order: HTMLElement[] = [];\n\n  readonly #onEnter = (event: Event): void => this.#pause(event.currentTarget as HTMLElement);\n  readonly #onLeave = (event: Event): void => this.#resume(event.currentTarget as HTMLElement);\n\n  override connect(): void {\n    if (!this.hasRegionTarget) return;\n    // Initial, server-rendered flashes: bridge them to the Announcer because an\n    // in-place live region present at page load is not announced on its own.\n    for (const message of this.messageTargets) {\n      this.#process(message, true);\n    }\n    if (typeof MutationObserver !== \"undefined\") {\n      this.#observer = new MutationObserver((mutations) => this.#onMutations(mutations));\n      this.#observer.observe(this.regionTarget, { childList: true, subtree: true });\n    }\n  }\n\n  override disconnect(): void {\n    this.#observer?.disconnect();\n    this.#observer = null;\n    this.#timers.clearAll();\n    for (const message of this.#order) this.#unbindPause(message);\n    this.#state.clear();\n    this.#order.length = 0;\n  }\n\n  /**\n   * Pause-on-hover/focus listeners, bound and unbound as a pair so the two sides\n   * stay in sync. Binding is gated by `pauseOnHover`; unbinding is unconditional\n   * and idempotent (a no-op when nothing was bound), which keeps teardown correct\n   * even if `pauseOnHover` were ever toggled during a message's life.\n   */\n  #bindPause(message: HTMLElement): void {\n    if (!this.pauseOnHoverValue) return;\n    message.addEventListener(\"mouseenter\", this.#onEnter);\n    message.addEventListener(\"mouseleave\", this.#onLeave);\n    message.addEventListener(\"focusin\", this.#onEnter);\n    message.addEventListener(\"focusout\", this.#onLeave);\n  }\n\n  #unbindPause(message: HTMLElement): void {\n    message.removeEventListener(\"mouseenter\", this.#onEnter);\n    message.removeEventListener(\"mouseleave\", this.#onLeave);\n    message.removeEventListener(\"focusin\", this.#onEnter);\n    message.removeEventListener(\"focusout\", this.#onLeave);\n  }\n\n  /** Dismisses the flash whose close control fired the event. */\n  dismiss(event: Event): void {\n    const target = (event.currentTarget || event.target) as HTMLElement | null;\n    const message = target?.closest<HTMLElement>(MESSAGE_SELECTOR);\n    if (message) this.#beginDismiss(message, \"user\");\n  }\n\n  /** Processes messages added after connect (Turbo Stream); their own role announces them. */\n  #onMutations(mutations: MutationRecord[]): void {\n    for (const mutation of mutations) {\n      for (const node of mutation.addedNodes) {\n        if (!(node instanceof HTMLElement)) continue;\n        if (node.matches(MESSAGE_SELECTOR)) this.#process(node, false);\n        for (const message of node.querySelectorAll<HTMLElement>(MESSAGE_SELECTOR)) {\n          this.#process(message, false);\n        }\n      }\n    }\n  }\n\n  /**\n   * Applies role/state, wires pause listeners, schedules auto-dismiss, and either\n   * bridges to the Announcer (`bridge`, for initial flashes) or leaves the message's\n   * own role to do the announcing (dynamic inserts). Idempotent per message.\n   */\n  #process(message: HTMLElement, bridge: boolean): void {\n    if (this.#state.has(message) || this.#order.includes(message)) return;\n\n    const type = message.getAttribute(\"data-flash-type\") ?? \"\";\n    const assertive = ASSERTIVE_TYPES.has(type);\n    // Don't clobber an authored role; otherwise map the flash type to a live role.\n    if (!message.hasAttribute(\"role\")) {\n      message.setAttribute(\"role\", assertive ? \"alert\" : \"status\");\n    }\n    message.setAttribute(\"data-flash-state\", \"visible\");\n    this.#order.push(message);\n\n    this.#bindPause(message);\n\n    const text = message.textContent?.trim() ?? \"\";\n    this.dispatch(\"show\", { target: message, detail: { type, message: text } });\n    if (bridge && text) {\n      window.dispatchEvent(\n        new CustomEvent(\"stimeo--announcer:announce\", { detail: { message: text, assertive } }),\n      );\n    }\n\n    this.#startTimer(message);\n    this.#enforceMax();\n  }\n\n  /** Removes the oldest visible flashes once the count exceeds `max` (0 = unlimited). */\n  #enforceMax(): void {\n    if (this.maxValue <= 0) return;\n    while (this.#order.length > this.maxValue) {\n      const oldest = this.#order[0];\n      if (!oldest) break;\n      this.#beginDismiss(oldest, \"limit\");\n    }\n  }\n\n  #startTimer(message: HTMLElement, duration = this.durationValue): void {\n    if (duration <= 0) return;\n    const existing = this.#state.get(message);\n    if (existing?.id) this.#timers.clear(existing.id);\n    const id = this.#timers.set(() => this.#beginDismiss(message, \"timeout\"), duration);\n    this.#state.set(message, { id, startedAt: Date.now(), remaining: duration });\n  }\n\n  /** Pauses a message's auto-dismiss, banking the time left (hover/focus, WCAG 2.2.1). */\n  #pause(message: HTMLElement): void {\n    const timer = this.#state.get(message);\n    if (!timer || timer.id === 0) return;\n    this.#timers.clear(timer.id);\n    const remaining = Math.max(0, timer.remaining - (Date.now() - timer.startedAt));\n    this.#state.set(message, { id: 0, startedAt: 0, remaining });\n  }\n\n  /** Resumes a paused message's auto-dismiss with the banked time. */\n  #resume(message: HTMLElement): void {\n    const timer = this.#state.get(message);\n    if (!timer) return;\n    // Only resume a genuinely paused timer (id 0) that still has time banked.\n    if (timer.id !== 0 || timer.remaining <= 0) return;\n    this.#startTimer(message, timer.remaining);\n  }\n\n  /** Marks a message leaving, then removes it after its CSS transition and emits dismiss. */\n  #beginDismiss(message: HTMLElement, reason: \"timeout\" | \"user\" | \"limit\"): void {\n    const timer = this.#state.get(message);\n    if (timer?.id) this.#timers.clear(timer.id);\n    this.#state.delete(message);\n    const index = this.#order.indexOf(message);\n    if (index !== -1) this.#order.splice(index, 1);\n\n    message.setAttribute(\"data-flash-state\", \"leaving\");\n\n    const finalize = (): void => {\n      this.#unbindPause(message);\n      message.remove();\n      this.dispatch(\"dismiss\", { detail: { element: message, reason } });\n    };\n\n    const transition = this.#transitionMs(message);\n    if (transition > 0) {\n      this.#timers.set(finalize, transition);\n    } else {\n      finalize();\n    }\n  }\n\n  /** First `transition-duration` of `el` in ms (0 when none / unsupported). */\n  #transitionMs(el: HTMLElement): number {\n    if (typeof window.getComputedStyle !== \"function\") return 0;\n    const first = window.getComputedStyle(el).transitionDuration.split(\",\")[0]?.trim() ?? \"\";\n    const amount = Number.parseFloat(first);\n    if (Number.isNaN(amount)) return 0;\n    return first.endsWith(\"ms\") ? amount : amount * 1000;\n  }\n}\n"]}

package/dist/controllers/focus_controller.d.ts

@@ -0,0 +1,69 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless **focus scope**: exposes the shared {@link FocusTrap} as a standalone,
+ * declarative focus boundary — `Tab` cycling, initial focus, and restore-on-release —
+ * for any region, without building a full modal (counterpart to Alpine `focus` /
+ * Headless UI's trap). No dedicated APG pattern; it is the primitive the overlay
+ * patterns use, surfaced for direct use.
+ *
+ * Markup contract (identifier: `stimeo--focus`):
+ *   <div data-controller="stimeo--focus" data-stimeo--focus-trap-value="true">
+ *     <input data-stimeo--focus-target="initial" />
+ *     …
+ *   </div>
+ *
+ * While `trap` is on, `Tab` / `Shift+Tab` cycle within the element, focus moves to the
+ * `initial` target (or the first focusable) when `auto`, `Escape` releases it, and on
+ * release focus returns to the opener when `restore`. With `inert` the rest of the page
+ * is made `inert` (a hard, modal-style isolation); left off it is a soft boundary —
+ * `Tab` still cycles but the background stays reachable. The element carries
+ * `data-focus-trapped` while active and emits `activate` / `deactivate`.
+ *
+ * @remarks
+ * Behavior only — it does not open/close or render an overlay (pair with Dialog) and
+ * does not move DOM (pair with Portal). It reuses `src/utils/focus_trap.ts`, so it never
+ * scroll-locks the page (unlike the modal overlays) and tracks live focusable children
+ * (dynamic additions are picked up on the next `Tab`). The opener is recorded on
+ * activate and refocused on release if still present. Everything is torn down on
+ * `disconnect()` (Turbo navigation included) without yanking focus.
+ */
+declare class FocusController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        trap: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        auto: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        restore: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        inert: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+    };
+    static actions: readonly ["activate", "deactivate"];
+    static events: readonly ["activate", "deactivate"];
+    readonly initialTarget: HTMLElement;
+    readonly hasInitialTarget: boolean;
+    trapValue: boolean;
+    autoValue: boolean;
+    restoreValue: boolean;
+    inertValue: boolean;
+    /** Stimulus drives activation from the `trap` value (also fires on connect). */
+    trapValueChanged(): void;
+    disconnect(): void;
+    /** Turns the trap on. Acts synchronously and keeps the `trap` value in sync. */
+    activate(): void;
+    /** Turns the trap off (also wired to Escape). */
+    deactivate(): void;
+}
+
+export { FocusController };