stimeo-ui 0.4.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,24 +278,31 @@ 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);
     this.element.setAttribute("data-scroll", position);
-    this.element.style.setProperty("--stimeo-scroll-progress", String(progress));
+    this.element.style.setProperty("--stimeo--scroll-progress", String(progress));
     const edge = position === "start" ? "start" : position === "end" ? "end" : null;
     if (overflowing && edge && edge !== this.#lastEdge) {
       this.#lastEdge = edge;
@@ -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();
   }
 };
 

data/dist/controllers/separator_controller.js

@@ -8,6 +8,13 @@ function isReservedArrowChord(event, allow = []) {
   return event.altKey && !allow.includes("alt") || event.ctrlKey && !allow.includes("ctrl") || event.metaKey && !allow.includes("meta") || event.shiftKey && !allow.includes("shift");
 }
 
+// src/utils/default_attribute.ts
+function setDefaultAttribute(element, name, value) {
+  if (element.hasAttribute(name)) return false;
+  element.setAttribute(name, value);
+  return true;
+}
+
 // src/controllers/separator_controller.ts
 var SeparatorController = class extends Controller {
   static values = {
@@ -18,19 +25,13 @@ var SeparatorController = class extends Controller {
   static actions = ["onKeydown"];
   static events = ["change"];
   connect() {
-    if (!this.element.hasAttribute("role")) {
-      this.element.setAttribute("role", "separator");
-    }
-    if (!this.element.hasAttribute("aria-orientation")) {
-      this.element.setAttribute("aria-orientation", this.orientationValue);
-    }
+    setDefaultAttribute(this.element, "role", "separator");
+    setDefaultAttribute(this.element, "aria-orientation", this.orientationValue);
     if (this.focusableValue) {
-      if (!this.element.hasAttribute("tabindex")) {
-        this.element.setAttribute("tabindex", "0");
-      }
-      this.#setDefault("aria-valuemin", "0");
-      this.#setDefault("aria-valuemax", "100");
-      this.#setDefault("aria-valuenow", String(this.#clamp(this.#value)));
+      setDefaultAttribute(this.element, "tabindex", "0");
+      setDefaultAttribute(this.element, "aria-valuemin", "0");
+      setDefaultAttribute(this.element, "aria-valuemax", "100");
+      setDefaultAttribute(this.element, "aria-valuenow", String(this.#clamp(this.#value)));
     }
   }
   /** Adjusts the value on arrow / Home / End keys (focusable variant only). */
@@ -84,11 +85,6 @@ var SeparatorController = class extends Controller {
     const parsed = Number.parseFloat(this.element.getAttribute(name) ?? "");
     return Number.isNaN(parsed) ? fallback : parsed;
   }
-  #setDefault(name, value) {
-    if (!this.element.hasAttribute(name)) {
-      this.element.setAttribute(name, value);
-    }
-  }
 };
 
 export { SeparatorController };

data/dist/controllers/skeleton_controller.js

@@ -19,6 +19,61 @@ function fillTemplate(template, values) {
   });
 }
 
+// src/utils/detach_gate.ts
+var DetachGate = class _DetachGate {
+  /** Set while a probe is queued, waiting for a reconnect to cancel it. */
+  #pending = false;
+  /**
+   * True while a probe is queued — the last disconnect was ambiguous and no
+   * reconnect has cancelled it yet. Read it from `connect()` to tell the
+   * reconnect half of an in-page move from a first connect: a controller whose
+   * initialisation restarts a measurement (a min-duration floor, an elapsed
+   * counter) must skip it for the move, where nothing actually restarted.
+   */
+  get pending() {
+    return this.#pending;
+  }
+  /**
+   * True when the disconnect is definitely a real detach — the element left
+   * the document, or `data-controller` no longer lists the identifier. False
+   * means ambiguous (in-page move or observed-root exit), NOT "alive".
+   */
+  static isDetached(host) {
+    if (!host.element.isConnected) return true;
+    const tokens = (host.element.getAttribute("data-controller") ?? "").split(/\s+/);
+    return !tokens.includes(host.identifier);
+  }
+  /**
+   * Call from `disconnect()`: runs `teardown` synchronously on a definite
+   * detach (fast path), otherwise defers it one microtask — a reconnect
+   * ({@link cancel} from `connect()`) keeps the state, no reconnect runs it.
+   * One microtask is the whole probe window: Stimulus reconnects a moved
+   * element within the same mutation batch, before the checkpoint drains.
+   */
+  disconnected(host, teardown) {
+    if (_DetachGate.isDetached(host)) {
+      this.#pending = false;
+      teardown();
+      return;
+    }
+    this.#pending = true;
+    queueMicrotask(() => {
+      if (!this.#pending) return;
+      this.#pending = false;
+      teardown();
+    });
+  }
+  /**
+   * Disarms a pending probe. Call from `connect()` (the reconnect that proves
+   * an in-page move) and from the head of any teardown path not routed through
+   * {@link disconnected} (disabled-toggle, Escape), so an orphaned probe can
+   * never run the teardown a second time.
+   */
+  cancel() {
+    this.#pending = false;
+  }
+};
+
 // src/utils/min_duration_floor.ts
 var MinDurationFloor = class {
   #timers;
@@ -131,14 +186,16 @@ var SkeletonController = class extends Controller {
   static events = ["ready"];
   #timers = new SafeTimeout();
   #floor = new MinDurationFloor(this.#timers);
+  #gate = new DetachGate();
   connect() {
-    if (this.#state !== "ready") {
+    const moved = this.#gate.pending;
+    this.#gate.cancel();
+    if (!moved && this.#state !== "ready") {
       this.#enterLoading();
     }
   }
   disconnect() {
-    this.#timers.clearAll();
-    this.#floor.cancel();
+    this.#gate.disconnected(this, () => this.#teardown());
   }
   /** Swaps to the real content. Honors `minDuration` to prevent a flash. */
   ready() {
@@ -167,6 +224,17 @@ var SkeletonController = class extends Controller {
     this.dispatch("ready", { detail: {} });
     announce(fillTemplate(this.announceReadyTextValue, {}));
   }
+  /**
+   * Drops the held reveal on a real detach. The markup keeps whatever it last
+   * held: an element on its way out of the document has no reader left, and one
+   * whose `data-controller` dropped the identifier no longer resolves its own
+   * targets, so the rollback could only ever be partial.
+   */
+  #teardown() {
+    this.#gate.cancel();
+    this.#timers.clearAll();
+    this.#floor.cancel();
+  }
   /** Current lifecycle phase as reflected on `data-state`. */
   get #state() {
     return this.element.getAttribute("data-state") ?? "loading";