@signal9/era-ui 2.1.0 → 2.2.0

package/dist/ai/stick-to-bottom.svelte.d.ts

@@ -0,0 +1,38 @@
+import type { Attachment } from 'svelte/attachments';
+/**
+ * The stick-to-bottom contract, distilled from the reference implementations
+ * (use-stick-to-bottom, open-webui, vercel/ai-elements):
+ *
+ * - auto-follow content growth while pinned to the bottom;
+ * - ANY user-initiated upward intent breaks the pin instantly (wheel up,
+ *   touch drag, PageUp/ArrowUp/Home, or a scroll event that moved up and
+ *   wasn't ours);
+ * - scrolling back to within `threshold` px of the bottom re-pins;
+ * - content growth is watched with a ResizeObserver on the CONTENT (scroll
+ *   events alone miss it — images, code blocks, expanding steps), and the
+ *   scroll events a resize provokes are guarded so a reflow never reads as
+ *   the user scrolling away;
+ * - an active text selection inside the viewport suspends following (never
+ *   yank text out from under a selecting user);
+ * - scrolling is a direct scrollTop write on the container, coalesced through
+ *   rAF — never scrollIntoView (it scrolls ancestors too).
+ *
+ * CSS `overflow-anchor` and `column-reverse` are deliberately not used: no
+ * Safari support for the former; reversed DOM order breaks screen readers,
+ * selection, and `role="log"` semantics for the latter.
+ */
+export declare class StickToBottom {
+    #private;
+    /** True while auto-following. Reactive — drive the ↓ button off it. */
+    pinned: boolean;
+    /** Px from the bottom still considered "at bottom" for re-pinning. */
+    threshold: number;
+    /** Attach to the scroll container (`overflow-y-auto`). */
+    viewport: Attachment<HTMLElement>;
+    /** Attach to the content wrapper INSIDE the viewport. */
+    content: Attachment<HTMLElement>;
+    /** Jump the viewport to the bottom (rAF-coalesced; safe to call per token). */
+    scrollToBottom(): void;
+    /** The ↓ button's action: re-pin and go. */
+    repin(): void;
+}

package/dist/ai/stick-to-bottom.svelte.js

@@ -0,0 +1,133 @@
+/**
+ * The stick-to-bottom contract, distilled from the reference implementations
+ * (use-stick-to-bottom, open-webui, vercel/ai-elements):
+ *
+ * - auto-follow content growth while pinned to the bottom;
+ * - ANY user-initiated upward intent breaks the pin instantly (wheel up,
+ *   touch drag, PageUp/ArrowUp/Home, or a scroll event that moved up and
+ *   wasn't ours);
+ * - scrolling back to within `threshold` px of the bottom re-pins;
+ * - content growth is watched with a ResizeObserver on the CONTENT (scroll
+ *   events alone miss it — images, code blocks, expanding steps), and the
+ *   scroll events a resize provokes are guarded so a reflow never reads as
+ *   the user scrolling away;
+ * - an active text selection inside the viewport suspends following (never
+ *   yank text out from under a selecting user);
+ * - scrolling is a direct scrollTop write on the container, coalesced through
+ *   rAF — never scrollIntoView (it scrolls ancestors too).
+ *
+ * CSS `overflow-anchor` and `column-reverse` are deliberately not used: no
+ * Safari support for the former; reversed DOM order breaks screen readers,
+ * selection, and `role="log"` semantics for the latter.
+ */
+export class StickToBottom {
+    /** True while auto-following. Reactive — drive the ↓ button off it. */
+    pinned = $state(true);
+    /** Px from the bottom still considered "at bottom" for re-pinning. */
+    threshold = 70;
+    #el = null;
+    #lastTop = 0;
+    #programmatic = 0;
+    #resizeGuard = 0;
+    #raf = 0;
+    /** Attach to the scroll container (`overflow-y-auto`). */
+    viewport = (el) => {
+        this.#el = el;
+        this.#lastTop = el.scrollTop;
+        const unpin = () => (this.pinned = false);
+        const onWheel = (e) => {
+            if (e.deltaY < 0)
+                unpin();
+        };
+        const onTouchMove = () => {
+            // A touch drag is user intent; if it lands near the bottom the
+            // scroll handler re-pins right after.
+            if (!this.#nearBottom())
+                unpin();
+        };
+        const onKeyDown = (e) => {
+            if (e.key === 'PageUp' || e.key === 'ArrowUp' || e.key === 'Home')
+                unpin();
+        };
+        const onScroll = () => {
+            const top = el.scrollTop;
+            const wasOurs = this.#programmatic > 0 || this.#resizeGuard > 0;
+            if (!wasOurs) {
+                if (top < this.#lastTop - 1)
+                    unpin();
+                else if (this.#nearBottom())
+                    this.pinned = true;
+            }
+            this.#lastTop = top;
+        };
+        const onScrollEnd = () => {
+            this.#programmatic = 0;
+        };
+        el.addEventListener('wheel', onWheel, { passive: true });
+        el.addEventListener('touchmove', onTouchMove, { passive: true });
+        el.addEventListener('keydown', onKeyDown);
+        el.addEventListener('scroll', onScroll, { passive: true });
+        el.addEventListener('scrollend', onScrollEnd);
+        return () => {
+            el.removeEventListener('wheel', onWheel);
+            el.removeEventListener('touchmove', onTouchMove);
+            el.removeEventListener('keydown', onKeyDown);
+            el.removeEventListener('scroll', onScroll);
+            el.removeEventListener('scrollend', onScrollEnd);
+            if (this.#el === el)
+                this.#el = null;
+        };
+    };
+    /** Attach to the content wrapper INSIDE the viewport. */
+    content = (el) => {
+        const ro = new ResizeObserver(() => {
+            if (!this.#el)
+                return;
+            // Guard the scroll events this resize provokes for two frames so a
+            // code-block reflow never reads as the user scrolling away.
+            this.#resizeGuard++;
+            if (this.pinned && !this.#selecting())
+                this.scrollToBottom();
+            requestAnimationFrame(() => requestAnimationFrame(() => {
+                this.#resizeGuard = Math.max(0, this.#resizeGuard - 1);
+            }));
+        });
+        ro.observe(el);
+        return () => ro.disconnect();
+    };
+    #nearBottom() {
+        const el = this.#el;
+        if (!el)
+            return true;
+        return el.scrollHeight - el.scrollTop - el.clientHeight <= this.threshold;
+    }
+    #selecting() {
+        if (typeof window === 'undefined')
+            return false;
+        const sel = window.getSelection();
+        return !!sel && !sel.isCollapsed && this.#el?.contains(sel.anchorNode) === true;
+    }
+    /** Jump the viewport to the bottom (rAF-coalesced; safe to call per token). */
+    scrollToBottom() {
+        if (this.#raf)
+            return;
+        this.#raf = requestAnimationFrame(() => {
+            this.#raf = 0;
+            const el = this.#el;
+            if (!el)
+                return;
+            this.#programmatic++;
+            el.scrollTop = el.scrollHeight;
+            // scrollend clears the flag; the double-rAF is the fallback for
+            // browsers that don't fire it.
+            requestAnimationFrame(() => requestAnimationFrame(() => {
+                this.#programmatic = Math.max(0, this.#programmatic - 1);
+            }));
+        });
+    }
+    /** The ↓ button's action: re-pin and go. */
+    repin() {
+        this.pinned = true;
+        this.scrollToBottom();
+    }
+}