stimeo-ui 0.9.0 → 0.10.0

package/dist/controllers/scroll_restore_controller.js

@@ -1,6 +1,17 @@
 import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/scroll_restore_controller.ts
+function parseStored(raw) {
+  if (raw === null) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function storedOffset(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
 var ScrollRestoreController = class extends Controller {
   static values = {
     key: { type: String, default: "" },
@@ -13,6 +24,26 @@ var ScrollRestoreController = class extends Controller {
   /** 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();
     if (this.#rafId !== null) return;
@@ -22,58 +53,127 @@ var ScrollRestoreController = class extends Controller {
     });
   };
   connect() {
+    this.#connected = true;
     this.#storageKey = this.#resolveKey();
-    if (!this.#storageKey) return;
-    this.#restore();
     this.element.addEventListener("scroll", this.#onScroll, { passive: true });
+    if (this.#storageKey) this.#restore();
   }
   disconnect() {
-    if (!this.#storageKey) return;
+    this.#connected = false;
     this.element.removeEventListener("scroll", this.#onScroll);
+    this.#cancelFrame();
+    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.#cancelFrame();
+    this.#storageKey = this.#resolveKey();
+    this.#echoTop = null;
+    this.#echoLeft = null;
+    this.#carried = {};
+    this.#capturedTop = false;
+    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;
     }
-    this.#persist();
   }
-  /** Records the live scroll offset for the configured axis. */
+  /**
+   * 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) this.#lastTop = this.element.scrollTop;
-    if (this.#tracksHorizontal) this.#lastLeft = this.element.scrollLeft;
+    if (this.#tracksVertical) {
+      const top = this.element.scrollTop;
+      if (top !== this.#echoTop) {
+        this.#echoTop = null;
+        this.#lastTop = top;
+        this.#capturedTop = true;
+      }
+    }
+    if (this.#tracksHorizontal) {
+      const left = this.element.scrollLeft;
+      if (left !== this.#echoLeft) {
+        this.#echoLeft = null;
+        this.#lastLeft = left;
+        this.#capturedLeft = true;
+      }
+    }
   }
-  /** Persists the last captured scroll offset for the configured axis. */
+  /**
+   * 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() {
-    const data = {};
-    if (this.#tracksVertical) data.top = this.#lastTop;
-    if (this.#tracksHorizontal) data.left = this.#lastLeft;
+    if (!this.#storageKey || !(this.#capturedTop || this.#capturedLeft)) return;
+    const data = { ...this.#carried };
+    if (this.#tracksVertical && this.#capturedTop) data.top = this.#lastTop;
+    if (this.#tracksHorizontal && this.#capturedLeft) data.left = this.#lastLeft;
     try {
-      sessionStorage.setItem(this.#storageKey, JSON.stringify(data));
+      window.sessionStorage.setItem(this.#storageKey, JSON.stringify(data));
     } catch {
     }
   }
   /** Applies the persisted scroll offset, if any, without moving focus. */
   #restore() {
-    let raw = null;
-    try {
-      raw = sessionStorage.getItem(this.#storageKey);
-    } catch {
-      return;
-    }
-    if (raw === null) return;
-    let data;
+    let raw;
     try {
-      data = JSON.parse(raw);
+      raw = window.sessionStorage.getItem(this.#storageKey);
     } catch {
       return;
     }
-    if (this.#tracksVertical && typeof data.top === "number") {
-      this.element.scrollTop = data.top;
-      this.#lastTop = data.top;
+    const data = parseStored(raw);
+    if (data === null) return;
+    this.#echoTop = null;
+    this.#echoLeft = null;
+    const top = storedOffset(data.top);
+    const left = storedOffset(data.left);
+    const options = { behavior: "instant" };
+    let requested = false;
+    if (this.#tracksVertical) {
+      if (top !== null) {
+        options.top = top;
+        this.#lastTop = top;
+        this.#capturedTop = true;
+        requested = true;
+      }
+    } else if (data.top !== void 0) {
+      this.#carried.top = data.top;
     }
-    if (this.#tracksHorizontal && typeof data.left === "number") {
-      this.element.scrollLeft = data.left;
-      this.#lastLeft = data.left;
+    if (this.#tracksHorizontal) {
+      if (left !== null) {
+        options.left = left;
+        this.#lastLeft = left;
+        this.#capturedLeft = true;
+        requested = true;
+      }
+    } else if (data.left !== void 0) {
+      this.#carried.left = data.left;
     }
+    if (!requested) return;
+    const beforeTop = this.element.scrollTop;
+    const beforeLeft = this.element.scrollLeft;
+    this.element.scrollTo(options);
+    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() {

package/dist/controllers/scroll_restore_controller.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/controllers/scroll_restore_controller.ts"],"names":[],"mappings":"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","file":"scroll_restore_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\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 * 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 * @remarks\n * Behavior only — it sets no ARIA/`data-*`/CSS and never moves focus (restore is\n * a plain `scrollTop`/`scrollLeft` assignment). The `scroll` listener is internal\n * and `passive` (no consumer `data-action` needed): each event records the live\n * offset synchronously, and a `requestAnimationFrame` coalesces the writes to\n * `sessionStorage`. On `disconnect()` (Turbo navigation included) it flushes the\n * **last captured** offset rather than re-reading the element — by the time Turbo\n * fires `disconnect` it has already detached the node, whose `scrollTop` then\n * reads `0`, so a fresh read would clobber the saved position with `0`. Keying by\n * `key` (falling back to the element `id`) in `sessionStorage` makes it\n * multi-instance safe and survives full reloads — unlike a module-scope variable,\n * which only survives Turbo Drive and assumes a single instance.\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  /** Pending rAF id that coalesces scroll bursts into one save. */\n  #rafId: number | null = null;\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  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    if (this.#rafId !== null) return;\n    this.#rafId = requestAnimationFrame(() => {\n      this.#rafId = null;\n      this.#persist();\n    });\n  };\n\n  override connect(): void {\n    this.#storageKey = this.#resolveKey();\n    if (!this.#storageKey) return; // No stable key → do nothing (avoid mixing pages).\n    this.#restore();\n    this.element.addEventListener(\"scroll\", this.#onScroll, { passive: true });\n  }\n\n  override disconnect(): void {\n    if (!this.#storageKey) return;\n    this.element.removeEventListener(\"scroll\", this.#onScroll);\n    if (this.#rafId !== null) {\n      cancelAnimationFrame(this.#rafId);\n      this.#rafId = null;\n    }\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  /** Records the live scroll offset for the configured axis. */\n  #capture(): void {\n    if (this.#tracksVertical) this.#lastTop = this.element.scrollTop;\n    if (this.#tracksHorizontal) this.#lastLeft = this.element.scrollLeft;\n  }\n\n  /** Persists the last captured scroll offset for the configured axis. */\n  #persist(): void {\n    const data: StoredScroll = {};\n    if (this.#tracksVertical) data.top = this.#lastTop;\n    if (this.#tracksHorizontal) data.left = this.#lastLeft;\n    try {\n      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 = null;\n    try {\n      raw = sessionStorage.getItem(this.#storageKey);\n    } catch {\n      return;\n    }\n    if (raw === null) return;\n    let data: StoredScroll;\n    try {\n      data = JSON.parse(raw) as StoredScroll;\n    } catch {\n      return;\n    }\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    if (this.#tracksVertical && typeof data.top === \"number\") {\n      this.element.scrollTop = data.top;\n      this.#lastTop = data.top;\n    }\n    if (this.#tracksHorizontal && typeof data.left === \"number\") {\n      this.element.scrollLeft = data.left;\n      this.#lastLeft = data.left;\n    }\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/controllers/scroll_restore_controller.ts"],"names":[],"mappings":"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","file":"scroll_restore_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\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  /** Pending rAF id that coalesces scroll bursts into one save. */\n  #rafId: number | null = null;\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    if (this.#rafId !== null) return;\n    this.#rafId = requestAnimationFrame(() => {\n      this.#rafId = null;\n      this.#persist();\n    });\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.#cancelFrame();\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.#cancelFrame();\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  /** Drops the pending coalesced save, if one is queued. */\n  #cancelFrame(): void {\n    if (this.#rafId !== null) {\n      cancelAnimationFrame(this.#rafId);\n      this.#rafId = null;\n    }\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

@@ -17,8 +17,11 @@ import { Controller } from '@hotwired/stimulus';
  *
  * In `offset` mode the element is shown once the scroll source is scrolled past
  * `offset` px; in `direction` mode it is hidden while scrolling down and shown
- * while scrolling up. Visibility is reflected through the `hidden` attribute (so a
- * hidden control also leaves the focus order) and `data-state`.
+ * while scrolling up. A `scroll` that carries no vertical movement — a
+ * horizontal scroll, an overscroll bounce — has no direction, so `direction`
+ * mode leaves the current visibility alone. Visibility is reflected through the
+ * `hidden` attribute (so a hidden control also leaves the focus order) and
+ * `data-state`.
  *
  * By default the **window** is the scroll source. When the page itself does not
  * scroll — e.g. a fixed-height app shell whose main column scrolls in a container
@@ -26,18 +29,27 @@ import { Controller } from '@hotwired/stimulus';
  * controller observes the element's scroll instead of the (never-scrolling)
  * window. `toTop` then scrolls that same container.
  *
- * `change` dispatches `{ visible: boolean }`.
+ * `change` dispatches `{ visible: boolean }` on transitions only: connecting
+ * reflects the current scroll state onto the hooks without announcing it, so a
+ * Turbo restore does not replay the state the snapshot already carries.
  *
  * @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). `toTop` honors
- * `prefers-reduced-motion` by forcing an instant jump independently of the
- * consumer's CSS `scroll-behavior`, and can move focus to a `focusSelector`
- * target (given `tabindex="-1"` if needed) to keep keyboard users oriented
- * after the scroll. A live disconnect removes only a `tabindex="-1"` this
- * controller instance added; authored tabindex values remain. This teardown does
- * not claim to rewrite a Turbo cache snapshot that was cloned before disconnect.
+ * `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
+ * 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
+ * instant jump independently of the consumer's CSS `scroll-behavior`, and can
+ * move focus to a `focusSelector` target (given `tabindex="-1"` if needed, and
+ * focused without scrolling so the smooth scroll survives) to keep keyboard
+ * users oriented after the scroll. A live disconnect removes only a
+ * `tabindex="-1"` this controller instance added; authored tabindex values
+ * remain. This teardown does not claim to rewrite a Turbo cache snapshot that
+ * was cloned before disconnect.
  */
 declare class ScrollVisibilityController extends Controller<HTMLElement> {
     #private;
@@ -70,6 +82,26 @@ declare class ScrollVisibilityController extends Controller<HTMLElement> {
     rootValue: string;
     connect(): void;
     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.
+     *
+     * 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
+     * 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. */
+    modeValueChanged(): void;
+    /** Validates `root` once so connect never parses a selector that throws. */
+    rootValueChanged(): void;
+    /** Validates `focusSelector` once so `toTop` never parses a selector that throws. */
+    focusSelectorValueChanged(): void;
     /** Scrolls the source to the top and, optionally, moves focus to a safe target. */
     toTop(): void;
 }

package/dist/controllers/scroll_visibility_controller.js

@@ -2,6 +2,61 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/scroll_visibility_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/reduced_motion.ts
 function prefersReducedMotion() {
   return typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
@@ -68,10 +123,11 @@ var TabindexLoan = class {
 };
 
 // src/controllers/scroll_visibility_controller.ts
+var DEFAULT_OFFSET = 400;
 var ScrollVisibilityController = class extends Controller {
   static targets = ["element"];
   static values = {
-    offset: { type: Number, default: 400 },
+    offset: { type: Number, default: DEFAULT_OFFSET },
     mode: { type: String, default: "offset" },
     focusSelector: { type: String, default: "" },
     root: { type: String, default: "" }
@@ -89,8 +145,32 @@ var ScrollVisibilityController = class extends Controller {
    * the window. Captured on connect so teardown detaches from the same source.
    */
   #scrollSource = window;
+  /**
+   * Gates the declaration callbacks to the connected window.
+   *
+   * Stimulus delivers a Value callback ahead of `connect()` and again for every
+   * runtime change; without the gate, merely connecting would evaluate — and
+   * announce — before `connect()` runs its own first reflection.
+   */
+  #connected = false;
+  /** Validated threshold; a non-finite declaration reads as the default. */
+  #offset = DEFAULT_OFFSET;
+  /** Validated `root` selector; an unparsable declaration reads as absent. */
+  #rootSelector = "";
+  /** Validated `focusSelector`; an unparsable declaration reads as absent. */
+  #focusSelector = "";
   /** Focus targets this instance lent a `tabindex` to. */
   #tabindex = new TabindexLoan();
+  /**
+   * The hide held back while the control itself owns focus.
+   *
+   * Completing the deferral re-runs the ordinary evaluation rather than applying
+   * the stale decision: by the time focus leaves, the scroll position may have
+   * moved back past the threshold.
+   */
+  #pendingHide = new BlurDeferral(() => {
+    if (this.#connected) this.#evaluate();
+  });
   #onScroll = () => {
     if (this.#rafId !== null) return;
     this.#rafId = requestAnimationFrame(() => {
@@ -102,61 +182,134 @@ var ScrollVisibilityController = class extends Controller {
     this.#scrollSource = this.#resolveScrollSource();
     this.#lastScrollY = this.#scrollY();
     this.#scrollSource.addEventListener("scroll", this.#onScroll, { passive: true });
-    this.#evaluate();
+    this.#evaluate(false);
+    this.#connected = true;
   }
   disconnect() {
+    this.#connected = false;
     this.#scrollSource.removeEventListener("scroll", this.#onScroll);
     if (this.#rafId !== null) {
       cancelAnimationFrame(this.#rafId);
       this.#rafId = null;
     }
+    this.#pendingHide.releaseAll();
     this.#tabindex.returnAll();
     this.#visible = null;
   }
+  /** Writes the current visibility onto a control that arrives after connect. */
+  elementTargetConnected(element) {
+    if (this.#visible !== null) element.hidden = !this.#visible;
+  }
+  /** Drops a held-back hide together with the control it was waiting on. */
+  elementTargetDisconnected() {
+    this.#pendingHide.releaseAll();
+  }
+  /**
+   * Validates `offset` once, then re-renders.
+   *
+   * 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
+   * comparison and strand the element (in `direction` mode, even the guarantee
+   * that the very top always reveals).
+   */
+  offsetValueChanged() {
+    this.#offset = Number.isFinite(this.offsetValue) ? this.offsetValue : DEFAULT_OFFSET;
+    if (this.#connected) this.#evaluate();
+  }
+  /** Re-renders when application code (or a Turbo morph) changes `mode` at runtime. */
+  modeValueChanged() {
+    if (this.#connected) this.#evaluate();
+  }
+  /** Validates `root` once so connect never parses a selector that throws. */
+  rootValueChanged() {
+    this.#rootSelector = this.#validSelector(this.rootValue);
+  }
+  /** Validates `focusSelector` once so `toTop` never parses a selector that throws. */
+  focusSelectorValueChanged() {
+    this.#focusSelector = this.#validSelector(this.focusSelectorValue);
+  }
   /** Scrolls the source to the top and, optionally, moves focus to a safe target. */
   toTop() {
     const behavior = prefersReducedMotion() ? "instant" : "smooth";
     this.#scrollSource.scrollTo({ top: 0, behavior });
-    if (this.focusSelectorValue) {
-      const target = document.querySelector(this.focusSelectorValue);
+    if (this.#focusSelector) {
+      const target = document.querySelector(this.#focusSelector);
       if (target) {
         this.#tabindex.lend(target);
-        target.focus();
+        target.focus({ preventScroll: true });
       }
     }
   }
-  /** Decides the next visibility from the current scroll state and applies it. */
-  #evaluate() {
+  /**
+   * Decides the next visibility from the current scroll state and applies it.
+   *
+   * @param notify - whether a transition announces itself. The reflection
+   *   `connect()` performs is the current state, not a change.
+   *
+   * @stimeoRenderRoot
+   */
+  #evaluate(notify = true) {
     const y = this.#scrollY();
     let nextVisible;
     if (this.modeValue === "direction") {
-      if (y <= this.offsetValue) {
+      if (y <= this.#offset) {
         nextVisible = true;
+      } else if (y === this.#lastScrollY) {
+        return;
       } else {
         nextVisible = y < this.#lastScrollY;
       }
     } else {
-      nextVisible = y > this.offsetValue;
+      nextVisible = y > this.#offset;
     }
     this.#lastScrollY = y;
-    this.#setVisible(nextVisible);
+    this.#setVisible(nextVisible, notify);
   }
   /** Applies visibility to the target, syncing `hidden`, `data-state`, `change`. */
-  #setVisible(next) {
+  #setVisible(next, notify) {
     if (next === this.#visible) return;
+    const focused = !next && this.hasElementTarget ? this.#focusedWithin() : null;
+    if (focused) {
+      this.#pendingHide.deferOnly(focused);
+      return;
+    }
     this.#visible = next;
     if (this.hasElementTarget) this.elementTarget.hidden = !next;
     this.element.setAttribute("data-state", next ? "visible" : "hidden");
-    this.dispatch("change", { detail: { visible: next } });
+    if (notify) this.dispatch("change", { detail: { visible: next } });
   }
   /** Resolves the scroll source from `root` (falling back to the window). */
   #resolveScrollSource() {
-    if (this.rootValue) {
-      const root = document.querySelector(this.rootValue);
+    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.
+   *
+   * `blur` does not bubble, so the deferral has to ride the focused element
+   * itself: waiting on a container that never receives the event would hold the
+   * hide forever.
+   */
+  #focusedWithin() {
+    const focused = document.activeElement;
+    if (focused instanceof HTMLElement && this.elementTarget.contains(focused)) return focused;
+    return null;
+  }
+  /** Returns `declared` when it parses as a selector, and `""` when it does not. */
+  #validSelector(declared) {
+    if (declared.length > 0) {
+      try {
+        this.element.matches(declared);
+        return declared;
+      } catch {
+      }
+    }
+    return "";
+  }
   #scrollY() {
     if (this.#scrollSource === window) {
       return window.scrollY ?? window.pageYOffset ?? 0;