stimeo-ui 0.3.0 → 0.4.0

data/dist/controllers/relative_time_controller.js

@@ -2,6 +2,68 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/relative_time_controller.ts
 
+// 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/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/utils/safe_timeout.ts
 var TimerRegistry = class {
   /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
@@ -73,11 +135,16 @@ var RelativeTimeController = class extends Controller {
     tickInterval: { type: Number, default: 6e4 }
   };
   #timers = new SafeTimeout();
+  /** Collapses a morph that swaps several render inputs at once into one repaint. */
+  #resync = new MicrotaskCoalescer(() => this.#resyncToValues());
+  #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
   /** Epoch ms parsed from `datetime`; `NaN` when absent or invalid. */
   #targetMs = Number.NaN;
   /** The authored absolute text, restored when the threshold fallback kicks in. */
   #absoluteText = "";
   connect() {
+    this.#resync.activate();
+    this.#beforeCache.activate();
     if (this.element.getAttribute("data-state") !== "relative") {
       this.#absoluteText = (this.element.textContent ?? "").trim();
     }
@@ -86,9 +153,50 @@ var RelativeTimeController = class extends Controller {
     this.#schedule();
   }
   disconnect() {
+    this.#resync.cancel();
+    this.#beforeCache.deactivate();
+    this.#timers.clearAll();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `locale` at runtime. */
+  localeValueChanged() {
+    this.#resync.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `threshold` at runtime. */
+  thresholdValueChanged() {
+    this.#resync.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `tickInterval` at runtime. */
+  tickIntervalValueChanged() {
+    this.#resync.schedule();
+  }
+  /**
+   * Renders against the current Values and re-arms the poll from now.
+   *
+   * Render only: it emits no event, and clearing first keeps the single self-arming
+   * timer single — scheduling on top of a pending one would double the poll rate for
+   * the rest of the session. A stamp whose `datetime` never parsed has nothing to
+   * render, and one that already reached its terminal fallback simply renders it
+   * again and stops.
+   */
+  #resyncToValues() {
+    if (Number.isNaN(this.#targetMs)) return;
     this.#timers.clearAll();
+    this.#schedule();
+  }
+  /**
+   * Restores the authored absolute text and the pre-render state for the snapshot
+   * Turbo is about to take, leaving the live page's poll timer alone.
+   *
+   * With no authored text held there is nothing to restore, and `data-state` has to
+   * stay as it is: that marker is what tells the next `connect()` the visible text is
+   * a rendered relative form rather than an absolute fallback to hold on to.
+   */
+  #rewindForCache() {
+    if (!this.#absoluteText) return;
+    this.element.textContent = this.#absoluteText;
+    this.element.removeAttribute("data-state");
   }
-  /** Renders the current representation and reschedules unless it is now absolute. */
+  /** Renders the current representation and reschedules unless polling can stop. */
   #schedule() {
     const nextDelay = this.#applyAndComputeDelay();
     if (nextDelay !== null) {
@@ -96,31 +204,44 @@ var RelativeTimeController = class extends Controller {
     }
   }
   /**
-   * Updates the visible text and returns the next poll delay (ms), or `null`
-   * once the absolute fallback is shown (which never changes, so stop polling).
+   * Updates the visible text and returns the next poll delay (ms), or `null` when
+   * polling can stop: a *past* timestamp that fell back to the absolute text can
+   * never leave it again, and a locale the runtime rejects has nothing to render
+   * until that value is corrected.
    */
   #applyAndComputeDelay() {
     const deltaMs = this.#targetMs - Date.now();
     const absSeconds = Math.abs(deltaMs) / 1e3;
+    const scale = UNITS.find((u) => absSeconds < u.limit) ?? YEAR_SCALE;
+    const unitFloor = scale.unit === "second" || scale.unit === "minute" ? 6e4 : scale.ms;
+    const nextDelay = Math.max(this.tickIntervalValue, Math.min(unitFloor, 864e5));
     if (this.thresholdValue > 0 && absSeconds >= this.thresholdValue && this.#absoluteText) {
       this.element.textContent = this.#absoluteText;
       this.element.setAttribute("data-state", "absolute");
-      return null;
+      if (deltaMs <= 0) return null;
+      return Math.min(nextDelay, deltaMs - this.thresholdValue * 1e3 + 1);
     }
-    const scale = UNITS.find((u) => absSeconds < u.limit) ?? YEAR_SCALE;
+    const formatter = this.#formatter;
+    if (formatter === null) return null;
     const value = Math.round(deltaMs / scale.ms);
-    this.element.textContent = this.#formatter.format(value, scale.unit);
+    this.element.textContent = formatter.format(value, scale.unit);
     this.element.setAttribute("data-state", "relative");
-    const unitFloor = scale.unit === "second" || scale.unit === "minute" ? 6e4 : scale.ms;
-    return Math.max(this.tickIntervalValue, Math.min(unitFloor, 864e5));
+    return nextDelay;
   }
-  /** A `RelativeTimeFormat` for the resolved locale (`numeric: "auto"`). */
+  /**
+   * A `RelativeTimeFormat` for the resolved locale (`numeric: "auto"`), or `null`
+   * when the runtime rejects that locale.
+   */
   get #formatter() {
-    return new Intl.RelativeTimeFormat(this.#locale, { numeric: "auto" });
+    try {
+      return new Intl.RelativeTimeFormat(this.#locale, { numeric: "auto" });
+    } catch {
+      return null;
+    }
   }
-  /** Locale precedence: the value, then the element's `lang`, then the document's. */
+  /** Locale precedence: the value, then the nearest `lang` up the ancestor chain. */
   get #locale() {
-    return this.localeValue || this.element.lang || document.documentElement.lang || void 0;
+    return this.localeValue || this.element.closest("[lang]")?.getAttribute("lang") || void 0;
   }
 };
 

data/dist/controllers/sidebar_controller.js

@@ -2,6 +2,35 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/sidebar_controller.ts
 
+// 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/escape_layer.ts
 var EscapeLayer = class _EscapeLayer {
   static #registries = /* @__PURE__ */ new WeakMap();
@@ -135,7 +164,7 @@ var FocusTrap = class {
     }
     if (this.#flag(this.#options.isolate, true)) this.#isolateBackground();
     document.addEventListener("keydown", this.#onKeydown);
-    document.addEventListener("turbo:before-cache", this.#onBeforeCache);
+    this.#beforeCache.activate();
     const onEscape = this.#options.onEscape;
     if (onEscape) this.#escapeLayer.activate(document, { onDismiss: () => onEscape() });
     if (this.#flag(this.#options.autoFocus, true)) this.#focusInitial();
@@ -152,7 +181,7 @@ var FocusTrap = class {
     this.#activeState = false;
     this.#escapeLayer.deactivate();
     document.removeEventListener("keydown", this.#onKeydown);
-    document.removeEventListener("turbo:before-cache", this.#onBeforeCache);
+    this.#beforeCache.deactivate();
     if (this.#scrollLocked) {
       document.body.style.overflow = this.#previousBodyOverflow;
       this.#scrollLocked = false;
@@ -176,9 +205,7 @@ var FocusTrap = class {
    * untouched (restore-open designs reopen against a clean baseline), and focus
    * is left alone mid-navigation. The listener lives only while active.
    */
-  #onBeforeCache = () => {
-    this.deactivate({ restoreFocus: false });
-  };
+  #beforeCache = new BeforeCacheReset(() => this.deactivate({ restoreFocus: false }));
   /**
    * Handles `Tab` (focus trap) while active. `Escape` dismissal is owned by the
    * shared {@link EscapeLayer} resolver, so Tab trapping stays independent of
@@ -474,7 +501,7 @@ var SidebarController = class extends Controller {
     key: { type: String, default: "" },
     collapsed: { type: Boolean, default: false }
   };
-  static actions = ["beforeCache", "close", "open", "toggle"];
+  static actions = ["close", "open", "toggle"];
   /** Exact panel currently owned by the modal lifecycle (survives target churn safely). */
   #activePanel = null;
   /** Owns the overlay modal side effects; Escape closes, focus falls to trigger. */
@@ -496,6 +523,7 @@ var SidebarController = class extends Controller {
   #connected = false;
   connect() {
     this.#connected = true;
+    this.#beforeCache.activate();
     this.#activePanel = this.hasPanelTarget ? this.panelTarget : null;
     this.#collapsed = this.#restoreCollapsed();
     this.#mqlQuery = this.#breakpointQuery;
@@ -505,6 +533,7 @@ var SidebarController = class extends Controller {
   }
   disconnect() {
     this.#connected = false;
+    this.#beforeCache.deactivate();
     this.#mql?.removeEventListener("change", this.#onMediaChange);
     this.#mql = null;
     this.#mqlQuery = null;
@@ -556,12 +585,12 @@ var SidebarController = class extends Controller {
    * closed immediately, and modal side effects are released without moving
    * focus during navigation.
    */
-  beforeCache() {
+  #beforeCache = new BeforeCacheReset(() => {
     if (!this.#connected || !this.#isOverlay) return;
     this.#transition.cancel();
     this.#trap.deactivate({ restoreFocus: false });
     this.#setOverlayClosedImmediate();
-  }
+  });
   /** Toggles the panel: inline flips collapsed/expanded, overlay flips open/closed. */
   toggle() {
     if (this.#isOverlay) {

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

@@ -18,6 +18,22 @@ function isReservedArrowChord(event, allow = []) {
   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 {
@@ -123,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 } });
   }