stimeo-ui 0.2.1 → 0.4.0

data/dist/controllers/range_slider_controller.js

@@ -1,5 +1,72 @@
 import { Controller } from '@hotwired/stimulus';
 
+// src/controllers/range_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/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/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/range_slider_controller.ts
 var START_PROPERTY = "--stimeo-range-start";
 var END_PROPERTY = "--stimeo-range-end";
@@ -10,25 +77,48 @@ var RangeSliderController = class extends Controller {
     max: { type: Number, default: 100 },
     step: { type: Number, default: 1 },
     start: { type: Number, default: 0 },
-    end: { type: Number, default: 100 }
+    end: { type: Number, default: 100 },
+    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);
+  }
   /** Normalizes the initial pair (clamped, snapped, ordered) and renders. */
+  /**
+   * Collapses a morph that swaps render inputs into one repaint, and refuses the
+   * pass Stimulus delivers before `connect()`.
+   */
+  #repaint = new MicrotaskCoalescer(() => {
+    this.#render(this.startValue, this.endValue);
+  });
   connect() {
+    this.#repaint.activate();
     const lo = Math.min(this.startValue, this.endValue);
     const hi = Math.max(this.startValue, this.endValue);
     this.#commit(lo, hi, false);
   }
   /** Cancels any active pointer drag so document listeners never leak. */
   disconnect() {
+    this.#repaint.cancel();
     this.#dragAbort?.abort();
     this.#dragAbort = null;
   }
+  /** Repaints when application code (or a Turbo morph) changes `min` at runtime. */
+  minValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `max` at runtime. */
+  maxValueChanged() {
+    this.#repaint.schedule();
+  }
   /** Keyboard stepping for whichever thumb is focused (the action's element). */
   onKeydown(event) {
+    if (isReservedArrowChord(event)) return;
     const thumb = event.currentTarget;
     const isStart = this.hasStartThumbTarget && thumb === this.startThumbTarget;
     const current = isStart ? this.startValue : this.endValue;
@@ -36,7 +126,7 @@ var RangeSliderController = class extends Controller {
     const upper = isStart ? this.endValue : this.maxValue;
     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 = current + this.stepValue;
@@ -66,7 +156,8 @@ var RangeSliderController = class extends Controller {
   /** Begins a pointer drag on the track, moving the thumb nearest the press. */
   onPointerDown(event) {
     if (!this.hasTrackTarget) return;
-    const value = this.#valueFromClientX(event.clientX);
+    const mirrored = this.#mirrored;
+    const value = this.#valueFromClientX(event.clientX, mirrored);
     if (value === null) return;
     event.preventDefault();
     const useStart = Math.abs(value - this.startValue) <= Math.abs(value - this.endValue);
@@ -80,7 +171,7 @@ var RangeSliderController = class extends Controller {
     const abort = new AbortController();
     this.#dragAbort = abort;
     const onMove = (move) => {
-      const moved = this.#valueFromClientX(move.clientX);
+      const moved = this.#valueFromClientX(move.clientX, mirrored);
       if (moved !== null) this.#moveThumb(useStart, moved);
     };
     const onUp = () => {
@@ -92,10 +183,11 @@ var RangeSliderController = class extends Controller {
     document.addEventListener("pointercancel", onUp, { signal: abort.signal });
   }
   /** Maps a pointer X coordinate to a raw value using the track geometry. */
-  #valueFromClientX(clientX) {
+  #valueFromClientX(clientX, mirrored) {
     const rect = this.trackTarget.getBoundingClientRect();
     if (rect.width === 0) return null;
-    const fraction = (clientX - rect.left) / rect.width;
+    const offset = (clientX - rect.left) / rect.width;
+    const fraction = mirrored ? 1 - offset : offset;
     return this.minValue + fraction * (this.maxValue - this.minValue);
   }
   /** Moves one thumb to a new raw value, keeping the pair ordered. */
@@ -139,14 +231,13 @@ var RangeSliderController = class extends Controller {
       this.endThumbTarget.setAttribute("aria-valuemax", String(this.maxValue));
       this.endThumbTarget.setAttribute("aria-valuenow", String(end));
     }
-    const span = this.maxValue - this.minValue;
     this.element.style.setProperty(
       START_PROPERTY,
-      String(span > 0 ? (start - this.minValue) / span : 0)
+      String(rangeFraction(start, this.minValue, this.maxValue))
     );
     this.element.style.setProperty(
       END_PROPERTY,
-      String(span > 0 ? (end - this.minValue) / span : 0)
+      String(rangeFraction(end, this.minValue, this.maxValue))
     );
   }
   /** Clamps `raw` to `[min, max]` and snaps it to the nearest step from `min`. */

data/dist/controllers/rating_controller.js

@@ -2,6 +2,50 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/rating_controller.ts
 
+// src/utils/logical_scroll.ts
+function isRtl(element) {
+  return window.getComputedStyle(element).direction === "rtl";
+}
+
+// src/utils/arrow_step.ts
+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/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/roving_tabindex.ts
 var RovingTabindex = class {
   /** Returns the current ordered item elements; called on every operation. */
@@ -48,13 +92,33 @@ var RatingController = class extends Controller {
   static events = ["change"];
   #roving = new RovingTabindex(() => this.symbolTargets);
   /** Reflects the initial value, or switches to the non-interactive readonly view. */
+  /**
+   * Collapses a morph that swaps render inputs into one repaint, and refuses the
+   * pass Stimulus delivers before `connect()`.
+   */
+  #repaint = new MicrotaskCoalescer(() => {
+    if (this.readonlyValue) {
+      this.#applyReadonly();
+      return;
+    }
+    this.#apply(this.#clamp(this.valueValue), { focus: false });
+  });
   connect() {
+    this.#repaint.activate();
     if (this.readonlyValue) {
       this.#applyReadonly();
       return;
     }
     this.#apply(this.#clamp(this.valueValue), { focus: false });
   }
+  /** Closes the window in which a queued repaint may still run. */
+  disconnect() {
+    this.#repaint.cancel();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `value` at runtime. */
+  valueValueChanged() {
+    this.#repaint.schedule();
+  }
   /** Selects (or clears) the clicked symbol. Bound via `data-action` (click). */
   select(event) {
     if (this.readonlyValue) return;
@@ -77,16 +141,19 @@ var RatingController = class extends Controller {
   }
   /** Arrow/Home/End/Space keyboard control, clamped (no wrap). */
   onKeydown(event) {
+    if (event.defaultPrevented) return;
+    if (isReservedArrowChord(event)) return;
     if (this.readonlyValue) return;
     let next = null;
+    const rtl = isRtl(this.element);
     switch (event.key) {
       case "ArrowRight":
       case "ArrowUp":
-        next = this.valueValue + 1;
+        next = this.valueValue + (event.key === "ArrowRight" && rtl ? -1 : 1);
         break;
       case "ArrowLeft":
       case "ArrowDown":
-        next = this.valueValue - 1;
+        next = this.valueValue - (event.key === "ArrowLeft" && rtl ? -1 : 1);
         break;
       case "Home":
         next = this.#minValue;

data/dist/controllers/read_more_controller.js

@@ -2,6 +2,61 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/read_more_controller.ts
 
+// src/utils/blur_deferral.ts
+var BlurDeferral = class {
+  /** Elements currently holding an update back, mapped to their `blur` listener. */
+  #pending = /* @__PURE__ */ new Map();
+  /** Called after a pending element blurs and has been detached. */
+  #onRelease;
+  /** @param onRelease - Invoked once `element` actually blurs; never on `release`. */
+  constructor(onRelease) {
+    this.#onRelease = onRelease;
+  }
+  /** Number of elements currently holding an update back. */
+  get size() {
+    return this.#pending.size;
+  }
+  /** Snapshot of the pending elements, safe to iterate while releasing them. */
+  get elements() {
+    return [...this.#pending.keys()];
+  }
+  /** Whether `element` is currently holding an update back. */
+  has(element) {
+    return this.#pending.has(element);
+  }
+  /** Holds an update back until `element` blurs. Idempotent (no stacked listeners). */
+  defer(element) {
+    if (this.#pending.has(element)) return;
+    const onBlur = () => {
+      this.#detach(element);
+      this.#onRelease(element);
+    };
+    this.#pending.set(element, onBlur);
+    element.addEventListener("blur", onBlur);
+  }
+  /** Defers `element` as the only pending entry, cancelling any others. */
+  deferOnly(element) {
+    for (const pending of this.elements) {
+      if (pending !== element) this.#detach(pending);
+    }
+    this.defer(element);
+  }
+  /** Cancels `element`'s deferral without completing it; no-ops when not pending. */
+  release(element) {
+    this.#detach(element);
+  }
+  /** Cancels every deferral without completing any of them. */
+  releaseAll() {
+    for (const element of this.elements) this.#detach(element);
+  }
+  /** Removes the `blur` listener for `element` and forgets it. */
+  #detach(element) {
+    const onBlur = this.#pending.get(element);
+    if (onBlur) element.removeEventListener("blur", onBlur);
+    this.#pending.delete(element);
+  }
+};
+
 // src/utils/layout_observer.ts
 var LayoutObserver = class {
   #callback;
@@ -69,15 +124,14 @@ var ReadMoreController = class extends Controller {
   #collapsed = true;
   #observedContent = null;
   #contentMutationObserver = null;
-  #deferredHideTrigger = null;
   #update = () => {
     if (this.#connected) this.#evaluateOverflow();
   };
   #layout = new LayoutObserver(this.#update);
-  #onDeferredHideBlur = () => {
-    this.#clearDeferredHide();
+  /** Holds the trigger's hide back while it has focus; re-evaluates on blur. */
+  #deferredHide = new BlurDeferral(() => {
     this.#update();
-  };
+  });
   connect() {
     this.#connected = true;
     this.#collapsed = this.#initialCollapsed();
@@ -98,7 +152,7 @@ var ReadMoreController = class extends Controller {
     this.#syncTargets();
   }
   triggerTargetDisconnected(trigger) {
-    if (this.#deferredHideTrigger === trigger) this.#clearDeferredHide();
+    this.#deferredHide.release(trigger);
     this.#syncTargets();
   }
   /** Toggles between the collapsed (clamped) and expanded states. */
@@ -149,7 +203,7 @@ var ReadMoreController = class extends Controller {
     }
   }
   #stopObservingContent() {
-    this.#clearDeferredHide();
+    this.#deferredHide.releaseAll();
     if (this.#observedContent) {
       this.#layout.unobserve(this.#observedContent);
       this.#observedContent.removeEventListener("load", this.#update, true);
@@ -159,32 +213,22 @@ var ReadMoreController = class extends Controller {
     this.#contentMutationObserver = null;
     this.#layout.unobserveViewport();
   }
-  #deferHide(trigger) {
-    if (this.#deferredHideTrigger === trigger) return;
-    this.#clearDeferredHide();
-    this.#deferredHideTrigger = trigger;
-    trigger.addEventListener("blur", this.#onDeferredHideBlur);
-  }
-  #clearDeferredHide() {
-    this.#deferredHideTrigger?.removeEventListener("blur", this.#onDeferredHideBlur);
-    this.#deferredHideTrigger = null;
-  }
   #evaluateOverflow() {
     if (!this.hasTriggerTarget || !this.hasContentTarget) return;
     const trigger = this.triggerTarget;
     const content = this.contentTarget;
     const useful = !this.#collapsed || content.scrollHeight > content.clientHeight;
     if (useful) {
-      this.#clearDeferredHide();
+      this.#deferredHide.releaseAll();
       trigger.hidden = false;
       return;
     }
     if (document.activeElement === trigger) {
       trigger.hidden = false;
-      this.#deferHide(trigger);
+      this.#deferredHide.deferOnly(trigger);
       return;
     }
-    this.#clearDeferredHide();
+    this.#deferredHide.releaseAll();
     trigger.hidden = true;
   }
 };

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;
   }
 };