stimeo-ui 0.1.0-alpha.1

package/dist/controllers/toolbar_controller.js

@@ -0,0 +1,113 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/toolbar_controller.ts
+
+// src/utils/roving_tabindex.ts
+var RovingTabindex = class {
+  /** Returns the current ordered item elements; called on every operation. */
+  #getItems;
+  /**
+   * @param getItems - Returns the current ordered item elements. Called on every
+   *   operation so the live target list is always used.
+   */
+  constructor(getItems) {
+    this.#getItems = getItems;
+  }
+  /** Index of the currently tabbable item (`tabindex="0"`), or `-1` if none. */
+  get activeIndex() {
+    return this.#getItems().findIndex((item) => item.tabIndex === 0);
+  }
+  /**
+   * Makes exactly the item at `index` tabbable (`tabindex="0"`) and removes every
+   * other item from the Tab sequence (`tabindex="-1"`). An out-of-range `index`
+   * (e.g. `-1`) leaves all items at `-1`, which a controller can use to express
+   * "nothing is currently tabbable".
+   *
+   * @param index - Position of the item to make tabbable.
+   * @param options - Pass `{ focus: true }` to also move DOM focus to that item.
+   */
+  setActive(index, { focus = false } = {}) {
+    const items = this.#getItems();
+    items.forEach((item, i) => {
+      item.tabIndex = i === index ? 0 : -1;
+    });
+    if (focus) items[index]?.focus();
+  }
+};
+function rovingMove(current, length, delta, wrap) {
+  if (length === 0) return -1;
+  const next = current + delta;
+  if (wrap === "wrap") return (next + length) % length;
+  return Math.min(length - 1, Math.max(0, next));
+}
+
+// src/controllers/toolbar_controller.ts
+var ToolbarController = class extends Controller {
+  static targets = ["control"];
+  static values = {
+    orientation: { type: String, default: "horizontal" },
+    wrap: { type: Boolean, default: true }
+  };
+  static actions = ["onKeydown"];
+  #roving = new RovingTabindex(() => this.controlTargets);
+  /**
+   * Establishes the single tab stop: keep an existing one if it is still
+   * navigable, else the first navigable control. Disabled / hidden controls are
+   * skipped so the toolbar's lone Tab stop never lands on an unfocusable element
+   * (which would make the whole group unreachable on Tab re-entry).
+   */
+  connect() {
+    const active = this.#roving.activeIndex;
+    const activeEl = active === -1 ? null : this.controlTargets[active];
+    if (activeEl && this.#isNavigable(activeEl)) {
+      this.#roving.setActive(active);
+      return;
+    }
+    const first = this.#navigableControls[0];
+    this.#roving.setActive(first ? this.controlTargets.indexOf(first) : -1);
+  }
+  /** Arrow/Home/End move focus and the single tab stop. Bound via `data-action`. */
+  onKeydown(event) {
+    const navigable = this.#navigableControls;
+    const current = navigable.indexOf(event.currentTarget);
+    if (current === -1) return;
+    const length = navigable.length;
+    const wrap = this.wrapValue ? "wrap" : "clamp";
+    const vertical = this.orientationValue === "vertical";
+    const forwardKey = vertical ? "ArrowDown" : "ArrowRight";
+    const backwardKey = vertical ? "ArrowUp" : "ArrowLeft";
+    let next;
+    if (event.key === forwardKey) {
+      next = rovingMove(current, length, 1, wrap);
+    } else if (event.key === backwardKey) {
+      next = rovingMove(current, length, -1, wrap);
+    } else if (event.key === "Home") {
+      next = 0;
+    } else if (event.key === "End") {
+      next = length - 1;
+    } else {
+      return;
+    }
+    event.preventDefault();
+    const target = navigable[next];
+    if (target) this.#roving.setActive(this.controlTargets.indexOf(target), { focus: true });
+  }
+  /** Controls eligible for the roving tab stop (excludes disabled / hidden). */
+  get #navigableControls() {
+    return this.controlTargets.filter((control) => this.#isNavigable(control));
+  }
+  /**
+   * A control can hold the tab stop unless it is `hidden`, `aria-disabled`, or a
+   * natively `disabled` form control. CSS-only visibility cannot be detected
+   * headlessly and stays the consumer's responsibility.
+   */
+  #isNavigable(control) {
+    if (control.hasAttribute("hidden")) return false;
+    if (control.getAttribute("aria-disabled") === "true") return false;
+    return !control.disabled;
+  }
+};
+
+export { ToolbarController };
+//# sourceMappingURL=toolbar_controller.js.map
+//# sourceMappingURL=toolbar_controller.js.map

package/dist/controllers/toolbar_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/roving_tabindex.ts","../../src/controllers/toolbar_controller.ts"],"names":[],"mappings":"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","file":"toolbar_controller.js","sourcesContent":["/**\n * Low-level roving-tabindex primitive shared by composite-widget controllers.\n *\n * The APG roving-tabindex pattern keeps a composite widget a single Tab stop:\n * exactly one item is in the Tab sequence (`tabindex=\"0\"`) while the rest are\n * removed from it (`tabindex=\"-1\"`), and the arrow keys move both DOM focus and\n * that single tabbable position together. {@link RovingTabindex} owns *only* that\n * mechanical bookkeeping — \"which one item is tabbable, and move focus there\".\n *\n * It is intentionally **policy-free**. Orientation, wrapping vs. clamping,\n * selection-follows-focus, typeahead, and `Home`/`End` semantics differ per APG\n * pattern (Radio Group, Toolbar, Rating, …); folding them into one helper would\n * flatten those widgets to a lowest common denominator and lose each pattern's\n * correctness. Those decisions therefore stay in each controller, which calls\n * {@link RovingTabindex.setActive} with an index it computed itself (optionally\n * via the pure {@link rovingMove} helper).\n *\n * @remarks\n * Items are read lazily through a getter so a controller can add or remove\n * targets (Stimulus re-scans the DOM) without re-wiring this helper.\n */\nexport class RovingTabindex {\n  /** Returns the current ordered item elements; called on every operation. */\n  readonly #getItems: () => HTMLElement[];\n\n  /**\n   * @param getItems - Returns the current ordered item elements. Called on every\n   *   operation so the live target list is always used.\n   */\n  constructor(getItems: () => HTMLElement[]) {\n    this.#getItems = getItems;\n  }\n\n  /** Index of the currently tabbable item (`tabindex=\"0\"`), or `-1` if none. */\n  get activeIndex(): number {\n    return this.#getItems().findIndex((item) => item.tabIndex === 0);\n  }\n\n  /**\n   * Makes exactly the item at `index` tabbable (`tabindex=\"0\"`) and removes every\n   * other item from the Tab sequence (`tabindex=\"-1\"`). An out-of-range `index`\n   * (e.g. `-1`) leaves all items at `-1`, which a controller can use to express\n   * \"nothing is currently tabbable\".\n   *\n   * @param index - Position of the item to make tabbable.\n   * @param options - Pass `{ focus: true }` to also move DOM focus to that item.\n   */\n  setActive(index: number, { focus = false }: { focus?: boolean } = {}): void {\n    const items = this.#getItems();\n    items.forEach((item, i) => {\n      item.tabIndex = i === index ? 0 : -1;\n    });\n    if (focus) items[index]?.focus();\n  }\n}\n\n/** Edge behavior for {@link rovingMove}: cycle past the ends, or stop at them. */\nexport type RovingWrap = \"wrap\" | \"clamp\";\n\n/**\n * Pure helper that resolves the target index for a one-step directional move.\n *\n * Keyboard/orientation mapping stays in the caller: it decides that a key means\n * `delta` `+1` (next) or `-1` (previous) and whether the widget should `\"wrap\"`\n * (Radio Group, Toolbar) or `\"clamp\"` at the ends.\n *\n * @param current - The index focus is moving from.\n * @param length - Number of items in the set.\n * @param delta - `+1` to move to the next item, `-1` for the previous.\n * @param wrap - `\"wrap\"` cycles around the ends; `\"clamp\"` stops at them.\n * @returns The resolved index, or `-1` when there are no items.\n */\nexport function rovingMove(\n  current: number,\n  length: number,\n  delta: number,\n  wrap: RovingWrap,\n): number {\n  if (length === 0) return -1;\n  const next = current + delta;\n  if (wrap === \"wrap\") return (next + length) % length;\n  return Math.min(length - 1, Math.max(0, next));\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { RovingTabindex, type RovingWrap, rovingMove } from \"../utils/roving_tabindex\";\n\n/**\n * Headless, accessible toolbar behavior.\n *\n * Markup contract (identifier: `stimeo--toolbar`):\n *   <div data-controller=\"stimeo--toolbar\" role=\"toolbar\" aria-label=\"Text formatting\"\n *        data-stimeo--toolbar-orientation-value=\"horizontal\">\n *     <button type=\"button\" data-stimeo--toolbar-target=\"control\"\n *             data-action=\"keydown->stimeo--toolbar#onKeydown\">Bold</button>\n *     <!-- more controls; exactly one tabindex=0 -->\n *   </div>\n *\n * Implements the WAI-ARIA APG **Toolbar** pattern: the group is a single Tab\n * stop (roving tabindex) and the arrow keys move focus between controls. Each\n * control's own function (press, toggle, open a menu) stays with that element or\n * its own controller — the toolbar only owns navigation.\n *\n * @remarks\n * Behavior only. The roving mechanics are delegated to {@link RovingTabindex};\n * orientation and wrap policy stay here per the APG (they differ per widget).\n *\n * Behavior provided:\n * - Exactly one control is tabbable (`tabindex=\"0\"`); the rest are `-1`.\n * - `ArrowRight`/`ArrowLeft` (horizontal) or `ArrowDown`/`ArrowUp` (vertical)\n *   move focus to the next/previous control; `Home`/`End` to the first/last.\n * - With `wrap=true` movement cycles past the ends; with `wrap=false` it stops.\n * - Returning focus from outside lands on the most recently active control,\n *   because that is the one left tabbable.\n */\nexport class ToolbarController extends Controller<HTMLElement> {\n  static override targets = [\"control\"];\n  static override values = {\n    orientation: { type: String, default: \"horizontal\" },\n    wrap: { type: Boolean, default: true },\n  };\n  static actions = [\"onKeydown\"] as const;\n\n  declare readonly controlTargets: HTMLElement[];\n  declare orientationValue: string;\n  declare wrapValue: boolean;\n\n  readonly #roving = new RovingTabindex(() => this.controlTargets);\n\n  /**\n   * Establishes the single tab stop: keep an existing one if it is still\n   * navigable, else the first navigable control. Disabled / hidden controls are\n   * skipped so the toolbar's lone Tab stop never lands on an unfocusable element\n   * (which would make the whole group unreachable on Tab re-entry).\n   */\n  override connect(): void {\n    const active = this.#roving.activeIndex;\n    const activeEl = active === -1 ? null : this.controlTargets[active];\n    if (activeEl && this.#isNavigable(activeEl)) {\n      this.#roving.setActive(active);\n      return;\n    }\n    const first = this.#navigableControls[0];\n    this.#roving.setActive(first ? this.controlTargets.indexOf(first) : -1);\n  }\n\n  /** Arrow/Home/End move focus and the single tab stop. Bound via `data-action`. */\n  onKeydown(event: KeyboardEvent): void {\n    const navigable = this.#navigableControls;\n    const current = navigable.indexOf(event.currentTarget as HTMLElement);\n    if (current === -1) return;\n\n    const length = navigable.length;\n    const wrap: RovingWrap = this.wrapValue ? \"wrap\" : \"clamp\";\n    const vertical = this.orientationValue === \"vertical\";\n    const forwardKey = vertical ? \"ArrowDown\" : \"ArrowRight\";\n    const backwardKey = vertical ? \"ArrowUp\" : \"ArrowLeft\";\n\n    let next: number;\n    if (event.key === forwardKey) {\n      next = rovingMove(current, length, 1, wrap);\n    } else if (event.key === backwardKey) {\n      next = rovingMove(current, length, -1, wrap);\n    } else if (event.key === \"Home\") {\n      next = 0;\n    } else if (event.key === \"End\") {\n      next = length - 1;\n    } else {\n      return;\n    }\n\n    event.preventDefault();\n    const target = navigable[next];\n    if (target) this.#roving.setActive(this.controlTargets.indexOf(target), { focus: true });\n  }\n\n  /** Controls eligible for the roving tab stop (excludes disabled / hidden). */\n  get #navigableControls(): HTMLElement[] {\n    return this.controlTargets.filter((control) => this.#isNavigable(control));\n  }\n\n  /**\n   * A control can hold the tab stop unless it is `hidden`, `aria-disabled`, or a\n   * natively `disabled` form control. CSS-only visibility cannot be detected\n   * headlessly and stays the consumer's responsibility.\n   */\n  #isNavigable(control: HTMLElement): boolean {\n    if (control.hasAttribute(\"hidden\")) return false;\n    if (control.getAttribute(\"aria-disabled\") === \"true\") return false;\n    return !(control as HTMLButtonElement | HTMLInputElement).disabled;\n  }\n}\n"]}

package/dist/controllers/tooltip_controller.d.ts

@@ -0,0 +1,74 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless, accessible **tooltip** behavior.
+ *
+ * Markup contract (identifier: `stimeo--tooltip`):
+ *   <span data-controller="stimeo--tooltip">
+ *     <button data-stimeo--tooltip-target="trigger" aria-describedby="tip"
+ *             data-action="mouseenter->stimeo--tooltip#show
+ *                          mouseleave->stimeo--tooltip#hide
+ *                          focusin->stimeo--tooltip#show
+ *                          focusout->stimeo--tooltip#hide
+ *                          keydown->stimeo--tooltip#onKeydown">Save</button>
+ *     <span id="tip" role="tooltip" data-stimeo--tooltip-target="content"
+ *           data-action="mouseenter->stimeo--tooltip#show
+ *                        mouseleave->stimeo--tooltip#hide" hidden>…</span>
+ *   </span>
+ *
+ * Implements the WAI-ARIA APG **Tooltip** pattern and WCAG 2.2 SC 1.4.13
+ * (hoverable / dismissible / persistent). The tooltip never receives focus and
+ * holds no interactive content — for that use `stimeo--hover-card` or
+ * `stimeo--popover`. The `aria-describedby` association is declared in the
+ * consumer's markup; this controller only toggles visibility.
+ *
+ * @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:
+ * - Show on `mouseenter`/`focusin`, hide on `mouseleave`/`focusout`, each gated by
+ *   `showDelay`/`hideDelay` to prevent flicker.
+ * - **Hoverable bridge**: binding show/hide on the content too means moving the
+ *   pointer from trigger into the tooltip cancels the pending hide, so it stays up.
+ * - **Dismissible**: while shown, `Escape` is watched at the `document` level so it
+ *   dismisses even when a hover (not focus) triggered it and focus is elsewhere.
+ * - Visibility flips `hidden` and `data-state` (`open`/`closed`); the
+ *   `aria-describedby` reference is always preserved.
+ */
+declare class TooltipController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        showDelay: {
+            type: NumberConstructor;
+            default: number;
+        };
+        hideDelay: {
+            type: NumberConstructor;
+            default: number;
+        };
+    };
+    static actions: readonly ["hide", "onKeydown", "show"];
+    readonly contentTarget: HTMLElement;
+    readonly hasContentTarget: boolean;
+    readonly showDelayValue: number;
+    readonly hideDelayValue: number;
+    /** Starts hidden. */
+    connect(): void;
+    /** Clears timers and the document `Escape` listener so nothing outlives the element. */
+    disconnect(): void;
+    /** Shows the tooltip, after `showDelay` ms (or immediately at 0). Cancels a pending hide. */
+    show(): void;
+    /** Hides the tooltip, after `hideDelay` ms (or immediately at 0). Cancels a pending show. */
+    hide(): void;
+    /**
+     * Dismisses the tooltip on `Escape` from the trigger. The authoritative
+     * dismissal path is the document-level listener (added while shown) so a
+     * hover-triggered tooltip is dismissible regardless of focus; this handler
+     * keeps the documented `keydown->#onKeydown` binding meaningful too.
+     */
+    onKeydown(event: KeyboardEvent): void;
+}
+
+export { TooltipController };

package/dist/controllers/tooltip_controller.js

@@ -0,0 +1,165 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/tooltip_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/tooltip_controller.ts
+var TooltipController = class extends Controller {
+  static targets = ["trigger", "content"];
+  static values = {
+    showDelay: { type: Number, default: 0 },
+    hideDelay: { type: Number, default: 0 }
+  };
+  static actions = ["hide", "onKeydown", "show"];
+  /** Pending show/hide timers, torn down together on disconnect. */
+  #timers = new SafeTimeout();
+  /** The id of the currently pending show or hide timer, if any. */
+  #pendingShow = null;
+  #pendingHide = null;
+  /** Starts hidden. */
+  connect() {
+    this.#conceal();
+  }
+  /** Clears timers and the document `Escape` listener so nothing outlives the element. */
+  disconnect() {
+    this.#timers.clearAll();
+    document.removeEventListener("keydown", this.#onDocumentKeydown);
+  }
+  /** Shows the tooltip, after `showDelay` ms (or immediately at 0). Cancels a pending hide. */
+  show() {
+    this.#cancelHide();
+    if (this.#isVisible || this.#pendingShow !== null) return;
+    if (this.showDelayValue <= 0) {
+      this.#reveal();
+      return;
+    }
+    this.#pendingShow = this.#timers.set(() => {
+      this.#pendingShow = null;
+      this.#reveal();
+    }, this.showDelayValue);
+  }
+  /** Hides the tooltip, after `hideDelay` ms (or immediately at 0). Cancels a pending show. */
+  hide() {
+    this.#cancelShow();
+    if (!this.#isVisible || this.#pendingHide !== null) return;
+    if (this.hideDelayValue <= 0) {
+      this.#conceal();
+      return;
+    }
+    this.#pendingHide = this.#timers.set(() => {
+      this.#pendingHide = null;
+      this.#conceal();
+    }, this.hideDelayValue);
+  }
+  /**
+   * Dismisses the tooltip on `Escape` from the trigger. The authoritative
+   * dismissal path is the document-level listener (added while shown) so a
+   * hover-triggered tooltip is dismissible regardless of focus; this handler
+   * keeps the documented `keydown->#onKeydown` binding meaningful too.
+   */
+  onKeydown(event) {
+    if (event.key === "Escape" && this.#isVisible) {
+      event.preventDefault();
+      this.#cancelShow();
+      this.#cancelHide();
+      this.#conceal();
+    }
+  }
+  /** Reveals the content and starts watching for a dismissing `Escape`. */
+  #reveal() {
+    if (!this.hasContentTarget) return;
+    this.contentTarget.hidden = false;
+    this.contentTarget.setAttribute("data-state", "open");
+    document.addEventListener("keydown", this.#onDocumentKeydown);
+  }
+  /** Hides the content and stops watching for `Escape`. */
+  #conceal() {
+    if (!this.hasContentTarget) return;
+    this.contentTarget.hidden = true;
+    this.contentTarget.setAttribute("data-state", "closed");
+    document.removeEventListener("keydown", this.#onDocumentKeydown);
+  }
+  /** Document-level `Escape` watcher (active only while shown). */
+  #onDocumentKeydown = (event) => {
+    if (event.key === "Escape") {
+      event.preventDefault();
+      this.#cancelShow();
+      this.#cancelHide();
+      this.#conceal();
+    }
+  };
+  /** Cancels any pending show timer. */
+  #cancelShow() {
+    if (this.#pendingShow !== null) {
+      this.#timers.clear(this.#pendingShow);
+      this.#pendingShow = null;
+    }
+  }
+  /** Cancels any pending hide timer. */
+  #cancelHide() {
+    if (this.#pendingHide !== null) {
+      this.#timers.clear(this.#pendingHide);
+      this.#pendingHide = null;
+    }
+  }
+  /** Whether the tooltip is currently shown. */
+  get #isVisible() {
+    return this.hasContentTarget && !this.contentTarget.hidden;
+  }
+};
+
+export { TooltipController };
+//# sourceMappingURL=tooltip_controller.js.map
+//# sourceMappingURL=tooltip_controller.js.map

package/dist/controllers/tooltip_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/safe_timeout.ts","../../src/controllers/tooltip_controller.ts"],"names":[],"mappings":"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","file":"tooltip_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 **tooltip** behavior.\n *\n * Markup contract (identifier: `stimeo--tooltip`):\n *   <span data-controller=\"stimeo--tooltip\">\n *     <button data-stimeo--tooltip-target=\"trigger\" aria-describedby=\"tip\"\n *             data-action=\"mouseenter->stimeo--tooltip#show\n *                          mouseleave->stimeo--tooltip#hide\n *                          focusin->stimeo--tooltip#show\n *                          focusout->stimeo--tooltip#hide\n *                          keydown->stimeo--tooltip#onKeydown\">Save</button>\n *     <span id=\"tip\" role=\"tooltip\" data-stimeo--tooltip-target=\"content\"\n *           data-action=\"mouseenter->stimeo--tooltip#show\n *                        mouseleave->stimeo--tooltip#hide\" hidden>…</span>\n *   </span>\n *\n * Implements the WAI-ARIA APG **Tooltip** pattern and WCAG 2.2 SC 1.4.13\n * (hoverable / dismissible / persistent). The tooltip never receives focus and\n * holds no interactive content — for that use `stimeo--hover-card` or\n * `stimeo--popover`. The `aria-describedby` association is declared in the\n * consumer's markup; this controller only toggles visibility.\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 * - Show on `mouseenter`/`focusin`, hide on `mouseleave`/`focusout`, each gated by\n *   `showDelay`/`hideDelay` to prevent flicker.\n * - **Hoverable bridge**: binding show/hide on the content too means moving the\n *   pointer from trigger into the tooltip cancels the pending hide, so it stays up.\n * - **Dismissible**: while shown, `Escape` is watched at the `document` level so it\n *   dismisses even when a hover (not focus) triggered it and focus is elsewhere.\n * - Visibility flips `hidden` and `data-state` (`open`/`closed`); the\n *   `aria-describedby` reference is always preserved.\n */\nexport class TooltipController extends Controller<HTMLElement> {\n  static override targets = [\"trigger\", \"content\"];\n  static override values = {\n    showDelay: { type: Number, default: 0 },\n    hideDelay: { type: Number, default: 0 },\n  };\n  static actions = [\"hide\", \"onKeydown\", \"show\"] as const;\n\n  declare readonly contentTarget: HTMLElement;\n  declare readonly hasContentTarget: boolean;\n  declare readonly showDelayValue: number;\n  declare readonly hideDelayValue: number;\n\n  /** Pending show/hide timers, torn down together on disconnect. */\n  readonly #timers = new SafeTimeout();\n  /** The id of the currently pending show or hide timer, if any. */\n  #pendingShow: number | null = null;\n  #pendingHide: number | null = null;\n\n  /** Starts hidden. */\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  /** Shows the tooltip, after `showDelay` ms (or immediately at 0). Cancels a pending hide. */\n  show(): void {\n    this.#cancelHide();\n    if (this.#isVisible || this.#pendingShow !== null) return;\n    if (this.showDelayValue <= 0) {\n      this.#reveal();\n      return;\n    }\n    this.#pendingShow = this.#timers.set(() => {\n      this.#pendingShow = null;\n      this.#reveal();\n    }, this.showDelayValue);\n  }\n\n  /** Hides the tooltip, after `hideDelay` ms (or immediately at 0). Cancels a pending show. */\n  hide(): void {\n    this.#cancelShow();\n    if (!this.#isVisible || this.#pendingHide !== null) return;\n    if (this.hideDelayValue <= 0) {\n      this.#conceal();\n      return;\n    }\n    this.#pendingHide = this.#timers.set(() => {\n      this.#pendingHide = null;\n      this.#conceal();\n    }, this.hideDelayValue);\n  }\n\n  /**\n   * Dismisses the tooltip on `Escape` from the trigger. The authoritative\n   * dismissal path is the document-level listener (added while shown) so a\n   * hover-triggered tooltip is dismissible regardless of focus; this handler\n   * keeps the documented `keydown->#onKeydown` binding meaningful too.\n   */\n  onKeydown(event: KeyboardEvent): void {\n    if (event.key === \"Escape\" && this.#isVisible) {\n      event.preventDefault();\n      this.#cancelShow();\n      this.#cancelHide();\n      this.#conceal();\n    }\n  }\n\n  /** Reveals the content and starts watching for a dismissing `Escape`. */\n  #reveal(): void {\n    if (!this.hasContentTarget) return;\n    this.contentTarget.hidden = false;\n    this.contentTarget.setAttribute(\"data-state\", \"open\");\n    document.addEventListener(\"keydown\", this.#onDocumentKeydown);\n  }\n\n  /** Hides the content and stops watching for `Escape`. */\n  #conceal(): void {\n    if (!this.hasContentTarget) return;\n    this.contentTarget.hidden = true;\n    this.contentTarget.setAttribute(\"data-state\", \"closed\");\n    document.removeEventListener(\"keydown\", this.#onDocumentKeydown);\n  }\n\n  /** Document-level `Escape` watcher (active only while shown). */\n  readonly #onDocumentKeydown = (event: KeyboardEvent): void => {\n    if (event.key === \"Escape\") {\n      event.preventDefault();\n      this.#cancelShow();\n      this.#cancelHide();\n      this.#conceal();\n    }\n  };\n\n  /** Cancels any pending show timer. */\n  #cancelShow(): void {\n    if (this.#pendingShow !== null) {\n      this.#timers.clear(this.#pendingShow);\n      this.#pendingShow = null;\n    }\n  }\n\n  /** Cancels any pending hide timer. */\n  #cancelHide(): void {\n    if (this.#pendingHide !== null) {\n      this.#timers.clear(this.#pendingHide);\n      this.#pendingHide = null;\n    }\n  }\n\n  /** Whether the tooltip is currently shown. */\n  get #isVisible(): boolean {\n    return this.hasContentTarget && !this.contentTarget.hidden;\n  }\n}\n"]}

package/dist/controllers/transition_controller.d.ts

@@ -0,0 +1,86 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless **enter/leave transition base**: stages CSS classes for showing and hiding
+ * an element (the shared substrate other widgets can lean on instead of hand-rolling
+ * it). Counterpart to Headless UI `Transition` / Alpine `x-transition` (no APG pattern;
+ * honors WCAG 2.2 **2.3.3** via `prefers-reduced-motion` and keeps the visual state in
+ * sync with `hidden`).
+ *
+ * Markup contract (identifier: `stimeo--transition`):
+ *   <div data-controller="stimeo--transition"
+ *        data-stimeo--transition-enter-value="ease-out duration-200"
+ *        data-stimeo--transition-enter-from-value="opacity-0"
+ *        data-stimeo--transition-enter-to-value="opacity-100"
+ *        data-stimeo--transition-leave-value="ease-in duration-150"
+ *        data-stimeo--transition-leave-from-value="opacity-100"
+ *        data-stimeo--transition-leave-to-value="opacity-0" hidden>…</div>
+ *
+ * `enter()` unhides the element, applies `enter` + `enterFrom`, then on the next frame
+ * swaps `enterFrom` → `enterTo` so the CSS transition runs, and on `transitionend` (or
+ * a safety timeout) settles to `entered`. `leave()` mirrors it and re-applies `hidden`.
+ * `toggle()` reverses the current direction. The element carries `data-transition-state`
+ * (`entering` / `entered` / `leaving` / `left`) and `entered` / `left` events fire on
+ * completion.
+ *
+ * @remarks
+ * Behavior only — the animation itself is the consumer's CSS; this controls *when* the
+ * stage classes are applied. Under `prefers-reduced-motion: reduce` it switches
+ * instantly (no staging). An interrupting call cancels the in-flight transition and
+ * starts the new one. State lives solely in `hidden` / `data-transition-state`, and
+ * `connect()` reconciles to a stable state (stripping any half-applied stage classes
+ * from a Turbo cache); the `transitionend` listener, rAF, and safety timer are released
+ * on `disconnect()` (Turbo navigation included).
+ */
+declare class TransitionController extends Controller<HTMLElement> {
+    #private;
+    static values: {
+        enter: {
+            type: StringConstructor;
+            default: string;
+        };
+        enterFrom: {
+            type: StringConstructor;
+            default: string;
+        };
+        enterTo: {
+            type: StringConstructor;
+            default: string;
+        };
+        leave: {
+            type: StringConstructor;
+            default: string;
+        };
+        leaveFrom: {
+            type: StringConstructor;
+            default: string;
+        };
+        leaveTo: {
+            type: StringConstructor;
+            default: string;
+        };
+        timeout: {
+            type: NumberConstructor;
+            default: number;
+        };
+    };
+    static actions: readonly ["enter", "leave", "toggle"];
+    static events: readonly ["entered", "left"];
+    enterValue: string;
+    enterFromValue: string;
+    enterToValue: string;
+    leaveValue: string;
+    leaveFromValue: string;
+    leaveToValue: string;
+    timeoutValue: number;
+    connect(): void;
+    disconnect(): void;
+    /** Shows the element with the enter transition. */
+    enter(): void;
+    /** Hides the element with the leave transition. */
+    leave(): void;
+    /** Reverses the current direction (enter when hidden/leaving, else leave). */
+    toggle(): void;
+}
+
+export { TransitionController };