stimeo-ui 0.3.0 → 0.4.0

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; `minDuration` is measured from it. */
-  #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";

data/dist/controllers/step_indicator_controller.js

@@ -1,5 +1,40 @@
 import { Controller } from '@hotwired/stimulus';
 
+// src/controllers/step_indicator_controller.ts
+
+// src/utils/microtask_coalescer.ts
+var MicrotaskCoalescer = class {
+  #run;
+  #queued = false;
+  #active = false;
+  #generation = 0;
+  /** @param run - the single reconciliation pass, invoked at most once per batch. */
+  constructor(run) {
+    this.#run = run;
+  }
+  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */
+  activate() {
+    this.#active = true;
+  }
+  /** Closes the window and drops any pending pass; call from `disconnect()`. */
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */
+  schedule() {
+    if (!this.#active || this.#queued) return;
+    this.#queued = true;
+    const generation = this.#generation;
+    queueMicrotask(() => {
+      if (generation !== this.#generation || !this.#queued || !this.#active) return;
+      this.#queued = false;
+      this.#run();
+    });
+  }
+};
+
 // src/controllers/step_indicator_controller.ts
 var StepIndicatorController = class extends Controller {
   static targets = ["step"];
@@ -8,26 +43,63 @@ var StepIndicatorController = class extends Controller {
   };
   static actions = ["setCurrent"];
   static events = ["change"];
+  /**
+   * Whether the target callbacks may render. Stimulus reports the authored steps
+   * as connected before `connect()` and the remaining ones as disconnected after
+   * `disconnect()`, so this keeps a connect at one render pass, not one per step.
+   */
+  /**
+   * Collapses a batch of step callbacks — and a morph that swaps `current` with
+   * them — into one repaint. Replacing a list of N steps delivers N callbacks, and
+   * each one would otherwise rewrite every step's state.
+   */
+  #repaint = new MicrotaskCoalescer(() => this.#render());
   /** Renders the initial state from the `current` value. */
   connect() {
+    this.#repaint.activate();
     this.#render();
   }
+  /** Closes the window in which a queued repaint may still run. */
+  disconnect() {
+    this.#repaint.cancel();
+  }
+  /** Syncs a step appended or replaced at runtime (the consumer owns the list). */
+  stepTargetConnected() {
+    this.#repaint.schedule();
+  }
+  /** Re-derives the remaining steps when one is removed at runtime. */
+  stepTargetDisconnected() {
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `current` at runtime. */
+  currentValueChanged() {
+    this.#repaint.schedule();
+  }
   /**
    * 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) {
     const next = event.detail?.current;
     if (typeof next !== "number" || !Number.isFinite(next)) return;
     const clamped = this.#clamp(next);
-    if (clamped === this.currentValue) return;
+    const moved = clamped !== this.#clamp(this.currentValue);
     this.currentValue = clamped;
+    if (!moved) return;
     this.#render();
     this.dispatch("change", {
       detail: { current: clamped, total: this.stepTargets.length }
     });
   }
-  /** Applies `data-state`, `aria-current`, and the progress ratio custom property. */
+  /**
+   * Applies `data-state`, `aria-current`, and the progress ratio custom property.
+   *
+   * A pure function of the step set and `current`, so running it again writes the
+   * same values — which is what lets the action path paint synchronously (the event
+   * goes out after the DOM is updated) while a coalesced pass may still follow.
+   */
   #render() {
     const total = this.stepTargets.length;
     const current = this.#clamp(this.currentValue);
@@ -42,10 +114,15 @@ var StepIndicatorController = class extends Controller {
     const ratio = total > 1 ? current / (total - 1) : 0;
     this.element.style.setProperty("--stimeo-step-indicator-ratio", String(ratio));
   }
-  /** Constrains an index to `[0, total-1]` (or `0` when there are no steps). */
+  /**
+   * Constrains an index to `[0, total-1]` (or `0` when there are no steps). A
+   * non-finite index falls back to the first step: `current` is read from markup,
+   * so an unparsable attribute arrives as `NaN` and would otherwise propagate
+   * into every state hook.
+   */
   #clamp(index) {
     const last = this.stepTargets.length - 1;
-    if (last < 0) return 0;
+    if (last < 0 || !Number.isFinite(index)) return 0;
     return Math.min(last, Math.max(0, Math.trunc(index)));
   }
 };

data/dist/controllers/stick_to_bottom_controller.js

@@ -17,14 +17,18 @@ var StickToBottomController = class extends Controller {
   static targets = ["content"];
   static values = {
     threshold: { type: Number, default: 80 },
-    behavior: { type: String, default: "auto" }
+    behavior: { type: String, default: "auto" },
+    pinOnConnect: { type: Boolean, default: false }
   };
   static actions = ["scrollToBottom"];
   static events = ["pin", "new"];
   #observer = null;
+  /** Watches for the box a deferred `pinOnConnect` jump is still waiting on. */
+  #layout = null;
   #pinned = false;
   #onScroll = () => this.#updatePinned();
   connect() {
+    if (this.pinOnConnectValue && this.#measurable()) this.#scrollToBottom("instant");
     this.#pinned = this.#isPinned();
     this.#reflectPinned();
     this.element.addEventListener("scroll", this.#onScroll, { passive: true });
@@ -32,21 +36,29 @@ var StickToBottomController = class extends Controller {
       this.#observer = new MutationObserver((mutations) => this.#onMutations(mutations));
       this.#observer.observe(this.#watched(), { childList: true });
     }
+    if (this.pinOnConnectValue && !this.#measurable()) this.#pinWhenLaidOut();
   }
   disconnect() {
     this.element.removeEventListener("scroll", this.#onScroll);
     this.#observer?.disconnect();
     this.#observer = null;
+    this.#stopWaitingForLayout();
   }
-  /** Jumps to the bottom and re-pins (wired to a "new messages" button). */
+  /**
+   * Jumps to the bottom and re-pins (wired to a "new messages" button).
+   *
+   * The has-new flag clears on request — the user has acknowledged the arrival — while
+   * pinned is read back from where the scroll landed: a jump that arrives by the time
+   * this returns pins immediately, an animated one settles from its own scroll events,
+   * and a jump the engine cannot honor leaves the container unpinned, so the next append
+   * flags it again instead of being swallowed by a pinned state that does not hold.
+   *
+   * Which of those happens is not this method's to decide — see {@link behaviorValue}.
+   */
   scrollToBottom() {
     this.#scrollToBottom();
     this.element.removeAttribute("data-has-new");
-    if (!this.#pinned) {
-      this.#pinned = true;
-      this.element.setAttribute("data-pinned", "true");
-      this.dispatch("pin", { detail: { pinned: true } });
-    }
+    this.#updatePinned();
   }
   /** Follows appended children while pinned; otherwise flags new content. */
   #onMutations(mutations) {
@@ -81,10 +93,43 @@ var StickToBottomController = class extends Controller {
     const el = this.element;
     return el.scrollHeight - el.clientHeight - el.scrollTop <= this.thresholdValue;
   }
-  #scrollToBottom() {
+  /**
+   * Whether the container has a box to scroll and to measure. One that is not rendered
+   * (inside a closed panel) reports every metric as 0, which reads as "already at the
+   * bottom" — a position describing no layout the user will ever see.
+   */
+  #measurable() {
+    return this.element.clientHeight > 0;
+  }
+  /**
+   * Holds the `pinOnConnect` jump until the container is laid out, then runs it and
+   * re-reads the state — otherwise the panel opens at the top still claiming the bottom.
+   */
+  #pinWhenLaidOut() {
+    if (typeof ResizeObserver === "undefined") return;
+    this.#layout = new ResizeObserver(() => {
+      if (!this.#measurable()) return;
+      this.#stopWaitingForLayout();
+      this.#scrollToBottom("instant");
+      this.#updatePinned();
+    });
+    this.#layout.observe(this.element);
+  }
+  /** Releases the layout watch, whether or not the deferred jump ever ran. */
+  #stopWaitingForLayout() {
+    this.#layout?.disconnect();
+    this.#layout = null;
+  }
+  /**
+   * Scrolls to the bottom, clamped by the engine to the maximum scroll offset — which is
+   * 0 for a container tall enough to hold its whole content, so the jump moves nothing
+   * there. `behavior` defaults to the configured follow behavior; pass `"instant"` for a
+   * jump that must not animate.
+   */
+  #scrollToBottom(behavior = this.#behavior()) {
     const top = this.element.scrollHeight;
     if (typeof this.element.scrollTo === "function") {
-      this.element.scrollTo({ top, behavior: this.#behavior() });
+      this.element.scrollTo({ top, behavior });
     } else {
       this.element.scrollTop = top;
     }
@@ -93,7 +138,12 @@ var StickToBottomController = class extends Controller {
   #watched() {
     return this.hasContentTarget ? this.contentTarget : this.element;
   }
-  /** Forces reduced-motion jumps while preserving the configured normal behavior. */
+  /**
+   * The behavior a follow-scroll runs with. `"auto"` is **not** a request to arrive at
+   * once: it hands the decision to the element's computed `scroll-behavior`, so a
+   * consumer stylesheet saying `smooth` animates these scrolls too. Only `"instant"`
+   * overrides that CSS, which is why reduced motion and the `pinOnConnect` jump name it.
+   */
   #behavior() {
     if (prefersReducedMotion()) return "instant";
     return this.behaviorValue === "smooth" ? "smooth" : "auto";