stimeo-ui 0.16.0 → 0.18.0

package/dist/controllers/scroll_restore_controller.js

@@ -1,15 +1,7 @@
 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(() => {
@@ -17,14 +9,6 @@ var FrameCoalescer = class {
       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);
@@ -32,7 +16,17 @@ var FrameCoalescer = class {
   }
 };
 
-// src/controllers/scroll_restore_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();
+  }
+};
+
 function parseStored(raw) {
   if (raw === null) return null;
   try {
@@ -49,58 +43,39 @@ var ScrollRestoreController = class extends Controller {
     key: { type: String, default: "" },
     axis: { type: String, default: "vertical" }
   };
-  /** 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. */
   #lastTop = 0;
   #lastLeft = 0;
-  /**
-   * The offsets this controller's own restore produced, awaiting the `scroll`
-   * the engine fires for them. A restore the layout cannot reach yet lands short,
-   * so treating that echo as the reader's position would cut the saved offset
-   * down to whatever the unfinished layout allowed.
-   */
   #echoTop = null;
   #echoLeft = null;
-  /** Offsets stored for an axis that is not tracked, carried through saves. */
   #carried = {};
-  /**
-   * Whether each axis holds an offset worth saving — one this namespace restored
-   * or the reader moved. A save writes only the axes that are marked, so an
-   * offset taken under a different key or axis is never re-published as if the
-   * reader had left it there.
-   */
   #capturedTop = false;
   #capturedLeft = false;
-  /** Whether the controller is connected; Value callbacks outside that window do not resync. */
   #connected = false;
   #onScroll = () => {
     this.#capture();
     this.#frames.schedule(() => this.#persist());
   };
+  #listeners = new ListenerSet();
   connect() {
     this.#connected = true;
     this.#storageKey = this.#resolveKey();
-    this.element.addEventListener("scroll", this.#onScroll, { passive: true });
+    this.#listeners.add(this.element, "scroll", this.#onScroll, { passive: true });
     if (this.#storageKey) this.#restore();
   }
   disconnect() {
     this.#connected = false;
-    this.element.removeEventListener("scroll", this.#onScroll);
+    this.#listeners.dispose();
     this.#frames.cancel();
     this.#persist();
   }
-  /** Re-derives the namespace when application code or a Turbo morph moves `key`. */
   keyValueChanged() {
     this.#resync();
   }
-  /** Re-derives the tracked axes when application code or a Turbo morph moves `axis`. */
   axisValueChanged() {
     this.#resync();
   }
-  /** Rebuilds the persistence state around the Values as they now read. */
   #resync() {
     if (!this.#connected) return;
     this.#frames.cancel();
@@ -112,15 +87,6 @@ var ScrollRestoreController = class extends Controller {
     this.#capturedLeft = false;
     if (this.#storageKey) this.#restore();
   }
-  /**
-   * Records the live scroll offset for the configured axis.
-   *
-   * An axis holds its echo until that axis actually moves. A scroll event names
-   * no axis, so consuming both on the first one to arrive would leave the other
-   * unguarded: on `both`, moving one axis would take the clamped reading of the
-   * untouched axis as the reader's own position and save it, cutting the stored
-   * offset down to whatever the layout could reach at restore time.
-   */
   #capture() {
     if (this.#tracksVertical) {
       const top = this.element.scrollTop;
@@ -139,10 +105,6 @@ var ScrollRestoreController = class extends Controller {
       }
     }
   }
-  /**
-   * Writes the marked axes, carrying through any offset held for an untracked one.
-   * Without a key, or with neither axis marked, it writes nothing.
-   */
   #persist() {
     if (!this.#storageKey || !(this.#capturedTop || this.#capturedLeft)) return;
     const data = { ...this.#carried };
@@ -153,7 +115,6 @@ var ScrollRestoreController = class extends Controller {
     } catch {
     }
   }
-  /** Applies the persisted scroll offset, if any, without moving focus. */
   #restore() {
     let raw;
     try {
@@ -196,7 +157,6 @@ var ScrollRestoreController = class extends Controller {
     if (this.element.scrollTop !== beforeTop) this.#echoTop = this.element.scrollTop;
     if (this.element.scrollLeft !== beforeLeft) this.#echoLeft = this.element.scrollLeft;
   }
-  /** The `sessionStorage` key: explicit `key`, else the element `id`, else none. */
   #resolveKey() {
     const base = this.keyValue || this.element.id;
     return base ? `stimeo--scroll-restore:${base}` : "";
@@ -210,5 +170,4 @@ var ScrollRestoreController = class extends Controller {
 };
 
 export { ScrollRestoreController };
-//# sourceMappingURL=scroll_restore_controller.js.map
 //# sourceMappingURL=scroll_restore_controller.js.map

package/dist/controllers/scroll_restore_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/frame_coalescer.ts","../../src/controllers/scroll_restore_controller.ts"],"names":[],"mappings":"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","file":"scroll_restore_controller.js","sourcesContent":["/**\n * Runs one piece of scroll-driven work per animation frame.\n *\n * A `scroll` listener fires many times between two paints, and each firing would\n * measure the same layout. Requesting a frame on the first firing and ignoring\n * the rest until it runs keeps the reads to one per frame; running on the frame\n * — rather than on a timer — keeps the measurement in step with what the reader\n * sees.\n *\n * **The first request of a burst wins.** Work handed in while a frame is already\n * pending is dropped, so a caller that queues a special first pass and then\n * receives scrolls gets that first pass, not the last scroll's.\n *\n * Cancelling drops the pending frame outright, and does nothing at all when none\n * is pending. A frame really is cancelled, so nothing needs a generation to tell\n * a stale callback from a fresh one, and nothing has to be refused before the\n * caller starts listening.\n *\n * Scope is the scheduling only. What to measure stays with the caller.\n *\n * @example\n * ```ts\n * readonly #frames = new FrameCoalescer();\n *\n * readonly #onScroll = (): void => this.#frames.schedule(() => this.#measure());\n *\n * disconnect(): void {\n *   this.#frames.cancel();\n * }\n * ```\n */\nexport class FrameCoalescer {\n  #frame: number | null = null;\n\n  /**\n   * Runs `run` on the next frame, unless a frame is already pending — the first\n   * request of a burst wins and the rest are dropped. The pending frame is\n   * released before `run`, so `run` may request the next one.\n   */\n  schedule(run: () => void): void {\n    if (this.#frame !== null) return;\n    this.#frame = requestAnimationFrame(() => {\n      this.#frame = null;\n      run();\n    });\n  }\n\n  /**\n   * Drops the pending frame, and reaches the platform only when there is one.\n   *\n   * There is no handle value that stands for \"nothing pending\":\n   * `cancelAnimationFrame` takes an `unsigned long`, so a negative placeholder\n   * arrives as a large positive number that the same allocator can hand out, and\n   * an idle cancel would then drop a frame belonging to someone else.\n   */\n  cancel(): void {\n    if (this.#frame === null) return;\n    cancelAnimationFrame(this.#frame);\n    this.#frame = null;\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { FrameCoalescer } from \"../utils/frame_coalescer\";\n\n/** Persisted scroll position; fields are present only for the saved axis. */\ninterface StoredScroll {\n  top?: number;\n  left?: number;\n}\n\n/**\n * Reads one persisted entry, or `null` when there is nothing usable to read.\n *\n * `JSON.parse` returns `null` for the literal `null` without throwing, so the\n * parse guard alone would hand back a value with no fields to read. Every field the\n * caller applies is validated there, which is what makes a bare literal harmless here.\n */\nfunction parseStored(raw: string | null): StoredScroll | null {\n  if (raw === null) return null;\n  try {\n    return JSON.parse(raw) as StoredScroll | null;\n  } catch {\n    return null;\n  }\n}\n\n/** One axis offset from a persisted entry, or `null` when it cannot be applied. */\nfunction storedOffset(value: unknown): number | null {\n  return typeof value === \"number\" && Number.isFinite(value) ? value : null;\n}\n\n/**\n * Headless **Scroll Restore** behavior: persists and restores the scroll\n * position of an inner scrolling region across Turbo Drive navigations (and full\n * reloads within the same tab session). No APG widget — a pure state-preservation\n * utility, like {@link import(\"./scroll_visibility_controller\").ScrollVisibilityController}\n * and the Sticky State Observer.\n *\n * Markup contract (identifier: `stimeo--scroll-restore`):\n *   <div data-controller=\"stimeo--scroll-restore\"\n *        data-stimeo--scroll-restore-key-value=\"sidebar\"\n *        style=\"overflow: auto\">\n *     …long content…\n *   </div>\n *\n * Turbo swaps the whole `<body>` on navigation, so an inner scroll container is\n * rebuilt with `scrollTop` reset to 0. Rather than have every app hand-write a\n * controller for this (which contradicts a \"ship the behavior\" library), this\n * persists the offset under a stable key in `sessionStorage` and restores it on\n * `connect()`.\n *\n * Values:\n * - `key` — the `sessionStorage` namespace. Empty falls back to the element `id`;\n *   with neither, nothing is saved or restored, so positions from unrelated pages\n *   cannot mix.\n * - `axis` — which offset is tracked: `vertical` (default, `scrollTop`),\n *   `horizontal` (`scrollLeft`) or `both`. An offset stored for an axis that is\n *   not tracked is neither applied nor discarded.\n *\n * Both Values are re-derived when they change at runtime, so a morph that\n * rewrites the attribute in place switches namespace or axis instead of going on\n * writing under the one that held at connect. A `key` left empty resolves through\n * the element `id`, which no Value callback observes; runtime `id` changes are\n * out of scope.\n *\n * @remarks\n * Behavior only — it sets no ARIA/`data-*`/CSS and never moves focus. Restoring\n * goes through `scrollTo({ behavior: \"instant\" })` so that a consumer's\n * `scroll-behavior: smooth` cannot turn it into an animation whose intermediate\n * offsets would be recorded as the reader's own scrolling. The `scroll` listener\n * is internal and `passive` (no consumer `data-action` needed): each event\n * records the live offset synchronously, and a `requestAnimationFrame` coalesces\n * the writes to `sessionStorage`. On `disconnect()` (Turbo navigation included)\n * it flushes the **last captured** offset rather than re-reading the element — by\n * the time Turbo fires `disconnect` it has already detached the node, whose\n * `scrollTop` then reads `0`, so a fresh read would clobber the saved position\n * with `0`. Keying by `key` (falling back to the element `id`) in\n * `sessionStorage` makes it multi-instance safe and survives full reloads —\n * unlike a module-scope variable, which only survives Turbo Drive and assumes a\n * single instance. Storage access is best-effort: a browser that refuses it\n * (private mode, quota) leaves the element working, just without persistence.\n */\nexport class ScrollRestoreController extends Controller<HTMLElement> {\n  static override values = {\n    key: { type: String, default: \"\" },\n    axis: { type: String, default: \"vertical\" },\n  };\n\n  declare keyValue: string;\n  declare axisValue: string;\n\n  /** Coalesces scroll bursts into one save per frame. */\n  readonly #frames = new FrameCoalescer();\n  /** Resolved storage key; empty disables persistence (no key and no id). */\n  #storageKey = \"\";\n  /** Last offset captured while the element was live; persisted as-is on teardown. */\n  #lastTop = 0;\n  #lastLeft = 0;\n  /**\n   * The offsets this controller's own restore produced, awaiting the `scroll`\n   * the engine fires for them. A restore the layout cannot reach yet lands short,\n   * so treating that echo as the reader's position would cut the saved offset\n   * down to whatever the unfinished layout allowed.\n   */\n  #echoTop: number | null = null;\n  #echoLeft: number | null = null;\n  /** Offsets stored for an axis that is not tracked, carried through saves. */\n  #carried: StoredScroll = {};\n  /**\n   * Whether each axis holds an offset worth saving — one this namespace restored\n   * or the reader moved. A save writes only the axes that are marked, so an\n   * offset taken under a different key or axis is never re-published as if the\n   * reader had left it there.\n   */\n  #capturedTop = false;\n  #capturedLeft = false;\n  /** Whether the controller is connected; Value callbacks outside that window do not resync. */\n  #connected = false;\n\n  readonly #onScroll = (): void => {\n    // Capture synchronously while the element is still connected and measurable;\n    // the rAF only debounces the sessionStorage write, never the read.\n    this.#capture();\n    this.#frames.schedule(() => this.#persist());\n  };\n\n  override connect(): void {\n    this.#connected = true;\n    this.#storageKey = this.#resolveKey();\n    this.element.addEventListener(\"scroll\", this.#onScroll, { passive: true });\n    if (this.#storageKey) this.#restore();\n  }\n\n  override disconnect(): void {\n    this.#connected = false;\n    this.element.removeEventListener(\"scroll\", this.#onScroll);\n    this.#frames.cancel();\n    // Flush the last captured offset (a throttled burst may have left the final\n    // frame unsaved). We do NOT re-read the element here: Turbo detaches the node\n    // before disconnect, so its scrollTop is 0 and would overwrite the real value.\n    this.#persist();\n  }\n\n  /** Re-derives the namespace when application code or a Turbo morph moves `key`. */\n  keyValueChanged(): void {\n    this.#resync();\n  }\n\n  /** Re-derives the tracked axes when application code or a Turbo morph moves `axis`. */\n  axisValueChanged(): void {\n    this.#resync();\n  }\n\n  /** Rebuilds the persistence state around the Values as they now read. */\n  #resync(): void {\n    if (!this.#connected) return;\n    // The pending frame holds an offset belonging to the previous namespace and\n    // axis, so it is dropped rather than written under the new ones.\n    this.#frames.cancel();\n    this.#storageKey = this.#resolveKey();\n    this.#echoTop = null;\n    this.#echoLeft = null;\n    this.#carried = {};\n    // An offset is only ever written for an axis this namespace seeded or the\n    // reader moved. Clearing both marks drops the ones taken under the previous\n    // key and axis, which the restore below re-establishes only where the new\n    // key actually holds a value.\n    this.#capturedTop = false;\n    this.#capturedLeft = false;\n    if (this.#storageKey) this.#restore();\n  }\n\n  /**\n   * Records the live scroll offset for the configured axis.\n   *\n   * An axis holds its echo until that axis actually moves. A scroll event names\n   * no axis, so consuming both on the first one to arrive would leave the other\n   * unguarded: on `both`, moving one axis would take the clamped reading of the\n   * untouched axis as the reader's own position and save it, cutting the stored\n   * offset down to whatever the layout could reach at restore time.\n   */\n  #capture(): void {\n    if (this.#tracksVertical) {\n      const top = this.element.scrollTop;\n      if (top !== this.#echoTop) {\n        this.#echoTop = null;\n        this.#lastTop = top;\n        this.#capturedTop = true;\n      }\n    }\n    if (this.#tracksHorizontal) {\n      const left = this.element.scrollLeft;\n      if (left !== this.#echoLeft) {\n        this.#echoLeft = null;\n        this.#lastLeft = left;\n        this.#capturedLeft = true;\n      }\n    }\n  }\n\n  /**\n   * Writes the marked axes, carrying through any offset held for an untracked one.\n   * Without a key, or with neither axis marked, it writes nothing.\n   */\n  #persist(): void {\n    if (!this.#storageKey || !(this.#capturedTop || this.#capturedLeft)) return;\n    const data: StoredScroll = { ...this.#carried };\n    if (this.#tracksVertical && this.#capturedTop) data.top = this.#lastTop;\n    if (this.#tracksHorizontal && this.#capturedLeft) data.left = this.#lastLeft;\n    try {\n      window.sessionStorage.setItem(this.#storageKey, JSON.stringify(data));\n    } catch {\n      // sessionStorage can throw (private mode / quota); persistence is best-effort.\n    }\n  }\n\n  /** Applies the persisted scroll offset, if any, without moving focus. */\n  #restore(): void {\n    let raw: string | null;\n    try {\n      raw = window.sessionStorage.getItem(this.#storageKey);\n    } catch {\n      return;\n    }\n    const data = parseStored(raw);\n    if (data === null) return;\n\n    // A restore writes its own echoes below; one left over from an earlier pass\n    // would otherwise swallow the first matching move the reader makes.\n    this.#echoTop = null;\n    this.#echoLeft = null;\n\n    const top = storedOffset(data.top);\n    const left = storedOffset(data.left);\n    const options: ScrollToOptions = { behavior: \"instant\" };\n    let requested = false;\n    // Seed the capture cache from the restored value so an immediate teardown\n    // (before any scroll) re-persists the restored position, not 0. Guard by the\n    // configured axis so a stale field from a different axis is never applied —\n    // and keep it, since the next save would otherwise drop it.\n    if (this.#tracksVertical) {\n      if (top !== null) {\n        options.top = top;\n        this.#lastTop = top;\n        this.#capturedTop = true;\n        requested = true;\n      }\n    } else if (data.top !== undefined) {\n      this.#carried.top = data.top;\n    }\n    if (this.#tracksHorizontal) {\n      if (left !== null) {\n        options.left = left;\n        this.#lastLeft = left;\n        this.#capturedLeft = true;\n        requested = true;\n      }\n    } else if (data.left !== undefined) {\n      this.#carried.left = data.left;\n    }\n    if (!requested) return;\n\n    const beforeTop = this.element.scrollTop;\n    const beforeLeft = this.element.scrollLeft;\n    this.element.scrollTo(options);\n    if (this.element.scrollTop !== beforeTop) this.#echoTop = this.element.scrollTop;\n    if (this.element.scrollLeft !== beforeLeft) this.#echoLeft = this.element.scrollLeft;\n  }\n\n  /** The `sessionStorage` key: explicit `key`, else the element `id`, else none. */\n  #resolveKey(): string {\n    const base = this.keyValue || this.element.id;\n    return base ? `stimeo--scroll-restore:${base}` : \"\";\n  }\n\n  get #tracksVertical(): boolean {\n    return this.axisValue !== \"horizontal\";\n  }\n\n  get #tracksHorizontal(): boolean {\n    return this.axisValue === \"horizontal\" || this.axisValue === \"both\";\n  }\n}\n"]}
+{"version":3,"sources":["../../src/utils/frame_coalescer.ts","../../src/utils/listener_set.ts","../../src/controllers/scroll_restore_controller.ts"],"names":[],"mappings":"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","file":"scroll_restore_controller.js","sourcesContent":["/**\n * Runs one piece of scroll-driven work per animation frame.\n *\n * A `scroll` listener fires many times between two paints, and each firing would\n * measure the same layout. Requesting a frame on the first firing and ignoring\n * the rest until it runs keeps the reads to one per frame; running on the frame\n * — rather than on a timer — keeps the measurement in step with what the reader\n * sees.\n *\n * **The first request of a burst wins.** Work handed in while a frame is already\n * pending is dropped, so a caller that queues a special first pass and then\n * receives scrolls gets that first pass, not the last scroll's.\n *\n * Cancelling drops the pending frame outright, and does nothing at all when none\n * is pending. A frame really is cancelled, so nothing needs a generation to tell\n * a stale callback from a fresh one, and nothing has to be refused before the\n * caller starts listening.\n *\n * Scope is the scheduling only. What to measure stays with the caller.\n *\n * @example\n * ```ts\n * readonly #frames = new FrameCoalescer();\n *\n * readonly #onScroll = (): void => this.#frames.schedule(() => this.#measure());\n *\n * disconnect(): void {\n *   this.#frames.cancel();\n * }\n * ```\n */\nexport class FrameCoalescer {\n  #frame: number | null = null;\n\n  /**\n   * Runs `run` on the next frame, unless a frame is already pending — the first\n   * request of a burst wins and the rest are dropped. The pending frame is\n   * released before `run`, so `run` may request the next one.\n   */\n  schedule(run: () => void): void {\n    if (this.#frame !== null) return;\n    this.#frame = requestAnimationFrame(() => {\n      this.#frame = null;\n      run();\n    });\n  }\n\n  /**\n   * Drops the pending frame, and reaches the platform only when there is one.\n   *\n   * There is no handle value that stands for \"nothing pending\":\n   * `cancelAnimationFrame` takes an `unsigned long`, so a negative placeholder\n   * arrives as a large positive number that the same allocator can hand out, and\n   * an idle cancel would then drop a frame belonging to someone else.\n   */\n  cancel(): void {\n    if (this.#frame === null) return;\n    cancelAnimationFrame(this.#frame);\n    this.#frame = null;\n  }\n}\n","/** What {@link ListenerSet.add} passes on besides the signal it supplies itself. */\nexport type ListenerOptions = Omit<AddEventListenerOptions, \"signal\">;\n\n/**\n * The event map a target's own `addEventListener` types its handlers with: the\n * window's, a document's, an HTML or SVG element's, any other element's, or a\n * media query list's. Other targets name none.\n */\ntype EventMapOf<T extends EventTarget> = T extends Window\n  ? WindowEventMap\n  : T extends Document\n    ? DocumentEventMap\n    : T extends HTMLElement\n      ? HTMLElementEventMap\n      : T extends SVGElement\n        ? SVGElementEventMap\n        : T extends Element\n          ? ElementEventMap\n          : T extends MediaQueryList\n            ? MediaQueryListEventMap\n            : Record<never, never>;\n\n/**\n * Owns every listener a controller attaches for one connected lifetime and\n * releases them together, so an event name is spelled once and the release\n * cannot drift from the registration.\n *\n * Detaching by hand repeats three things at the release site — the type, the\n * handler reference and the capture flag — and any one of them drifting leaves\n * a listener alive on an element the controller no longer drives. Aborting the\n * signal a registration was created with releases it whatever it was made of,\n * so the release site names nothing.\n *\n * One set per lifetime, held as a field and never rebuilt.\n * {@link ListenerSet.dispose} is the only thing that closes a generation, and it opens\n * the next one in the same step, so the lifecycle hooks can call `add` and\n * `dispose` in any order any number of times, and no `add` ever meets an\n * already aborted signal — a DOM that registers a listener on such a signal\n * would keep it forever. Rebuilding the set instead would leak:\n * `addEventListener` matches an existing registration on target, type, callback\n * and capture alone, so re-adding the same handler while the first registration\n * is live is discarded, and that live registration keeps the signal it was\n * attached with — a set built by a second `connect()` can never release what it\n * appears to own.\n *\n * Scope is the registration only. Timers, observers, leases and the order they\n * are unwound in stay with the controller, which places `dispose()` in its\n * cleanup sequence. A receiver that changes at runtime (a\n * swapped target) is rebound by calling `dispose()` and then `add()` again from\n * the rebind, not by a second set.\n *\n * A lifetime shorter than the connection — while a Value holds, until a first\n * load, while a subscription is open — gets a set of its own, which the end of\n * that lifetime disposes. A controller therefore holds one set per lifetime: the\n * connection's, and one for each swapped receiver or shorter span.\n *\n * The set must own every registration of a tuple it holds: a listener the same\n * target already carries for the same type, callback and capture flag keeps the\n * right to remove it, and this set's `add` for that tuple is discarded. A\n * subscription shared between instances behind a participant count, listeners of\n * several elements that come and go one at a time, and those one gesture holds\n * keep their own pair of calls or a signal of their own.\n *\n * @example\n * ```ts\n * readonly #listeners = new ListenerSet();\n *\n * connect(): void {\n *   this.#listeners.add(this.element, \"submit\", this.#onNativeSubmit, { capture: true });\n *   this.#listeners.add(this.element, \"turbo:submit-start\", this.#onSubmitStart);\n *   this.#listeners.add(this.element, \"turbo:submit-end\", this.#onSubmitEnd);\n * }\n *\n * disconnect(): void {\n *   this.#listeners.dispose();\n * }\n * ```\n */\nexport class ListenerSet {\n  /** The generation every `add` joins until the next `dispose()`. */\n  #abort = new AbortController();\n\n  /**\n   * Attaches `handler` to the open generation, exactly as the caller spelled it.\n   *\n   * The set supplies the signal, so `options` carries everything else the DOM\n   * accepts — `capture` included. A removal by hand would have to repeat that\n   * flag; aborting the signal releases the listener without it.\n   *\n   * A `type` the target's own event map names types `handler` with that event,\n   * as the target's `addEventListener` does, so a handler written for a\n   * `KeyboardEvent` is passed as it is; any other `type` takes an\n   * `EventListener`.\n   */\n  add<T extends EventTarget, K extends keyof EventMapOf<T> & string>(\n    target: T,\n    type: K,\n    handler: (event: EventMapOf<T>[K]) => void,\n    options?: ListenerOptions,\n  ): void;\n  add(target: EventTarget, type: string, handler: EventListener, options?: ListenerOptions): void;\n  add(target: EventTarget, type: string, handler: EventListener, options?: ListenerOptions): void {\n    target.addEventListener(type, handler, { ...options, signal: this.#abort.signal });\n  }\n\n  /**\n   * Releases every listener of the open generation, synchronously, and opens the\n   * next one. Idempotent, and safe before anything has been added.\n   */\n  dispose(): void {\n    this.#abort.abort();\n    this.#abort = new AbortController();\n  }\n}\n","import { Controller } from \"@hotwired/stimulus\";\nimport { FrameCoalescer } from \"../utils/frame_coalescer\";\nimport { ListenerSet } from \"../utils/listener_set\";\n\n/** Persisted scroll position; fields are present only for the saved axis. */\ninterface StoredScroll {\n  top?: number;\n  left?: number;\n}\n\n/**\n * Reads one persisted entry, or `null` when there is nothing usable to read.\n *\n * `JSON.parse` returns `null` for the literal `null` without throwing, so the\n * parse guard alone would hand back a value with no fields to read. Every field the\n * caller applies is validated there, which is what makes a bare literal harmless here.\n */\nfunction parseStored(raw: string | null): StoredScroll | null {\n  if (raw === null) return null;\n  try {\n    return JSON.parse(raw) as StoredScroll | null;\n  } catch {\n    return null;\n  }\n}\n\n/** One axis offset from a persisted entry, or `null` when it cannot be applied. */\nfunction storedOffset(value: unknown): number | null {\n  return typeof value === \"number\" && Number.isFinite(value) ? value : null;\n}\n\n/**\n * Headless **Scroll Restore** behavior: persists and restores the scroll\n * position of an inner scrolling region across Turbo Drive navigations (and full\n * reloads within the same tab session). Like `stimeo--scroll-visibility` and\n * `stimeo--sticky-observer`, it implements no APG widget; it is a pure\n * state-preservation utility.\n *\n * Markup contract (identifier: `stimeo--scroll-restore`):\n *   <div data-controller=\"stimeo--scroll-restore\"\n *        data-stimeo--scroll-restore-key-value=\"sidebar\"\n *        style=\"overflow: auto\">\n *     …long content…\n *   </div>\n *\n * Turbo swaps the whole `<body>` on navigation, so an inner scroll container is\n * rebuilt with `scrollTop` reset to 0. Rather than have every app hand-write a\n * controller for this (which contradicts a \"ship the behavior\" library), this\n * persists the offset under a stable key in `sessionStorage` and restores it on\n * `connect()`.\n *\n * Values:\n * - `key` — the `sessionStorage` namespace. Empty falls back to the element `id`;\n *   with neither, nothing is saved or restored, so positions from unrelated pages\n *   cannot mix.\n * - `axis` — which offset is tracked: `vertical` (default, `scrollTop`),\n *   `horizontal` (`scrollLeft`) or `both`. An offset stored for an axis that is\n *   not tracked is neither applied nor discarded.\n *\n * Both Values are re-derived when they change at runtime, so a morph that\n * rewrites the attribute in place switches namespace or axis instead of going on\n * writing under the one that held at connect. A `key` left empty resolves through\n * the element `id`, which no Value callback observes; runtime `id` changes are\n * out of scope.\n *\n * @remarks\n * Behavior only — it sets no ARIA/`data-*`/CSS and never moves focus. Restoring\n * goes through `scrollTo({ behavior: \"instant\" })` so that a consumer's\n * `scroll-behavior: smooth` cannot turn it into an animation whose intermediate\n * offsets would be recorded as the reader's own scrolling. The `scroll` listener\n * is internal and `passive` (no consumer `data-action` needed): each event\n * records the live offset synchronously, and a `requestAnimationFrame` coalesces\n * the writes to `sessionStorage`. On `disconnect()` (Turbo navigation included)\n * it flushes the **last captured** offset rather than re-reading the element — by\n * the time Turbo fires `disconnect` it has already detached the node, whose\n * `scrollTop` then reads `0`, so a fresh read would clobber the saved position\n * with `0`. Keying by `key` (falling back to the element `id`) in\n * `sessionStorage` makes it multi-instance safe and survives full reloads —\n * unlike a module-scope variable, which only survives Turbo Drive and assumes a\n * single instance. Storage access is best-effort: a browser that refuses it\n * (private mode, quota) leaves the element working, just without persistence.\n */\nexport class ScrollRestoreController extends Controller<HTMLElement> {\n  static override values = {\n    key: { type: String, default: \"\" },\n    axis: { type: String, default: \"vertical\" },\n  };\n\n  declare keyValue: string;\n  declare axisValue: string;\n\n  /** Coalesces scroll bursts into one save per frame. */\n  readonly #frames = new FrameCoalescer();\n  /** Resolved storage key; empty disables persistence (no key and no id). */\n  #storageKey = \"\";\n  /** Last offset captured while the element was live; persisted as-is on teardown. */\n  #lastTop = 0;\n  #lastLeft = 0;\n  /**\n   * The offsets this controller's own restore produced, awaiting the `scroll`\n   * the engine fires for them. A restore the layout cannot reach yet lands short,\n   * so treating that echo as the reader's position would cut the saved offset\n   * down to whatever the unfinished layout allowed.\n   */\n  #echoTop: number | null = null;\n  #echoLeft: number | null = null;\n  /** Offsets stored for an axis that is not tracked, carried through saves. */\n  #carried: StoredScroll = {};\n  /**\n   * Whether each axis holds an offset worth saving — one this namespace restored\n   * or the reader moved. A save writes only the axes that are marked, so an\n   * offset taken under a different key or axis is never re-published as if the\n   * reader had left it there.\n   */\n  #capturedTop = false;\n  #capturedLeft = false;\n  /** Whether the controller is connected; Value callbacks outside that window do not resync. */\n  #connected = false;\n\n  readonly #onScroll = (): void => {\n    // Capture synchronously while the element is still connected and measurable;\n    // the rAF only debounces the sessionStorage write, never the read.\n    this.#capture();\n    this.#frames.schedule(() => this.#persist());\n  };\n\n  /** The listeners of one connection, released together on `disconnect()`. */\n  readonly #listeners = new ListenerSet();\n\n  override connect(): void {\n    this.#connected = true;\n    this.#storageKey = this.#resolveKey();\n    this.#listeners.add(this.element, \"scroll\", this.#onScroll, { passive: true });\n    if (this.#storageKey) this.#restore();\n  }\n\n  override disconnect(): void {\n    this.#connected = false;\n    this.#listeners.dispose();\n    this.#frames.cancel();\n    // Flush the last captured offset (a throttled burst may have left the final\n    // frame unsaved). We do NOT re-read the element here: Turbo detaches the node\n    // before disconnect, so its scrollTop is 0 and would overwrite the real value.\n    this.#persist();\n  }\n\n  /** Re-derives the namespace when application code or a Turbo morph moves `key`. */\n  keyValueChanged(): void {\n    this.#resync();\n  }\n\n  /** Re-derives the tracked axes when application code or a Turbo morph moves `axis`. */\n  axisValueChanged(): void {\n    this.#resync();\n  }\n\n  /** Rebuilds the persistence state around the Values as they now read. */\n  #resync(): void {\n    if (!this.#connected) return;\n    // A frame a scroll queued before the swap belongs to the previous namespace and\n    // axis, so it is dropped rather than run against the new ones.\n    this.#frames.cancel();\n    this.#storageKey = this.#resolveKey();\n    this.#echoTop = null;\n    this.#echoLeft = null;\n    this.#carried = {};\n    // An offset is only ever written for an axis this namespace seeded or the\n    // reader moved. Clearing both marks drops the ones taken under the previous\n    // key and axis, which the restore below re-establishes only where the new\n    // key actually holds a value.\n    this.#capturedTop = false;\n    this.#capturedLeft = false;\n    if (this.#storageKey) this.#restore();\n  }\n\n  /**\n   * Records the live scroll offset for the configured axis.\n   *\n   * An axis holds its echo until that axis actually moves. A scroll event names\n   * no axis, so consuming both on the first one to arrive would leave the other\n   * unguarded: on `both`, moving one axis would take the clamped reading of the\n   * untouched axis as the reader's own position and save it, cutting the stored\n   * offset down to whatever the layout could reach at restore time.\n   */\n  #capture(): void {\n    if (this.#tracksVertical) {\n      const top = this.element.scrollTop;\n      if (top !== this.#echoTop) {\n        this.#echoTop = null;\n        this.#lastTop = top;\n        this.#capturedTop = true;\n      }\n    }\n    if (this.#tracksHorizontal) {\n      const left = this.element.scrollLeft;\n      if (left !== this.#echoLeft) {\n        this.#echoLeft = null;\n        this.#lastLeft = left;\n        this.#capturedLeft = true;\n      }\n    }\n  }\n\n  /**\n   * Writes the marked axes, carrying through any offset held for an untracked one.\n   * Without a key, or with neither axis marked, it writes nothing.\n   */\n  #persist(): void {\n    if (!this.#storageKey || !(this.#capturedTop || this.#capturedLeft)) return;\n    const data: StoredScroll = { ...this.#carried };\n    if (this.#tracksVertical && this.#capturedTop) data.top = this.#lastTop;\n    if (this.#tracksHorizontal && this.#capturedLeft) data.left = this.#lastLeft;\n    try {\n      window.sessionStorage.setItem(this.#storageKey, JSON.stringify(data));\n    } catch {\n      // sessionStorage can throw (private mode / quota); persistence is best-effort.\n    }\n  }\n\n  /** Applies the persisted scroll offset, if any, without moving focus. */\n  #restore(): void {\n    let raw: string | null;\n    try {\n      raw = window.sessionStorage.getItem(this.#storageKey);\n    } catch {\n      return;\n    }\n    const data = parseStored(raw);\n    if (data === null) return;\n\n    // A restore writes its own echoes below; one left over from an earlier pass\n    // would otherwise swallow the first matching move the reader makes.\n    this.#echoTop = null;\n    this.#echoLeft = null;\n\n    const top = storedOffset(data.top);\n    const left = storedOffset(data.left);\n    const options: ScrollToOptions = { behavior: \"instant\" };\n    let requested = false;\n    // Seed the capture cache from the restored value so an immediate teardown\n    // (before any scroll) re-persists the restored position, not 0. Guard by the\n    // configured axis so a stale field from a different axis is never applied —\n    // and keep it, since the next save would otherwise drop it.\n    if (this.#tracksVertical) {\n      if (top !== null) {\n        options.top = top;\n        this.#lastTop = top;\n        this.#capturedTop = true;\n        requested = true;\n      }\n    } else if (data.top !== undefined) {\n      this.#carried.top = data.top;\n    }\n    if (this.#tracksHorizontal) {\n      if (left !== null) {\n        options.left = left;\n        this.#lastLeft = left;\n        this.#capturedLeft = true;\n        requested = true;\n      }\n    } else if (data.left !== undefined) {\n      this.#carried.left = data.left;\n    }\n    if (!requested) return;\n\n    const beforeTop = this.element.scrollTop;\n    const beforeLeft = this.element.scrollLeft;\n    this.element.scrollTo(options);\n    if (this.element.scrollTop !== beforeTop) this.#echoTop = this.element.scrollTop;\n    if (this.element.scrollLeft !== beforeLeft) this.#echoLeft = this.element.scrollLeft;\n  }\n\n  /** The `sessionStorage` key: explicit `key`, else the element `id`, else none. */\n  #resolveKey(): string {\n    const base = this.keyValue || this.element.id;\n    return base ? `stimeo--scroll-restore:${base}` : \"\";\n  }\n\n  get #tracksVertical(): boolean {\n    return this.axisValue !== \"horizontal\";\n  }\n\n  get #tracksHorizontal(): boolean {\n    return this.axisValue === \"horizontal\" || this.axisValue === \"both\";\n  }\n}\n"]}

package/dist/controllers/scroll_visibility_controller.d.ts

@@ -36,10 +36,14 @@ import { Controller } from '@hotwired/stimulus';
  * @remarks
  * Behavior only — the look and any transition are the consumer's CSS. The scroll
  * listener is `passive`, coalesced through `requestAnimationFrame`, and removed on
- * `disconnect()` (Turbo navigation included). `offset` / `mode` are re-read at
- * runtime, so a Turbo morph that swaps either attribute is followed without
- * waiting for the next scroll; a selector (`root`, `focusSelector`) or a
- * threshold that cannot be parsed reads as its default, keeping the rest of the
+ * `disconnect()` (Turbo navigation included). `offset`, `mode` and `root` follow a
+ * runtime change — a Turbo morph, a Stream, an author script — without waiting for
+ * the next scroll: the Values a batch changes are applied in one pass after it. A
+ * `root` that names another container, or a morph that reaches this element after
+ * replacing the container its selector names, moves the listener to the container
+ * resolved now; the position found there is a baseline rather than a movement, and
+ * the visibility is decided again from it. A selector (`root`, `focusSelector`) or
+ * a threshold that cannot be parsed reads as its default, keeping the rest of the
  * element alive. **A scroll never hides the control while it owns focus**: that
  * hide waits for it to blur and is decided again from the scroll position at that
  * moment. `toTop` honors `prefers-reduced-motion` by forcing an
@@ -72,9 +76,15 @@ declare class ScrollVisibilityController extends Controller<HTMLElement> {
             default: string;
         };
     };
+    static valueConstraints: {
+        offset: {
+            readonly finite: true;
+        };
+    };
     static actions: readonly ["toTop"];
     static events: readonly ["change"];
     readonly elementTarget: HTMLElement;
+    readonly elementTargets: HTMLElement[];
     readonly hasElementTarget: boolean;
     offsetValue: number;
     modeValue: string;
@@ -84,21 +94,27 @@ declare class ScrollVisibilityController extends Controller<HTMLElement> {
     disconnect(): void;
     /** Writes the current visibility onto a control that arrives after connect. */
     elementTargetConnected(element: HTMLElement): void;
-    /** Drops a held-back hide together with the control it was waiting on. */
-    elementTargetDisconnected(): void;
     /**
-     * Validates `offset` once, then re-renders.
+     * Drops a held-back hide with its control, gives a control that no longer resolves its
+     * own `hidden` back, even after `disconnect()`, and writes the visibility onto the one
+     * that stays.
+     */
+    elementTargetDisconnected(element: HTMLElement): void;
+    /**
+     * Validates `offset` once, then asks for a pass.
      *
-     * Re-renders when application code (or a Turbo morph) changes `offset` at
-     * runtime. A declaration that is not a finite number reads as the default, so
-     * the comparison path never sees `NaN` — which would answer `false` to every
+     * A declaration that is not a finite number reads as the default, so the
+     * comparison path never sees `NaN` — which would answer `false` to every
      * comparison and strand the element (in `direction` mode, even the guarantee
      * that the very top always reveals).
      */
     offsetValueChanged(): void;
-    /** Re-renders when application code (or a Turbo morph) changes `mode` at runtime. */
+    /** Asks for a pass when application code (or a Turbo morph) changes `mode`. */
     modeValueChanged(): void;
-    /** Validates `root` once so connect never parses a selector that throws. */
+    /**
+     * Validates `root` once, so no resolve parses a selector that throws, then asks
+     * for a pass that follows the source it names.
+     */
     rootValueChanged(): void;
     /** Validates `focusSelector` once so `toTop` never parses a selector that throws. */
     focusSelectorValueChanged(): void;