stimeo-ui 0.9.0 → 0.11.0

data/dist/controllers/preview_guard_controller.js

@@ -1,19 +1,108 @@
 import { Controller } from '@hotwired/stimulus';
 
+// src/controllers/preview_guard_controller.ts
+
+// src/utils/before_cache_reset.ts
+var BeforeCacheReset = class _BeforeCacheReset {
+  /** Every subscribed instance, iterated by the one shared document listener. */
+  static #subscribers = /* @__PURE__ */ new Set();
+  /** The shared listener; installed while at least one instance is subscribed. */
+  static #onBeforeCache = () => {
+    for (const subscriber of _BeforeCacheReset.#subscribers) subscriber.#rewind();
+  };
+  #rewind;
+  /** @param rewind - the pass that returns this controller's state to its initial form. */
+  constructor(rewind) {
+    this.#rewind = rewind;
+  }
+  /** Subscribes to `turbo:before-cache`; call from `connect()`. Idempotent. */
+  activate() {
+    const first = _BeforeCacheReset.#subscribers.size === 0;
+    _BeforeCacheReset.#subscribers.add(this);
+    if (first) {
+      document.addEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
+    }
+  }
+  /** Unsubscribes; call from `disconnect()`. Safe when never subscribed. */
+  deactivate() {
+    _BeforeCacheReset.#subscribers.delete(this);
+    if (_BeforeCacheReset.#subscribers.size > 0) return;
+    document.removeEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
+  }
+};
+
+// src/utils/style_property_lease.ts
+var StylePropertyLease = class {
+  #property;
+  #records = /* @__PURE__ */ new Map();
+  /** @param property - The CSS property whose temporary values this lease owns. */
+  constructor(property) {
+    this.#property = property;
+  }
+  /** Writes or removes the leased declaration while preserving its authored value. */
+  write(element, value, priority = "") {
+    const existing = this.#records.get(element);
+    if (existing) {
+      existing.writtenValue = value;
+      existing.writtenPriority = value === null ? "" : priority;
+    } else {
+      this.#records.set(element, {
+        originalValue: element.style.getPropertyValue(this.#property),
+        originalPriority: element.style.getPropertyPriority(this.#property),
+        writtenValue: value,
+        writtenPriority: value === null ? "" : priority
+      });
+    }
+    this.#reflect(element, value, priority);
+  }
+  /** Returns one lease without overwriting a later consumer declaration. */
+  return(element) {
+    const record = this.#records.get(element);
+    if (!record) return;
+    this.#records.delete(element);
+    const style = element.style;
+    const stillOwned = style.getPropertyValue(this.#property) === (record.writtenValue ?? "") && style.getPropertyPriority(this.#property) === record.writtenPriority;
+    if (stillOwned) {
+      this.#reflect(element, record.originalValue, record.originalPriority);
+    }
+  }
+  /** Returns every outstanding declaration lease. */
+  returnAll() {
+    for (const element of Array.from(this.#records.keys())) this.return(element);
+  }
+  /** Reflects only a real declaration transition. */
+  #reflect(element, value, priority) {
+    const style = element.style;
+    const nextValue = value ?? "";
+    const nextPriority = value === null ? "" : priority;
+    if (style.getPropertyValue(this.#property) === nextValue && style.getPropertyPriority(this.#property) === nextPriority) {
+      return;
+    }
+    if (value === null) style.removeProperty(this.#property);
+    else style.setProperty(this.#property, value, priority);
+  }
+};
+
 // src/controllers/preview_guard_controller.ts
 var PreviewGuardController = class extends Controller {
   static values = {
-    placeholder: { type: String, default: "" },
-    mode: { type: String, default: "hide" }
+    placeholder: { type: String, default: "" }
   };
   static events = ["hide", "show"];
+  #visibility = new StylePropertyLease("visibility");
+  #beforeCache = new BeforeCacheReset(() => this.#restore());
   #observer = null;
+  #connected = false;
   #hidden = false;
-  /** Saved inline visibility (hide mode), restored on show. */
-  #savedVisibility = "";
-  /** Saved text (placeholder mode); non-null marks that text — not visibility — was swapped. */
-  #savedText = null;
+  /** Child nodes a placeholder displaced; non-null marks that content — not visibility — was swapped. */
+  #savedNodes = null;
+  /** The descendant that held focus when the guard went up, so show can hand it back. */
+  #focused = null;
   connect() {
+    this.#connected = true;
+    if (this.#hidden) this.#reguard();
+    else this.element.removeAttribute("data-preview-hidden");
+    this.#beforeCache.activate();
     if (typeof MutationObserver !== "undefined") {
       this.#observer = new MutationObserver(() => this.#sync());
       this.#observer.observe(document.documentElement, {
@@ -24,44 +113,115 @@ var PreviewGuardController = class extends Controller {
     this.#sync();
   }
   disconnect() {
+    this.#connected = false;
+    this.#beforeCache.deactivate();
     this.#observer?.disconnect();
     this.#observer = null;
-    this.#restore();
   }
-  /** Reflects the current `data-turbo-preview` state onto the element. */
+  /**
+   * Re-guards to match a `placeholder` changed at runtime — the value is the content on
+   * display while the guard is up, so a morph that swaps it must not leave the old one.
+   */
+  placeholderValueChanged() {
+    if (!this.#connected || !this.#hidden) return;
+    this.#reguard();
+  }
+  /**
+   * Reflects the current `data-turbo-preview` state onto the element.
+   *
+   * @stimeoRenderRoot
+   */
   #sync() {
     const previewing = document.documentElement.hasAttribute("data-turbo-preview");
     if (previewing && !this.#hidden) this.#hide();
     else if (!previewing && this.#hidden) this.#show();
   }
   #hide() {
+    this.#focused = this.#focusedInside();
+    this.#applyGuard();
+    this.dispatch("hide", { detail: {} });
+  }
+  /** Puts the guard up in the form the current `placeholder` calls for. */
+  #applyGuard() {
     this.#hidden = true;
-    if (this.modeValue === "placeholder") {
-      this.#savedText = this.element.textContent;
-      this.element.textContent = this.placeholderValue;
+    if (this.placeholderValue === "") {
+      this.#visibility.write(this.element, "hidden");
     } else {
-      this.#savedVisibility = this.element.style.visibility;
-      this.element.style.visibility = "hidden";
+      this.#savedNodes = document.createDocumentFragment();
+      this.#savedNodes.append(...this.element.childNodes);
+      this.element.textContent = this.placeholderValue;
     }
     this.element.setAttribute("data-preview-hidden", "true");
-    this.dispatch("hide", { detail: {} });
+  }
+  /**
+   * Re-forms a guard that is already up so it matches the current `placeholder`.
+   *
+   * No event: `hide` reports that the guard went up, and it has not come down. Swapping
+   * one stand-in text for another writes only that text — putting the held content back
+   * first would reconnect the whole subtree for an instant. Only a change of *form* —
+   * to or from the empty placeholder — has to revert, and the focus the guard is holding
+   * carries across it rather than being handed back and taken again.
+   */
+  #reguard() {
+    if (this.#savedNodes && this.placeholderValue !== "") {
+      this.element.textContent = this.placeholderValue;
+      return;
+    }
+    const held = this.#focused;
+    this.#revert();
+    this.#applyGuard();
+    this.#focused = held;
   }
   #show() {
     this.#restore();
     this.dispatch("show", { detail: {} });
   }
-  /** Reverts the guard. Safe to call when not hidden (no-op) — used by show and teardown. */
+  /** Reverts the guard and hands focus back. Used by show and by the snapshot rewind. */
   #restore() {
-    if (!this.#hidden) return;
+    this.#revert();
+    this.#refocus();
+  }
+  /**
+   * Puts the element back the way the guard found it.
+   *
+   * Every step is a no-op on an element this controller never guarded: the lease returns
+   * only declarations it recorded, and the hook is removed whether or not it is there.
+   */
+  #revert() {
     this.#hidden = false;
-    if (this.#savedText !== null) {
-      this.element.textContent = this.#savedText;
-      this.#savedText = null;
+    if (this.#savedNodes) {
+      this.element.textContent = "";
+      this.element.append(this.#savedNodes);
+      this.#savedNodes = null;
     } else {
-      this.element.style.visibility = this.#savedVisibility;
+      this.#visibility.return(this.element);
     }
     this.element.removeAttribute("data-preview-hidden");
   }
+  /**
+   * The focused element the guard is about to make unfocusable, if any.
+   *
+   * The element itself counts as well as its descendants: guarding takes focus either way
+   * — a `visibility: hidden` subtree cannot hold it, and a placeholder displaces the nodes
+   * outright — so the browser drops focus to `<body>` the moment the guard goes up.
+   */
+  #focusedInside() {
+    const active = document.activeElement;
+    return active instanceof HTMLElement && this.element.contains(active) ? active : null;
+  }
+  /**
+   * Hands focus back to the element the guard took it from.
+   *
+   * Only when that element is still in the document and focus has not moved on since —
+   * anything else is the user's or another controller's, and putting it back would be
+   * taking it.
+   */
+  #refocus() {
+    const target = this.#focused;
+    this.#focused = null;
+    if (!target?.isConnected || document.activeElement !== document.body) return;
+    target.focus();
+  }
 };
 
 export { PreviewGuardController };

data/dist/controllers/resizable_controller.js

@@ -251,7 +251,7 @@ var ResizableController = class extends Controller {
       this.#dispatchChange();
     }
   }
-  /** Double-click or Enter to collapse the primary pane, or put it back. */
+  /** Collapses the primary pane to its minimum, or returns it to the last position. */
   toggle() {
     const { min, max } = this.#range;
     if (this.#position > min) {

data/dist/controllers/roving_controller.js

@@ -12,6 +12,20 @@ function isReservedArrowChord(event, allow = []) {
   if (!event.key.startsWith("Arrow")) return false;
   return event.altKey && !allow.includes("alt") || event.ctrlKey && !allow.includes("ctrl") || event.metaKey && !allow.includes("meta") || event.shiftKey && !allow.includes("shift");
 }
+function hasModifierChord(event) {
+  return event.altKey || event.ctrlKey || event.metaKey || event.shiftKey;
+}
+
+// src/utils/focus_candidate.ts
+function inheritsFieldsetDisabled(control) {
+  let fieldset = control.closest("fieldset[disabled]");
+  while (fieldset) {
+    const legend = Array.from(fieldset.children).find((child) => child.tagName === "LEGEND");
+    if (!legend?.contains(control)) return true;
+    fieldset = fieldset.parentElement?.closest("fieldset[disabled]") ?? null;
+  }
+  return false;
+}
 
 // src/utils/microtask_coalescer.ts
 var MicrotaskCoalescer = class {
@@ -88,6 +102,7 @@ function rovingMove(current, length, delta, wrap) {
 }
 
 // src/controllers/roving_controller.ts
+var STATE_ATTRIBUTES = ["disabled", "hidden"];
 var RovingController = class extends Controller {
   static targets = ["item"];
   static values = {
@@ -97,12 +112,14 @@ var RovingController = class extends Controller {
   };
   static events = ["change"];
   #roving = new RovingTabindex(() => this.itemTargets);
-  #reconcile = new MicrotaskCoalescer(() => this.#ensureTabStop());
+  #reconcile = new MicrotaskCoalescer(() => this.#ensureTabStop(true));
   #connected = false;
+  #observer = null;
   connect() {
-    this.#ensureTabStop();
+    this.#ensureTabStop(false);
     this.element.addEventListener("keydown", this.#onKeydown);
     this.element.addEventListener("focusin", this.#onFocusin);
+    this.#watchState();
     this.#connected = true;
     this.#reconcile.activate();
   }
@@ -111,6 +128,8 @@ var RovingController = class extends Controller {
     this.#reconcile.cancel();
     this.element.removeEventListener("keydown", this.#onKeydown);
     this.element.removeEventListener("focusin", this.#onFocusin);
+    this.#observer?.disconnect();
+    this.#observer = null;
   }
   /** Drops a runtime-added item from the Tab sequence before batch reconciliation. */
   itemTargetConnected(item) {
@@ -126,10 +145,9 @@ var RovingController = class extends Controller {
   #onKeydown = (event) => {
     if (event.defaultPrevented) return;
     if (isReservedArrowChord(event)) return;
-    const items = this.itemTargets;
+    if (event.isComposing) return;
     const current = this.#indexOf(event.target);
     if (current === -1) return;
-    const length = items.length;
     const wrap = this.wrapValue ? "wrap" : "clamp";
     const orientation = this.orientationValue;
     const horizontal = orientation === "horizontal" || orientation === "both";
@@ -139,16 +157,16 @@ var RovingController = class extends Controller {
     const backwardKey = rtl ? "ArrowRight" : "ArrowLeft";
     let next;
     if (horizontal && event.key === forwardKey || vertical && event.key === "ArrowDown") {
-      next = rovingMove(current, length, 1, wrap);
+      next = this.#step(current, 1, wrap);
     } else if (horizontal && event.key === backwardKey || vertical && event.key === "ArrowUp") {
-      next = rovingMove(current, length, -1, wrap);
-    } else if (this.homeEndValue && event.key === "Home") {
-      next = 0;
-    } else if (this.homeEndValue && event.key === "End") {
-      next = length - 1;
+      next = this.#step(current, -1, wrap);
+    } else if (this.homeEndValue && (event.key === "Home" || event.key === "End")) {
+      if (hasModifierChord(event)) return;
+      next = event.key === "Home" ? this.#firstReachable() : this.#lastReachable();
     } else {
       return;
     }
+    if (next === -1) return;
     event.preventDefault();
     this.#activate(next, true);
   };
@@ -159,7 +177,8 @@ var RovingController = class extends Controller {
    */
   #onFocusin = (event) => {
     const index = this.#indexOf(event.target);
-    if (index !== -1) this.#activate(index, false);
+    if (index === -1 || !this.#reachable(index)) return;
+    this.#activate(index, false);
   };
   /** Resolves the item index owning an event target (the item or a descendant). */
   #indexOf(target) {
@@ -175,10 +194,104 @@ var RovingController = class extends Controller {
       this.dispatch("change", { detail: { index, item: this.itemTargets[index] } });
     }
   }
-  /** Keeps the first existing Tab stop, falling back to the first live item. */
-  #ensureTabStop() {
+  /**
+   * Keeps the Tab stop on a reachable item.
+   *
+   * `followFocus` is on for re-establishment only: an item added and focused in
+   * the same task has already claimed the stop through `focusin`, and the batch
+   * that follows must not hand it back to the first item. `connect()` passes it
+   * off so the authored DOM decides the initial stop. With nothing reachable the
+   * DOM is left as it is — a group inside a collapsed region gets its stop back
+   * when the region opens, instead of losing it for good.
+   */
+  #ensureTabStop(followFocus) {
+    const items = this.itemTargets;
+    const focused = followFocus ? items.findIndex((item, i) => item === document.activeElement && this.#reachable(i)) : -1;
     const active = this.#roving.activeIndex;
-    this.#roving.setActive(active === -1 ? 0 : active);
+    const kept = active !== -1 && this.#reachable(active) ? active : -1;
+    const index = focused !== -1 ? focused : kept !== -1 ? kept : this.#firstReachable();
+    if (index === -1) return;
+    this.#roving.setActive(index);
+  }
+  /**
+   * Resolves the next reachable index in `delta`'s direction, honouring `wrap`.
+   *
+   * An arrow on the widget's own axis is the widget's to consume even when the
+   * position does not change, so a clamped end resolves to the current item
+   * rather than to nothing. An unreachable origin escapes to the first reachable
+   * item instead of sitting in a dead end, and `-1` is left for the one case that
+   * really is not ours: no reachable item anywhere.
+   */
+  #step(current, delta, wrap) {
+    const length = this.itemTargets.length;
+    let index = current;
+    for (let taken = 0; taken < length; taken += 1) {
+      const candidate = rovingMove(index, length, delta, wrap);
+      if (candidate === index) break;
+      index = candidate;
+      if (this.#reachable(index)) return index;
+    }
+    return this.#reachable(current) ? current : this.#firstReachable();
+  }
+  /** Index of the first reachable item, or `-1`. */
+  #firstReachable() {
+    return this.itemTargets.findIndex((_item, i) => this.#reachable(i));
+  }
+  /** Index of the last reachable item, or `-1`. */
+  #lastReachable() {
+    for (let i = this.itemTargets.length - 1; i >= 0; i -= 1) {
+      if (this.#reachable(i)) return i;
+    }
+    return -1;
+  }
+  /**
+   * Whether the item at `index` can hold the Tab stop and take focus.
+   *
+   * `aria-disabled` is deliberately not consulted: it keeps an item reachable and
+   * only suppresses activation, which this part does not own.
+   */
+  #reachable(index) {
+    const item = this.itemTargets[index];
+    if (!item) return false;
+    if (this.#hidden(item)) return false;
+    if (!("disabled" in item)) return true;
+    if (item.disabled) return false;
+    return !inheritsFieldsetDisabled(item);
+  }
+  /**
+   * Whether `item`, or anything between it and the container, is `hidden`.
+   *
+   * The walk stops at the container on purpose: a group inside a hidden region is
+   * already out of the page's Tab order, and calling every item unreachable there
+   * would drop the stop with nothing left to restore it — the ancestor lies
+   * outside the subtree whose state attributes are watched.
+   */
+  #hidden(item) {
+    let node = item;
+    while (node && node !== this.element) {
+      if (node.hasAttribute("hidden")) return true;
+      node = node.parentElement;
+    }
+    return false;
+  }
+  /**
+   * Watches the attributes that decide reachability, so disabling the item that
+   * holds the Tab stop hands it to another one instead of taking the whole set
+   * out of the Tab sequence. An enclosing `fieldset` disables items from outside
+   * the observed subtree, so each one's own `disabled` is watched too.
+   */
+  #watchState() {
+    if (typeof MutationObserver === "undefined") return;
+    const observer = new MutationObserver(() => this.#reconcile.schedule());
+    observer.observe(this.element, {
+      subtree: true,
+      attributes: true,
+      attributeFilter: STATE_ATTRIBUTES
+    });
+    for (let fieldset = this.element.parentElement?.closest("fieldset") ?? null; fieldset; fieldset = fieldset.parentElement?.closest("fieldset") ?? null) {
+      observer.observe(fieldset, { attributes: true, attributeFilter: ["disabled"] });
+    }
+    this.#observer = observer;
   }
 };
 

data/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() {