stimeo-ui 0.1.0-alpha.1

package/dist/controllers/highlight_controller.js

@@ -0,0 +1,107 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/highlight_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/highlight_controller.ts
+var HighlightController = class extends Controller {
+  static values = {
+    duration: { type: Number, default: 1500 },
+    observe: { type: Boolean, default: false }
+  };
+  static events = ["start", "end"];
+  #timeouts = new SafeTimeout();
+  #observer = null;
+  connect() {
+    if (this.observeValue) {
+      if (typeof MutationObserver !== "undefined") {
+        this.#observer = new MutationObserver((mutations) => this.#onMutations(mutations));
+        this.#observer.observe(this.element, { childList: true });
+      }
+      return;
+    }
+    this.#highlight(this.element);
+  }
+  disconnect() {
+    this.#observer?.disconnect();
+    this.#observer = null;
+    this.#timeouts.clearAll();
+  }
+  /** Highlights every element child added by a childList mutation. */
+  #onMutations(mutations) {
+    for (const mutation of mutations) {
+      for (const node of mutation.addedNodes) {
+        if (node instanceof HTMLElement) this.#highlight(node);
+      }
+    }
+  }
+  /** Flags `el` with `data-highlight` and schedules its removal (unless reduced-motion). */
+  #highlight(el) {
+    if (this.#prefersReducedMotion()) return;
+    el.setAttribute("data-highlight", "true");
+    this.dispatch("start", { target: el, detail: { element: el } });
+    this.#timeouts.set(() => {
+      el.removeAttribute("data-highlight");
+      this.dispatch("end", { target: el, detail: { element: el } });
+    }, this.durationValue);
+  }
+  #prefersReducedMotion() {
+    return typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  }
+};
+
+export { HighlightController };
+//# sourceMappingURL=highlight_controller.js.map
+//# sourceMappingURL=highlight_controller.js.map

package/dist/controllers/highlight_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/safe_timeout.ts","../../src/controllers/highlight_controller.ts"],"names":[],"mappings":"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","file":"highlight_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 \"highlight on insert\" behavior: briefly flags a freshly inserted element\n * with `data-highlight` so CSS can flash / fade it in, then removes the flag after\n * `duration` ms (no dedicated APG pattern; a purely visual emphasis that honors the\n * WCAG \"animation from interactions\" practice via `prefers-reduced-motion`).\n *\n * Markup contract (identifier: `stimeo--highlight`):\n *   <!-- self-highlight: put it on the inserted row itself -->\n *   <li data-controller=\"stimeo--highlight\">New item</li>\n *\n *   <!-- container mode: watch for added children and highlight each -->\n *   <ul data-controller=\"stimeo--highlight\" data-stimeo--highlight-observe-value=\"true\"></ul>\n *\n * In the default (self) mode the controller element is highlighted once on\n * `connect()`. With `observe`, a `MutationObserver` instead highlights every element\n * child added to the container (e.g. Turbo Stream appends). Each highlight sets\n * `data-highlight=\"true\"`, dispatches `start`, and after `duration` removes it and\n * dispatches `end` — both carry `detail.element`.\n *\n * @remarks\n * Behavior only — it ships no color or animation, just the hook (pair with CSS, and\n * with Announcer / Flash for non-visual notice). Under `prefers-reduced-motion: reduce`\n * the emphasis is suppressed entirely (the element simply appears), so no hook or\n * event is emitted. The self hook is added on `connect()` and removed before its\n * `duration` elapses, so it does not linger into a `turbo:before-cache` snapshot; the\n * observer and pending timers are torn down on `disconnect()` (Turbo navigation\n * included).\n */\nexport class HighlightController extends Controller<HTMLElement> {\n  static override values = {\n    duration: { type: Number, default: 1500 },\n    observe: { type: Boolean, default: false },\n  };\n  static events = [\"start\", \"end\"] as const;\n\n  declare durationValue: number;\n  declare observeValue: boolean;\n\n  readonly #timeouts = new SafeTimeout();\n  #observer: MutationObserver | null = null;\n\n  override connect(): void {\n    if (this.observeValue) {\n      if (typeof MutationObserver !== \"undefined\") {\n        this.#observer = new MutationObserver((mutations) => this.#onMutations(mutations));\n        this.#observer.observe(this.element, { childList: true });\n      }\n      return;\n    }\n    this.#highlight(this.element);\n  }\n\n  override disconnect(): void {\n    this.#observer?.disconnect();\n    this.#observer = null;\n    this.#timeouts.clearAll();\n  }\n\n  /** Highlights every element child added by a childList mutation. */\n  #onMutations(mutations: MutationRecord[]): void {\n    for (const mutation of mutations) {\n      for (const node of mutation.addedNodes) {\n        if (node instanceof HTMLElement) this.#highlight(node);\n      }\n    }\n  }\n\n  /** Flags `el` with `data-highlight` and schedules its removal (unless reduced-motion). */\n  #highlight(el: HTMLElement): void {\n    // Reduced motion: suppress the emphasis so the element just appears — no hook,\n    // no timer, no events, nothing to transition.\n    if (this.#prefersReducedMotion()) return;\n\n    el.setAttribute(\"data-highlight\", \"true\");\n    this.dispatch(\"start\", { target: el, detail: { element: el } });\n    this.#timeouts.set(() => {\n      el.removeAttribute(\"data-highlight\");\n      this.dispatch(\"end\", { target: el, detail: { element: el } });\n    }, this.durationValue);\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/hover_card_controller.d.ts

@@ -0,0 +1,79 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless, accessible **hover card** behavior.
+ *
+ * Markup contract (identifier: `stimeo--hover-card`):
+ *   <span data-controller="stimeo--hover-card">
+ *     <a href="/users/jane" data-stimeo--hover-card-target="trigger"
+ *        aria-expanded="false" aria-controls="hc"
+ *        data-action="mouseenter->stimeo--hover-card#open
+ *                     mouseleave->stimeo--hover-card#close
+ *                     focusin->stimeo--hover-card#open
+ *                     focusout->stimeo--hover-card#close
+ *                     keydown->stimeo--hover-card#onKeydown">@jane</a>
+ *     <div id="hc" data-stimeo--hover-card-target="card"
+ *          data-action="mouseenter->stimeo--hover-card#open
+ *                       mouseleave->stimeo--hover-card#close" hidden>…</div>
+ *   </span>
+ *
+ * There is no dedicated APG pattern; this follows the **Disclosure** convention
+ * (`aria-expanded`) for a hover/focus-opened, non-modal popover that *may* hold
+ * interactive content (unlike a tooltip). The card is **not** a `role="dialog"`:
+ * it is supplementary, so its content must also be reachable from the trigger
+ * itself. For a short text hint use `stimeo--tooltip`; for a click-opened
+ * action panel use `stimeo--popover`.
+ *
+ * @remarks
+ * Behavior only — placement is the consumer's CSS (static) or the opt-in
+ * `stimeo-ui/positioning` module (dynamic); this controller never imports it.
+ *
+ * Behavior provided:
+ * - Open on `mouseenter`/`focusin`, close on `mouseleave`/`focusout`, each gated by
+ *   `openDelay`/`closeDelay` to prevent accidental flicker.
+ * - **Hoverable bridge**: binding open/close on the card cancels a pending close
+ *   when the pointer crosses into it; the delayed close also re-checks focus, so
+ *   tabbing into a link inside the card keeps it open.
+ * - **Dismissible**: while open, `Escape` is watched at the `document` level, so it
+ *   closes regardless of where focus sits (card, trigger, or elsewhere).
+ * - Open/closed flips the trigger's `aria-expanded`, the card's `hidden`, and a
+ *   `data-state` (`open`/`closed`). Focus is never stolen on open.
+ */
+declare class HoverCardController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        openDelay: {
+            type: NumberConstructor;
+            default: number;
+        };
+        closeDelay: {
+            type: NumberConstructor;
+            default: number;
+        };
+    };
+    static actions: readonly ["close", "onKeydown", "open"];
+    readonly triggerTarget: HTMLElement;
+    readonly cardTarget: HTMLElement;
+    readonly hasTriggerTarget: boolean;
+    readonly hasCardTarget: boolean;
+    readonly openDelayValue: number;
+    readonly closeDelayValue: number;
+    /** Starts closed. */
+    connect(): void;
+    /** Clears timers and the document `Escape` listener so nothing outlives the element. */
+    disconnect(): void;
+    /** Opens the card, after `openDelay` ms (or immediately at 0). Cancels a pending close. */
+    open(): void;
+    /**
+     * Schedules the card to close after `closeDelay`. Cancels a pending open. The
+     * delayed callback re-checks whether focus has landed inside the controller
+     * (e.g. a link in the card) and, if so, aborts the close — covering keyboard
+     * traversal that the pointer-only hoverable bridge cannot.
+     */
+    close(): void;
+    /** Closes immediately on `Escape` while open (keyboard dismissal from the trigger). */
+    onKeydown(event: KeyboardEvent): void;
+}
+
+export { HoverCardController };

package/dist/controllers/hover_card_controller.js

@@ -0,0 +1,165 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/hover_card_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/hover_card_controller.ts
+var HoverCardController = class extends Controller {
+  static targets = ["trigger", "card"];
+  static values = {
+    openDelay: { type: Number, default: 300 },
+    closeDelay: { type: Number, default: 200 }
+  };
+  static actions = ["close", "onKeydown", "open"];
+  /** Pending open/close timers, torn down together on disconnect. */
+  #timers = new SafeTimeout();
+  #pendingOpen = null;
+  #pendingClose = null;
+  /** Starts closed. */
+  connect() {
+    this.#conceal();
+  }
+  /** Clears timers and the document `Escape` listener so nothing outlives the element. */
+  disconnect() {
+    this.#timers.clearAll();
+    document.removeEventListener("keydown", this.#onDocumentKeydown);
+  }
+  /** Opens the card, after `openDelay` ms (or immediately at 0). Cancels a pending close. */
+  open() {
+    this.#cancelClose();
+    if (this.#isOpen || this.#pendingOpen !== null) return;
+    if (this.openDelayValue <= 0) {
+      this.#reveal();
+      return;
+    }
+    this.#pendingOpen = this.#timers.set(() => {
+      this.#pendingOpen = null;
+      this.#reveal();
+    }, this.openDelayValue);
+  }
+  /**
+   * Schedules the card to close after `closeDelay`. Cancels a pending open. The
+   * delayed callback re-checks whether focus has landed inside the controller
+   * (e.g. a link in the card) and, if so, aborts the close — covering keyboard
+   * traversal that the pointer-only hoverable bridge cannot.
+   */
+  close() {
+    this.#cancelOpen();
+    if (!this.#isOpen || this.#pendingClose !== null) return;
+    this.#pendingClose = this.#timers.set(() => {
+      this.#pendingClose = null;
+      if (this.element.contains(document.activeElement)) return;
+      this.#conceal();
+    }, this.closeDelayValue);
+  }
+  /** Closes immediately on `Escape` while open (keyboard dismissal from the trigger). */
+  onKeydown(event) {
+    if (event.key === "Escape" && this.#isOpen) {
+      event.preventDefault();
+      this.#dismiss();
+    }
+  }
+  /** Reveals the card, reflects state, and starts watching for a dismissing `Escape`. */
+  #reveal() {
+    if (!this.hasCardTarget) return;
+    this.cardTarget.hidden = false;
+    this.cardTarget.setAttribute("data-state", "open");
+    if (this.hasTriggerTarget) this.triggerTarget.setAttribute("aria-expanded", "true");
+    document.addEventListener("keydown", this.#onDocumentKeydown);
+  }
+  /** Hides the card, reflects state, and stops watching for `Escape`. */
+  #conceal() {
+    if (!this.hasCardTarget) return;
+    this.cardTarget.hidden = true;
+    this.cardTarget.setAttribute("data-state", "closed");
+    if (this.hasTriggerTarget) this.triggerTarget.setAttribute("aria-expanded", "false");
+    document.removeEventListener("keydown", this.#onDocumentKeydown);
+  }
+  /** Cancels pending timers and conceals immediately (shared Escape path). */
+  #dismiss() {
+    this.#cancelOpen();
+    this.#cancelClose();
+    this.#conceal();
+  }
+  /** Document-level `Escape` watcher (active only while open). */
+  #onDocumentKeydown = (event) => {
+    if (event.key === "Escape") {
+      event.preventDefault();
+      this.#dismiss();
+    }
+  };
+  /** Cancels any pending open timer. */
+  #cancelOpen() {
+    if (this.#pendingOpen !== null) {
+      this.#timers.clear(this.#pendingOpen);
+      this.#pendingOpen = null;
+    }
+  }
+  /** Cancels any pending close timer. */
+  #cancelClose() {
+    if (this.#pendingClose !== null) {
+      this.#timers.clear(this.#pendingClose);
+      this.#pendingClose = null;
+    }
+  }
+  /** Whether the card is currently visible. */
+  get #isOpen() {
+    return this.hasCardTarget && !this.cardTarget.hidden;
+  }
+};
+
+export { HoverCardController };
+//# sourceMappingURL=hover_card_controller.js.map
+//# sourceMappingURL=hover_card_controller.js.map

package/dist/controllers/hover_card_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/safe_timeout.ts","../../src/controllers/hover_card_controller.ts"],"names":[],"mappings":"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","file":"hover_card_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, accessible **hover card** behavior.\n *\n * Markup contract (identifier: `stimeo--hover-card`):\n *   <span data-controller=\"stimeo--hover-card\">\n *     <a href=\"/users/jane\" data-stimeo--hover-card-target=\"trigger\"\n *        aria-expanded=\"false\" aria-controls=\"hc\"\n *        data-action=\"mouseenter->stimeo--hover-card#open\n *                     mouseleave->stimeo--hover-card#close\n *                     focusin->stimeo--hover-card#open\n *                     focusout->stimeo--hover-card#close\n *                     keydown->stimeo--hover-card#onKeydown\">@jane</a>\n *     <div id=\"hc\" data-stimeo--hover-card-target=\"card\"\n *          data-action=\"mouseenter->stimeo--hover-card#open\n *                       mouseleave->stimeo--hover-card#close\" hidden>…</div>\n *   </span>\n *\n * There is no dedicated APG pattern; this follows the **Disclosure** convention\n * (`aria-expanded`) for a hover/focus-opened, non-modal popover that *may* hold\n * interactive content (unlike a tooltip). The card is **not** a `role=\"dialog\"`:\n * it is supplementary, so its content must also be reachable from the trigger\n * itself. For a short text hint use `stimeo--tooltip`; for a click-opened\n * action panel use `stimeo--popover`.\n *\n * @remarks\n * Behavior only — placement is the consumer's CSS (static) or the opt-in\n * `stimeo-ui/positioning` module (dynamic); this controller never imports it.\n *\n * Behavior provided:\n * - Open on `mouseenter`/`focusin`, close on `mouseleave`/`focusout`, each gated by\n *   `openDelay`/`closeDelay` to prevent accidental flicker.\n * - **Hoverable bridge**: binding open/close on the card cancels a pending close\n *   when the pointer crosses into it; the delayed close also re-checks focus, so\n *   tabbing into a link inside the card keeps it open.\n * - **Dismissible**: while open, `Escape` is watched at the `document` level, so it\n *   closes regardless of where focus sits (card, trigger, or elsewhere).\n * - Open/closed flips the trigger's `aria-expanded`, the card's `hidden`, and a\n *   `data-state` (`open`/`closed`). Focus is never stolen on open.\n */\nexport class HoverCardController extends Controller<HTMLElement> {\n  static override targets = [\"trigger\", \"card\"];\n  static override values = {\n    openDelay: { type: Number, default: 300 },\n    closeDelay: { type: Number, default: 200 },\n  };\n  static actions = [\"close\", \"onKeydown\", \"open\"] as const;\n\n  declare readonly triggerTarget: HTMLElement;\n  declare readonly cardTarget: HTMLElement;\n  declare readonly hasTriggerTarget: boolean;\n  declare readonly hasCardTarget: boolean;\n  declare readonly openDelayValue: number;\n  declare readonly closeDelayValue: number;\n\n  /** Pending open/close timers, torn down together on disconnect. */\n  readonly #timers = new SafeTimeout();\n  #pendingOpen: number | null = null;\n  #pendingClose: number | null = null;\n\n  /** Starts closed. */\n  override connect(): void {\n    this.#conceal();\n  }\n\n  /** Clears timers and the document `Escape` listener so nothing outlives the element. */\n  override disconnect(): void {\n    this.#timers.clearAll();\n    document.removeEventListener(\"keydown\", this.#onDocumentKeydown);\n  }\n\n  /** Opens the card, after `openDelay` ms (or immediately at 0). Cancels a pending close. */\n  open(): void {\n    this.#cancelClose();\n    if (this.#isOpen || this.#pendingOpen !== null) return;\n    if (this.openDelayValue <= 0) {\n      this.#reveal();\n      return;\n    }\n    this.#pendingOpen = this.#timers.set(() => {\n      this.#pendingOpen = null;\n      this.#reveal();\n    }, this.openDelayValue);\n  }\n\n  /**\n   * Schedules the card to close after `closeDelay`. Cancels a pending open. The\n   * delayed callback re-checks whether focus has landed inside the controller\n   * (e.g. a link in the card) and, if so, aborts the close — covering keyboard\n   * traversal that the pointer-only hoverable bridge cannot.\n   */\n  close(): void {\n    this.#cancelOpen();\n    if (!this.#isOpen || this.#pendingClose !== null) return;\n    this.#pendingClose = this.#timers.set(() => {\n      this.#pendingClose = null;\n      if (this.element.contains(document.activeElement)) return;\n      this.#conceal();\n    }, this.closeDelayValue);\n  }\n\n  /** Closes immediately on `Escape` while open (keyboard dismissal from the trigger). */\n  onKeydown(event: KeyboardEvent): void {\n    if (event.key === \"Escape\" && this.#isOpen) {\n      event.preventDefault();\n      this.#dismiss();\n    }\n  }\n\n  /** Reveals the card, reflects state, and starts watching for a dismissing `Escape`. */\n  #reveal(): void {\n    if (!this.hasCardTarget) return;\n    this.cardTarget.hidden = false;\n    this.cardTarget.setAttribute(\"data-state\", \"open\");\n    if (this.hasTriggerTarget) this.triggerTarget.setAttribute(\"aria-expanded\", \"true\");\n    document.addEventListener(\"keydown\", this.#onDocumentKeydown);\n  }\n\n  /** Hides the card, reflects state, and stops watching for `Escape`. */\n  #conceal(): void {\n    if (!this.hasCardTarget) return;\n    this.cardTarget.hidden = true;\n    this.cardTarget.setAttribute(\"data-state\", \"closed\");\n    if (this.hasTriggerTarget) this.triggerTarget.setAttribute(\"aria-expanded\", \"false\");\n    document.removeEventListener(\"keydown\", this.#onDocumentKeydown);\n  }\n\n  /** Cancels pending timers and conceals immediately (shared Escape path). */\n  #dismiss(): void {\n    this.#cancelOpen();\n    this.#cancelClose();\n    this.#conceal();\n  }\n\n  /** Document-level `Escape` watcher (active only while open). */\n  readonly #onDocumentKeydown = (event: KeyboardEvent): void => {\n    if (event.key === \"Escape\") {\n      event.preventDefault();\n      this.#dismiss();\n    }\n  };\n\n  /** Cancels any pending open timer. */\n  #cancelOpen(): void {\n    if (this.#pendingOpen !== null) {\n      this.#timers.clear(this.#pendingOpen);\n      this.#pendingOpen = null;\n    }\n  }\n\n  /** Cancels any pending close timer. */\n  #cancelClose(): void {\n    if (this.#pendingClose !== null) {\n      this.#timers.clear(this.#pendingClose);\n      this.#pendingClose = null;\n    }\n  }\n\n  /** Whether the card is currently visible. */\n  get #isOpen(): boolean {\n    return this.hasCardTarget && !this.cardTarget.hidden;\n  }\n}\n"]}

package/dist/controllers/idle_controller.d.ts

@@ -0,0 +1,51 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless inactivity / session-timeout detector: fires `idle` after `timeout` ms
+ * with no user activity, an optional `prompt` `promptBefore` ms earlier, and
+ * `active` when the user returns (no dedicated APG pattern; supports WCAG 2.2.1 by
+ * giving the app a warning hook before a timeout).
+ *
+ * Markup contract (identifier: `stimeo--idle`):
+ *   <body data-controller="stimeo--idle"
+ *         data-stimeo--idle-timeout-value="900000"
+ *         data-stimeo--idle-prompt-before-value="60000"
+ *         data-action="stimeo--idle:prompt->session#warn
+ *                      stimeo--idle:idle->session#logout"></body>
+ *
+ * Activity events (`events`, passive) are watched on `document` with capture so
+ * non-bubbling ones like `scroll` are seen anywhere; returning to a hidden tab
+ * (`visibilitychange` → visible) counts as activity too. While idle the controller
+ * element carries `data-idle`.
+ *
+ * @remarks
+ * Behavior only — it renders no warning UI (pair with Dialog/Confirm) and never
+ * touches the server session. Timers are owned by {@link SafeTimeout} and the
+ * listeners are removed on `disconnect()` (Turbo navigation included). Place one on
+ * the root element; `data-turbo-permanent` keeps the count running across visits.
+ */
+declare class IdleController extends Controller<HTMLElement> {
+    #private;
+    static values: {
+        timeout: {
+            type: NumberConstructor;
+            default: number;
+        };
+        promptBefore: {
+            type: NumberConstructor;
+            default: number;
+        };
+        events: {
+            type: ArrayConstructor;
+            default: string[];
+        };
+    };
+    static events: readonly ["prompt", "idle", "active"];
+    timeoutValue: number;
+    promptBeforeValue: number;
+    eventsValue: string[];
+    connect(): void;
+    disconnect(): void;
+}
+
+export { IdleController };

package/dist/controllers/idle_controller.js

@@ -0,0 +1,141 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/idle_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/idle_controller.ts
+var IdleController = class extends Controller {
+  static values = {
+    timeout: { type: Number, default: 9e5 },
+    promptBefore: { type: Number, default: 0 },
+    events: {
+      type: Array,
+      default: ["mousemove", "mousedown", "keydown", "wheel", "touchstart", "scroll"]
+    }
+  };
+  static events = ["prompt", "idle", "active"];
+  #timeouts = new SafeTimeout();
+  #idle = false;
+  #prompted = false;
+  /** Timestamp of the last activity; the timers self-reschedule against it. */
+  #lastActivity = 0;
+  #onActivity = () => {
+    this.#lastActivity = Date.now();
+    if (this.#idle || this.#prompted) {
+      this.#idle = false;
+      this.#prompted = false;
+      this.element.removeAttribute("data-idle");
+      this.dispatch("active", { detail: {} });
+      this.#arm();
+    }
+  };
+  #onVisibility = () => {
+    if (document.visibilityState === "visible") this.#onActivity();
+  };
+  connect() {
+    for (const type of this.eventsValue) {
+      document.addEventListener(type, this.#onActivity, { passive: true, capture: true });
+    }
+    document.addEventListener("visibilitychange", this.#onVisibility);
+    this.#arm();
+  }
+  disconnect() {
+    for (const type of this.eventsValue) {
+      document.removeEventListener(type, this.#onActivity, { capture: true });
+    }
+    document.removeEventListener("visibilitychange", this.#onVisibility);
+    this.#timeouts.clearAll();
+  }
+  /** Schedules the prompt and idle checks from the current activity baseline. */
+  #arm() {
+    this.#timeouts.clearAll();
+    this.#lastActivity = Date.now();
+    const { promptBeforeValue: prompt, timeoutValue: timeout } = this;
+    if (prompt > 0 && prompt < timeout) {
+      this.#timeouts.set(() => this.#checkPrompt(), timeout - prompt);
+    }
+    this.#timeouts.set(() => this.#checkIdle(), timeout);
+  }
+  /**
+   * Idle-timer callback: go idle only if there has genuinely been no activity for
+   * `timeout`; otherwise reschedule for the remaining time. This lets activity events
+   * stay O(1) (a timestamp write) while the deadline still tracks the last activity.
+   */
+  #checkIdle() {
+    const remaining = this.timeoutValue - (Date.now() - this.#lastActivity);
+    if (remaining > 0) {
+      this.#timeouts.set(() => this.#checkIdle(), remaining);
+      return;
+    }
+    this.#idle = true;
+    this.#prompted = false;
+    this.element.setAttribute("data-idle", "true");
+    this.dispatch("idle", { detail: {} });
+  }
+  /** Prompt-timer callback: warn at `promptBefore` before the idle deadline. */
+  #checkPrompt() {
+    const remaining = this.timeoutValue - this.promptBeforeValue - (Date.now() - this.#lastActivity);
+    if (remaining > 0) {
+      this.#timeouts.set(() => this.#checkPrompt(), remaining);
+      return;
+    }
+    this.#prompted = true;
+    this.dispatch("prompt", { detail: { remaining: this.promptBeforeValue } });
+  }
+};
+
+export { IdleController };
+//# sourceMappingURL=idle_controller.js.map
+//# sourceMappingURL=idle_controller.js.map

package/dist/controllers/idle_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/safe_timeout.ts","../../src/controllers/idle_controller.ts"],"names":[],"mappings":"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","file":"idle_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 inactivity / session-timeout detector: fires `idle` after `timeout` ms\n * with no user activity, an optional `prompt` `promptBefore` ms earlier, and\n * `active` when the user returns (no dedicated APG pattern; supports WCAG 2.2.1 by\n * giving the app a warning hook before a timeout).\n *\n * Markup contract (identifier: `stimeo--idle`):\n *   <body data-controller=\"stimeo--idle\"\n *         data-stimeo--idle-timeout-value=\"900000\"\n *         data-stimeo--idle-prompt-before-value=\"60000\"\n *         data-action=\"stimeo--idle:prompt->session#warn\n *                      stimeo--idle:idle->session#logout\"></body>\n *\n * Activity events (`events`, passive) are watched on `document` with capture so\n * non-bubbling ones like `scroll` are seen anywhere; returning to a hidden tab\n * (`visibilitychange` → visible) counts as activity too. While idle the controller\n * element carries `data-idle`.\n *\n * @remarks\n * Behavior only — it renders no warning UI (pair with Dialog/Confirm) and never\n * touches the server session. Timers are owned by {@link SafeTimeout} and the\n * listeners are removed on `disconnect()` (Turbo navigation included). Place one on\n * the root element; `data-turbo-permanent` keeps the count running across visits.\n */\nexport class IdleController extends Controller<HTMLElement> {\n  static override values = {\n    timeout: { type: Number, default: 900_000 },\n    promptBefore: { type: Number, default: 0 },\n    events: {\n      type: Array,\n      default: [\"mousemove\", \"mousedown\", \"keydown\", \"wheel\", \"touchstart\", \"scroll\"],\n    },\n  };\n  static events = [\"prompt\", \"idle\", \"active\"] as const;\n\n  declare timeoutValue: number;\n  declare promptBeforeValue: number;\n  declare eventsValue: string[];\n\n  readonly #timeouts = new SafeTimeout();\n  #idle = false;\n  #prompted = false;\n  /** Timestamp of the last activity; the timers self-reschedule against it. */\n  #lastActivity = 0;\n\n  readonly #onActivity = (): void => {\n    // Hot path (fires on every mousemove/scroll/wheel): just record the time. The\n    // prompt/idle timers re-check this when they fire and reschedule if needed, so we\n    // never tear down and re-create timers on each event (no per-event timer churn).\n    this.#lastActivity = Date.now();\n    if (this.#idle || this.#prompted) {\n      // We were already idle/prompted, so the timers have lapsed — wake and re-arm.\n      this.#idle = false;\n      this.#prompted = false;\n      this.element.removeAttribute(\"data-idle\");\n      this.dispatch(\"active\", { detail: {} });\n      this.#arm();\n    }\n  };\n\n  readonly #onVisibility = (): void => {\n    // Returning to the tab is activity; leaving it keeps the clock running (being\n    // away counts toward the timeout).\n    if (document.visibilityState === \"visible\") this.#onActivity();\n  };\n\n  override connect(): void {\n    for (const type of this.eventsValue) {\n      document.addEventListener(type, this.#onActivity, { passive: true, capture: true });\n    }\n    document.addEventListener(\"visibilitychange\", this.#onVisibility);\n    this.#arm();\n  }\n\n  override disconnect(): void {\n    for (const type of this.eventsValue) {\n      document.removeEventListener(type, this.#onActivity, { capture: true });\n    }\n    document.removeEventListener(\"visibilitychange\", this.#onVisibility);\n    this.#timeouts.clearAll();\n  }\n\n  /** Schedules the prompt and idle checks from the current activity baseline. */\n  #arm(): void {\n    this.#timeouts.clearAll();\n    this.#lastActivity = Date.now();\n    const { promptBeforeValue: prompt, timeoutValue: timeout } = this;\n    if (prompt > 0 && prompt < timeout) {\n      this.#timeouts.set(() => this.#checkPrompt(), timeout - prompt);\n    }\n    this.#timeouts.set(() => this.#checkIdle(), timeout);\n  }\n\n  /**\n   * Idle-timer callback: go idle only if there has genuinely been no activity for\n   * `timeout`; otherwise reschedule for the remaining time. This lets activity events\n   * stay O(1) (a timestamp write) while the deadline still tracks the last activity.\n   */\n  #checkIdle(): void {\n    const remaining = this.timeoutValue - (Date.now() - this.#lastActivity);\n    if (remaining > 0) {\n      this.#timeouts.set(() => this.#checkIdle(), remaining);\n      return;\n    }\n    this.#idle = true;\n    this.#prompted = false;\n    this.element.setAttribute(\"data-idle\", \"true\");\n    this.dispatch(\"idle\", { detail: {} });\n  }\n\n  /** Prompt-timer callback: warn at `promptBefore` before the idle deadline. */\n  #checkPrompt(): void {\n    const remaining =\n      this.timeoutValue - this.promptBeforeValue - (Date.now() - this.#lastActivity);\n    if (remaining > 0) {\n      this.#timeouts.set(() => this.#checkPrompt(), remaining);\n      return;\n    }\n    this.#prompted = true;\n    this.dispatch(\"prompt\", { detail: { remaining: this.promptBeforeValue } });\n  }\n}\n"]}