stimeo-ui 0.10.0 → 0.12.0

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

data/dist/controllers/sticky_observer_controller.js

@@ -9,6 +9,14 @@ function isBeforeRootStart(entry) {
   const rootTop = entry.rootBounds?.top ?? 0;
   return rect.bottom <= rootTop;
 }
+function queryRoot(selector) {
+  if (!selector) return null;
+  try {
+    return document.querySelector(selector);
+  } catch {
+  }
+  return null;
+}
 var IntersectionWatcher = class {
   #onEntries;
   #observer = null;
@@ -30,7 +38,10 @@ var IntersectionWatcher = class {
    * the watcher inert — without `IntersectionObserver` support (very old
    * browsers; the caller's no-JS fallback stays in charge) or with no targets.
    * If initial construction with the configured options fails, the watcher
-   * warns and retries once with the same root and platform defaults.
+   * warns and retries once with the same root and platform defaults. A
+   * `rootSelector` that does not parse resolves to the viewport (see
+   * {@link IntersectionWatchOptions.rootSelector}), so a typo never fails the
+   * call.
    *
    * @throws The fallback constructor error if both construction attempts fail,
    *   or whatever the platform throws from `observe()`. The exception is passed
@@ -43,7 +54,7 @@ var IntersectionWatcher = class {
     if (typeof IntersectionObserver === "undefined") return false;
     const list = Array.isArray(targets) ? targets : [targets];
     if (list.length === 0) return false;
-    const root = "root" in options ? options.root ?? null : options.rootSelector ? document.querySelector(options.rootSelector) : null;
+    const root = "root" in options ? options.root ?? null : queryRoot(options.rootSelector);
     let observer = null;
     try {
       const onEntries = (entries) => {