@octanejs/stick-to-bottom 0.0.1

package/LICENSE

@@ -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,21 @@
+# @octanejs/stick-to-bottom
+
+Octane binding for [`use-stick-to-bottom@1.1.6`](https://github.com/stackblitz/use-stick-to-bottom).
+
+```tsrx
+import { StickToBottom } from '@octanejs/stick-to-bottom';
+
+export function Transcript(props: { messages: string[] }) @{
+	<StickToBottom>
+		<StickToBottom.Content>
+			@for (const message of props.messages; key message) {
+				<p>{message}</p>
+			}
+		</StickToBottom.Content>
+	</StickToBottom>
+}
+```
+
+Nested TSRX children render normally. Function children remain render props and receive the stick-to-bottom context.
+
+See [UPSTREAM.md](./UPSTREAM.md).

package/UPSTREAM.md

@@ -0,0 +1,45 @@
+# Upstream provenance
+
+`@octanejs/stick-to-bottom` is pinned to `use-stick-to-bottom@1.1.6`.
+
+- repository: https://github.com/stackblitz/use-stick-to-bottom
+- tag: `1.1.6`
+- tag commit: `8d6a19a0ca6ab632830588073e6a29312a06a088` (npm tarball had no `gitHead`; SHA is the tagged commit)
+- advertised range: `1.1.x`
+- license: MIT
+- npm integrity: `sha512-z3Up8jYQGTkUCsGBnwg6/wj70KgXoW5Kz1AAc1j8MtQuYMBo6ZsdhrIXoegxa7gaMMilgQYyTohTrt3p94jHog==`
+- npm shasum: `c35e7f9bcb1ee3da0c059c448fb9a61bdf01fe6b`
+
+## Source boundary
+
+- `upstream/src/` is the canonical tagged source (`useStickToBottom.ts`, `StickToBottom.tsx`, `index.ts`), LICENSE, README, CHANGELOG, and tsconfig.
+- `upstream/npm/` is the published tarball (compiled `dist/`).
+- Octane `src/` mirrors `upstream/src/`.
+
+Vendored evidence is development-only and excluded from package `files`.
+
+## Export crosswalk
+
+| Upstream export | Octane status | Evidence / divergence |
+| --- | --- | --- |
+| `useStickToBottom` | Ported | `src/useStickToBottom.ts`; upstream logic retained with structural ref types and explicit hook-slot forwarding; `tests/stick-to-bottom.test.ts` |
+| `StickToBottom` | Ported | `src/StickToBottom.tsrx` |
+| `StickToBottom.Content` | Ported | Assigned as `StickToBottom.Content` |
+| `useStickToBottomContext` | Ported | throws outside provider; `tests/stick-to-bottom.test.ts` |
+| `StickToBottomState` / options / instance types | Ported | `src/useStickToBottom.ts` |
+
+## Upstream test disposition
+
+| Upstream artifact | Disposition |
+| --- | --- |
+| package scripts (`dev`, `build`, `lint`; no `test`) | Confirmed at pin: the repository has no unit test suite |
+| Demo / playground | Out of scope |
+
+Octane behavioral coverage is `tests/stick-to-bottom.test.ts`. It is Octane-only because upstream ships no tests.
+
+## Intentional divergences
+
+- React ref types are structural.
+- The plain TypeScript hook accepts and forwards a compiler-injected trailing
+  slot; when called without options, a symbol in the options position is
+  treated as empty options.

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@octanejs/stick-to-bottom",
+  "version": "0.0.1",
+  "description": "Octane binding for use-stick-to-bottom 1.1.6.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22.22.2"
+  },
+  "octane": {
+    "hookSlots": {
+      "manual": [
+        "src/useStickToBottom.ts"
+      ]
+    }
+  },
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/stick-to-bottom"
+  },
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "src",
+    "README.md",
+    "UPSTREAM.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "octane": "0.1.45"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.10",
+    "@octanejs/testing-library": "0.1.42",
+    "octane": "0.1.45"
+  },
+  "scripts": {
+    "test": "vitest run --root ../.. --config vitest.config.js --project stick-to-bottom",
+    "typecheck": "tsrx-tsc --noEmit"
+  }
+}

package/src/StickToBottom.tsrx

@@ -0,0 +1,173 @@
+/*!---------------------------------------------------------------------------------------------
+ *  Copyright (c) StackBlitz. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+import {
+	type OctaneNode,
+	createContext,
+	isChildrenBlock,
+	useCallback,
+	useContext,
+	useEffect,
+	useImperativeHandle,
+	useLayoutEffect,
+	useMemo,
+	useRef,
+} from 'octane';
+import {
+	type GetTargetScrollTop,
+	type StickToBottomInstance,
+	type StickToBottomOptions,
+	type StickToBottomState,
+	type ScrollToBottom,
+	type StopScroll,
+	useStickToBottom,
+} from './useStickToBottom';
+
+type DivProps = import('octane/jsx-runtime').Octane.JSX.IntrinsicElements['div'];
+
+export interface StickToBottomContext {
+	contentRef: StickToBottomInstance['contentRef'];
+	scrollRef: StickToBottomInstance['scrollRef'];
+	scrollToBottom: ScrollToBottom;
+	stopScroll: StopScroll;
+	isAtBottom: boolean;
+	escapedFromLock: boolean;
+	get targetScrollTop(): GetTargetScrollTop | null;
+	set targetScrollTop(targetScrollTop: GetTargetScrollTop | null);
+	state: StickToBottomState;
+}
+
+const StickToBottomContext = createContext<StickToBottomContext | null>(null);
+
+type StickToBottomContextRef =
+	{ current: StickToBottomContext | null } | ((value: StickToBottomContext | null) => void);
+
+export interface StickToBottomProps extends Omit<DivProps, 'children'>, StickToBottomOptions {
+	contextRef?: StickToBottomContextRef;
+	instance?: StickToBottomInstance;
+	children: ((context: StickToBottomContext) => OctaneNode) | OctaneNode;
+}
+
+const useIsomorphicLayoutEffect =
+	typeof window !== 'undefined' ? useLayoutEffect : useEffect;
+
+export function StickToBottom({
+	instance,
+	children,
+	resize,
+	initial,
+	mass,
+	damping,
+	stiffness,
+	targetScrollTop: currentTargetScrollTop,
+	contextRef,
+	...props
+}: StickToBottomProps) {
+	const customTargetScrollTop = useRef<GetTargetScrollTop | null>(null);
+
+	const targetScrollTop = useCallback<GetTargetScrollTop>(
+		function getTargetScrollTop(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(function createContextValue(): StickToBottomContext {
+		return {
+			scrollToBottom,
+			stopScroll,
+			scrollRef,
+			isAtBottom,
+			escapedFromLock,
+			contentRef,
+			state,
+			get targetScrollTop() {
+				return customTargetScrollTop.current;
+			},
+			set targetScrollTop(next: GetTargetScrollTop | null) {
+				customTargetScrollTop.current = next;
+			},
+		};
+	}, [
+		scrollToBottom,
+		isAtBottom,
+		contentRef,
+		scrollRef,
+		stopScroll,
+		escapedFromLock,
+		state,
+	]);
+
+	useImperativeHandle(contextRef, function getContext() {
+		return context;
+	}, [context]);
+
+	useIsomorphicLayoutEffect(function ensureOverflow() {
+		if (!scrollRef.current) {
+			return;
+		}
+
+		if (getComputedStyle(scrollRef.current).overflow === 'visible') {
+			scrollRef.current.style.overflow = 'auto';
+		}
+	}, []);
+
+	return <StickToBottomContext.Provider value={context}>
+		<div {...props}>
+			{typeof children === 'function' && !isChildrenBlock(children) ? children(context) : children}
+		</div>
+	</StickToBottomContext.Provider>;
+}
+
+export interface StickToBottomContentProps extends Omit<DivProps, 'children'> {
+	children: ((context: StickToBottomContext) => OctaneNode) | OctaneNode;
+	scrollClassName?: string;
+}
+
+export function StickToBottomContent({
+	children,
+	scrollClassName,
+	...props
+}: StickToBottomContentProps) {
+	const context = useStickToBottomContext();
+
+	return <div
+		ref={context.scrollRef}
+		style={{
+			height: '100%',
+			width: '100%',
+			scrollbarGutter: 'stable both-edges',
+		}}
+		className={scrollClassName}
+	>
+		<div {...props} ref={context.contentRef}>
+			{typeof children === 'function' && !isChildrenBlock(children) ? children(context) : children}
+		</div>
+	</div>;
+}
+
+StickToBottom.Content = StickToBottomContent;
+
+export function useStickToBottomContext(): StickToBottomContext {
+	const context = useContext(StickToBottomContext);
+	if (!context) {
+		throw new Error('use-stick-to-bottom component context must be used within a StickToBottom component');
+	}
+
+	return context;
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './useStickToBottom';
+export * from './StickToBottom.tsrx';

package/src/useStickToBottom.ts

@@ -0,0 +1,708 @@
+/*!---------------------------------------------------------------------------------------------
+ *  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 'octane';
+
+type DependencyList = readonly unknown[];
+type RefCallback<T> = (instance: T | null) => void;
+type MutableRefObject<T> = { current: T };
+
+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;
+}
+
+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,
+};
+
+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;
+	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;
+
+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 function useStickToBottom(options?: StickToBottomOptions): StickToBottomInstance;
+export function useStickToBottom(
+	options: StickToBottomOptions | symbol = {},
+	...rest: [slot?: symbol]
+): StickToBottomInstance {
+	const slot = typeof options === 'symbol' ? options : rest[0];
+	options = typeof options === 'symbol' ? {} : options;
+	const [escapedFromLock, updateEscapedFromLock] = useState(
+		false,
+		subSlot(slot, 'escaped-from-lock'),
+	);
+	const [isAtBottom, updateIsAtBottom] = useState(
+		options.initial !== false,
+		subSlot(slot, 'at-bottom'),
+	);
+	const [isNearBottom, setIsNearBottom] = useState(false, subSlot(slot, 'near-bottom'));
+
+	const optionsRef = useRef<StickToBottomOptions>(null!, subSlot(slot, 'options'));
+	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)
+			);
+		},
+		[],
+		subSlot(slot, 'is-selecting'),
+	);
+
+	const setIsAtBottom = useCallback(
+		(isAtBottom: boolean) => {
+			state.isAtBottom = isAtBottom;
+			updateIsAtBottom(isAtBottom);
+		},
+		[],
+		subSlot(slot, 'set-at-bottom'),
+	);
+
+	const setEscapedFromLock = useCallback(
+		(escapedFromLock: boolean) => {
+			state.escapedFromLock = escapedFromLock;
+			updateEscapedFromLock(escapedFromLock);
+		},
+		[],
+		subSlot(slot, 'set-escaped-from-lock'),
+	);
+
+	// biome-ignore lint/correctness/useExhaustiveDependencies: not needed
+	const state = useMemo<StickToBottomState>(
+		() => {
+			let lastCalculation: { targetScrollTop: number; calculatedScrollTop: number } | undefined;
+
+			return {
+				escapedFromLock,
+				isAtBottom,
+				resizeDifference: 0,
+				accumulated: 0,
+				velocity: 0,
+				listeners: new Set(),
+
+				get scrollTop() {
+					return scrollRef.current?.scrollTop ?? 0;
+				},
+				set scrollTop(scrollTop: number) {
+					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;
+				},
+			};
+		},
+		[],
+		subSlot(slot, 'state'),
+	);
+
+	const scrollToBottom = useCallback<ScrollToBottom>(
+		(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: number;
+			let startTarget = state.calculatedTargetScrollTop;
+
+			if (scrollOptions.duration instanceof Promise) {
+				scrollOptions.duration.finally(() => {
+					durationElapsed = Date.now();
+				});
+			} else {
+				durationElapsed = waitElapsed + (scrollOptions.duration ?? 0);
+			}
+
+			const next = async (): Promise<boolean> => {
+				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 ||= { 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) {
+						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],
+		subSlot(slot, 'scroll-to-bottom'),
+	);
+
+	const stopScroll = useCallback(
+		(): void => {
+			setEscapedFromLock(true);
+			setIsAtBottom(false);
+		},
+		[setEscapedFromLock, setIsAtBottom],
+		subSlot(slot, 'stop-scroll'),
+	);
+
+	const handleScroll = useCallback(
+		({ target }: Event) => {
+			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],
+		subSlot(slot, 'handle-scroll'),
+	);
+
+	const handleWheel = useCallback(
+		({ target, deltaY }: WheelEvent) => {
+			let element = target as HTMLElement;
+
+			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],
+		subSlot(slot, 'handle-wheel'),
+	);
+
+	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 });
+		},
+		[],
+		subSlot(slot, 'scroll-ref'),
+	);
+
+	const contentRef = useRefCallback(
+		(content) => {
+			state.resizeObserver?.disconnect();
+			state.resizeObserver = undefined;
+
+			if (!content) {
+				return;
+			}
+
+			let previousHeight: number | undefined;
+
+			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 animation = mergeAnimations(
+						optionsRef.current,
+						previousHeight ? optionsRef.current.resize : optionsRef.current.initial,
+					);
+
+					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);
+		},
+		[],
+		subSlot(slot, 'content-ref'),
+	);
+
+	return {
+		contentRef,
+		scrollRef,
+		scrollToBottom,
+		stopScroll,
+		isAtBottom: isAtBottom || isNearBottom,
+		isNearBottom,
+		escapedFromLock,
+		state,
+	};
+}
+
+export interface StickToBottomInstance {
+	contentRef: MutableRefObject<HTMLElement | null> & RefCallback<HTMLElement>;
+	scrollRef: MutableRefObject<HTMLElement | null> & RefCallback<HTMLElement>;
+	scrollToBottom: ScrollToBottom;
+	stopScroll: StopScroll;
+	isAtBottom: boolean;
+	isNearBottom: boolean;
+	escapedFromLock: boolean;
+	state: StickToBottomState;
+}
+
+function useRefCallback<T extends (ref: HTMLElement | null) => any>(
+	callback: T,
+	deps: DependencyList,
+	slot: symbol,
+) {
+	// biome-ignore lint/correctness/useExhaustiveDependencies: not needed
+	const result = useCallback(
+		(ref: HTMLElement | null) => {
+			result.current = ref;
+			return callback(ref);
+		},
+		deps as unknown[],
+		slot,
+	) as any as MutableRefObject<HTMLElement | null> & RefCallback<HTMLElement>;
+
+	return result;
+}
+
+const animationCache = new Map<string, Readonly<Required<SpringAnimation>>>();
+
+function mergeAnimations(...animations: (Animation | boolean | undefined)[]) {
+	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)!;
+}
+
+const subSlotCache = new Map<symbol, Map<string, symbol>>();
+const bareSlotCache = new Map<string, symbol>();
+
+function subSlot(slot: symbol | undefined, tag: string): symbol {
+	if (slot === undefined) {
+		let bare = bareSlotCache.get(tag);
+		if (bare === undefined) {
+			bare = Symbol.for(`@octanejs/stick-to-bottom:${tag}`);
+			bareSlotCache.set(tag, bare);
+		}
+		return bare;
+	}
+
+	let children = subSlotCache.get(slot);
+	if (children === undefined) {
+		children = new Map();
+		subSlotCache.set(slot, children);
+	}
+
+	let child = children.get(tag);
+	if (child === undefined) {
+		child = Symbol.for(`${slot.description ?? ''}:stick-to-bottom:${tag}`);
+		children.set(tag, child);
+	}
+	return child;
+}