stimeo-ui 0.14.0 → 0.16.0

data/dist/controllers/scroll_area_controller.js

@@ -150,16 +150,51 @@ function hasTabStop(root) {
   return firstTabStop(root) !== null;
 }
 
+// src/utils/frame_coalescer.ts
+var FrameCoalescer = class {
+  #frame = null;
+  /**
+   * Runs `run` on the next frame, unless a frame is already pending — the first
+   * request of a burst wins and the rest are dropped. The pending frame is
+   * released before `run`, so `run` may request the next one.
+   */
+  schedule(run) {
+    if (this.#frame !== null) return;
+    this.#frame = requestAnimationFrame(() => {
+      this.#frame = null;
+      run();
+    });
+  }
+  /**
+   * Drops the pending frame, and reaches the platform only when there is one.
+   *
+   * There is no handle value that stands for "nothing pending":
+   * `cancelAnimationFrame` takes an `unsigned long`, so a negative placeholder
+   * arrives as a large positive number that the same allocator can hand out, and
+   * an idle cancel would then drop a frame belonging to someone else.
+   */
+  cancel() {
+    if (this.#frame === null) return;
+    cancelAnimationFrame(this.#frame);
+    this.#frame = null;
+  }
+};
+
 // src/utils/layout_observer.ts
 var LayoutObserver = class {
   #callback;
   #resizeObserverFactory;
   #resizeObserver = null;
   #observingViewport = false;
+  #loadContainer = null;
   /** Stable bound handler so add/removeEventListener target the same reference. */
   #handleViewportResize = () => {
     this.#callback();
   };
+  /** Stable bound handler for the capture-phase `load`; see {@link observeDescendantLoads}. */
+  #handleDescendantLoad = () => {
+    this.#callback();
+  };
   constructor(callback, options = {}) {
     this.#callback = callback;
     this.#resizeObserverFactory = options.resizeObserverFactory ?? (typeof ResizeObserver === "undefined" ? null : (cb) => new ResizeObserver(cb));
@@ -195,14 +230,35 @@ var LayoutObserver = class {
     window.removeEventListener("resize", this.#handleViewportResize);
   }
   /**
-   * Releases every observation: disconnects the {@link ResizeObserver} and
-   * removes the viewport listener. Safe to call multiple times. Call this from a
-   * controller's `disconnect()`.
+   * Starts reporting a `load` from anywhere inside `container` — an image or a
+   * frame settling changes the box it sits in, and it measures as zero high until
+   * then. `load` does not bubble, so the subscription is a capture-phase listener
+   * on the container itself and nothing the caller spells.
+   *
+   * **One container at a time.** A further call moves the observation, so a widget
+   * whose content element is swapped at runtime releases the element it let go by
+   * naming the new one — there is no second place for the release to drift from.
+   */
+  observeDescendantLoads(container) {
+    this.unobserveDescendantLoads();
+    this.#loadContainer = container;
+    container.addEventListener("load", this.#handleDescendantLoad, true);
+  }
+  /** Stops reporting descendant loads without affecting element or viewport observation. */
+  unobserveDescendantLoads() {
+    this.#loadContainer?.removeEventListener("load", this.#handleDescendantLoad, true);
+    this.#loadContainer = null;
+  }
+  /**
+   * Releases every observation: disconnects the {@link ResizeObserver} and removes
+   * the viewport and descendant-load listeners. Safe to call multiple times. Call
+   * this from a controller's `disconnect()`.
    */
   disconnect() {
     this.#resizeObserver?.disconnect();
     this.#resizeObserver = null;
     this.unobserveViewport();
+    this.unobserveDescendantLoads();
   }
 };
 
@@ -359,20 +415,14 @@ var ScrollAreaController = class extends Controller {
   #observedNameIds = /* @__PURE__ */ new Set();
   #observedNameSources = [];
   #fonts = null;
-  #scrollFrame = null;
+  /** Coalesces scroll bursts into one position sync per frame. */
+  #frames = new FrameCoalescer();
   #overflowing = false;
   #lastEdge = null;
   #ownedHostMutations = /* @__PURE__ */ new Map();
-  #onScroll = () => {
-    if (this.#scrollFrame !== null) return;
-    this.#scrollFrame = requestAnimationFrame(() => {
-      this.#scrollFrame = null;
-      const viewport = this.#viewport;
-      if (viewport) this.#syncPosition(viewport, this.#overflowing);
-    });
-  };
-  #onLoad = () => {
-    this.#refresh();
+  #onScroll = (event) => {
+    const viewport = event.currentTarget;
+    this.#frames.schedule(() => this.#syncPosition(viewport, this.#overflowing));
   };
   #onFontsSettled = () => {
     this.#refresh();
@@ -387,7 +437,7 @@ var ScrollAreaController = class extends Controller {
   disconnect() {
     this.#beforeCache.deactivate();
     this.#rebind.cancel();
-    this.#cancelScrollFrame();
+    this.#frames.cancel();
     if (this.#viewport) this.#unbindViewport(this.#viewport);
     this.#layout.disconnect();
     this.#unbindFonts();
@@ -420,7 +470,7 @@ var ScrollAreaController = class extends Controller {
       return;
     }
     next.addEventListener("scroll", this.#onScroll, { passive: true });
-    next.addEventListener("load", this.#onLoad, true);
+    this.#layout.observeDescendantLoads(next);
     this.#layout.observe(next);
     this.#bindContentObserver(next);
     this.#refresh();
@@ -455,9 +505,9 @@ var ScrollAreaController = class extends Controller {
   }
   /** Releases every resource and borrowed attribute owned by one former viewport. */
   #unbindViewport(viewport) {
-    this.#cancelScrollFrame();
+    this.#frames.cancel();
     viewport.removeEventListener("scroll", this.#onScroll);
-    viewport.removeEventListener("load", this.#onLoad, true);
+    this.#layout.unobserveDescendantLoads();
     this.#layout.unobserve(viewport);
     this.#content?.disconnect();
     this.#content = null;
@@ -468,11 +518,15 @@ var ScrollAreaController = class extends Controller {
     this.#overflowing = false;
     this.#lastEdge = null;
   }
-  /** Runs the full structural and positional measurement pass. */
+  /**
+   * Runs the full structural and positional measurement pass.
+   *
+   * @stimeoRenderRoot
+   */
   #refresh() {
     const viewport = this.#viewport;
     if (!viewport) return;
-    this.#cancelScrollFrame();
+    this.#frames.cancel();
     this.#syncNameSources(viewport);
     this.#overflowing = this.#syncOverflow(viewport);
     this.#syncKeyboardReach(viewport, this.#overflowing);
@@ -680,16 +734,10 @@ var ScrollAreaController = class extends Controller {
     this.#fonts?.removeEventListener("loadingerror", this.#onFontsSettled);
     this.#fonts = null;
   }
-  /** Cancels a pending scroll frame. */
-  #cancelScrollFrame() {
-    if (this.#scrollFrame === null) return;
-    cancelAnimationFrame(this.#scrollFrame);
-    this.#scrollFrame = null;
-  }
   /** Suspends live resources and returns all derived state before snapshotting. */
   #rewindForCache() {
     this.#rebind.cancel();
-    this.#cancelScrollFrame();
+    this.#frames.cancel();
     if (this.#viewport) this.#unbindViewport(this.#viewport);
     this.#layout.disconnect();
     this.#unbindFonts();

data/dist/controllers/scroll_restore_controller.js

@@ -1,5 +1,37 @@
 import { Controller } from '@hotwired/stimulus';
 
+// src/controllers/scroll_restore_controller.ts
+
+// src/utils/frame_coalescer.ts
+var FrameCoalescer = class {
+  #frame = null;
+  /**
+   * Runs `run` on the next frame, unless a frame is already pending — the first
+   * request of a burst wins and the rest are dropped. The pending frame is
+   * released before `run`, so `run` may request the next one.
+   */
+  schedule(run) {
+    if (this.#frame !== null) return;
+    this.#frame = requestAnimationFrame(() => {
+      this.#frame = null;
+      run();
+    });
+  }
+  /**
+   * Drops the pending frame, and reaches the platform only when there is one.
+   *
+   * There is no handle value that stands for "nothing pending":
+   * `cancelAnimationFrame` takes an `unsigned long`, so a negative placeholder
+   * arrives as a large positive number that the same allocator can hand out, and
+   * an idle cancel would then drop a frame belonging to someone else.
+   */
+  cancel() {
+    if (this.#frame === null) return;
+    cancelAnimationFrame(this.#frame);
+    this.#frame = null;
+  }
+};
+
 // src/controllers/scroll_restore_controller.ts
 function parseStored(raw) {
   if (raw === null) return null;
@@ -17,8 +49,8 @@ var ScrollRestoreController = class extends Controller {
     key: { type: String, default: "" },
     axis: { type: String, default: "vertical" }
   };
-  /** Pending rAF id that coalesces scroll bursts into one save. */
-  #rafId = null;
+  /** Coalesces scroll bursts into one save per frame. */
+  #frames = new FrameCoalescer();
   /** Resolved storage key; empty disables persistence (no key and no id). */
   #storageKey = "";
   /** Last offset captured while the element was live; persisted as-is on teardown. */
@@ -46,11 +78,7 @@ var ScrollRestoreController = class extends Controller {
   #connected = false;
   #onScroll = () => {
     this.#capture();
-    if (this.#rafId !== null) return;
-    this.#rafId = requestAnimationFrame(() => {
-      this.#rafId = null;
-      this.#persist();
-    });
+    this.#frames.schedule(() => this.#persist());
   };
   connect() {
     this.#connected = true;
@@ -61,7 +89,7 @@ var ScrollRestoreController = class extends Controller {
   disconnect() {
     this.#connected = false;
     this.element.removeEventListener("scroll", this.#onScroll);
-    this.#cancelFrame();
+    this.#frames.cancel();
     this.#persist();
   }
   /** Re-derives the namespace when application code or a Turbo morph moves `key`. */
@@ -75,7 +103,7 @@ var ScrollRestoreController = class extends Controller {
   /** Rebuilds the persistence state around the Values as they now read. */
   #resync() {
     if (!this.#connected) return;
-    this.#cancelFrame();
+    this.#frames.cancel();
     this.#storageKey = this.#resolveKey();
     this.#echoTop = null;
     this.#echoLeft = null;
@@ -84,13 +112,6 @@ var ScrollRestoreController = class extends Controller {
     this.#capturedLeft = false;
     if (this.#storageKey) this.#restore();
   }
-  /** Drops the pending coalesced save, if one is queued. */
-  #cancelFrame() {
-    if (this.#rafId !== null) {
-      cancelAnimationFrame(this.#rafId);
-      this.#rafId = null;
-    }
-  }
   /**
    * Records the live scroll offset for the configured axis.
    *

data/dist/controllers/scroll_visibility_controller.js

@@ -77,11 +77,53 @@ function validSelector(element, raw, fallback) {
   );
 }
 
+// src/utils/frame_coalescer.ts
+var FrameCoalescer = class {
+  #frame = null;
+  /**
+   * Runs `run` on the next frame, unless a frame is already pending — the first
+   * request of a burst wins and the rest are dropped. The pending frame is
+   * released before `run`, so `run` may request the next one.
+   */
+  schedule(run) {
+    if (this.#frame !== null) return;
+    this.#frame = requestAnimationFrame(() => {
+      this.#frame = null;
+      run();
+    });
+  }
+  /**
+   * Drops the pending frame, and reaches the platform only when there is one.
+   *
+   * There is no handle value that stands for "nothing pending":
+   * `cancelAnimationFrame` takes an `unsigned long`, so a negative placeholder
+   * arrives as a large positive number that the same allocator can hand out, and
+   * an idle cancel would then drop a frame belonging to someone else.
+   */
+  cancel() {
+    if (this.#frame === null) return;
+    cancelAnimationFrame(this.#frame);
+    this.#frame = null;
+  }
+};
+
 // src/utils/reduced_motion.ts
 function prefersReducedMotion() {
   return typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
 }
 
+// src/utils/scroll_source.ts
+function resolveScrollContainer(selector) {
+  const match = selector ? document.querySelector(selector) : null;
+  return match instanceof HTMLElement ? match : null;
+}
+function resolveScrollSource(selector) {
+  return resolveScrollContainer(selector) ?? window;
+}
+function scrollOffset(source) {
+  return source === window ? window.scrollY ?? window.pageYOffset ?? 0 : source.scrollTop;
+}
+
 // src/utils/before_cache_reset.ts
 var BeforeCacheReset = class _BeforeCacheReset {
   /** Every subscribed instance, iterated by the one shared document listener. */
@@ -154,8 +196,8 @@ var ScrollVisibilityController = class extends Controller {
   };
   static actions = ["toTop"];
   static events = ["change"];
-  /** Pending rAF id that coalesces scroll bursts into one measurement. */
-  #rafId = null;
+  /** Coalesces scroll bursts into one measurement per frame. */
+  #frames = new FrameCoalescer();
   /** Previous scroll position, for `direction` mode delta detection. */
   #lastScrollY = 0;
   /** Current visibility, tracked to dispatch `change` only on real transitions. */
@@ -191,16 +233,10 @@ var ScrollVisibilityController = class extends Controller {
   #pendingHide = new BlurDeferral(() => {
     if (this.#connected) this.#evaluate();
   });
-  #onScroll = () => {
-    if (this.#rafId !== null) return;
-    this.#rafId = requestAnimationFrame(() => {
-      this.#rafId = null;
-      this.#evaluate();
-    });
-  };
+  #onScroll = () => this.#frames.schedule(() => this.#evaluate());
   connect() {
-    this.#scrollSource = this.#resolveScrollSource();
-    this.#lastScrollY = this.#scrollY();
+    this.#scrollSource = resolveScrollSource(this.#rootSelector);
+    this.#lastScrollY = scrollOffset(this.#scrollSource);
     this.#scrollSource.addEventListener("scroll", this.#onScroll, { passive: true });
     this.#evaluate(false);
     this.#connected = true;
@@ -208,10 +244,7 @@ var ScrollVisibilityController = class extends Controller {
   disconnect() {
     this.#connected = false;
     this.#scrollSource.removeEventListener("scroll", this.#onScroll);
-    if (this.#rafId !== null) {
-      cancelAnimationFrame(this.#rafId);
-      this.#rafId = null;
-    }
+    this.#frames.cancel();
     this.#pendingHide.releaseAll();
     this.#tabindex.returnAll();
     this.#visible = null;
@@ -270,7 +303,7 @@ var ScrollVisibilityController = class extends Controller {
    * @stimeoRenderRoot
    */
   #evaluate(notify = true) {
-    const y = this.#scrollY();
+    const y = scrollOffset(this.#scrollSource);
     let nextVisible;
     if (this.modeValue === "direction") {
       if (y <= this.#offset) {
@@ -299,14 +332,6 @@ var ScrollVisibilityController = class extends Controller {
     this.element.setAttribute("data-state", next ? "visible" : "hidden");
     if (notify) this.dispatch("change", { detail: { visible: next } });
   }
-  /** Resolves the scroll source from `root` (falling back to the window). */
-  #resolveScrollSource() {
-    if (this.#rootSelector) {
-      const root = document.querySelector(this.#rootSelector);
-      if (root) return root;
-    }
-    return window;
-  }
   /**
    * The focus owner inside the target, or `null` when focus is elsewhere.
    *
@@ -319,12 +344,6 @@ var ScrollVisibilityController = class extends Controller {
     if (focused instanceof HTMLElement && this.elementTarget.contains(focused)) return focused;
     return null;
   }
-  #scrollY() {
-    if (this.#scrollSource === window) {
-      return window.scrollY ?? window.pageYOffset ?? 0;
-    }
-    return this.#scrollSource.scrollTop;
-  }
 };
 
 export { ScrollVisibilityController };

data/dist/controllers/scrollspy_controller.js

@@ -10,6 +10,47 @@ 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/frame_coalescer.ts
+var FrameCoalescer = class {
+  #frame = null;
+  /**
+   * Runs `run` on the next frame, unless a frame is already pending — the first
+   * request of a burst wins and the rest are dropped. The pending frame is
+   * released before `run`, so `run` may request the next one.
+   */
+  schedule(run) {
+    if (this.#frame !== null) return;
+    this.#frame = requestAnimationFrame(() => {
+      this.#frame = null;
+      run();
+    });
+  }
+  /**
+   * Drops the pending frame, and reaches the platform only when there is one.
+   *
+   * There is no handle value that stands for "nothing pending":
+   * `cancelAnimationFrame` takes an `unsigned long`, so a negative placeholder
+   * arrives as a large positive number that the same allocator can hand out, and
+   * an idle cancel would then drop a frame belonging to someone else.
+   */
+  cancel() {
+    if (this.#frame === null) return;
+    cancelAnimationFrame(this.#frame);
+    this.#frame = null;
+  }
+};
 
 // src/utils/intersection_watcher.ts
 function queryRoot(selector) {
@@ -117,6 +158,15 @@ function prefersReducedMotion() {
   return typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
 }
 
+// src/utils/scroll_source.ts
+function resolveScrollContainer(selector) {
+  const match = selector ? document.querySelector(selector) : null;
+  return match instanceof HTMLElement ? match : null;
+}
+function scrollOffset(source) {
+  return source === window ? window.scrollY ?? window.pageYOffset ?? 0 : source.scrollTop;
+}
+
 // src/controllers/scrollspy_controller.ts
 var ANCHOR_ATTRIBUTES = ["href", "data-href"];
 var ScrollspyController = class extends Controller {
@@ -163,8 +213,10 @@ var ScrollspyController = class extends Controller {
    * rather than from whatever the selector resolves to now.
    */
   #scrollSource = null;
-  /** Pending re-evaluation frame; coalesces a scroll burst into one measurement. */
-  #frame = null;
+  /** Coalesces a scroll burst into one measurement per frame. */
+  #frames = new FrameCoalescer();
+  /** The validated `rootSelector`, or `""` when the declaration cannot be parsed. */
+  #rootSelector = "";
   /** Watches the link targets' anchor attributes for an in-place morph rewrite. */
   #anchorObserver = null;
   /** True while a coalesced observation rebuild is queued; see {@link #scheduleResync}. */
@@ -181,10 +233,7 @@ var ScrollspyController = class extends Controller {
     this.#anchorObserver?.disconnect();
     this.#anchorObserver = null;
     this.#detachScrollListener();
-    if (this.#frame !== null) {
-      cancelAnimationFrame(this.#frame);
-      this.#frame = null;
-    }
+    this.#frames.cancel();
     this.#intersectionStates.clear();
     this.#activeSectionId = "";
     this.#rootElement = null;
@@ -201,6 +250,7 @@ var ScrollspyController = class extends Controller {
     this.#initializeObserver();
   }
   rootSelectorValueChanged() {
+    this.#rootSelector = validSelector(this.element, this.rootSelectorValue, "");
     if (!this.#isConnected) return;
     this.#initializeObserver();
   }
@@ -294,10 +344,10 @@ var ScrollspyController = class extends Controller {
     const offset = this.#offset;
     if (rootElement) {
       const containerRect = rootElement.getBoundingClientRect();
-      const scrollPosition = rootElement.scrollTop + (targetRect.top - containerRect.top) - offset;
+      const scrollPosition = scrollOffset(rootElement) + (targetRect.top - containerRect.top) - offset;
       rootElement.scrollTo({ top: scrollPosition, behavior });
     } else {
-      const scrollPosition = window.scrollY + targetRect.top - offset;
+      const scrollPosition = scrollOffset(window) + targetRect.top - offset;
       window.scrollTo({ top: scrollPosition, behavior });
     }
     if (this.focusSectionValue) this.#focusSection(targetElement);
@@ -332,19 +382,14 @@ var ScrollspyController = class extends Controller {
   /**
    * Resolves `rootSelector` to a scrollable element.
    *
-   * @returns The container, or `null` meaning "spy the viewport" when the value
-   * is empty, matches nothing, matches a non-HTML element (an SVG node is not a
-   * scroll container), or is not a valid selector — a typo in a data attribute
-   * must degrade to viewport spying, not leave the controller inert.
+   * @returns The container, or `null` meaning "spy the viewport" when the
+   * declaration is empty, matches nothing, or matches a non-HTML element. A typo
+   * reads as empty: the declaration is validated once when it changes, so a
+   * selector that cannot be parsed degrades to viewport spying rather than
+   * leaving the controller inert.
    */
   #queryRootElement() {
-    if (!this.rootSelectorValue) return null;
-    try {
-      const root = document.querySelector(this.rootSelectorValue);
-      return root instanceof HTMLElement ? root : null;
-    } catch {
-      return null;
-    }
+    return resolveScrollContainer(this.#rootSelector);
   }
   /**
    * Re-evaluates once per frame while the reader scrolls.
@@ -359,13 +404,7 @@ var ScrollspyController = class extends Controller {
    * end in {@link #evaluateActiveSection} — which measures section rects and the
    * root's top edge at that instant — they converge on the same answer.
    */
-  #onScroll = () => {
-    if (this.#frame !== null) return;
-    this.#frame = requestAnimationFrame(() => {
-      this.#frame = null;
-      this.#evaluateActiveSection();
-    });
-  };
+  #onScroll = () => this.#frames.schedule(() => this.#evaluateActiveSection());
   /**
    * Points the `scroll` listener at whatever the reader actually scrolls: the
    * resolved root, or the window when the viewport is spied.
@@ -383,6 +422,10 @@ var ScrollspyController = class extends Controller {
     this.#scrollSource?.removeEventListener("scroll", this.#onScroll);
     this.#scrollSource = null;
   }
+  /**
+   * @stimeoRuntimeOnly `rootMargin` wires the observer this call installs; the active section it
+   *   republishes is the one already recorded.
+   */
   #initializeObserver() {
     this.#watcher.stop();
     this.#intersectionStates.clear();
@@ -428,6 +471,8 @@ var ScrollspyController = class extends Controller {
    * threshold) against a freshly computed trigger line mixes two moments in
    * time, which would make the result depend on how the reader arrived at a
    * position — a smooth scroll and an instant jump to the same offset disagree.
+   *
+   * @stimeoRenderRoot
    */
   #evaluateActiveSection() {
     const rootEl = this.#scrollRoot();