stimeo-ui 0.5.0 → 0.6.0

data/dist/controllers/scroll_area_controller.js

@@ -2,6 +2,43 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/scroll_area_controller.ts
 
+// src/utils/attribute_lease.ts
+var AttributeLease = class {
+  #attribute;
+  #records = /* @__PURE__ */ new Map();
+  /** @param attribute - The attribute whose temporary values this lease owns. */
+  constructor(attribute) {
+    this.#attribute = attribute;
+  }
+  /** Writes or removes the leased attribute while preserving its authored value. */
+  write(element, value) {
+    const existing = this.#records.get(element);
+    if (existing) {
+      existing.written = value;
+    } else {
+      this.#records.set(element, {
+        original: element.getAttribute(this.#attribute),
+        written: value
+      });
+    }
+    if (value === null) element.removeAttribute(this.#attribute);
+    else element.setAttribute(this.#attribute, value);
+  }
+  /** Returns one lease without overwriting a value subsequently authored by a consumer. */
+  return(element) {
+    const record = this.#records.get(element);
+    if (!record) return;
+    this.#records.delete(element);
+    if (element.getAttribute(this.#attribute) !== record.written) return;
+    if (record.original === null) element.removeAttribute(this.#attribute);
+    else element.setAttribute(this.#attribute, record.original);
+  }
+  /** Returns every outstanding lease using the same ownership check as {@link return}. */
+  returnAll() {
+    for (const element of Array.from(this.#records.keys())) this.return(element);
+  }
+};
+
 // src/utils/layout_observer.ts
 var LayoutObserver = class {
   #callback;
@@ -72,10 +109,74 @@ function logicalScrollMetrics(element, horizontal) {
   return { position: Math.min(max, Math.max(0, position)), max };
 }
 
+// src/utils/microtask_coalescer.ts
+var MicrotaskCoalescer = class {
+  #run;
+  #queued = false;
+  #active = false;
+  #generation = 0;
+  /** @param run - the single reconciliation pass, invoked at most once per batch. */
+  constructor(run) {
+    this.#run = run;
+  }
+  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */
+  activate() {
+    this.#active = true;
+  }
+  /** Closes the window and drops any pending pass; call from `disconnect()`. */
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */
+  schedule() {
+    if (!this.#active || this.#queued) return;
+    this.#queued = true;
+    const generation = this.#generation;
+    queueMicrotask(() => {
+      if (generation !== this.#generation || !this.#queued || !this.#active) return;
+      this.#queued = false;
+      this.#run();
+    });
+  }
+};
+
+// 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/tabindex_loan.ts
 var TabindexLoan = class {
   #value;
   #lent = /* @__PURE__ */ new Set();
+  /** Returns live loans before Turbo can copy them into its page snapshot. */
+  #beforeCache = new BeforeCacheReset(() => this.returnAll());
   /**
    * @param value - the `tabindex` to lend. `"-1"` (the default) is
    *   programmatically focusable but not a Tab stop; `"0"` is a real Tab stop,
@@ -89,6 +190,7 @@ var TabindexLoan = class {
     if (element.hasAttribute("tabindex")) return;
     element.setAttribute("tabindex", this.#value);
     this.#lent.add(element);
+    this.#beforeCache.activate();
   }
   /** Takes back every loan whose value is still the one that was lent. */
   returnAll() {
@@ -96,6 +198,7 @@ var TabindexLoan = class {
       if (element.getAttribute("tabindex") === this.#value) element.removeAttribute("tabindex");
     }
     this.#lent.clear();
+    this.#beforeCache.deactivate();
   }
 };
 
@@ -117,29 +220,56 @@ var ScrollAreaController = class extends Controller {
   };
   static events = ["reach"];
   #layout = new LayoutObserver(() => this.#update());
+  /** Current element receiving scroll, resize, mutation, and keyboard-reach behavior. */
+  #viewport = null;
+  /** Guards target callbacks before connect and after disconnect. */
+  #connected = false;
+  /** Collapses target replacement callbacks into one final-DOM rebind. */
+  #rebind = new MicrotaskCoalescer(() => this.#syncViewport());
   /** Re-checks the tab stop when the viewport's focusable content comes or goes. */
   #content = null;
   /** Last edge reported via `reach`, so the event fires once per arrival. */
   #lastEdge = null;
   /** Whether this controller added `tabindex`, so teardown only removes its own. */
   #tabindex = new TabindexLoan("0");
-  /** Whether this controller added `role="region"`, for symmetric teardown. */
-  #addedRole = false;
+  /** Temporarily owns a derived `role="region"` without losing an authored replacement. */
+  #role = new AttributeLease("role");
   #onScroll = () => {
     this.#update();
   };
   connect() {
-    if (!this.hasViewportTarget) return;
-    this.viewportTarget.addEventListener("scroll", this.#onScroll, { passive: true });
-    this.#layout.observe(this.viewportTarget);
+    this.#connected = true;
+    this.#rebind.activate();
     this.#layout.observeViewport();
+    this.#syncViewport();
+  }
+  /** Schedules a complete observer/listener rebind for a runtime viewport target. */
+  viewportTargetConnected() {
+    this.#rebind.schedule();
+  }
+  /** Schedules cleanup or replacement binding after a viewport leaves. */
+  viewportTargetDisconnected() {
+    this.#rebind.schedule();
+  }
+  /** Rebinds every viewport-owned resource against the final target in this mutation batch. */
+  #syncViewport() {
+    if (!this.#connected) return;
+    const next = this.hasViewportTarget ? this.viewportTarget : null;
+    if (next === this.#viewport) {
+      this.#update();
+      return;
+    }
+    if (this.#viewport) this.#unbindViewport(this.#viewport);
+    this.#viewport = next;
+    if (!next) return;
+    next.addEventListener("scroll", this.#onScroll, { passive: true });
+    this.#layout.observe(next);
     if (typeof MutationObserver !== "undefined") {
       this.#content = new MutationObserver(() => {
-        if (!this.hasViewportTarget) return;
-        const vp = this.viewportTarget;
-        this.#syncKeyboardReach(vp, this.#syncOverflow(vp));
+        if (this.#viewport !== next) return;
+        this.#syncKeyboardReach(next, this.#syncOverflow(next));
       });
-      this.#content.observe(this.viewportTarget, {
+      this.#content.observe(next, {
         subtree: true,
         childList: true,
         attributes: true
@@ -148,19 +278,26 @@ var ScrollAreaController = class extends Controller {
     this.#update();
   }
   disconnect() {
-    if (this.hasViewportTarget) {
-      this.viewportTarget.removeEventListener("scroll", this.#onScroll);
-      this.#clearAddedAttributes(this.viewportTarget);
-    }
+    this.#connected = false;
+    this.#rebind.cancel();
+    if (this.#viewport) this.#unbindViewport(this.#viewport);
     this.#layout.disconnect();
+    this.#lastEdge = null;
+  }
+  /** Releases every resource and derived attribute owned by one former viewport. */
+  #unbindViewport(viewport) {
+    viewport.removeEventListener("scroll", this.#onScroll);
+    this.#layout.unobserve(viewport);
     this.#content?.disconnect();
     this.#content = null;
+    this.#clearAddedAttributes(viewport);
+    if (this.#viewport === viewport) this.#viewport = null;
     this.#lastEdge = null;
   }
   /** Re-measures overflow and scroll position and reflects the state hooks. */
   #update() {
-    if (!this.hasViewportTarget) return;
-    const vp = this.viewportTarget;
+    const vp = this.#viewport;
+    if (!vp) return;
     const overflowing = this.#syncOverflow(vp);
     this.#syncKeyboardReach(vp, overflowing);
     const { position, progress } = this.#measurePosition(vp);
@@ -174,7 +311,6 @@ var ScrollAreaController = class extends Controller {
       this.#lastEdge = null;
     }
   }
-  /** Whether the viewport can scroll on the configured axis. */
   /**
    * Measures overflow and reflects the `data-overflow` hook.
    *
@@ -219,8 +355,7 @@ var ScrollAreaController = class extends Controller {
     if (wantsTabindex) {
       this.#tabindex.lend(vp);
       if (!vp.hasAttribute("role") && this.#hasAccessibleName(vp)) {
-        vp.setAttribute("role", "region");
-        this.#addedRole = true;
+        this.#role.write(vp, "region");
       }
     } else {
       this.#clearAddedAttributes(vp);
@@ -229,10 +364,7 @@ var ScrollAreaController = class extends Controller {
   /** Removes (and resets the flags for) only the attributes this controller added. */
   #clearAddedAttributes(vp) {
     this.#tabindex.returnAll();
-    if (this.#addedRole) {
-      vp.removeAttribute("role");
-      this.#addedRole = false;
-    }
+    this.#role.return(vp);
   }
   /**
    * Whether the viewport owns something the user can Tab to *right now*.

data/dist/controllers/scroll_visibility_controller.js

@@ -7,10 +7,41 @@ function prefersReducedMotion() {
   return typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
 }
 
+// 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/tabindex_loan.ts
 var TabindexLoan = class {
   #value;
   #lent = /* @__PURE__ */ new Set();
+  /** Returns live loans before Turbo can copy them into its page snapshot. */
+  #beforeCache = new BeforeCacheReset(() => this.returnAll());
   /**
    * @param value - the `tabindex` to lend. `"-1"` (the default) is
    *   programmatically focusable but not a Tab stop; `"0"` is a real Tab stop,
@@ -24,6 +55,7 @@ var TabindexLoan = class {
     if (element.hasAttribute("tabindex")) return;
     element.setAttribute("tabindex", this.#value);
     this.#lent.add(element);
+    this.#beforeCache.activate();
   }
   /** Takes back every loan whose value is still the one that was lent. */
   returnAll() {
@@ -31,6 +63,7 @@ var TabindexLoan = class {
       if (element.getAttribute("tabindex") === this.#value) element.removeAttribute("tabindex");
     }
     this.#lent.clear();
+    this.#beforeCache.deactivate();
   }
 };