use-stick-to-bottom-extended 1.2.0

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 - present StackBlitz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,145 @@
+# `use-stick-to-bottom-extended`
+
+> Designed with AI chat bots in mind
+
+This package is a fork of the original [`use-stick-to-bottom`](https://github.com/stackblitz-labs/use-stick-to-bottom). The original implementation and copyright belong to StackBlitz/Sam Denty. This extended fork is maintained by [duz52](https://github.com/duz52/).
+
+This fork adds `resize={false}` / `resize: false`, which disables ResizeObserver-driven automatic scrolling after initial layout. Use it when a chat should scroll once after sending a new message only if the user was already at the bottom, without continuing to stick to the bottom while the window is being resized.
+
+A lightweight **zero-dependency** React hook + Component that automatically sticks to the bottom of container and smoothly animates the content to keep it's visual position on screen whilst new content is being added.
+
+## Features
+
+- Does not require [`overflow-anchor`](https://developer.mozilla.org/en-US/docs/Web/CSS/overflow-anchor) browser-level CSS support which Safari does not support.
+- Can be connected up to any existing component using a hook with refs. Or simply use the provided component, which handles the refs for you plus provides context - so child components can check `isAtBottom` & programmatically scroll to the bottom.
+- Uses the modern, yet well-supported, [`ResizeObserver`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver) API to detect when content resizes.
+  - Supports content shrinking without losing stickiness - not just getting taller.
+- Correctly handles [Scroll Anchoring](https://developer.mozilla.org/en-US/docs/Web/CSS/overflow-anchor/Guide_to_scroll_anchoring). This is where when content above the viewport resizes, it doesn't cause the content currently displayed in viewport to jump up or down.
+- Allows the user to cancel the stickiness at any time by scrolling up.
+  - Clever logic distinguishes the user scrolling from the custom animation scroll events (without doing any debouncing which could cause some events to be missed).
+  - Mobile devices work well with this logic too.
+- Uses a custom implemented smooth scrolling algorithm, featuring velocity-based spring animations (with configurable parameters).
+  - Other libraries use easing functions with durations instead, but these doesn't work well when you want to stream in new content with variable sizing - which is common for AI chatbot use cases.
+  - `scrollToBottom` returns a `Promise<boolean>` which will resolve to `true` as soon as the scroll was successful, or `false` if the scroll was cancelled.
+
+## Installation
+
+```bash
+npm install github:duz52/use-stick-to-bottom-extended
+```
+
+## Usage
+
+### `<StickToBottom>` Component
+
+```jsx
+import { StickToBottom, useStickToBottomContext } from 'use-stick-to-bottom-extended';
+
+function Chat() {
+  return (
+    <StickToBottom className="h-[50vh] relative" resize="smooth" initial="smooth">
+      <StickToBottom.Content className="flex flex-col gap-4">
+        {messages.map((message) => (
+          <Message key={message.id} message={message} />
+        ))}
+      </StickToBottom.Content>
+
+      <ScrollToBottom />
+
+      {/* This component uses `useStickToBottomContext` to scroll to bottom when the user enters a message */}
+      <ChatBox />
+    </StickToBottom>
+  );
+}
+
+function ScrollToBottom() {
+  const { isAtBottom, scrollToBottom } = useStickToBottomContext();
+
+  return (
+    !isAtBottom && (
+      <button
+        className="absolute i-ph-arrow-circle-down-fill text-4xl rounded-lg left-[50%] translate-x-[-50%] bottom-0"
+        onClick={() => scrollToBottom()}
+      />
+    )
+  );
+}
+```
+
+### One-shot send scroll without resize stickiness
+
+Set `resize={false}` to disable automatic scrolling from content resize events after the initial layout. Capture whether the user was at the bottom before appending the message, then scroll once after the message is rendered.
+
+```jsx
+import { useLayoutEffect, useRef, useState } from 'react';
+import { StickToBottom, useStickToBottomContext } from 'use-stick-to-bottom-extended';
+
+function Chat() {
+  const [messages, setMessages] = useState([]);
+
+  return (
+    <StickToBottom className="h-[50vh] relative" resize={false} initial="instant">
+      <ChatContent messages={messages} setMessages={setMessages} />
+    </StickToBottom>
+  );
+}
+
+function ChatContent({ messages, setMessages }) {
+  const { isAtBottom, scrollToBottom } = useStickToBottomContext();
+  const shouldScrollAfterSend = useRef(false);
+
+  const sendMessage = (text) => {
+    shouldScrollAfterSend.current = isAtBottom;
+    setMessages((current) => [...current, { id: crypto.randomUUID(), text }]);
+  };
+
+  useLayoutEffect(() => {
+    if (!shouldScrollAfterSend.current) {
+      return;
+    }
+
+    shouldScrollAfterSend.current = false;
+    scrollToBottom({ animation: 'instant' });
+  }, [messages.length, scrollToBottom]);
+
+  return (
+    <>
+      <StickToBottom.Content className="flex flex-col gap-4">
+        {messages.map((message) => (
+          <Message key={message.id} message={message} />
+        ))}
+      </StickToBottom.Content>
+
+      <ChatBox onSend={sendMessage} />
+    </>
+  );
+}
+```
+
+### `useStickToBottom` Hook
+
+```jsx
+import { useStickToBottom } from 'use-stick-to-bottom-extended';
+
+function Component() {
+  const { scrollRef, contentRef } = useStickToBottom({ resize: false });
+
+  return (
+    <div style={{ overflow: 'auto' }} ref={scrollRef}>
+      <div ref={contentRef}>
+        {messages.map((message) => (
+          <Message key={message.id} message={message} />
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+## Extended API
+
+### `resize: false`
+
+The original package accepts `resize` as an animation setting, such as `"smooth"`, `"instant"`, or a spring animation object. This fork also accepts `false`.
+
+When `resize` is `false`, the hook still observes content size changes so scroll state stays accurate, but it does not automatically call `scrollToBottom` for positive content resizes after the first layout. That lets applications implement explicit, one-shot scroll behavior on send while avoiding continued bottom locking during window resize.

package/dist/StickToBottom.d.ts

@@ -0,0 +1,35 @@
+/*!---------------------------------------------------------------------------------------------
+ *  Copyright (c) StackBlitz. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from "react";
+import { type ReactElement, type ReactNode } from "react";
+import { type GetTargetScrollTop, type ScrollToBottom, type StickToBottomInstance, type StickToBottomOptions, type StickToBottomState, type StopScroll } from "./useStickToBottom.js";
+export interface StickToBottomContext {
+    contentRef: React.MutableRefObject<HTMLElement | null> & React.RefCallback<HTMLElement>;
+    scrollRef: React.MutableRefObject<HTMLElement | null> & React.RefCallback<HTMLElement>;
+    scrollToBottom: ScrollToBottom;
+    stopScroll: StopScroll;
+    isAtBottom: boolean;
+    escapedFromLock: boolean;
+    get targetScrollTop(): GetTargetScrollTop | null;
+    set targetScrollTop(targetScrollTop: GetTargetScrollTop | null);
+    state: StickToBottomState;
+}
+export interface StickToBottomProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "children">, StickToBottomOptions {
+    contextRef?: React.Ref<StickToBottomContext>;
+    instance?: StickToBottomInstance;
+    children: ((context: StickToBottomContext) => ReactNode) | ReactNode;
+}
+export declare function StickToBottom({ instance, children, resize, initial, mass, damping, stiffness, targetScrollTop: currentTargetScrollTop, contextRef, ...props }: StickToBottomProps): ReactElement;
+export declare namespace StickToBottom {
+    interface ContentProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
+        children: ((context: StickToBottomContext) => ReactNode) | ReactNode;
+        scrollClassName?: string;
+    }
+    function Content({ children, scrollClassName, ...props }: ContentProps): ReactElement;
+}
+/**
+ * Use this hook inside a <StickToBottom> component to gain access to whether the component is at the bottom of the scrollable area.
+ */
+export declare function useStickToBottomContext(): StickToBottomContext;

package/dist/StickToBottom.js

@@ -0,0 +1,81 @@
+/*!---------------------------------------------------------------------------------------------
+ *  Copyright (c) StackBlitz. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from "react";
+import { createContext, useContext, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, } from "react";
+import { useStickToBottom, } from "./useStickToBottom.js";
+const StickToBottomContext = createContext(null);
+const useIsomorphicLayoutEffect = typeof window !== "undefined" ? useLayoutEffect : useEffect;
+export function StickToBottom({ instance, children, resize, initial, mass, damping, stiffness, targetScrollTop: currentTargetScrollTop, contextRef, ...props }) {
+    const customTargetScrollTop = useRef(null);
+    const targetScrollTop = React.useCallback((target, elements) => {
+        const get = context?.targetScrollTop ?? currentTargetScrollTop;
+        return get?.(target, elements) ?? target;
+    }, [currentTargetScrollTop]);
+    const defaultInstance = useStickToBottom({
+        mass,
+        damping,
+        stiffness,
+        resize,
+        initial,
+        targetScrollTop,
+    });
+    const { scrollRef, contentRef, scrollToBottom, stopScroll, isAtBottom, escapedFromLock, state, } = instance ?? defaultInstance;
+    const context = useMemo(() => ({
+        scrollToBottom,
+        stopScroll,
+        scrollRef,
+        isAtBottom,
+        escapedFromLock,
+        contentRef,
+        state,
+        get targetScrollTop() {
+            return customTargetScrollTop.current;
+        },
+        set targetScrollTop(targetScrollTop) {
+            customTargetScrollTop.current = targetScrollTop;
+        },
+    }), [
+        scrollToBottom,
+        isAtBottom,
+        contentRef,
+        scrollRef,
+        stopScroll,
+        escapedFromLock,
+        state,
+    ]);
+    useImperativeHandle(contextRef, () => context, [context]);
+    useIsomorphicLayoutEffect(() => {
+        if (!scrollRef.current) {
+            return;
+        }
+        if (getComputedStyle(scrollRef.current).overflow === "visible") {
+            scrollRef.current.style.overflow = "auto";
+        }
+    }, []);
+    return (React.createElement(StickToBottomContext.Provider, { value: context },
+        React.createElement("div", { ...props }, typeof children === "function" ? children(context) : children)));
+}
+(function (StickToBottom) {
+    function Content({ children, scrollClassName, ...props }) {
+        const context = useStickToBottomContext();
+        return (React.createElement("div", { ref: context.scrollRef, style: {
+                height: "100%",
+                width: "100%",
+                scrollbarGutter: "stable both-edges",
+            }, className: scrollClassName },
+            React.createElement("div", { ...props, ref: context.contentRef }, typeof children === "function" ? children(context) : children)));
+    }
+    StickToBottom.Content = Content;
+})(StickToBottom || (StickToBottom = {}));
+/**
+ * Use this hook inside a <StickToBottom> component to gain access to whether the component is at the bottom of the scrollable area.
+ */
+export function useStickToBottomContext() {
+    const context = useContext(StickToBottomContext);
+    if (!context) {
+        throw new Error("use-stick-to-bottom-extended component context must be used within a StickToBottom component");
+    }
+    return context;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./useStickToBottom.js";
+export * from "./StickToBottom.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from "./useStickToBottom.js";
+export * from "./StickToBottom.js";

package/dist/tsconfig.app.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["../src/StickToBottom.tsx","../src/index.ts","../src/useStickToBottom.ts"],"version":"5.8.2"}

package/dist/tsconfig.demo.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["../demo/Demo.tsx","../demo/index.tsx","../demo/useFakeMessages.tsx"],"version":"5.8.2"}

package/dist/useStickToBottom.d.ts

@@ -0,0 +1,106 @@
+/*!---------------------------------------------------------------------------------------------
+ *  Copyright (c) StackBlitz. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+export interface StickToBottomState {
+    scrollTop: number;
+    lastScrollTop?: number;
+    ignoreScrollToTop?: number;
+    targetScrollTop: number;
+    calculatedTargetScrollTop: number;
+    scrollDifference: number;
+    resizeDifference: number;
+    animation?: {
+        behavior: "instant" | Required<SpringAnimation>;
+        ignoreEscapes: boolean;
+        promise: Promise<boolean>;
+    };
+    lastTick?: number;
+    velocity: number;
+    accumulated: number;
+    escapedFromLock: boolean;
+    isAtBottom: boolean;
+    isNearBottom: boolean;
+    resizeObserver?: ResizeObserver;
+}
+declare const DEFAULT_SPRING_ANIMATION: {
+    /**
+     * A value from 0 to 1, on how much to damp the animation.
+     * 0 means no damping, 1 means full damping.
+     *
+     * @default 0.7
+     */
+    damping: number;
+    /**
+     * The stiffness of how fast/slow the animation gets up to speed.
+     *
+     * @default 0.05
+     */
+    stiffness: number;
+    /**
+     * The inertial mass associated with the animation.
+     * Higher numbers make the animation slower.
+     *
+     * @default 1.25
+     */
+    mass: number;
+};
+export interface SpringAnimation extends Partial<typeof DEFAULT_SPRING_ANIMATION> {
+}
+export type Animation = ScrollBehavior | SpringAnimation;
+export interface ScrollElements {
+    scrollElement: HTMLElement;
+    contentElement: HTMLElement;
+}
+export type GetTargetScrollTop = (targetScrollTop: number, context: ScrollElements) => number;
+export interface StickToBottomOptions extends SpringAnimation {
+    resize?: Animation | false;
+    initial?: Animation | boolean;
+    targetScrollTop?: GetTargetScrollTop;
+}
+export type ScrollToBottomOptions = ScrollBehavior | {
+    animation?: Animation;
+    /**
+     * Whether to wait for any existing scrolls to finish before
+     * performing this one. Or if a millisecond is passed,
+     * it will wait for that duration before performing the scroll.
+     *
+     * @default false
+     */
+    wait?: boolean | number;
+    /**
+     * Whether to prevent the user from escaping the scroll,
+     * by scrolling up with their mouse.
+     */
+    ignoreEscapes?: boolean;
+    /**
+     * Only scroll to the bottom if we're already at the bottom.
+     *
+     * @default false
+     */
+    preserveScrollPosition?: boolean;
+    /**
+     * The extra duration in ms that this scroll event should persist for.
+     * (in addition to the time that it takes to get to the bottom)
+     *
+     * Not to be confused with the duration of the animation -
+     * for that you should adjust the animation option.
+     *
+     * @default 0
+     */
+    duration?: number | Promise<void>;
+};
+export type ScrollToBottom = (scrollOptions?: ScrollToBottomOptions) => Promise<boolean> | boolean;
+export type StopScroll = () => void;
+export declare const useStickToBottom: (options?: StickToBottomOptions) => StickToBottomInstance;
+export interface StickToBottomInstance {
+    contentRef: React.MutableRefObject<HTMLElement | null> & React.RefCallback<HTMLElement>;
+    scrollRef: React.MutableRefObject<HTMLElement | null> & React.RefCallback<HTMLElement>;
+    scrollToBottom: ScrollToBottom;
+    stopScroll: StopScroll;
+    isAtBottom: boolean;
+    isNearBottom: boolean;
+    escapedFromLock: boolean;
+    state: StickToBottomState;
+}
+export {};

package/dist/useStickToBottom.js

@@ -0,0 +1,425 @@
+/*!---------------------------------------------------------------------------------------------
+ *  Copyright (c) StackBlitz. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+import { useCallback, useMemo, useRef, useState, } from "react";
+const DEFAULT_SPRING_ANIMATION = {
+    /**
+     * A value from 0 to 1, on how much to damp the animation.
+     * 0 means no damping, 1 means full damping.
+     *
+     * @default 0.7
+     */
+    damping: 0.7,
+    /**
+     * The stiffness of how fast/slow the animation gets up to speed.
+     *
+     * @default 0.05
+     */
+    stiffness: 0.05,
+    /**
+     * The inertial mass associated with the animation.
+     * Higher numbers make the animation slower.
+     *
+     * @default 1.25
+     */
+    mass: 1.25,
+};
+const STICK_TO_BOTTOM_OFFSET_PX = 70;
+const SIXTY_FPS_INTERVAL_MS = 1000 / 60;
+const RETAIN_ANIMATION_DURATION_MS = 350;
+let mouseDown = false;
+globalThis.document?.addEventListener("mousedown", () => {
+    mouseDown = true;
+});
+globalThis.document?.addEventListener("mouseup", () => {
+    mouseDown = false;
+});
+globalThis.document?.addEventListener("click", () => {
+    mouseDown = false;
+});
+export const useStickToBottom = (options = {}) => {
+    const [escapedFromLock, updateEscapedFromLock] = useState(false);
+    const [isAtBottom, updateIsAtBottom] = useState(options.initial !== false);
+    const [isNearBottom, setIsNearBottom] = useState(false);
+    const optionsRef = useRef(null);
+    optionsRef.current = options;
+    const isSelecting = useCallback(() => {
+        if (!mouseDown) {
+            return false;
+        }
+        const selection = window.getSelection();
+        if (!selection || !selection.rangeCount) {
+            return false;
+        }
+        const range = selection.getRangeAt(0);
+        return (range.commonAncestorContainer.contains(scrollRef.current) ||
+            scrollRef.current?.contains(range.commonAncestorContainer));
+    }, []);
+    const setIsAtBottom = useCallback((isAtBottom) => {
+        state.isAtBottom = isAtBottom;
+        updateIsAtBottom(isAtBottom);
+    }, []);
+    const setEscapedFromLock = useCallback((escapedFromLock) => {
+        state.escapedFromLock = escapedFromLock;
+        updateEscapedFromLock(escapedFromLock);
+    }, []);
+    // biome-ignore lint/correctness/useExhaustiveDependencies: not needed
+    const state = useMemo(() => {
+        let lastCalculation;
+        return {
+            escapedFromLock,
+            isAtBottom,
+            resizeDifference: 0,
+            accumulated: 0,
+            velocity: 0,
+            listeners: new Set(),
+            get scrollTop() {
+                return scrollRef.current?.scrollTop ?? 0;
+            },
+            set scrollTop(scrollTop) {
+                if (scrollRef.current) {
+                    // Override CSS scroll-behavior so programmatic scrollTop
+                    // assignments take effect immediately and aren't intercepted
+                    // by the browser's smooth scrolling.
+                    const { scrollBehavior } = getComputedStyle(scrollRef.current);
+                    if (scrollBehavior !== "auto") {
+                        scrollRef.current.style.scrollBehavior = "auto";
+                    }
+                    scrollRef.current.scrollTop = scrollTop;
+                    state.ignoreScrollToTop = scrollRef.current.scrollTop;
+                    if (scrollBehavior !== "auto") {
+                        scrollRef.current.style.scrollBehavior = scrollBehavior;
+                    }
+                }
+            },
+            get targetScrollTop() {
+                if (!scrollRef.current || !contentRef.current) {
+                    return 0;
+                }
+                return (scrollRef.current.scrollHeight - 1 - scrollRef.current.clientHeight);
+            },
+            get calculatedTargetScrollTop() {
+                if (!scrollRef.current || !contentRef.current) {
+                    return 0;
+                }
+                const { targetScrollTop } = this;
+                if (!options.targetScrollTop) {
+                    return targetScrollTop;
+                }
+                if (lastCalculation?.targetScrollTop === targetScrollTop) {
+                    return lastCalculation.calculatedScrollTop;
+                }
+                const calculatedScrollTop = Math.max(Math.min(options.targetScrollTop(targetScrollTop, {
+                    scrollElement: scrollRef.current,
+                    contentElement: contentRef.current,
+                }), targetScrollTop), 0);
+                lastCalculation = { targetScrollTop, calculatedScrollTop };
+                requestAnimationFrame(() => {
+                    lastCalculation = undefined;
+                });
+                return calculatedScrollTop;
+            },
+            get scrollDifference() {
+                return this.calculatedTargetScrollTop - this.scrollTop;
+            },
+            get isNearBottom() {
+                return this.scrollDifference <= STICK_TO_BOTTOM_OFFSET_PX;
+            },
+        };
+    }, []);
+    const scrollToBottom = useCallback((scrollOptions = {}) => {
+        if (typeof scrollOptions === "string") {
+            scrollOptions = { animation: scrollOptions };
+        }
+        if (!scrollOptions.preserveScrollPosition) {
+            setIsAtBottom(true);
+        }
+        const waitElapsed = Date.now() + (Number(scrollOptions.wait) || 0);
+        const behavior = mergeAnimations(optionsRef.current, scrollOptions.animation);
+        const { ignoreEscapes = false } = scrollOptions;
+        let durationElapsed;
+        let startTarget = state.calculatedTargetScrollTop;
+        if (scrollOptions.duration instanceof Promise) {
+            scrollOptions.duration.finally(() => {
+                durationElapsed = Date.now();
+            });
+        }
+        else {
+            durationElapsed = waitElapsed + (scrollOptions.duration ?? 0);
+        }
+        const next = async () => {
+            const promise = new Promise(requestAnimationFrame).then(() => {
+                if (!state.isAtBottom) {
+                    state.animation = undefined;
+                    return false;
+                }
+                const { scrollTop } = state;
+                const tick = performance.now();
+                const tickDelta = (tick - (state.lastTick ?? tick)) / SIXTY_FPS_INTERVAL_MS;
+                state.animation || (state.animation = { behavior, promise, ignoreEscapes });
+                if (state.animation.behavior === behavior) {
+                    state.lastTick = tick;
+                }
+                if (isSelecting()) {
+                    return next();
+                }
+                if (waitElapsed > Date.now()) {
+                    return next();
+                }
+                if (scrollTop < Math.min(startTarget, state.calculatedTargetScrollTop)) {
+                    if (state.animation?.behavior === behavior) {
+                        if (behavior === "instant") {
+                            state.scrollTop = state.calculatedTargetScrollTop;
+                            return next();
+                        }
+                        state.velocity =
+                            (behavior.damping * state.velocity +
+                                behavior.stiffness * state.scrollDifference) /
+                                behavior.mass;
+                        state.accumulated += state.velocity * tickDelta;
+                        state.scrollTop += state.accumulated;
+                        if (state.scrollTop !== scrollTop) {
+                            state.accumulated = 0;
+                        }
+                    }
+                    return next();
+                }
+                if (durationElapsed > Date.now()) {
+                    startTarget = state.calculatedTargetScrollTop;
+                    return next();
+                }
+                state.animation = undefined;
+                /**
+                 * If we're still below the target, then queue
+                 * up another scroll to the bottom with the last
+                 * requested animation.
+                 */
+                if (state.scrollTop < state.calculatedTargetScrollTop) {
+                    if (optionsRef.current.resize === false) {
+                        return state.isNearBottom;
+                    }
+                    return scrollToBottom({
+                        animation: mergeAnimations(optionsRef.current, optionsRef.current.resize),
+                        ignoreEscapes,
+                        duration: Math.max(0, durationElapsed - Date.now()) || undefined,
+                    });
+                }
+                return state.isAtBottom;
+            });
+            return promise.then((isAtBottom) => {
+                requestAnimationFrame(() => {
+                    if (!state.animation) {
+                        state.lastTick = undefined;
+                        state.velocity = 0;
+                    }
+                });
+                return isAtBottom;
+            });
+        };
+        if (scrollOptions.wait !== true) {
+            state.animation = undefined;
+        }
+        if (state.animation?.behavior === behavior) {
+            return state.animation.promise;
+        }
+        return next();
+    }, [setIsAtBottom, isSelecting, state]);
+    const stopScroll = useCallback(() => {
+        setEscapedFromLock(true);
+        setIsAtBottom(false);
+    }, [setEscapedFromLock, setIsAtBottom]);
+    const handleScroll = useCallback(({ target }) => {
+        if (target !== scrollRef.current) {
+            return;
+        }
+        const { scrollTop, ignoreScrollToTop } = state;
+        let { lastScrollTop = scrollTop } = state;
+        state.lastScrollTop = scrollTop;
+        state.ignoreScrollToTop = undefined;
+        if (ignoreScrollToTop && ignoreScrollToTop > scrollTop) {
+            /**
+             * When the user scrolls up while the animation plays, the `scrollTop` may
+             * not come in separate events; if this happens, to make sure `isScrollingUp`
+             * is correct, set the lastScrollTop to the ignored event.
+             */
+            lastScrollTop = ignoreScrollToTop;
+        }
+        setIsNearBottom(state.isNearBottom);
+        /**
+         * Scroll events may come before a ResizeObserver event,
+         * so in order to ignore resize events correctly we use a
+         * timeout.
+         *
+         * @see https://github.com/WICG/resize-observer/issues/25#issuecomment-248757228
+         */
+        setTimeout(() => {
+            /**
+             * When theres a resize difference ignore the resize event.
+             */
+            if (state.resizeDifference || scrollTop === ignoreScrollToTop) {
+                return;
+            }
+            if (isSelecting()) {
+                setEscapedFromLock(true);
+                setIsAtBottom(false);
+                return;
+            }
+            const isScrollingDown = scrollTop > lastScrollTop;
+            const isScrollingUp = scrollTop < lastScrollTop;
+            if (state.animation?.ignoreEscapes) {
+                state.scrollTop = lastScrollTop;
+                return;
+            }
+            if (isScrollingUp) {
+                setEscapedFromLock(true);
+                setIsAtBottom(false);
+            }
+            if (isScrollingDown) {
+                setEscapedFromLock(false);
+            }
+            if (!state.escapedFromLock && state.isNearBottom) {
+                setIsAtBottom(true);
+            }
+        }, 1);
+    }, [setEscapedFromLock, setIsAtBottom, isSelecting, state]);
+    const handleWheel = useCallback(({ target, deltaY }) => {
+        let element = target;
+        while (!["scroll", "auto"].includes(getComputedStyle(element).overflow)) {
+            if (!element.parentElement) {
+                return;
+            }
+            element = element.parentElement;
+        }
+        /**
+         * The browser may cancel the scrolling from the mouse wheel
+         * if we update it from the animation in meantime.
+         * To prevent this, always escape when the wheel is scrolled up.
+         */
+        if (element === scrollRef.current &&
+            deltaY < 0 &&
+            scrollRef.current.scrollHeight > scrollRef.current.clientHeight &&
+            !state.animation?.ignoreEscapes) {
+            setEscapedFromLock(true);
+            setIsAtBottom(false);
+        }
+    }, [setEscapedFromLock, setIsAtBottom, state]);
+    const scrollRef = useRefCallback((scroll) => {
+        scrollRef.current?.removeEventListener("scroll", handleScroll);
+        scrollRef.current?.removeEventListener("wheel", handleWheel);
+        scroll?.addEventListener("scroll", handleScroll, { passive: true });
+        scroll?.addEventListener("wheel", handleWheel, { passive: true });
+    }, []);
+    const contentRef = useRefCallback((content) => {
+        state.resizeObserver?.disconnect();
+        state.resizeObserver = undefined;
+        if (!content) {
+            return;
+        }
+        let previousHeight;
+        state.resizeObserver = new ResizeObserver(([entry]) => {
+            const { height } = entry.contentRect;
+            const difference = height - (previousHeight ?? height);
+            state.resizeDifference = difference;
+            /**
+             * Sometimes the browser can overscroll past the target,
+             * so check for this and adjust appropriately.
+             */
+            if (state.scrollTop > state.targetScrollTop) {
+                state.scrollTop = state.targetScrollTop;
+            }
+            setIsNearBottom(state.isNearBottom);
+            if (difference >= 0) {
+                /**
+                 * If it's a positive resize, scroll to the bottom when
+                 * we're already at the bottom.
+                 */
+                const resize = previousHeight
+                    ? optionsRef.current.resize
+                    : optionsRef.current.initial;
+                if (resize === false) {
+                    setIsAtBottom(state.isNearBottom);
+                }
+                else {
+                    const animation = mergeAnimations(optionsRef.current, resize);
+                    scrollToBottom({
+                        animation,
+                        wait: true,
+                        preserveScrollPosition: true,
+                        duration: animation === "instant"
+                            ? undefined
+                            : RETAIN_ANIMATION_DURATION_MS,
+                    });
+                }
+            }
+            else {
+                /**
+                 * Else if it's a negative resize, check if we're near the bottom
+                 * if we are want to un-escape from the lock, because the resize
+                 * could have caused the container to be at the bottom.
+                 */
+                if (state.isNearBottom) {
+                    setEscapedFromLock(false);
+                    setIsAtBottom(true);
+                }
+            }
+            previousHeight = height;
+            /**
+             * Reset the resize difference after the scroll event
+             * has fired. Requires a rAF to wait for the scroll event,
+             * and a setTimeout to wait for the other timeout we have in
+             * resizeObserver in case the scroll event happens after the
+             * resize event.
+             */
+            requestAnimationFrame(() => {
+                setTimeout(() => {
+                    if (state.resizeDifference === difference) {
+                        state.resizeDifference = 0;
+                    }
+                }, 1);
+            });
+        });
+        state.resizeObserver?.observe(content);
+    }, []);
+    return {
+        contentRef,
+        scrollRef,
+        scrollToBottom,
+        stopScroll,
+        isAtBottom: isAtBottom || isNearBottom,
+        isNearBottom,
+        escapedFromLock,
+        state,
+    };
+};
+function useRefCallback(callback, deps) {
+    // biome-ignore lint/correctness/useExhaustiveDependencies: not needed
+    const result = useCallback((ref) => {
+        result.current = ref;
+        return callback(ref);
+    }, deps);
+    return result;
+}
+const animationCache = new Map();
+function mergeAnimations(...animations) {
+    const result = { ...DEFAULT_SPRING_ANIMATION };
+    let instant = false;
+    for (const animation of animations) {
+        if (animation === "instant") {
+            instant = true;
+            continue;
+        }
+        if (typeof animation !== "object") {
+            continue;
+        }
+        instant = false;
+        result.damping = animation.damping ?? result.damping;
+        result.stiffness = animation.stiffness ?? result.stiffness;
+        result.mass = animation.mass ?? result.mass;
+    }
+    const key = JSON.stringify(result);
+    if (!animationCache.has(key)) {
+        animationCache.set(key, Object.freeze(result));
+    }
+    return instant ? "instant" : animationCache.get(key);
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "use-stick-to-bottom-extended",
+  "author": "Sam Denty <samddenty@gmail.com> (https://samdenty.io/)",
+  "contributors": [
+    {
+      "name": "duz52",
+      "url": "https://github.com/duz52/"
+    }
+  ],
+  "description": "A lightweight React Hook intended mainly for AI chat applications, with optional resize auto-scroll control",
+  "homepage": "https://github.com/duz52/use-stick-to-bottom-extended#readme",
+  "private": false,
+  "version": "1.2.0",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/samdenty"
+    }
+  ],
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "scripts": {
+    "dev": "vite",
+    "build": "rm -rf dist > /dev/null 2>&1; tsc -b",
+    "prepublishOnly": "pnpm build",
+    "lint": "biome check",
+    "lint:fix": "pnpm lint --write"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/duz52/use-stick-to-bottom-extended.git"
+  },
+  "bugs": {
+    "url": "https://github.com/duz52/use-stick-to-bottom-extended/issues"
+  },
+  "peerDependencies": {
+    "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@egoist/tailwindcss-icons": "^1.8.1",
+    "@iconify-json/ph": "^1.2.0",
+    "@tailwindcss/typography": "^0.5.15",
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.3.1",
+    "autoprefixer": "^10.4.20",
+    "globals": "^15.9.0",
+    "lorem-ipsum": "^2.0.8",
+    "postcss": "^8.4.45",
+    "react": "^16.8.0 || ^17.0.0 || ^18.0.0",
+    "react-dom": "^18.0.0",
+    "tailwindcss": "^3.4.10",
+    "typescript": "^5.5.3",
+    "vite": "^5.4.1",
+    "vite-plugin-dts": "^4.2.1",
+    "@biomejs/biome": "^1.9.4"
+  },
+  "packageManager": "pnpm@9.12.3+sha512.cce0f9de9c5a7c95bef944169cc5dfe8741abfb145078c0d508b868056848a87c81e626246cb60967cbd7fd29a6c062ef73ff840d96b3c86c40ac92cf4a813ee"
+}