stimeo-ui 0.3.0 → 0.5.0

package/dist/controllers/spinner_controller.d.ts

@@ -1,37 +1,59 @@
 import { Controller } from '@hotwired/stimulus';
 
 /**
- * Headless loading-indicator behavior built on the live-region + `aria-busy`
- * practice (no dedicated APG pattern).
+ * Headless loading-indicator behavior built on the `aria-busy` practice (no
+ * dedicated APG pattern).
  *
  * Markup contract (identifier: `stimeo--spinner`):
  *   <div data-controller="stimeo--spinner"
  *        data-stimeo--spinner-delay-value="150"
  *        data-stimeo--spinner-min-duration-value="500"
+ *        data-stimeo--spinner-timeout-value="0"
+ *        data-stimeo--spinner-announce-text-value="Loading…"
+ *        data-stimeo--spinner-announce-ready-text-value="Loading finished."
  *        data-action="loading:start->stimeo--spinner#start
  *                     loading:stop->stimeo--spinner#stop">
- *     <div role="status" aria-live="polite" hidden
- *          data-stimeo--spinner-target="indicator">
+ *     <div hidden data-stimeo--spinner-target="indicator">
  *       <span data-stimeo--spinner-target="message">Loading…</span>
  *     </div>
  *     <div aria-busy="false" data-stimeo--spinner-target="region"></div>
  *   </div>
  *
- * The indicator is a `role="status"` live region carrying *text* (never an icon
- * alone) so screen readers announce loading; the controlled `region` mirrors the
- * busy state via `aria-busy`. Two timers tame flicker: `delay` suppresses the
- * spinner for fast operations, and `minDuration` keeps it visible long enough to
- * be perceived once shown.
+ * The indicator is the visual half — its text plus a spinner the consumer marks
+ * `aria-hidden="true"` — and the controlled `region` mirrors the busy state via
+ * `aria-busy`. Assistive tech hears the transition through `announceText` /
+ * `announceReadyText`, which go to the page's announcer: an indicator that only
+ * becomes visible at the moment of the change is not reliably read, and giving it
+ * live-region semantics on top of the announcement would say it twice. Two timers
+ * tame flicker: `delay` suppresses the spinner for fast operations, and
+ * `minDuration` keeps it visible long enough to be perceived once shown.
+ * `timeout` is the opt-in safety net for the case the consumer's `stop` never
+ * arrives.
+ *
+ * Events (all with an empty `detail`):
+ * - `stimeo--spinner:show` — the indicator became visible, after `delay`.
+ * - `stimeo--spinner:hide` — the indicator went away, after `minDuration`.
+ * - `stimeo--spinner:timeout` — `timeout` elapsed with the load still running;
+ *   the controller then ends it exactly as `stop` would, so a `hide` follows.
  *
  * @remarks
  * Behavior only — the visual spinner is the consumer's, alongside the text and
- * `aria-hidden="true"`. Both timers are owned by {@link SafeTimeout} and torn
- * down on `disconnect()` (Turbo navigation included).
+ * `aria-hidden="true"`. Both timers are owned by {@link SafeTimeout}, kept across
+ * an in-page move and dropped on a real detach via {@link DetachGate}, while the
+ * loading state a cached page would freeze is rewound by {@link BeforeCacheReset}.
  */
 declare class SpinnerController extends Controller<HTMLElement> {
     #private;
     static targets: string[];
     static values: {
+        announceText: {
+            type: StringConstructor;
+            default: string;
+        };
+        announceReadyText: {
+            type: StringConstructor;
+            default: string;
+        };
         delay: {
             type: NumberConstructor;
             default: number;
@@ -40,9 +62,13 @@ declare class SpinnerController extends Controller<HTMLElement> {
             type: NumberConstructor;
             default: number;
         };
+        timeout: {
+            type: NumberConstructor;
+            default: number;
+        };
     };
     static actions: readonly ["start", "stop"];
-    static events: readonly ["hide", "show"];
+    static events: readonly ["hide", "show", "timeout"];
     readonly indicatorTarget: HTMLElement;
     readonly regionTarget: HTMLElement;
     readonly messageTarget: HTMLElement;
@@ -51,7 +77,19 @@ declare class SpinnerController extends Controller<HTMLElement> {
     readonly hasMessageTarget: boolean;
     delayValue: number;
     minDurationValue: number;
+    timeoutValue: number;
+    announceTextValue: string;
+    announceReadyTextValue: string;
     connect(): void;
+    /**
+     * Re-applies the current phase to an indicator that arrived after `connect()`.
+     *
+     * A Turbo Stream can swap the indicator for a fresh node mid-load, and that node
+     * carries the markup contract's `hidden`. Without this the spinner would vanish
+     * while `data-state` still says `loading`, and nothing but the next cycle would
+     * bring it back.
+     */
+    indicatorTargetConnected(target: HTMLElement): void;
     disconnect(): void;
     /** Begins loading. Honors `delay` before the spinner actually appears. */
     start(): void;

package/dist/controllers/spinner_controller.js

@@ -2,6 +2,162 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/spinner_controller.ts
 
+// src/utils/announce.ts
+function announce(message, options = {}) {
+  const text = message.trim();
+  if (text.length === 0) return;
+  window.dispatchEvent(
+    new CustomEvent("stimeo--announcer:announce", {
+      detail: { message: text, assertive: options.assertive === true }
+    })
+  );
+}
+function fillTemplate(template, values) {
+  return template.replace(/\{([a-zA-Z][a-zA-Z0-9]*)\}/g, (match, name) => {
+    const replacement = values[name];
+    return replacement === void 0 ? match : String(replacement);
+  });
+}
+
+// src/utils/before_cache_reset.ts
+var BeforeCacheReset = class _BeforeCacheReset {
+  /** Every subscribed instance, iterated by the one shared document listener. */
+  static #subscribers = /* @__PURE__ */ new Set();
+  /** The shared listener; installed while at least one instance is subscribed. */
+  static #onBeforeCache = () => {
+    for (const subscriber of _BeforeCacheReset.#subscribers) subscriber.#rewind();
+  };
+  #rewind;
+  /** @param rewind - the pass that returns this controller's state to its initial form. */
+  constructor(rewind) {
+    this.#rewind = rewind;
+  }
+  /** Subscribes to `turbo:before-cache`; call from `connect()`. Idempotent. */
+  activate() {
+    const first = _BeforeCacheReset.#subscribers.size === 0;
+    _BeforeCacheReset.#subscribers.add(this);
+    if (first) {
+      document.addEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
+    }
+  }
+  /** Unsubscribes; call from `disconnect()`. Safe when never subscribed. */
+  deactivate() {
+    _BeforeCacheReset.#subscribers.delete(this);
+    if (_BeforeCacheReset.#subscribers.size > 0) return;
+    document.removeEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
+  }
+};
+
+// src/utils/default_attribute.ts
+function setDefaultAttribute(element, name, value) {
+  if (element.hasAttribute(name)) return false;
+  element.setAttribute(name, value);
+  return true;
+}
+
+// src/utils/detach_gate.ts
+var DetachGate = class _DetachGate {
+  /** Set while a probe is queued, waiting for a reconnect to cancel it. */
+  #pending = false;
+  /**
+   * True while a probe is queued — the last disconnect was ambiguous and no
+   * reconnect has cancelled it yet. Read it from `connect()` to tell the
+   * reconnect half of an in-page move from a first connect: a controller whose
+   * initialisation restarts a measurement (a min-duration floor, an elapsed
+   * counter) must skip it for the move, where nothing actually restarted.
+   */
+  get pending() {
+    return this.#pending;
+  }
+  /**
+   * True when the disconnect is definitely a real detach — the element left
+   * the document, or `data-controller` no longer lists the identifier. False
+   * means ambiguous (in-page move or observed-root exit), NOT "alive".
+   */
+  static isDetached(host) {
+    if (!host.element.isConnected) return true;
+    const tokens = (host.element.getAttribute("data-controller") ?? "").split(/\s+/);
+    return !tokens.includes(host.identifier);
+  }
+  /**
+   * Call from `disconnect()`: runs `teardown` synchronously on a definite
+   * detach (fast path), otherwise defers it one microtask — a reconnect
+   * ({@link cancel} from `connect()`) keeps the state, no reconnect runs it.
+   * One microtask is the whole probe window: Stimulus reconnects a moved
+   * element within the same mutation batch, before the checkpoint drains.
+   */
+  disconnected(host, teardown) {
+    if (_DetachGate.isDetached(host)) {
+      this.#pending = false;
+      teardown();
+      return;
+    }
+    this.#pending = true;
+    queueMicrotask(() => {
+      if (!this.#pending) return;
+      this.#pending = false;
+      teardown();
+    });
+  }
+  /**
+   * Disarms a pending probe. Call from `connect()` (the reconnect that proves
+   * an in-page move) and from the head of any teardown path not routed through
+   * {@link disconnected} (disabled-toggle, Escape), so an orphaned probe can
+   * never run the teardown a second time.
+   */
+  cancel() {
+    this.#pending = false;
+  }
+};
+
+// src/utils/min_duration_floor.ts
+var MinDurationFloor = class {
+  #timers;
+  /** Pending finish timer id, or `null` when nothing is held back. */
+  #timerId = null;
+  /** Epoch ms the floor is measured from. */
+  #since = 0;
+  /** @param timers - the controller's registry; the floor schedules into it. */
+  constructor(timers) {
+    this.#timers = timers;
+  }
+  /** Starts the floor: call when the state being held becomes visible. */
+  begin() {
+    this.#since = Date.now();
+  }
+  /** True while a finish is held back waiting for the floor to elapse. */
+  get pending() {
+    return this.#timerId !== null;
+  }
+  /**
+   * Runs `finish` once the floor has elapsed, immediately when it already has.
+   *
+   * A held-back finish is **replaced**, never stacked: only the most recently
+   * queued id is cancellable, so a second timer would outlive every cancel and
+   * end a state that has since restarted. Controllers that want the first signal
+   * to win guard on {@link pending} before calling.
+   */
+  schedule(minDuration, finish) {
+    this.cancel();
+    const remaining = minDuration - (Date.now() - this.#since);
+    if (remaining > 0) {
+      this.#timerId = this.#timers.set(() => {
+        this.#timerId = null;
+        finish();
+      }, remaining);
+    } else {
+      finish();
+    }
+  }
+  /** Drops a held-back finish. Safe when none is queued, or after a bulk clear. */
+  cancel() {
+    if (this.#timerId !== null) {
+      this.#timers.clear(this.#timerId);
+      this.#timerId = null;
+    }
+  }
+};
+
 // src/utils/safe_timeout.ts
 var TimerRegistry = class {
   /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
@@ -59,38 +215,59 @@ var SafeTimeout = class extends TimerRegistry {
 var SpinnerController = class extends Controller {
   static targets = ["indicator", "region", "message"];
   static values = {
+    announceText: { type: String, default: "" },
+    announceReadyText: { type: String, default: "" },
     delay: { type: Number, default: 0 },
-    minDuration: { type: Number, default: 0 }
+    minDuration: { type: Number, default: 0 },
+    timeout: { type: Number, default: 0 }
   };
   static actions = ["start", "stop"];
-  static events = ["hide", "show"];
+  static events = ["hide", "show", "timeout"];
   #timers = new SafeTimeout();
+  #floor = new MinDurationFloor(this.#timers);
+  #gate = new DetachGate();
+  #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
   /** Pending show-delay timer id, or `null` when no start is awaiting its delay. */
   #delayTimerId = null;
-  /** Pending min-duration hide timer id, or `null` when none is scheduled. */
-  #hideTimerId = null;
-  /** Epoch ms when the spinner became visible; `minDuration` is measured from it. */
-  #shownAt = 0;
+  /** Pending safety-net timer id, or `null` when `timeout` is off or not armed. */
+  #timeoutTimerId = null;
   connect() {
-    if (!this.element.hasAttribute("data-state")) {
+    this.#gate.cancel();
+    this.#beforeCache.activate();
+    if (this.#state === "pending" && this.#delayTimerId === null) {
+      this.#setBusy(false);
       this.element.setAttribute("data-state", "idle");
+      return;
     }
+    setDefaultAttribute(this.element, "data-state", "idle");
+  }
+  /**
+   * Re-applies the current phase to an indicator that arrived after `connect()`.
+   *
+   * A Turbo Stream can swap the indicator for a fresh node mid-load, and that node
+   * carries the markup contract's `hidden`. Without this the spinner would vanish
+   * while `data-state` still says `loading`, and nothing but the next cycle would
+   * bring it back.
+   */
+  indicatorTargetConnected(target) {
+    target.hidden = this.#state !== "loading";
   }
   disconnect() {
-    this.#timers.clearAll();
-    this.#delayTimerId = null;
-    this.#hideTimerId = null;
+    this.#beforeCache.deactivate();
+    this.#gate.disconnected(this, () => this.#teardown());
   }
   /** Begins loading. Honors `delay` before the spinner actually appears. */
   start() {
     if (this.#state === "loading") {
       this.#setBusy(true);
-      this.#cancelHide();
+      this.#floor.cancel();
+      this.#armTimeout();
       return;
     }
     if (this.#state !== "idle") return;
     this.#setBusy(true);
-    this.#cancelHide();
+    this.#floor.cancel();
+    this.#armTimeout();
     if (this.delayValue > 0) {
       this.element.setAttribute("data-state", "pending");
       this.#delayTimerId = this.#timers.set(() => {
@@ -104,6 +281,7 @@ var SpinnerController = class extends Controller {
   /** Ends loading. Honors `minDuration` so a shown spinner does not flicker. */
   stop() {
     const state = this.#state;
+    this.#cancelTimeout();
     if (state === "pending") {
       this.#cancelDelay();
       this.#setBusy(false);
@@ -112,28 +290,52 @@ var SpinnerController = class extends Controller {
     }
     if (state !== "loading") return;
     this.#setBusy(false);
-    const remaining = this.minDurationValue - (Date.now() - this.#shownAt);
-    if (remaining > 0) {
-      this.#hideTimerId = this.#timers.set(() => {
-        this.#hideTimerId = null;
-        this.#hide();
-      }, remaining);
-    } else {
-      this.#hide();
-    }
+    this.#floor.schedule(this.minDurationValue, () => this.#hide());
   }
   /** Reveals the indicator, marks the moment shown, and announces via the live region. */
   #show() {
-    this.#shownAt = Date.now();
+    this.#floor.begin();
+    this.#setBusy(true);
     if (this.hasIndicatorTarget) this.indicatorTarget.hidden = false;
     this.element.setAttribute("data-state", "loading");
     this.dispatch("show", { detail: {} });
+    announce(fillTemplate(this.announceTextValue, {}));
   }
   /** Hides the indicator and returns to the idle state. */
   #hide() {
     if (this.hasIndicatorTarget) this.indicatorTarget.hidden = true;
     this.element.setAttribute("data-state", "idle");
     this.dispatch("hide", { detail: {} });
+    announce(fillTemplate(this.announceReadyTextValue, {}));
+  }
+  /**
+   * Drops both timers on a real detach. The markup keeps whatever it last held: an
+   * element on its way out of the document has no reader left, and one whose
+   * `data-controller` dropped the identifier no longer resolves its own targets, so
+   * the rollback could only ever be partial. The snapshot is rewound where it is
+   * still whole, on `turbo:before-cache`.
+   */
+  #teardown() {
+    this.#gate.cancel();
+    this.#timers.clearAll();
+    this.#delayTimerId = null;
+    this.#timeoutTimerId = null;
+    this.#floor.cancel();
+  }
+  /**
+   * Returns the loading state to idle for the snapshot Turbo is about to take,
+   * so a page reached with the Back button is not restored mid-load with a
+   * spinner nothing can stop. State only: `data-state`, the indicator's `hidden`,
+   * and `aria-busy`. No `hide` is dispatched — the load was never observed to
+   * finish, and a snapshot rewind is not a lifecycle event the consumer can act
+   * on. The live page keeps its timers, so a navigation that never completes
+   * leaves the running cycle intact.
+   */
+  #rewindForCache() {
+    this.#cancelTimeout();
+    this.#setBusy(false);
+    if (this.hasIndicatorTarget) this.indicatorTarget.hidden = true;
+    this.element.setAttribute("data-state", "idle");
   }
   /** Reflects busy state onto the controlled region (if present). */
   #setBusy(busy) {
@@ -141,18 +343,32 @@ var SpinnerController = class extends Controller {
       this.regionTarget.setAttribute("aria-busy", String(busy));
     }
   }
+  /**
+   * Arms the safety net so a `stop` that never arrives cannot strand the spinner.
+   * Off by default: the consumer owns the async work, so only it knows whether a
+   * ceiling makes sense. Re-arming on a restart measures from the newest start.
+   */
+  #armTimeout() {
+    this.#cancelTimeout();
+    if (this.timeoutValue <= 0) return;
+    this.#timeoutTimerId = this.#timers.set(() => {
+      this.#timeoutTimerId = null;
+      this.dispatch("timeout", { detail: {} });
+      this.stop();
+    }, this.timeoutValue);
+  }
+  #cancelTimeout() {
+    if (this.#timeoutTimerId !== null) {
+      this.#timers.clear(this.#timeoutTimerId);
+      this.#timeoutTimerId = null;
+    }
+  }
   #cancelDelay() {
     if (this.#delayTimerId !== null) {
       this.#timers.clear(this.#delayTimerId);
       this.#delayTimerId = null;
     }
   }
-  #cancelHide() {
-    if (this.#hideTimerId !== null) {
-      this.#timers.clear(this.#hideTimerId);
-      this.#hideTimerId = null;
-    }
-  }
   /** Current lifecycle phase as reflected on `data-state`. */
   get #state() {
     return this.element.getAttribute("data-state") ?? "idle";

package/dist/controllers/spinner_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/safe_timeout.ts","../../src/controllers/spinner_controller.ts"],"names":[],"mappings":"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","file":"spinner_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 loading-indicator behavior built on the live-region + `aria-busy`\n * practice (no dedicated APG pattern).\n *\n * Markup contract (identifier: `stimeo--spinner`):\n *   <div data-controller=\"stimeo--spinner\"\n *        data-stimeo--spinner-delay-value=\"150\"\n *        data-stimeo--spinner-min-duration-value=\"500\"\n *        data-action=\"loading:start->stimeo--spinner#start\n *                     loading:stop->stimeo--spinner#stop\">\n *     <div role=\"status\" aria-live=\"polite\" hidden\n *          data-stimeo--spinner-target=\"indicator\">\n *       <span data-stimeo--spinner-target=\"message\">Loading…</span>\n *     </div>\n *     <div aria-busy=\"false\" data-stimeo--spinner-target=\"region\"></div>\n *   </div>\n *\n * The indicator is a `role=\"status\"` live region carrying *text* (never an icon\n * alone) so screen readers announce loading; the controlled `region` mirrors the\n * busy state via `aria-busy`. Two timers tame flicker: `delay` suppresses the\n * spinner for fast operations, and `minDuration` keeps it visible long enough to\n * be perceived once shown.\n *\n * @remarks\n * Behavior only — the visual spinner is the consumer's, alongside the text and\n * `aria-hidden=\"true\"`. Both timers are owned by {@link SafeTimeout} and torn\n * down on `disconnect()` (Turbo navigation included).\n */\nexport class SpinnerController extends Controller<HTMLElement> {\n  static override targets = [\"indicator\", \"region\", \"message\"];\n  static override values = {\n    delay: { type: Number, default: 0 },\n    minDuration: { type: Number, default: 0 },\n  };\n  static actions = [\"start\", \"stop\"] as const;\n  static events = [\"hide\", \"show\"] as const;\n\n  declare readonly indicatorTarget: HTMLElement;\n  declare readonly regionTarget: HTMLElement;\n  declare readonly messageTarget: HTMLElement;\n  declare readonly hasIndicatorTarget: boolean;\n  declare readonly hasRegionTarget: boolean;\n  declare readonly hasMessageTarget: boolean;\n\n  declare delayValue: number;\n  declare minDurationValue: number;\n\n  readonly #timers = new SafeTimeout();\n\n  /** Pending show-delay timer id, or `null` when no start is awaiting its delay. */\n  #delayTimerId: number | null = null;\n  /** Pending min-duration hide timer id, or `null` when none is scheduled. */\n  #hideTimerId: number | null = null;\n  /** Epoch ms when the spinner became visible; `minDuration` is measured from it. */\n  #shownAt = 0;\n\n  override connect(): void {\n    if (!this.element.hasAttribute(\"data-state\")) {\n      this.element.setAttribute(\"data-state\", \"idle\");\n    }\n  }\n\n  override disconnect(): void {\n    this.#timers.clearAll();\n    this.#delayTimerId = null;\n    this.#hideTimerId = null;\n  }\n\n  /** Begins loading. Honors `delay` before the spinner actually appears. */\n  start(): void {\n    if (this.#state === \"loading\") {\n      // Already shown (possibly waiting out `minDuration` after a stop): a quick\n      // stop→start within that window must keep the spinner visible. Restore the\n      // busy state and cancel the pending hide instead of returning a no-op, which\n      // would let the stale hide fire and flicker the spinner away mid-load.\n      this.#setBusy(true);\n      this.#cancelHide();\n      return;\n    }\n    if (this.#state !== \"idle\") return;\n    this.#setBusy(true);\n    // A pending hide from a previous cycle is now stale.\n    this.#cancelHide();\n    if (this.delayValue > 0) {\n      this.element.setAttribute(\"data-state\", \"pending\");\n      this.#delayTimerId = this.#timers.set(() => {\n        this.#delayTimerId = null;\n        this.#show();\n      }, this.delayValue);\n    } else {\n      this.#show();\n    }\n  }\n\n  /** Ends loading. Honors `minDuration` so a shown spinner does not flicker. */\n  stop(): void {\n    const state = this.#state;\n    if (state === \"pending\") {\n      // The delay never elapsed — the spinner never appeared, so just cancel.\n      this.#cancelDelay();\n      this.#setBusy(false);\n      this.element.setAttribute(\"data-state\", \"idle\");\n      return;\n    }\n    if (state !== \"loading\") return;\n\n    this.#setBusy(false);\n    const remaining = this.minDurationValue - (Date.now() - this.#shownAt);\n    if (remaining > 0) {\n      this.#hideTimerId = this.#timers.set(() => {\n        this.#hideTimerId = null;\n        this.#hide();\n      }, remaining);\n    } else {\n      this.#hide();\n    }\n  }\n\n  /** Reveals the indicator, marks the moment shown, and announces via the live region. */\n  #show(): void {\n    this.#shownAt = Date.now();\n    if (this.hasIndicatorTarget) this.indicatorTarget.hidden = false;\n    this.element.setAttribute(\"data-state\", \"loading\");\n    this.dispatch(\"show\", { detail: {} });\n  }\n\n  /** Hides the indicator and returns to the idle state. */\n  #hide(): void {\n    if (this.hasIndicatorTarget) this.indicatorTarget.hidden = true;\n    this.element.setAttribute(\"data-state\", \"idle\");\n    this.dispatch(\"hide\", { detail: {} });\n  }\n\n  /** Reflects busy state onto the controlled region (if present). */\n  #setBusy(busy: boolean): void {\n    if (this.hasRegionTarget) {\n      this.regionTarget.setAttribute(\"aria-busy\", String(busy));\n    }\n  }\n\n  #cancelDelay(): void {\n    if (this.#delayTimerId !== null) {\n      this.#timers.clear(this.#delayTimerId);\n      this.#delayTimerId = null;\n    }\n  }\n\n  #cancelHide(): void {\n    if (this.#hideTimerId !== null) {\n      this.#timers.clear(this.#hideTimerId);\n      this.#hideTimerId = null;\n    }\n  }\n\n  /** Current lifecycle phase as reflected on `data-state`. */\n  get #state(): string {\n    return this.element.getAttribute(\"data-state\") ?? \"idle\";\n  }\n}\n"]}
+{"version":3,"sources":["../../src/utils/announce.ts","../../src/utils/before_cache_reset.ts","../../src/utils/default_attribute.ts","../../src/utils/detach_gate.ts","../../src/utils/min_duration_floor.ts","../../src/utils/safe_timeout.ts","../../src/controllers/spinner_controller.ts"],"names":[],"mappings":"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","file":"spinner_controller.js","sourcesContent":["/**\n * Sends one message to the page's shared `stimeo--announcer`.\n *\n * A component that has to reach assistive tech does not carry a live region of its\n * own: a region only announces what changes *after* assistive tech already knows\n * about it, which a region that appears (or is un-hidden) with its message cannot\n * satisfy. The one region that can is the announcer sitting in the page from the\n * start, so state changes are handed to it as an event and it does the reading.\n *\n * The event goes to `window` because the announcer is usually a sibling high in the\n * document rather than an ancestor of the component dispatching it.\n *\n * Wording comes from the consumer — the library ships no English strings — so an\n * empty message is silently dropped and nothing is announced.\n *\n * @example\n * ```ts\n * announce(this.announceTextValue, { assertive: false });\n * ```\n */\nexport function announce(message: string, options: { assertive?: boolean } = {}): void {\n  const text = message.trim();\n  if (text.length === 0) return;\n  window.dispatchEvent(\n    new CustomEvent(\"stimeo--announcer:announce\", {\n      detail: { message: text, assertive: options.assertive === true },\n    }),\n  );\n}\n\n/**\n * Fills `{name}` placeholders in an announcement template from `values`.\n *\n * The same substitution the value-text templates use, so a consumer writes\n * `\"{percent}% complete\"` in one attribute and gets the same rules everywhere. A\n * placeholder with no matching entry is left as authored rather than blanked, which\n * keeps a typo visible instead of silently swallowing the word.\n */\nexport function fillTemplate(template: string, values: Record<string, string | number>): string {\n  return template.replace(/\\{([a-zA-Z][a-zA-Z0-9]*)\\}/g, (match, name: string) => {\n    const replacement = values[name];\n    return replacement === undefined ? match : String(replacement);\n  });\n}\n","/**\n * Runs a controller's \"return to the initial state\" pass just before Turbo\n * caches the page.\n *\n * **`disconnect()` cannot do this job, for two independent reasons.** Turbo\n * queues the clone from this event rather than taking it here, and the body swap\n * that runs the controller's `disconnect()` is queued separately — so which of\n * the two lands first is not something a controller can rely on, and a rewind\n * written in `disconnect()` may reach only the DOM being thrown away. In the\n * other direction, `disconnect()` also fires on an in-page move (Stimulus tears\n * down and reconnects the same element), where rewinding would wipe a\n * legitimately in-progress interaction — a spinner mid-load would vanish. One\n * timing is unreliable, the other is too eager; `turbo:before-cache` is the only\n * point that is exactly \"the page is about to be frozen\".\n *\n * Scope is the subscription only: registering on `activate()`, unregistering on\n * `deactivate()`, and one shared document listener no matter how many instances\n * are live. *What* to return to its initial state — which `data-state`, which\n * `hidden`, which `aria-busy` — stays in the controller, because no two\n * consumers answer it the same way (the `MicrotaskCoalescer` split).\n *\n * **Rewind state, not appearance.** The pass writes attributes the controller\n * itself owns; the visual result of those attributes is the consumer's CSS, and\n * a library that reached for style or class names would be guessing at markup\n * it does not own.\n *\n * Both entry points are idempotent, so the lifecycle hooks can call them\n * unconditionally: a second `activate()` does not double-subscribe and does not\n * make the callback run twice, and `deactivate()` on an instance that never\n * subscribed is a no-op.\n *\n * This file's own doc block is dropped from `dist`, but every member comment is\n * inlined into each consumer entry (`tsup` builds with `splitting: false`), so\n * rationale belongs here and only the contract belongs on the members.\n *\n * @example\n * ```ts\n * readonly #beforeCache = new BeforeCacheReset(() => this.#rewind());\n *\n * connect()    { this.#beforeCache.activate(); }\n * disconnect() { this.#beforeCache.deactivate(); }\n * ```\n */\nexport class BeforeCacheReset {\n  /** Every subscribed instance, iterated by the one shared document listener. */\n  static readonly #subscribers = new Set<BeforeCacheReset>();\n\n  /** The shared listener; installed while at least one instance is subscribed. */\n  static readonly #onBeforeCache = (): void => {\n    for (const subscriber of BeforeCacheReset.#subscribers) subscriber.#rewind();\n  };\n\n  readonly #rewind: () => void;\n\n  /** @param rewind - the pass that returns this controller's state to its initial form. */\n  constructor(rewind: () => void) {\n    this.#rewind = rewind;\n  }\n\n  /** Subscribes to `turbo:before-cache`; call from `connect()`. Idempotent. */\n  activate(): void {\n    const first = BeforeCacheReset.#subscribers.size === 0;\n    BeforeCacheReset.#subscribers.add(this);\n    if (first) {\n      document.addEventListener(\"turbo:before-cache\", BeforeCacheReset.#onBeforeCache);\n    }\n  }\n\n  /** Unsubscribes; call from `disconnect()`. Safe when never subscribed. */\n  deactivate(): void {\n    BeforeCacheReset.#subscribers.delete(this);\n    if (BeforeCacheReset.#subscribers.size > 0) return;\n    document.removeEventListener(\"turbo:before-cache\", BeforeCacheReset.#onBeforeCache);\n  }\n}\n","/**\n * Adds an attribute default without displacing an authored value.\n *\n * Attribute presence — including an authored empty string — is the ownership\n * boundary. The return value lets a caller remember that it supplied the\n * default when that caller must later restore the authored state.\n *\n * @param element - Element that owns the attribute\n * @param name - Attribute name\n * @param value - Value to write only when the attribute is absent\n * @returns Whether this call added the attribute\n */\nexport function setDefaultAttribute(element: Element, name: string, value: string): boolean {\n  if (element.hasAttribute(name)) return false;\n  element.setAttribute(name, value);\n  return true;\n}\n","/**\n * Shared \"in-page move vs real detach\" discriminator for `disconnect()`.\n *\n * A mid-session `disconnect()` whose element is still in the document is\n * ambiguous. It can be:\n *\n * - an **in-page move** — a consumer (sortable, a teleport) re-inserted the\n *   element; Stimulus reconnects the SAME instance in the same mutation batch\n *   and the controller's runtime state must survive;\n * - a **detach that keeps the element** — `data-controller` no longer lists the\n *   identifier (a Turbo 8 morph), or the element moved outside the observed\n *   root (a scoped `Application.start(root)`, a shadow root); no reconnect will\n *   ever come and the controller must tear down or it leaks its sessions,\n *   document listeners, and moved nodes.\n *\n * Neither available signal decides this alone. A synchronous `data-controller`\n * token check catches the morph case but misses an observed-root exit (the\n * token stays, the reconnect never comes). Deferring teardown one microtask and\n * letting `connect()` cancel it catches the root exit, but leans on Stimulus\n * reconnecting moved elements within the same mutation batch — internal\n * behavior, not a public contract. {@link DetachGate} composes both: the token\n * check is the synchronous fast path (no probe, no reliance on batching), the\n * microtask probe is the fallback for the genuinely ambiguous remainder.\n *\n * Policy stays with the consumer (the `SafeTimeout` / `FocusTrap` lineage —\n * this util owns the discrimination only):\n *\n * - **Probe** ({@link disconnected}) when the teardown must eventually happen —\n *   live drag sessions, document listeners, teleported *content*. Call\n *   {@link cancel} from `connect()` (a reconnect means in-page move) and from\n *   the head of any direct teardown path (see below).\n * - **Keep** (bare {@link DetachGate.isDetached}) when undoing the ambiguous\n *   case would fight the controller's own effect: a controller that moves its\n *   OWN element (portal's no-`content` form) exits a scoped observed root as\n *   its normal job — a probe-driven teardown would restore the element into\n *   the root, reconnect, re-teleport, and disconnect again, forever. Such\n *   controllers keep their state on an ambiguous disconnect and tear down only\n *   on {@link DetachGate.isDetached}.\n *\n * Event convention for probe consumers: teardown into a dead (detached) tree is\n * silent — consumers restore from their own `connect()`; a detach that keeps the\n * tree alive must end an in-flight session with a `cancel` event, or composing\n * consumers strand their session bookkeeping.\n */\n\n/** The slice of a Stimulus controller the gate inspects. */\nexport interface DetachGateHost {\n  readonly element: Element;\n  readonly identifier: string;\n}\n\n/**\n * Per-controller-instance gate deciding whether a `disconnect()` is a real\n * detach. Hold one per controller (`#gate = new DetachGate()`) — Stimulus\n * reuses the instance across reconnects, so the pending probe state carries\n * over exactly as the protocol needs.\n *\n * @example\n * ```ts\n * #gate = new DetachGate();\n *\n * connect(): void {\n *   this.#gate.cancel(); // a reconnect: the element moved in-page\n *   // …\n * }\n *\n * disconnect(): void {\n *   this.#gate.disconnected(this, () => this.#teardown());\n * }\n *\n * #teardown(): void {\n *   this.#gate.cancel(); // disarm a still-queued probe (double-run guard)\n *   // …\n * }\n * ```\n */\nexport class DetachGate {\n  /** Set while a probe is queued, waiting for a reconnect to cancel it. */\n  #pending = false;\n\n  /**\n   * True while a probe is queued — the last disconnect was ambiguous and no\n   * reconnect has cancelled it yet. Read it from `connect()` to tell the\n   * reconnect half of an in-page move from a first connect: a controller whose\n   * initialisation restarts a measurement (a min-duration floor, an elapsed\n   * counter) must skip it for the move, where nothing actually restarted.\n   */\n  get pending(): boolean {\n    return this.#pending;\n  }\n\n  /**\n   * True when the disconnect is definitely a real detach — the element left\n   * the document, or `data-controller` no longer lists the identifier. False\n   * means ambiguous (in-page move or observed-root exit), NOT \"alive\".\n   */\n  static isDetached(host: DetachGateHost): boolean {\n    if (!host.element.isConnected) return true;\n    const tokens = (host.element.getAttribute(\"data-controller\") ?? \"\").split(/\\s+/);\n    return !tokens.includes(host.identifier);\n  }\n\n  /**\n   * Call from `disconnect()`: runs `teardown` synchronously on a definite\n   * detach (fast path), otherwise defers it one microtask — a reconnect\n   * ({@link cancel} from `connect()`) keeps the state, no reconnect runs it.\n   * One microtask is the whole probe window: Stimulus reconnects a moved\n   * element within the same mutation batch, before the checkpoint drains.\n   */\n  disconnected(host: DetachGateHost, teardown: () => void): void {\n    if (DetachGate.isDetached(host)) {\n      // Also disarms a probe a previous ambiguous disconnect left queued\n      // (defer, element removed, disconnect again) — exactly one teardown.\n      this.#pending = false;\n      teardown();\n      return;\n    }\n    this.#pending = true;\n    queueMicrotask(() => {\n      if (!this.#pending) return;\n      this.#pending = false;\n      teardown();\n    });\n  }\n\n  /**\n   * Disarms a pending probe. Call from `connect()` (the reconnect that proves\n   * an in-page move) and from the head of any teardown path not routed through\n   * {@link disconnected} (disabled-toggle, Escape), so an orphaned probe can\n   * never run the teardown a second time.\n   */\n  cancel(): void {\n    this.#pending = false;\n  }\n}\n","import type { SafeTimeout } from \"./safe_timeout\";\n\n/**\n * Holds a transient state visible for a minimum time before letting it end.\n *\n * A loading indicator that appears and disappears within a few frames reads as a\n * flicker rather than as feedback, so several controllers keep one up for a floor\n * of `minDuration` milliseconds measured from the moment it became visible. The\n * shape is always the same: note the moment, and when the end signal arrives\n * either run it now, because the floor has already passed, or hold it on a timer\n * for whatever is left.\n *\n * The floor **borrows** a {@link SafeTimeout} instead of owning one, so a\n * controller that also schedules other work (a show delay) keeps every timer in a\n * single registry and one `clearAll()` in its teardown still drops them all.\n * Cancelling after such a bulk clear is safe: the registry no-ops on an id it no\n * longer holds.\n *\n * Scope is the floor itself. **When an end signal is allowed to arrive at all\n * stays with the controller**, because the answers differ — one keeps the first\n * queued finish and ignores repeats, another lets the newest replace it — and\n * flattening that into a shared default would silently change what the consumers\n * already promise.\n *\n * @example\n * ```ts\n * readonly #timers = new SafeTimeout();\n * readonly #floor = new MinDurationFloor(this.#timers);\n *\n * #show()  { this.#floor.begin(); … }\n * stop()   { this.#floor.schedule(this.minDurationValue, () => this.#hide()); }\n * ```\n */\nexport class MinDurationFloor {\n  readonly #timers: SafeTimeout;\n\n  /** Pending finish timer id, or `null` when nothing is held back. */\n  #timerId: number | null = null;\n\n  /** Epoch ms the floor is measured from. */\n  #since = 0;\n\n  /** @param timers - the controller's registry; the floor schedules into it. */\n  constructor(timers: SafeTimeout) {\n    this.#timers = timers;\n  }\n\n  /** Starts the floor: call when the state being held becomes visible. */\n  begin(): void {\n    this.#since = Date.now();\n  }\n\n  /** True while a finish is held back waiting for the floor to elapse. */\n  get pending(): boolean {\n    return this.#timerId !== null;\n  }\n\n  /**\n   * Runs `finish` once the floor has elapsed, immediately when it already has.\n   *\n   * A held-back finish is **replaced**, never stacked: only the most recently\n   * queued id is cancellable, so a second timer would outlive every cancel and\n   * end a state that has since restarted. Controllers that want the first signal\n   * to win guard on {@link pending} before calling.\n   */\n  schedule(minDuration: number, finish: () => void): void {\n    this.cancel();\n    const remaining = minDuration - (Date.now() - this.#since);\n    if (remaining > 0) {\n      this.#timerId = this.#timers.set(() => {\n        this.#timerId = null;\n        finish();\n      }, remaining);\n    } else {\n      finish();\n    }\n  }\n\n  /** Drops a held-back finish. Safe when none is queued, or after a bulk clear. */\n  cancel(): void {\n    if (this.#timerId !== null) {\n      this.#timers.clear(this.#timerId);\n      this.#timerId = null;\n    }\n  }\n}\n","/**\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 { announce, fillTemplate } from \"../utils/announce\";\nimport { BeforeCacheReset } from \"../utils/before_cache_reset\";\nimport { setDefaultAttribute } from \"../utils/default_attribute\";\nimport { DetachGate } from \"../utils/detach_gate\";\nimport { MinDurationFloor } from \"../utils/min_duration_floor\";\nimport { SafeTimeout } from \"../utils/safe_timeout\";\n\n/**\n * Headless loading-indicator behavior built on the `aria-busy` practice (no\n * dedicated APG pattern).\n *\n * Markup contract (identifier: `stimeo--spinner`):\n *   <div data-controller=\"stimeo--spinner\"\n *        data-stimeo--spinner-delay-value=\"150\"\n *        data-stimeo--spinner-min-duration-value=\"500\"\n *        data-stimeo--spinner-timeout-value=\"0\"\n *        data-stimeo--spinner-announce-text-value=\"Loading…\"\n *        data-stimeo--spinner-announce-ready-text-value=\"Loading finished.\"\n *        data-action=\"loading:start->stimeo--spinner#start\n *                     loading:stop->stimeo--spinner#stop\">\n *     <div hidden data-stimeo--spinner-target=\"indicator\">\n *       <span data-stimeo--spinner-target=\"message\">Loading…</span>\n *     </div>\n *     <div aria-busy=\"false\" data-stimeo--spinner-target=\"region\"></div>\n *   </div>\n *\n * The indicator is the visual half — its text plus a spinner the consumer marks\n * `aria-hidden=\"true\"` — and the controlled `region` mirrors the busy state via\n * `aria-busy`. Assistive tech hears the transition through `announceText` /\n * `announceReadyText`, which go to the page's announcer: an indicator that only\n * becomes visible at the moment of the change is not reliably read, and giving it\n * live-region semantics on top of the announcement would say it twice. Two timers\n * tame flicker: `delay` suppresses the spinner for fast operations, and\n * `minDuration` keeps it visible long enough to be perceived once shown.\n * `timeout` is the opt-in safety net for the case the consumer's `stop` never\n * arrives.\n *\n * Events (all with an empty `detail`):\n * - `stimeo--spinner:show` — the indicator became visible, after `delay`.\n * - `stimeo--spinner:hide` — the indicator went away, after `minDuration`.\n * - `stimeo--spinner:timeout` — `timeout` elapsed with the load still running;\n *   the controller then ends it exactly as `stop` would, so a `hide` follows.\n *\n * @remarks\n * Behavior only — the visual spinner is the consumer's, alongside the text and\n * `aria-hidden=\"true\"`. Both timers are owned by {@link SafeTimeout}, kept across\n * an in-page move and dropped on a real detach via {@link DetachGate}, while the\n * loading state a cached page would freeze is rewound by {@link BeforeCacheReset}.\n */\nexport class SpinnerController extends Controller<HTMLElement> {\n  static override targets = [\"indicator\", \"region\", \"message\"];\n  static override values = {\n    announceText: { type: String, default: \"\" },\n    announceReadyText: { type: String, default: \"\" },\n    delay: { type: Number, default: 0 },\n    minDuration: { type: Number, default: 0 },\n    timeout: { type: Number, default: 0 },\n  };\n  static actions = [\"start\", \"stop\"] as const;\n  static events = [\"hide\", \"show\", \"timeout\"] as const;\n\n  declare readonly indicatorTarget: HTMLElement;\n  declare readonly regionTarget: HTMLElement;\n  declare readonly messageTarget: HTMLElement;\n  declare readonly hasIndicatorTarget: boolean;\n  declare readonly hasRegionTarget: boolean;\n  declare readonly hasMessageTarget: boolean;\n\n  declare delayValue: number;\n  declare minDurationValue: number;\n  declare timeoutValue: number;\n  declare announceTextValue: string;\n  declare announceReadyTextValue: string;\n\n  readonly #timers = new SafeTimeout();\n  readonly #floor = new MinDurationFloor(this.#timers);\n  readonly #gate = new DetachGate();\n  readonly #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());\n\n  /** Pending show-delay timer id, or `null` when no start is awaiting its delay. */\n  #delayTimerId: number | null = null;\n  /** Pending safety-net timer id, or `null` when `timeout` is off or not armed. */\n  #timeoutTimerId: number | null = null;\n\n  override connect(): void {\n    this.#gate.cancel();\n    this.#beforeCache.activate();\n    if (this.#state === \"pending\" && this.#delayTimerId === null) {\n      // `pending` lives exactly as long as its show-delay timer. Reading it back with\n      // no timer of this instance behind it means the markup outlived the timer — a\n      // restored snapshot, or an element re-attached too late to count as a move — so\n      // nothing is left to advance it and `start()` would refuse every later load.\n      // Fall back to idle, dropping the busy flag the interrupted `start()` set.\n      this.#setBusy(false);\n      this.element.setAttribute(\"data-state\", \"idle\");\n      return;\n    }\n    setDefaultAttribute(this.element, \"data-state\", \"idle\");\n  }\n\n  /**\n   * Re-applies the current phase to an indicator that arrived after `connect()`.\n   *\n   * A Turbo Stream can swap the indicator for a fresh node mid-load, and that node\n   * carries the markup contract's `hidden`. Without this the spinner would vanish\n   * while `data-state` still says `loading`, and nothing but the next cycle would\n   * bring it back.\n   */\n  indicatorTargetConnected(target: HTMLElement): void {\n    target.hidden = this.#state !== \"loading\";\n  }\n\n  override disconnect(): void {\n    // Symmetric with `connect()` regardless of why the disconnect came: an in-page\n    // move re-subscribes, and only the timers are held back for the reconnect.\n    this.#beforeCache.deactivate();\n    this.#gate.disconnected(this, () => this.#teardown());\n  }\n\n  /** Begins loading. Honors `delay` before the spinner actually appears. */\n  start(): void {\n    if (this.#state === \"loading\") {\n      // Already shown (possibly waiting out `minDuration` after a stop): a quick\n      // stop→start within that window must keep the spinner visible. Restore the\n      // busy state and cancel the pending hide instead of returning a no-op, which\n      // would let the stale hide fire and flicker the spinner away mid-load.\n      this.#setBusy(true);\n      this.#floor.cancel();\n      this.#armTimeout();\n      return;\n    }\n    if (this.#state !== \"idle\") return;\n    this.#setBusy(true);\n    // A hide held back from a previous cycle is now stale.\n    this.#floor.cancel();\n    this.#armTimeout();\n    if (this.delayValue > 0) {\n      this.element.setAttribute(\"data-state\", \"pending\");\n      this.#delayTimerId = this.#timers.set(() => {\n        this.#delayTimerId = null;\n        this.#show();\n      }, this.delayValue);\n    } else {\n      this.#show();\n    }\n  }\n\n  /** Ends loading. Honors `minDuration` so a shown spinner does not flicker. */\n  stop(): void {\n    const state = this.#state;\n    this.#cancelTimeout();\n    if (state === \"pending\") {\n      // The delay never elapsed — the spinner never appeared, so just cancel.\n      this.#cancelDelay();\n      this.#setBusy(false);\n      this.element.setAttribute(\"data-state\", \"idle\");\n      return;\n    }\n    if (state !== \"loading\") return;\n\n    this.#setBusy(false);\n    this.#floor.schedule(this.minDurationValue, () => this.#hide());\n  }\n\n  /** Reveals the indicator, marks the moment shown, and announces via the live region. */\n  #show(): void {\n    this.#floor.begin();\n    // A visible spinner always means a busy region. Re-asserting it costs nothing on\n    // the direct path and closes the one where a snapshot rewind cleared the flag\n    // while the show-delay timer it deliberately spared was still armed.\n    this.#setBusy(true);\n    if (this.hasIndicatorTarget) this.indicatorTarget.hidden = false;\n    this.element.setAttribute(\"data-state\", \"loading\");\n    this.dispatch(\"show\", { detail: {} });\n    // loading ↔ ready is the transition worth reading; the spinner itself is\n    // visual and carries no words.\n    announce(fillTemplate(this.announceTextValue, {}));\n  }\n\n  /** Hides the indicator and returns to the idle state. */\n  #hide(): void {\n    if (this.hasIndicatorTarget) this.indicatorTarget.hidden = true;\n    this.element.setAttribute(\"data-state\", \"idle\");\n    this.dispatch(\"hide\", { detail: {} });\n    announce(fillTemplate(this.announceReadyTextValue, {}));\n  }\n\n  /**\n   * Drops both timers on a real detach. The markup keeps whatever it last held: an\n   * element on its way out of the document has no reader left, and one whose\n   * `data-controller` dropped the identifier no longer resolves its own targets, so\n   * the rollback could only ever be partial. The snapshot is rewound where it is\n   * still whole, on `turbo:before-cache`.\n   */\n  #teardown(): void {\n    this.#gate.cancel();\n    this.#timers.clearAll();\n    this.#delayTimerId = null;\n    this.#timeoutTimerId = null;\n    this.#floor.cancel();\n  }\n\n  /**\n   * Returns the loading state to idle for the snapshot Turbo is about to take,\n   * so a page reached with the Back button is not restored mid-load with a\n   * spinner nothing can stop. State only: `data-state`, the indicator's `hidden`,\n   * and `aria-busy`. No `hide` is dispatched — the load was never observed to\n   * finish, and a snapshot rewind is not a lifecycle event the consumer can act\n   * on. The live page keeps its timers, so a navigation that never completes\n   * leaves the running cycle intact.\n   */\n  #rewindForCache(): void {\n    this.#cancelTimeout();\n    this.#setBusy(false);\n    if (this.hasIndicatorTarget) this.indicatorTarget.hidden = true;\n    this.element.setAttribute(\"data-state\", \"idle\");\n  }\n\n  /** Reflects busy state onto the controlled region (if present). */\n  #setBusy(busy: boolean): void {\n    if (this.hasRegionTarget) {\n      this.regionTarget.setAttribute(\"aria-busy\", String(busy));\n    }\n  }\n\n  /**\n   * Arms the safety net so a `stop` that never arrives cannot strand the spinner.\n   * Off by default: the consumer owns the async work, so only it knows whether a\n   * ceiling makes sense. Re-arming on a restart measures from the newest start.\n   */\n  #armTimeout(): void {\n    this.#cancelTimeout();\n    if (this.timeoutValue <= 0) return;\n    this.#timeoutTimerId = this.#timers.set(() => {\n      this.#timeoutTimerId = null;\n      this.dispatch(\"timeout\", { detail: {} });\n      this.stop();\n    }, this.timeoutValue);\n  }\n\n  #cancelTimeout(): void {\n    if (this.#timeoutTimerId !== null) {\n      this.#timers.clear(this.#timeoutTimerId);\n      this.#timeoutTimerId = null;\n    }\n  }\n\n  #cancelDelay(): void {\n    if (this.#delayTimerId !== null) {\n      this.#timers.clear(this.#delayTimerId);\n      this.#delayTimerId = null;\n    }\n  }\n\n  /** Current lifecycle phase as reflected on `data-state`. */\n  get #state(): string {\n    return this.element.getAttribute(\"data-state\") ?? \"idle\";\n  }\n}\n"]}

package/dist/controllers/step_indicator_controller.d.ts

@@ -20,11 +20,12 @@ import { Controller } from '@hotwired/stimulus';
  * @remarks
  * Behavior only. Each step `<li>` gets a `data-state` (`complete`/`current`/
  * `upcoming`) derived from the current index; the consumer draws the circles,
- * lines, and numbers from those hooks. A `--stimeo-step-indicator-ratio`
+ * lines, and numbers from those hooks. A `--stimeo--step-indicator-ratio`
  * (0–1) custom property on the root expresses overall progress for CSS.
  *
  * Behavior provided:
  * - Reflects `current` onto each step's `data-state` and `aria-current`.
+ * - Re-derives every step when the step set changes at runtime.
  * - `setCurrent` (bound to an event whose `detail.current` is the 0-based index)
  *   updates the current step and dispatches `stimeo--step-indicator:change`.
  */
@@ -43,9 +44,19 @@ declare class StepIndicatorController extends Controller<HTMLElement> {
     currentValue: number;
     /** Renders the initial state from the `current` value. */
     connect(): void;
+    /** Closes the window in which a queued repaint may still run. */
+    disconnect(): void;
+    /** Syncs a step appended or replaced at runtime (the consumer owns the list). */
+    stepTargetConnected(): void;
+    /** Re-derives the remaining steps when one is removed at runtime. */
+    stepTargetDisconnected(): void;
+    /** Repaints when application code (or a Turbo morph) changes `current` at runtime. */
+    currentValueChanged(): void;
     /**
      * Updates the current step from an external event (`detail.current`, 0-based)
-     * and dispatches `change`. Out-of-range indices are clamped to the step set.
+     * and dispatches `change`. Out-of-range indices are clamped to the step set,
+     * and both sides of the no-op test are clamped, so moving onto the step an
+     * out-of-range `current` already renders is not reported as a change.
      */
     setCurrent(event: CustomEvent<{
         current?: number;