stimeo-ui 0.2.1 → 0.4.0

data/dist/controllers/skeleton_controller.js

@@ -2,6 +2,71 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/skeleton_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/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,15 +124,13 @@ var SafeTimeout = class extends TimerRegistry {
 var SkeletonController = class extends Controller {
   static targets = ["placeholder", "content"];
   static values = {
+    announceReadyText: { type: String, default: "" },
     minDuration: { type: Number, default: 0 }
   };
   static actions = ["ready", "reset"];
   static events = ["ready"];
   #timers = new SafeTimeout();
-  /** Pending min-duration reveal timer id, or `null` when none is scheduled. */
-  #revealTimerId = null;
-  /** Epoch ms when the loading state began, used to enforce `minDuration`. */
-  #loadingSince = 0;
+  #floor = new MinDurationFloor(this.#timers);
   connect() {
     if (this.#state !== "ready") {
       this.#enterLoading();
@@ -75,32 +138,21 @@ var SkeletonController = class extends Controller {
   }
   disconnect() {
     this.#timers.clearAll();
-    this.#revealTimerId = null;
+    this.#floor.cancel();
   }
   /** Swaps to the real content. Honors `minDuration` to prevent a flash. */
   ready() {
-    if (this.#state === "ready" || this.#revealTimerId !== null) return;
-    const remaining = this.minDurationValue - (Date.now() - this.#loadingSince);
-    if (remaining > 0) {
-      this.#revealTimerId = this.#timers.set(() => {
-        this.#revealTimerId = null;
-        this.#reveal();
-      }, remaining);
-    } else {
-      this.#reveal();
-    }
+    if (this.#state === "ready" || this.#floor.pending) return;
+    this.#floor.schedule(this.minDurationValue, () => this.#reveal());
   }
   /** Returns to the loading state (e.g. a Turbo Stream re-fetch). */
   reset() {
-    if (this.#revealTimerId !== null) {
-      this.#timers.clear(this.#revealTimerId);
-      this.#revealTimerId = null;
-    }
+    this.#floor.cancel();
     this.#enterLoading();
   }
   /** Shows the placeholder, hides content, and marks the region busy. */
   #enterLoading() {
-    this.#loadingSince = Date.now();
+    this.#floor.begin();
     if (this.hasPlaceholderTarget) this.placeholderTarget.hidden = false;
     if (this.hasContentTarget) this.contentTarget.hidden = true;
     this.element.setAttribute("aria-busy", "true");
@@ -113,6 +165,7 @@ var SkeletonController = class extends Controller {
     this.element.setAttribute("aria-busy", "false");
     this.element.setAttribute("data-state", "ready");
     this.dispatch("ready", { detail: {} });
+    announce(fillTemplate(this.announceReadyTextValue, {}));
   }
   /** Current lifecycle phase as reflected on `data-state`. */
   get #state() {

data/dist/controllers/slider_controller.js

@@ -1,5 +1,39 @@
 import { Controller } from '@hotwired/stimulus';
 
+// src/controllers/slider_controller.ts
+
+// src/utils/logical_scroll.ts
+function isRtl(element) {
+  return window.getComputedStyle(element).direction === "rtl";
+}
+
+// src/utils/arrow_step.ts
+function logicalArrowKey(key, element) {
+  if (key !== "ArrowRight" && key !== "ArrowLeft") return key;
+  if (!isRtl(element)) return key;
+  return key === "ArrowRight" ? "ArrowLeft" : "ArrowRight";
+}
+function isReservedArrowChord(event, allow = []) {
+  if (!event.key.startsWith("Arrow")) return false;
+  return event.altKey && !allow.includes("alt") || event.ctrlKey && !allow.includes("ctrl") || event.metaKey && !allow.includes("meta") || event.shiftKey && !allow.includes("shift");
+}
+
+// src/utils/range.ts
+function rangeFraction(value, min, max) {
+  const span = max - min;
+  if (!(span > 0)) return 0;
+  const clamped = Math.min(max, Math.max(min, value));
+  let fraction;
+  if (Number.isFinite(span)) {
+    fraction = (clamped - min) / span;
+  } else {
+    const scale = Math.max(Math.abs(min), Math.abs(max));
+    fraction = (clamped / scale - min / scale) / (max / scale - min / scale);
+  }
+  if (!Number.isFinite(fraction)) return 0;
+  return Math.min(1, Math.max(0, fraction));
+}
+
 // src/controllers/slider_controller.ts
 var FRACTION_PROPERTY = "--stimeo--slider-fraction";
 var SliderController = class extends Controller {
@@ -8,12 +42,17 @@ var SliderController = class extends Controller {
     min: { type: Number, default: 0 },
     max: { type: Number, default: 100 },
     step: { type: Number, default: 1 },
-    value: { type: Number, default: 0 }
+    value: { type: Number, default: 0 },
+    logicalTrack: { type: Boolean, default: false }
   };
   static actions = ["onKeydown", "onPointerDown"];
   static events = ["change"];
   /** Aborts in-progress pointer-drag listeners when the drag ends or on teardown. */
   #dragAbort = null;
+  /** Whether the consumer declared a mirroring track and the direction mirrors it. */
+  get #mirrored() {
+    return this.logicalTrackValue && isRtl(this.element);
+  }
   /** Clamps the initial value and renders the starting position. */
   connect() {
     this.#setValue(this.valueValue, { silent: true });
@@ -25,9 +64,10 @@ var SliderController = class extends Controller {
   }
   /** Handles keyboard stepping per the APG slider model. */
   onKeydown(event) {
+    if (isReservedArrowChord(event)) return;
     const big = this.stepValue * 10;
     let next = null;
-    switch (event.key) {
+    switch (this.#mirrored ? logicalArrowKey(event.key, this.element) : event.key) {
       case "ArrowRight":
       case "ArrowUp":
         next = this.valueValue + this.stepValue;
@@ -58,12 +98,13 @@ var SliderController = class extends Controller {
   onPointerDown(event) {
     if (!this.hasTrackTarget) return;
     event.preventDefault();
-    this.#updateFromClientX(event.clientX);
+    const mirrored = this.#mirrored;
+    this.#updateFromClientX(event.clientX, mirrored);
     if (this.hasThumbTarget) this.thumbTarget.focus();
     this.#dragAbort?.abort();
     const abort = new AbortController();
     this.#dragAbort = abort;
-    const onMove = (move) => this.#updateFromClientX(move.clientX);
+    const onMove = (move) => this.#updateFromClientX(move.clientX, mirrored);
     const onUp = () => {
       abort.abort();
       this.#dragAbort = null;
@@ -73,10 +114,11 @@ var SliderController = class extends Controller {
     document.addEventListener("pointercancel", onUp, { signal: abort.signal });
   }
   /** Maps a pointer X coordinate to a value using the track's geometry. */
-  #updateFromClientX(clientX) {
+  #updateFromClientX(clientX, mirrored) {
     const rect = this.trackTarget.getBoundingClientRect();
     if (rect.width === 0) return;
-    const fraction = (clientX - rect.left) / rect.width;
+    const offset = (clientX - rect.left) / rect.width;
+    const fraction = mirrored ? 1 - offset : offset;
     this.#setValue(this.minValue + fraction * (this.maxValue - this.minValue));
   }
   /**
@@ -97,8 +139,7 @@ var SliderController = class extends Controller {
       this.thumbTarget.setAttribute("aria-valuemax", String(this.maxValue));
       this.thumbTarget.setAttribute("aria-valuenow", String(value));
     }
-    const span = this.maxValue - this.minValue;
-    const fraction = span > 0 ? (value - this.minValue) / span : 0;
+    const fraction = rangeFraction(value, this.minValue, this.maxValue);
     this.element.style.setProperty(FRACTION_PROPERTY, String(fraction));
     if (changed && !silent) this.dispatch("change", { detail: { value } });
   }

data/dist/controllers/sortable_controller.js

@@ -1,5 +1,12 @@
 import { Controller } from '@hotwired/stimulus';
 
+// src/controllers/sortable_controller.ts
+
+// src/utils/logical_scroll.ts
+function isRtl(element) {
+  return window.getComputedStyle(element).direction === "rtl";
+}
+
 // src/controllers/sortable_controller.ts
 var SortableController = class extends Controller {
   static targets = ["list", "item", "status"];
@@ -67,6 +74,12 @@ var SortableController = class extends Controller {
    * Keyboard stepping: `pointer-drag` reports *cumulative* synthetic deltas, so
    * the difference from the last consumed value is one arrow press — its sign is
    * the direction. Cross-axis arrows never change the primary delta (no move).
+   *
+   * The sign is physical (`ArrowRight` is always `+dx`), so a right-to-left row
+   * has to invert it: there, moving the item rightward means moving it *earlier*
+   * in the DOM. Skipping this would also split the two halves of one keypress —
+   * `roving` already moves focus logically, so the same arrow would send the
+   * focus and the grabbed item opposite ways.
    */
   #stepFromKeyboard(session, detail) {
     const primary = Number(this.#isVertical ? detail.dy : detail.dx) || 0;
@@ -75,7 +88,8 @@ var SortableController = class extends Controller {
     if (delta === 0) return;
     const items = this.#items();
     const index = items.indexOf(session.item);
-    const next = Math.max(0, Math.min(index + (delta > 0 ? 1 : -1), items.length - 1));
+    const step = (delta > 0 ? 1 : -1) * (this.#isReversed ? -1 : 1);
+    const next = Math.max(0, Math.min(index + step, items.length - 1));
     if (next === index) return;
     this.#moveTo(session.item, next);
     this.#announce("moved", session.item);
@@ -91,11 +105,13 @@ var SortableController = class extends Controller {
     if (others.length === 0) return;
     let laidOut = false;
     let target = 0;
+    const reversed = this.#isReversed;
     for (const other of others) {
       const rect = other.getBoundingClientRect();
       if (rect.width > 0 || rect.height > 0) laidOut = true;
       const midpoint = this.#isVertical ? rect.top + rect.height / 2 : rect.left + rect.width / 2;
-      if (pointer > midpoint) target += 1;
+      const precedes = reversed ? pointer < midpoint : pointer > midpoint;
+      if (precedes) target += 1;
     }
     if (!laidOut) return;
     const current = this.#items().indexOf(session.item);
@@ -118,7 +134,7 @@ var SortableController = class extends Controller {
    * Mirrors a step into the `status` live region. Copy is localizable through
    * `data-grabbed` / `data-moved` / `data-dropped` / `data-canceled` templates on
    * the status element (`%{name}` / `%{position}` / `%{total}` placeholders);
-   * terse English is the fallback (the library's shared status-channel design).
+   * terse English is the fallback.
    */
   #announce(key, item) {
     if (!this.hasStatusTarget) return;
@@ -160,6 +176,21 @@ var SortableController = class extends Controller {
   get #isVertical() {
     return this.orientationValue !== "horizontal";
   }
+  /**
+   * Whether DOM order runs opposite to the primary coordinate — true only for a
+   * horizontal row under `dir="rtl"`, where the first item sits at the largest
+   * `x`. Both drag paths reach this controller in physical terms (`pointer-drag`
+   * documents its deltas as physical and hands RTL to its consumer, which is
+   * this controller), so both have to be mapped back onto DOM order here.
+   *
+   * Read from the list, the element that lays the items out — never from the
+   * dragged item, which may carry its own `dir`. The list inherits the computed
+   * direction, so authoring `dir` on the root works too. A vertical list is
+   * unaffected: writing direction does not mirror the block axis.
+   */
+  get #isReversed() {
+    return !this.#isVertical && isRtl(this.#list);
+  }
 };
 
 export { SortableController };

data/dist/controllers/spinner_controller.js

@@ -2,6 +2,145 @@ 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/detach_gate.ts
+var DetachGate = class _DetachGate {
+  /** Set while a probe is queued, waiting for a reconnect to cancel it. */
+  #pending = false;
+  /**
+   * 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 +198,61 @@ 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, used to enforce `minDuration`. */
-  #shownAt = 0;
+  /** Pending safety-net timer id, or `null` when `timeout` is off or not armed. */
+  #timeoutTimerId = null;
   connect() {
+    this.#gate.cancel();
+    this.#beforeCache.activate();
+    if (this.#state === "pending" && this.#delayTimerId === null) {
+      this.#setBusy(false);
+      this.element.setAttribute("data-state", "idle");
+      return;
+    }
     if (!this.element.hasAttribute("data-state")) {
       this.element.setAttribute("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 +266,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 +275,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 +328,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";