stimeo-ui 0.16.0 → 0.18.0

data/dist/controllers/intersection_controller.js

@@ -1,8 +1,5 @@
 import { Controller } from '@hotwired/stimulus';
 
-// src/controllers/intersection_controller.ts
-
-// src/utils/declared_value.ts
 function parseDeclared(raw, parse, fallback) {
   try {
     return parse(raw);
@@ -10,8 +7,18 @@ function parseDeclared(raw, parse, fallback) {
     return fallback;
   }
 }
+function validSelector(element, raw, fallback) {
+  if (raw.length === 0) return fallback;
+  return parseDeclared(
+    raw,
+    (selector) => {
+      element.matches(selector);
+      return selector;
+    },
+    fallback
+  );
+}
 
-// src/utils/intersection_watcher.ts
 function isBeforeRootStart(entry) {
   const rect = entry.boundingClientRect;
   if (rect.width === 0 && rect.height === 0) return false;
@@ -30,30 +37,12 @@ var IntersectionWatcher = class {
   constructor(onEntries) {
     this.#onEntries = onEntries;
   }
-  /** Whether an observer is live (started, `IntersectionObserver` supported). */
   get active() {
     return this.#active;
   }
-  /** Whether the live observer discarded configured options after construction failed. */
   get usingPlatformDefaults() {
     return this.#usingPlatformDefaults;
   }
-  /**
-   * (Re)creates the observer and observes `targets`. Returns `false` — leaving
-   * the watcher inert — without `IntersectionObserver` support (very old
-   * browsers; the caller's no-JS fallback stays in charge) or with no targets.
-   * If initial construction with the configured options fails, the watcher
-   * warns and retries once with the same root and platform defaults. A
-   * `rootSelector` that does not parse resolves to the viewport (see
-   * {@link IntersectionWatchOptions.rootSelector}), so a typo never fails the
-   * call.
-   *
-   * @throws The fallback constructor error if both construction attempts fail,
-   *   or whatever the platform throws from `observe()`. The exception is passed
-   *   through unchanged, but the watcher rolls back first: every target observed
-   *   so far is released and `active` stays `false`, so a caller that retries
-   *   starts from a clean slate.
-   */
   start(targets, options = {}) {
     this.stop();
     if (typeof IntersectionObserver === "undefined") return false;
@@ -91,14 +80,6 @@ var IntersectionWatcher = class {
       throw error;
     }
   }
-  /**
-   * Re-delivers `target`'s CURRENT intersection state: `IntersectionObserver`
-   * only reports *changes*, but `observe()` always reports the present state,
-   * so unobserve→observe turns "still intersecting" into a fresh callback.
-   *
-   * @throws Whatever `unobserve()`/`observe()` throws. The watcher is stopped
-   *   first, so it never stays live with a half-rearmed target.
-   */
   rearm(target) {
     if (!this.#observer) return;
     try {
@@ -109,7 +90,6 @@ var IntersectionWatcher = class {
       throw error;
     }
   }
-  /** Severs the observer; late queued callbacks become no-ops via the guard. */
   stop() {
     this.#active = false;
     this.#observer?.disconnect();
@@ -118,10 +98,85 @@ var IntersectionWatcher = class {
   }
 };
 
-// src/controllers/intersection_controller.ts
+var MicrotaskCoalescer = class {
+  #run;
+  #queued = false;
+  #active = false;
+  #generation = 0;
+  constructor(run) {
+    this.#run = run;
+  }
+  activate() {
+    this.#active = true;
+  }
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  get pending() {
+    return this.#queued;
+  }
+  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();
+    });
+  }
+};
+
+var NUMBER_BOUNDS = {
+  finite: { finite: true }};
+function matchesNumberBounds(value, bounds) {
+  if (!Number.isFinite(value)) {
+    const direction = value === Infinity ? "positive" : value === -Infinity ? "negative" : null;
+    if (direction === null) return false;
+    if (bounds.allowInfinity !== "both" && bounds.allowInfinity !== direction) return false;
+  }
+  if (bounds.min !== void 0 && value < bounds.min) return false;
+  if (bounds.max !== void 0 && value > bounds.max) return false;
+  if (bounds.exclusiveMin !== void 0 && value <= bounds.exclusiveMin) return false;
+  if (bounds.integer && !Number.isInteger(value)) return false;
+  if (bounds.allowedValues !== void 0 && !bounds.allowedValues.includes(value)) return false;
+  return true;
+}
+
+function readNumber(raw, fallback, bounds) {
+  return matchesNumberBounds(raw, bounds) ? raw : fallback;
+}
+
+var NumberValueReader = class {
+  #lastRejected = /* @__PURE__ */ new Map();
+  read(owner, name, raw, fallback, bounds) {
+    const resolved = readNumber(raw, fallback, bounds);
+    if (matchesNumberBounds(raw, bounds)) {
+      this.#lastRejected.delete(name);
+      return resolved;
+    }
+    const attribute = `data-${owner.identifier}-${name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}-value`;
+    const literal = owner.element.getAttribute(attribute);
+    if (literal === null) {
+      this.#lastRejected.delete(name);
+      return resolved;
+    }
+    if (this.#lastRejected.get(name) !== literal) {
+      this.#lastRejected.set(name, literal);
+      console.warn(
+        `Stimeo UI: "${owner.identifier}" has an invalid number Value "${name}" declaration ${JSON.stringify(literal)}; using ${fallback}.`
+      );
+    }
+    return resolved;
+  }
+};
+
 var RATIO_PROPERTY = "--stimeo--intersection-ratio";
 var RATIO_EPSILON = 0.01;
-var IntersectionController = class extends Controller {
+var IntersectionController = class _IntersectionController extends Controller {
+  #numbers = new NumberValueReader();
   static values = {
     threshold: { type: Number, default: 0 },
     ratioSteps: { type: Number, default: 0 },
@@ -129,13 +184,18 @@ var IntersectionController = class extends Controller {
     rootSelector: { type: String, default: "" },
     once: { type: Boolean, default: false }
   };
+  static valueConstraints = {
+    threshold: NUMBER_BOUNDS.finite,
+    ratioSteps: { finite: true, min: 0, max: 1e3 }
+  };
   static actions = ["refresh"];
   static events = ["enter", "exit", "change", "passed"];
-  /** Shared IO plumbing (support guard, root resolution, active guard, re-arm). */
   #watcher = new IntersectionWatcher((entries) => this.#onIntersect(entries));
-  /** Threshold actually installed in the live observer (0 after option fallback). */
+  #rebuild = new MicrotaskCoalescer(() => this.#sync());
+  #rootSelector = "";
+  #builtRoot = null;
+  #builtOptions = "";
   #effectiveThreshold = 0;
-  /** Bumped by `refresh()`: an in-flight batch becomes stale and stops. */
   #generation = 0;
   #onIntersect(entries) {
     const generation = this.#generation;
@@ -151,46 +211,49 @@ var IntersectionController = class extends Controller {
     }
   }
   connect() {
-    if (this.onceValue && this.element.getAttribute("data-intersecting") === "true") return;
-    this.#observe();
+    this.#rebuild.activate();
+    this.#sync();
   }
   disconnect() {
+    this.#rebuild.cancel();
     this.#watcher.stop();
   }
-  /**
-   * Re-reads the visibility line and rebuilds the observer. Turbo 8 morphing
-   * rewrites the attribute in place without a reconnect, and the line is what
-   * the intersection callback compares every ratio against, so a value frozen at
-   * connect time would decide `data-intersecting` wrongly for the rest of the
-   * page's life. Nothing to rebuild before the first `connect()`; after a spent
-   * one-shot the watcher is deliberately stopped, and re-observing would deliver
-   * the current state and fire `enter` a second time.
-   */
   thresholdValueChanged() {
-    if (this.#watcher.active) this.#observe();
+    this.#rebuild.schedule();
+  }
+  ratioStepsValueChanged() {
+    this.#rebuild.schedule();
+  }
+  rootMarginValueChanged() {
+    this.#rebuild.schedule();
+  }
+  rootSelectorValueChanged() {
+    this.#rootSelector = validSelector(this.element, this.rootSelectorValue, "");
+    this.#rebuild.schedule();
   }
-  /** (Re)installs the observer from the current Values. */
-  #observe() {
-    this.#effectiveThreshold = this.#clampedThreshold();
+  onceValueChanged() {
+    this.#rebuild.schedule();
+  }
+  #sync() {
+    if (this.onceValue && this.element.getAttribute("data-intersecting") === "true") {
+      this.#watcher.stop();
+      return;
+    }
+    const root = this.#rootSelector ? document.querySelector(this.#rootSelector) : null;
+    const threshold = this.#clampedThreshold();
+    const thresholds = this.#thresholds();
+    const options = `${this.rootMarginValue} ${threshold} ${thresholds.join(",")}`;
+    if (this.#watcher.active && root === this.#builtRoot && options === this.#builtOptions) return;
+    this.#builtRoot = root;
+    this.#builtOptions = options;
+    this.#effectiveThreshold = threshold;
     this.#watcher.start(this.element, {
-      rootSelector: this.rootSelectorValue,
+      root,
       rootMargin: this.rootMarginValue,
-      threshold: this.#thresholds()
+      threshold: thresholds
     });
     if (this.#watcher.usingPlatformDefaults) this.#effectiveThreshold = 0;
   }
-  /**
-   * Re-delivers the current intersection state as a fresh transition. Bound via
-   * `data-action` (e.g. `my-feed:appended@window->stimeo--intersection#refresh`).
-   *
-   * `IntersectionObserver` only reports state *changes*, so a sentinel that
-   * stays visible while content is appended below it never fires `enter` again
-   * and a hand-rolled infinite scroll stalls. `observe()` always delivers the
-   * current state, and clearing the recorded `data-intersecting`/`data-passed`
-   * makes that delivery count as a transition — a still-visible sentinel
-   * re-fires `enter`. No-op once the observer is gone (`once` fired, no
-   * `IntersectionObserver` support, or after `disconnect()`).
-   */
   refresh() {
     if (!this.#watcher.active) return;
     this.#generation += 1;
@@ -198,16 +261,6 @@ var IntersectionController = class extends Controller {
     this.element.removeAttribute("data-passed");
     this.#watcher.rearm(this.element);
   }
-  /**
-   * Reflects the visibility onto `data-intersecting` and fires `enter`/`exit`
-   * on transitions. The previous state is the DOM attribute (source of truth),
-   * so the observer's initial callback fires `enter` for an element that starts
-   * visible but stays silent after a cache restore that already recorded it.
-   * An initial not-visible state is established silently (no `exit`).
-   *
-   * @stimeoRuntimeOnly `once` decides whether this enter spends the watcher's one shot; the hook it
-   *   writes follows the entry.
-   */
   #syncIntersecting(intersecting, ratio, entry) {
     const previous = this.element.getAttribute("data-intersecting");
     this.element.setAttribute("data-intersecting", intersecting ? "true" : "false");
@@ -220,57 +273,48 @@ var IntersectionController = class extends Controller {
       });
     }
   }
-  /**
-   * Which edge the element left across, for the `exit` detail. A non-zero
-   * `threshold` withdraws visibility while the element still overlaps the root,
-   * so the leaving rect can straddle the start edge — the direction is the
-   * element's own top against that edge, not whether it has cleared the root
-   * entirely (that is what `passed` reports). An element with no layout box
-   * (`display: none`, a collapsed `<details>`) is reported with an empty rect
-   * that carries no position at all, so it is deliberately neither direction
-   * and takes the "still ahead" reading.
-   */
   #leftViaStartEdge(entry) {
     const rect = entry.boundingClientRect;
     if (rect.width === 0 && rect.height === 0) return false;
     return rect.top < (entry.rootBounds?.top ?? 0);
   }
-  /**
-   * Reflects the "scrolled past" state onto `data-passed` and fires `passed` on
-   * transitions — the line sticky headers and reading progress key off. Like
-   * `enter`, an initial `passed=true` (page restored mid-scroll) fires; the
-   * initial `false` is established silently.
-   */
   #syncPassed(passed) {
     const previous = this.element.getAttribute("data-passed");
     this.element.setAttribute("data-passed", passed ? "true" : "false");
     const changed = previous === null ? passed : previous === "true" !== passed;
     if (changed) this.dispatch("passed", { detail: { passed } });
   }
-  /** The configured `threshold`, clamped to the 0..1 the observer accepts. */
   #clampedThreshold() {
-    return Math.min(1, Math.max(0, this.thresholdValue));
+    return Math.min(1, Math.max(0, this.#safeThreshold));
   }
-  /**
-   * Observer thresholds: the `threshold` line itself, plus `ratioSteps` evenly
-   * spaced steps when fine-grained `change` ratios are wanted (progress bars).
-   *
-   * 0 is always observed. An observer notifies only at the lines it was given,
-   * so a non-zero `threshold` on its own delivers its last callback while the
-   * element is still partly visible: the element leaving for good would never be
-   * reported, freezing the ratio and `data-passed` mid-departure.
-   */
   #thresholds() {
     const thresholds = /* @__PURE__ */ new Set([0, this.#clampedThreshold()]);
-    if (this.ratioStepsValue > 0) {
-      for (let i = 0; i <= this.ratioStepsValue; i += 1) {
-        thresholds.add(i / this.ratioStepsValue);
+    if (this.#safeRatioSteps > 0) {
+      for (let i = 0; i <= this.#safeRatioSteps; i += 1) {
+        thresholds.add(i / this.#safeRatioSteps);
       }
     }
     return [...thresholds].sort((a, b) => a - b);
   }
+  get #safeThreshold() {
+    return this.#numbers.read(
+      this,
+      "threshold",
+      this.thresholdValue,
+      _IntersectionController.values.threshold.default,
+      _IntersectionController.valueConstraints.threshold
+    );
+  }
+  get #safeRatioSteps() {
+    return this.#numbers.read(
+      this,
+      "ratioSteps",
+      this.ratioStepsValue,
+      _IntersectionController.values.ratioSteps.default,
+      _IntersectionController.valueConstraints.ratioSteps
+    );
+  }
 };
 
 export { IntersectionController };
-//# sourceMappingURL=intersection_controller.js.map
 //# sourceMappingURL=intersection_controller.js.map

data/dist/controllers/lazy_frame_controller.js

@@ -1,8 +1,5 @@
 import { Controller } from '@hotwired/stimulus';
 
-// src/controllers/lazy_frame_controller.ts
-
-// src/utils/declared_value.ts
 function parseDeclared(raw, parse, fallback) {
   try {
     return parse(raw);
@@ -11,7 +8,6 @@ function parseDeclared(raw, parse, fallback) {
   }
 }
 
-// src/utils/intersection_watcher.ts
 function queryRoot(selector) {
   if (!selector) return null;
   return parseDeclared(selector, (raw) => document.querySelector(raw), null);
@@ -24,30 +20,12 @@ var IntersectionWatcher = class {
   constructor(onEntries) {
     this.#onEntries = onEntries;
   }
-  /** Whether an observer is live (started, `IntersectionObserver` supported). */
   get active() {
     return this.#active;
   }
-  /** Whether the live observer discarded configured options after construction failed. */
   get usingPlatformDefaults() {
     return this.#usingPlatformDefaults;
   }
-  /**
-   * (Re)creates the observer and observes `targets`. Returns `false` — leaving
-   * the watcher inert — without `IntersectionObserver` support (very old
-   * browsers; the caller's no-JS fallback stays in charge) or with no targets.
-   * If initial construction with the configured options fails, the watcher
-   * warns and retries once with the same root and platform defaults. A
-   * `rootSelector` that does not parse resolves to the viewport (see
-   * {@link IntersectionWatchOptions.rootSelector}), so a typo never fails the
-   * call.
-   *
-   * @throws The fallback constructor error if both construction attempts fail,
-   *   or whatever the platform throws from `observe()`. The exception is passed
-   *   through unchanged, but the watcher rolls back first: every target observed
-   *   so far is released and `active` stays `false`, so a caller that retries
-   *   starts from a clean slate.
-   */
   start(targets, options = {}) {
     this.stop();
     if (typeof IntersectionObserver === "undefined") return false;
@@ -85,14 +63,6 @@ var IntersectionWatcher = class {
       throw error;
     }
   }
-  /**
-   * Re-delivers `target`'s CURRENT intersection state: `IntersectionObserver`
-   * only reports *changes*, but `observe()` always reports the present state,
-   * so unobserve→observe turns "still intersecting" into a fresh callback.
-   *
-   * @throws Whatever `unobserve()`/`observe()` throws. The watcher is stopped
-   *   first, so it never stays live with a half-rearmed target.
-   */
   rearm(target) {
     if (!this.#observer) return;
     try {
@@ -103,7 +73,6 @@ var IntersectionWatcher = class {
       throw error;
     }
   }
-  /** Severs the observer; late queued callbacks become no-ops via the guard. */
   stop() {
     this.#active = false;
     this.#observer?.disconnect();
@@ -112,7 +81,17 @@ var IntersectionWatcher = class {
   }
 };
 
-// src/controllers/lazy_frame_controller.ts
+var ListenerSet = class {
+  #abort = new AbortController();
+  add(target, type, handler, options) {
+    target.addEventListener(type, handler, { ...options, signal: this.#abort.signal });
+  }
+  dispose() {
+    this.#abort.abort();
+    this.#abort = new AbortController();
+  }
+};
+
 var LazyFrameController = class extends Controller {
   static values = {
     url: { type: String, default: "" },
@@ -120,38 +99,29 @@ var LazyFrameController = class extends Controller {
     once: { type: Boolean, default: true }
   };
   static events = ["load"];
-  /** Shared IO plumbing (support guard, active guard, teardown). */
   #watcher = new IntersectionWatcher((entries) => this.#onIntersect(entries));
   #connected = false;
   #loaded = false;
-  /**
-   * Whether the observer last saw the frame inside the observed area — `null`
-   * until it has reported. A re-entry needs a frame that was seen inside and
-   * then left, so an unknown position is never a departure.
-   */
   #inside = null;
-  /**
-   * Focus reaching the frame starts the FIRST load before it intersects (keyboard / AT).
-   * `#load` releases this listener, so focus never reaches an already-loaded frame.
-   */
   #onFocus = () => this.#load();
-  /**
-   * Follows the held URL at runtime: one that arrives arms the frame, one that is
-   * taken away disarms it, so an empty `url` holds no triggers either way.
-   *
-   * Stimulus runs value callbacks before `connect()`, so the connected guard keeps
-   * arming in one place. A frame that already loaded keeps its held URL for the next
-   * re-entry instead of fetching on the spot.
-   */
+  #focusListeners = new ListenerSet();
   urlValueChanged() {
     if (!this.#connected || this.#loaded) return;
     if (this.urlValue) this.#arm();
     else this.#stopObserving();
   }
-  /** Rebuilds the observer when the early-load margin changes at runtime. */
   rootMarginValueChanged() {
     if (this.#connected && this.#watcher.active) this.#observe();
   }
+  onceValueChanged() {
+    if (!this.#connected || !this.#loaded) return;
+    if (this.onceValue) {
+      this.#watcher.stop();
+    } else if (!this.#watcher.active) {
+      this.#inside = null;
+      this.#arm();
+    }
+  }
   connect() {
     this.#loaded = this.element.hasAttribute("data-lazy-loaded");
     this.#inside = null;
@@ -163,10 +133,9 @@ var LazyFrameController = class extends Controller {
     this.#connected = false;
     this.#stopObserving();
   }
-  /** Attaches the triggers that still have a job to do. */
   #arm() {
     if (!this.urlValue) return;
-    if (!this.#loaded) this.element.addEventListener("focusin", this.#onFocus);
+    if (!this.#loaded) this.#focusListeners.add(this.element, "focusin", this.#onFocus);
     this.#observe();
   }
   #observe() {
@@ -183,7 +152,6 @@ var LazyFrameController = class extends Controller {
       }
     }
   }
-  /** Applies an intersecting entry: the first one loads, a return re-fetches. */
   #enter(returning) {
     if (!this.#loaded) {
       this.#load();
@@ -192,26 +160,15 @@ var LazyFrameController = class extends Controller {
     if (this.onceValue || !returning) return;
     this.#reload();
   }
-  /**
-   * Starts the load by writing the held URL to `src`.
-   *
-   * @stimeoRuntimeOnly `url` is the address this one load fetches and `once` decides whether it
-   *   stops the watcher.
-   */
   #load() {
     if (!this.urlValue) return;
     this.#loaded = true;
     this.element.setAttribute("src", this.urlValue);
     this.element.setAttribute("data-lazy-loaded", "true");
     this.dispatch("load", { detail: { url: this.urlValue } });
-    this.element.removeEventListener("focusin", this.#onFocus);
+    this.#focusListeners.dispose();
     if (this.onceValue) this.#watcher.stop();
   }
-  /**
-   * Re-entry while `once` is off: fetch the held URL again.
-   *
-   * @stimeoRuntimeOnly `url` is the address this one re-entry reloads.
-   */
   #reload() {
     const src = this.element.getAttribute("src");
     if (this.urlValue && this.urlValue !== src) {
@@ -226,10 +183,9 @@ var LazyFrameController = class extends Controller {
   }
   #stopObserving() {
     this.#watcher.stop();
-    this.element.removeEventListener("focusin", this.#onFocus);
+    this.#focusListeners.dispose();
   }
 };
 
 export { LazyFrameController };
-//# sourceMappingURL=lazy_frame_controller.js.map
 //# sourceMappingURL=lazy_frame_controller.js.map