stimeo-ui 0.9.0 → 0.11.0

data/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;

data/dist/controllers/sidebar_controller.js

@@ -315,15 +315,25 @@ var FocusTrap = class {
    * content cannot be focused or reached by assistive technology, honoring the
    * `aria-modal="true"` contract. An element that was *already* `inert` is left
    * untracked so `#releaseBackground` does not wrongly clear it.
+   *
+   * The walk climbs from the container to `body` and inerts each ancestor's other
+   * children. Scanning only `body`'s children would skip the branch the container
+   * sits in — everything beside it inside that branch is background too, and a
+   * nested container is the ordinary case.
    */
   #isolateBackground() {
     const container = this.#getContainer();
     this.#inertedSiblings = [];
-    for (const sibling of Array.from(document.body.children)) {
-      if (!(sibling instanceof HTMLElement)) continue;
-      if (sibling.contains(container) || sibling.inert) continue;
-      sibling.inert = true;
-      this.#inertedSiblings.push(sibling);
+    for (let node = container; node !== document.body; ) {
+      const parent = node.parentElement;
+      if (!parent) break;
+      for (const sibling of Array.from(parent.children)) {
+        if (!(sibling instanceof HTMLElement)) continue;
+        if (sibling === node || sibling.inert) continue;
+        sibling.inert = true;
+        this.#inertedSiblings.push(sibling);
+      }
+      node = parent;
     }
   }
   /** Reverts the `inert` flags applied by `#isolateBackground`. */

data/dist/controllers/step_indicator_controller.js

@@ -43,11 +43,6 @@ var StepIndicatorController = class extends Controller {
   };
   static actions = ["setCurrent"];
   static events = ["change"];
-  /**
-   * Whether the target callbacks may render. Stimulus reports the authored steps
-   * as connected before `connect()` and the remaining ones as disconnected after
-   * `disconnect()`, so this keeps a connect at one render pass, not one per step.
-   */
   /**
    * Collapses a batch of step callbacks — and a morph that swaps `current` with
    * them — into one repaint. Replacing a list of N steps delivers N callbacks, and

data/dist/controllers/stick_to_bottom_controller.js

@@ -2,12 +2,69 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/stick_to_bottom_controller.ts
 
+// src/utils/layout_observer.ts
+var LayoutObserver = class {
+  #callback;
+  #resizeObserverFactory;
+  #resizeObserver = null;
+  #observingViewport = false;
+  /** Stable bound handler so add/removeEventListener target the same reference. */
+  #handleViewportResize = () => {
+    this.#callback();
+  };
+  constructor(callback, options = {}) {
+    this.#callback = callback;
+    this.#resizeObserverFactory = options.resizeObserverFactory ?? (typeof ResizeObserver === "undefined" ? null : (cb) => new ResizeObserver(cb));
+  }
+  /**
+   * Starts observing an element's size. Repeated calls observe additional
+   * elements through the same shared observer. No-ops when no
+   * `ResizeObserver` implementation is available.
+   */
+  observe(element) {
+    if (!this.#resizeObserverFactory) return;
+    if (!this.#resizeObserver) {
+      this.#resizeObserver = this.#resizeObserverFactory(() => {
+        this.#callback();
+      });
+    }
+    this.#resizeObserver.observe(element);
+  }
+  /** Stops observing a single element while leaving any others in place. */
+  unobserve(element) {
+    this.#resizeObserver?.unobserve(element);
+  }
+  /** Starts observing viewport resizes. Idempotent: the listener is added once. */
+  observeViewport() {
+    if (this.#observingViewport) return;
+    this.#observingViewport = true;
+    window.addEventListener("resize", this.#handleViewportResize);
+  }
+  /** Stops observing viewport resizes without affecting element observation. */
+  unobserveViewport() {
+    if (!this.#observingViewport) return;
+    this.#observingViewport = false;
+    window.removeEventListener("resize", this.#handleViewportResize);
+  }
+  /**
+   * Releases every observation: disconnects the {@link ResizeObserver} and
+   * removes the viewport listener. Safe to call multiple times. Call this from a
+   * controller's `disconnect()`.
+   */
+  disconnect() {
+    this.#resizeObserver?.disconnect();
+    this.#resizeObserver = null;
+    this.unobserveViewport();
+  }
+};
+
 // src/utils/reduced_motion.ts
 function prefersReducedMotion() {
   return typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
 }
 
 // src/controllers/stick_to_bottom_controller.ts
+var DEFAULT_THRESHOLD = 80;
 var countElements = (nodes) => {
   let n = 0;
   for (const node of nodes) if (node.nodeType === Node.ELEMENT_NODE) n += 1;
@@ -16,34 +73,53 @@ var countElements = (nodes) => {
 var StickToBottomController = class extends Controller {
   static targets = ["content"];
   static values = {
-    threshold: { type: Number, default: 80 },
+    threshold: { type: Number, default: DEFAULT_THRESHOLD },
     behavior: { type: String, default: "auto" },
     pinOnConnect: { type: Boolean, default: false }
   };
   static actions = ["scrollToBottom"];
   static events = ["pin", "new"];
   #observer = null;
-  /** Watches for the box a deferred `pinOnConnect` jump is still waiting on. */
-  #layout = null;
+  /** The element the append observer currently holds, so a swap can be detected. */
+  #watched = null;
+  /** Watches for the box a container connected without one is still waiting on. */
+  #layout = new LayoutObserver(() => this.#onLaidOut());
+  #awaitingLayout = false;
+  #connected = false;
   #pinned = false;
   #onScroll = () => this.#updatePinned();
   connect() {
+    this.#connected = true;
     if (this.pinOnConnectValue && this.#measurable()) this.#scrollToBottom("instant");
+    this.element.removeAttribute("data-has-new");
     this.#pinned = this.#isPinned();
     this.#reflectPinned();
     this.element.addEventListener("scroll", this.#onScroll, { passive: true });
-    if (typeof MutationObserver !== "undefined") {
-      this.#observer = new MutationObserver((mutations) => this.#onMutations(mutations));
-      this.#observer.observe(this.#watched(), { childList: true });
-    }
-    if (this.pinOnConnectValue && !this.#measurable()) this.#pinWhenLaidOut();
+    this.#syncWatched();
+    if (!this.#measurable()) this.#waitForLayout();
   }
   disconnect() {
+    this.#connected = false;
     this.element.removeEventListener("scroll", this.#onScroll);
-    this.#observer?.disconnect();
-    this.#observer = null;
+    this.#stopWatching();
     this.#stopWaitingForLayout();
   }
+  /** Moves the append watch onto a `content` target that arrived at runtime. */
+  contentTargetConnected() {
+    this.#syncWatched();
+  }
+  /** Moves the append watch off a `content` target that left, back onto the container. */
+  contentTargetDisconnected() {
+    this.#syncWatched();
+  }
+  /**
+   * Re-derives pinned when the distance that counts as the bottom is changed at runtime
+   * (a morph that swaps the attribute on a retained element).
+   */
+  thresholdValueChanged() {
+    if (!this.#connected) return;
+    this.#updatePinned();
+  }
   /**
    * Jumps to the bottom and re-pins (wired to a "new messages" button).
    *
@@ -72,7 +148,11 @@ var StickToBottomController = class extends Controller {
       this.dispatch("new", { detail: { count: added } });
     }
   }
-  /** Recomputes pinned from the scroll position and reflects it on a transition. */
+  /**
+   * Recomputes pinned from the scroll position and reflects it on a transition.
+   *
+   * @stimeoRenderRoot
+   */
   #updatePinned() {
     const pinned = this.#isPinned();
     if (pinned === this.#pinned) return;
@@ -89,9 +169,25 @@ var StickToBottomController = class extends Controller {
       this.element.removeAttribute("data-pinned");
     }
   }
+  /** Whether the container currently sits within `threshold` of its bottom. */
   #isPinned() {
+    if (!this.#measurable()) return false;
     const el = this.element;
-    return el.scrollHeight - el.clientHeight - el.scrollTop <= this.thresholdValue;
+    return el.scrollHeight - el.clientHeight - el.scrollTop <= this.#threshold;
+  }
+  /**
+   * The distance from the bottom that counts as pinned: a finite, non-negative number of
+   * pixels. Anything else names no distance the container can be at, and settles the
+   * comparison the same way at every scroll position, so it falls back to the default.
+   * `Number` reads `"abc"` as `NaN` and every comparison against it is false; a negative
+   * distance sits below the closest the container ever gets; `Infinity` is never
+   * exceeded. The first two stop following and flag every append as new, and the last
+   * never stops following — it takes the reading position the flag exists to protect.
+   * Zero is a real declaration: it pins at the exact bottom only.
+   */
+  get #threshold() {
+    const declared = this.thresholdValue;
+    return Number.isFinite(declared) && declared >= 0 ? declared : DEFAULT_THRESHOLD;
   }
   /**
    * Whether the container has a box to scroll and to measure. One that is not rendered
@@ -102,23 +198,25 @@ var StickToBottomController = class extends Controller {
     return this.element.clientHeight > 0;
   }
   /**
-   * Holds the `pinOnConnect` jump until the container is laid out, then runs it and
-   * re-reads the state — otherwise the panel opens at the top still claiming the bottom.
+   * Holds the pinned decision until the container is laid out — otherwise the panel opens
+   * at the top while the state claims the bottom, and the appends that arrived meanwhile
+   * were followed into a box that could not move rather than flagged.
    */
-  #pinWhenLaidOut() {
-    if (typeof ResizeObserver === "undefined") return;
-    this.#layout = new ResizeObserver(() => {
-      if (!this.#measurable()) return;
-      this.#stopWaitingForLayout();
-      this.#scrollToBottom("instant");
-      this.#updatePinned();
-    });
+  #waitForLayout() {
+    this.#awaitingLayout = true;
     this.#layout.observe(this.element);
   }
-  /** Releases the layout watch, whether or not the deferred jump ever ran. */
+  /** Runs the held decision once the container has the box it was waiting for. */
+  #onLaidOut() {
+    if (!this.#awaitingLayout || !this.#measurable()) return;
+    this.#stopWaitingForLayout();
+    if (this.pinOnConnectValue) this.#scrollToBottom("instant");
+    this.#updatePinned();
+  }
+  /** Releases the layout watch, whether or not the held decision ever ran. */
   #stopWaitingForLayout() {
-    this.#layout?.disconnect();
-    this.#layout = null;
+    this.#awaitingLayout = false;
+    this.#layout.disconnect();
   }
   /**
    * Scrolls to the bottom, clamped by the engine to the maximum scroll offset — which is
@@ -134,9 +232,32 @@ var StickToBottomController = class extends Controller {
       this.element.scrollTop = top;
     }
   }
-  /** The append-watched element: the `content` target, or the container itself. */
-  #watched() {
-    return this.hasContentTarget ? this.contentTarget : this.element;
+  /**
+   * Points the append watch at the current `content` target, or at the container when
+   * there is none. Re-resolved whenever that target changes, so a swap does not leave the
+   * observer holding a detached node whose appends nobody sees.
+   *
+   * Stimulus runs the target callbacks outside the connected window too — before
+   * `connect()` for a target already in the DOM, and after `disconnect()` while the
+   * element is torn down — where this would arm an observer nothing releases. Re-syncing
+   * to the target already held is left alone, so an arrival still in flight is not
+   * dropped with the observer that was about to deliver it.
+   */
+  #syncWatched() {
+    if (!this.#connected) return;
+    const next = this.hasContentTarget ? this.contentTarget : this.element;
+    if (next === this.#watched) return;
+    this.#stopWatching();
+    this.#watched = next;
+    if (typeof MutationObserver === "undefined") return;
+    this.#observer = new MutationObserver((mutations) => this.#onMutations(mutations));
+    this.#observer.observe(next, { childList: true });
+  }
+  /** Releases the append watch and the element it held. */
+  #stopWatching() {
+    this.#observer?.disconnect();
+    this.#observer = null;
+    this.#watched = null;
   }
   /**
    * The behavior a follow-scroll runs with. `"auto"` is **not** a request to arrive at