Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
15.0 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

/**
 * @file useChatStreamScroll.ts
 * @input Uses React refs, state, callbacks, useMediaQuery, and the input
 *   stream's document scroll events when the page itself scrolls
 * @output Exports useChatStreamScroll hook for AI chat scroll behavior
 * @position Utility hook — used by ChatLayout, also usable standalone
 *
 * Spring-based scroll-to-bottom with lock/unlock:
 * - Locked (default): content growth auto-scrolls to bottom via rAF spring
 * - Scrolling up (any source): unlocks immediately
 * - Scrolling settles at bottom: re-locks on scrollend
 * - The first fill positions instantly (whether content is present at
 *   mount or arrives async); only subsequent growth springs
 * - `scrollToBottom({behavior: 'instant'})` jumps in one frame, no animation
 * - Under `prefers-reduced-motion`, every spring path falls back to the
 *   same instant jump — following still works, it just doesn't animate
 * - Fractional spring position is retained between frames so browsers that
 *   round scrollTop do not strand the animation short of the bottom
 *
 * Reads user intent from position: a scroll that lands above the last
 * position this hook set or saw is the reader — wheel, touch, scrollbar
 * drag, keyboard, everything, including a move the spring's next frame
 * would otherwise outrun. While following, the hook owns the position:
 * it disables scroll anchoring on the container, so the only move the
 * browser makes on its own is a resize clamp onto the bottom.
 *
 * SYNC: When modified, update:
 * - /packages/core/src/Chat/index.ts (exports)
 */

import {useCallback, useEffect, useRef, useState} from 'react';
import {useMediaQuery} from '../hooks/useMediaQuery';
import {setScrollAnchoringOff} from '../privateAttributes/scrollAnchoring.stylex';
import {subscribeInput} from '../utils/inputStream';

// =============================================================================
// Types
// =============================================================================

export interface ChatScrollToBottomOptions {
  /**
   * `'instant'` jumps to the bottom in a single frame instead of running
   * the spring animation. Use for programmatic positioning (opening a
   * conversation, restoring a session) — keep the default `'spring'` for
   * user-initiated scrolls like the scroll-to-bottom button. Mirrors the
   * DOM's `scrollTo({behavior})`. When the user prefers reduced motion,
   * `'spring'` also jumps instantly.
   * @default 'spring'
   */
  behavior?: 'instant' | 'spring';
}

export interface UseChatStreamScrollOptions {
  /**
   * Ref to the scrollable container element.
   */
  scrollRef: React.RefObject<HTMLElement | null>;

  /**
   * Whether scroll behavior is enabled.
   * @default true
   */
  enabled?: boolean;

  /**
   * Distance from bottom (in px) within which scrollend re-locks.
   * Keep small so users aren't yanked back from a slight scroll.
   * @default 10
   */
  lockThreshold?: number;

  /**
   * Distance from bottom (in px) beyond which the scroll-to-bottom
   * button becomes visible.
   * @default 100
   */
  buttonThreshold?: number;

  /**
   * Spring damping — how quickly the animation settles.
   * @default 0.7
   */
  damping?: number;

  /**
   * Spring stiffness — how fast the animation accelerates.
   * @default 0.05
   */
  stiffness?: number;

  /**
   * Spring mass — higher = slower animation.
   * @default 1.25
   */
  mass?: number;
}

export interface UseChatStreamScrollReturn {
  /** Whether the user has scrolled up past buttonThreshold. */
  isScrolledUp: boolean;

  /** Whether auto-scroll is locked (following content). */
  isLocked: boolean;

  /** Scroll to the bottom of the container and re-lock. */
  scrollToBottom: (options?: ChatScrollToBottomOptions) => void;

  /** Scroll so a specific element is at the top of the visible area. No lock change. */
  scrollToMessage: (el: HTMLElement) => void;

  /** Lock auto-scroll and scroll to bottom. */
  lock: () => void;

  /** Unlock auto-scroll. */
  unlock: () => void;

  /** Scroll to bottom if currently locked. Call on content resize. */
  scrollIfLocked: () => void;

  /** Scroll to the last message in the container. */
  scrollToLastMessage: () => void;
}

// =============================================================================
// Hook
// =============================================================================

const SIXTY_FPS_MS = 1000 / 60;

// The scrollers whose hook follows the newest message now, kept in step with
// each hook's lock.
const following = new WeakSet<Element>();

/**
 * Whether the stream scroll on `scroller` follows its newest message now, as
 * its lock says. Internal to Chat.
 */
export function isFollowingNewest(scroller: Element): boolean {
  return following.has(scroller);
}

// The lock's marks on the scroller: anchoring off while the hook follows, and
// the state `isFollowingNewest` reads.
function markFollowing(el: Element, locked: boolean): void {
  setScrollAnchoringOff(el, locked);
  if (locked) {
    following.add(el);
  } else {
    following.delete(el);
  }
}

// The page's scroll fires at the document. The root's box moves up by that
// scroll.
function scrollsPage(el: HTMLElement): boolean {
  const doc = el.ownerDocument;
  return el === doc.scrollingElement || el === doc.documentElement;
}

export function useChatStreamScroll({
  scrollRef,
  enabled = true,
  lockThreshold = 10,
  buttonThreshold = 100,
  damping = 0.7,
  stiffness = 0.05,
  mass = 1.25,
}: UseChatStreamScrollOptions): UseChatStreamScrollReturn {
  const [isScrolledUp, setIsScrolledUp] = useState(false);
  const [isLocked, setIsLocked] = useState(true);

  const lockedRef = useRef(true);
  // True until the initial fill has been positioned — consumed by the first
  // scrollIfLocked that sees scrollable content.
  const initialFillPendingRef = useRef(true);
  const velocityRef = useRef(0);
  const springPositionRef = useRef<number | undefined>(undefined);
  const animatingRef = useRef(false);
  const lastTickRef = useRef<number | undefined>(undefined);
  // The spring's pending frame, so a jump can cancel it for real.
  const rafRef = useRef<number>(0);
  // The last position this hook set or saw. Updated by every write of ours
  // (spring frame, jump, scrollToMessage) as well as by every scroll event,
  // so a reader's move that lands between two spring frames still shows as
  // "above where we put it" even when the next frame's write outran it.
  const lastScrollTopRef = useRef(0);

  // While following, this hook is the only thing that should move the
  // container: scroll anchoring is off, so the browser's one remaining move
  // is the resize clamp onto the bottom, and every other upward move is the
  // reader. Unlocked, the element's own anchoring applies again — a reader up
  // in the history wants it when content above them changes.
  const setLocked = useCallback(
    (locked: boolean) => {
      lockedRef.current = locked;
      setIsLocked(locked);
      const el = scrollRef.current;
      if (el != null) {
        markFollowing(el, locked);
      }
    },
    [scrollRef],
  );

  // --- Spring animation ---

  const animate = useCallback(() => {
    const el = scrollRef.current;
    if (!el || !lockedRef.current) {
      animatingRef.current = false;
      lastTickRef.current = undefined;
      velocityRef.current = 0;
      return;
    }

    if (el.scrollHeight <= el.clientHeight) {
      animatingRef.current = false;
      lastTickRef.current = undefined;
      velocityRef.current = 0;
      return;
    }

    const target = el.scrollHeight - el.clientHeight;
    const position = Math.max(
      0,
      Math.min(target, springPositionRef.current ?? el.scrollTop),
    );
    const diff = target - position;

    if (Math.abs(diff) < 0.5 && Math.abs(velocityRef.current) < 0.1) {
      // eslint-disable-next-line react-compiler/react-compiler -- imperative DOM: scrollTop assignment
      el.scrollTop = target;
      animatingRef.current = false;
      lastTickRef.current = undefined;
      velocityRef.current = 0;
      return;
    }

    const now = performance.now();
    const tickDelta = lastTickRef.current
      ? (now - lastTickRef.current) / SIXTY_FPS_MS
      : 1;
    lastTickRef.current = now;

    velocityRef.current =
      (damping * velocityRef.current + stiffness * diff) / mass;
    springPositionRef.current = position + velocityRef.current * tickDelta;
    el.scrollTop = springPositionRef.current;
    lastScrollTopRef.current = el.scrollTop;

    rafRef.current = requestAnimationFrame(animate);
  }, [scrollRef, damping, stiffness, mass]);

  // Jump to the bottom in a single frame — cancels any in-flight spring so
  // a later animation tick can't fight the assignment.
  const jumpToBottom = useCallback(() => {
    const el = scrollRef.current;
    if (!el) {
      return;
    }
    cancelAnimationFrame(rafRef.current);
    animatingRef.current = false;
    velocityRef.current = 0;
    lastTickRef.current = undefined;
    el.scrollTop = el.scrollHeight - el.clientHeight;
    lastScrollTopRef.current = el.scrollTop;
  }, [scrollRef]);

  const prefersReducedMotion = useMediaQuery(
    '(prefers-reduced-motion: reduce)',
  );

  // Every spring entry point (scrollToBottom, lock, scrollIfLocked growth
  // follow) funnels through here, so this one branch covers them all.
  const startAnimation = useCallback(() => {
    if (!lockedRef.current) {
      return;
    }
    if (prefersReducedMotion) {
      jumpToBottom();
      return;
    }
    if (!animatingRef.current) {
      animatingRef.current = true;
      lastTickRef.current = undefined;
      springPositionRef.current = scrollRef.current?.scrollTop;
      rafRef.current = requestAnimationFrame(animate);
    }
  }, [animate, jumpToBottom, prefersReducedMotion, scrollRef]);

  // --- Public API ---

  const scrollToBottom = useCallback(
    (options?: ChatScrollToBottomOptions) => {
      setLocked(true);
      setIsScrolledUp(false);
      initialFillPendingRef.current = false;
      if (options?.behavior === 'instant') {
        jumpToBottom();
        return;
      }
      startAnimation();
    },
    [setLocked, startAnimation, jumpToBottom],
  );

  const scrollToMessage = useCallback(
    (el: HTMLElement) => {
      const container = scrollRef.current;
      if (!container) {
        return;
      }
      // The page's visible area starts at the viewport's top, not at the
      // root's box.
      const top = scrollsPage(container)
        ? 0
        : container.getBoundingClientRect().top;
      const offset = el.getBoundingClientRect().top - top + container.scrollTop;
      container.scrollTo({top: offset, behavior: 'instant'});
      lastScrollTopRef.current = container.scrollTop;
    },
    [scrollRef],
  );

  const scrollToLastMessage = useCallback(() => {
    const container = scrollRef.current;
    if (!container) {
      return;
    }
    const messages = container.getElementsByClassName('astryx-chat-message');
    const last = messages[messages.length - 1];
    if (last instanceof HTMLElement) {
      scrollToMessage(last);
    }
  }, [scrollRef, scrollToMessage]);

  const lock = useCallback(() => {
    setLocked(true);
    setIsScrolledUp(false);
    startAnimation();
  }, [setLocked, startAnimation]);

  const unlock = useCallback(() => {
    setLocked(false);
    animatingRef.current = false;
  }, [setLocked]);

  const scrollIfLocked = useCallback(() => {
    if (!enabled) {
      return;
    }
    if (!lockedRef.current) {
      return;
    }
    // Initial fill: content appearing for the first time (e.g. an
    // async-loaded conversation) positions in one frame instead of
    // spring-flying from the top. Stays pending through empty/loading
    // resizes until the container is actually scrollable.
    const el = scrollRef.current;
    if (
      initialFillPendingRef.current &&
      el &&
      el.scrollHeight > el.clientHeight
    ) {
      initialFillPendingRef.current = false;
      jumpToBottom();
      return;
    }
    startAnimation();
  }, [enabled, startAnimation, jumpToBottom, scrollRef]);

  // --- Event listeners ---

  // Syncs the scroll and scrollend listeners with `enabled`: the stream
  // container's own, or the document's when the container scrolls the page.
  useEffect(() => {
    const el = scrollRef.current;
    if (!el || !enabled) {
      return;
    }

    lastScrollTopRef.current = el.scrollTop;
    markFollowing(el, lockedRef.current);
    const doc = el.ownerDocument;
    const isPage = scrollsPage(el);
    // The root's offsetHeight is the page's height. Its clientHeight is the
    // viewport's, which is what the reader sees.
    const shownHeight = () => (isPage ? el.clientHeight : el.offsetHeight);

    const onScroll = () => {
      const {scrollTop, scrollHeight} = el;
      const dist = scrollHeight - scrollTop - shownHeight();

      // Button visibility
      setIsScrolledUp(dist > buttonThreshold);

      const isScrollingUp = scrollTop < lastScrollTopRef.current;
      lastScrollTopRef.current = scrollTop;

      // With anchoring off, the browser only ever moves a following
      // container up to clamp it onto a new, smaller bottom, and a reader
      // scrolling up never lands there. (clientHeight, not dist: offsetHeight
      // includes borders and a horizontal scrollbar.)
      const landedAtBottom = scrollHeight - scrollTop - el.clientHeight < 1;

      if (isScrollingUp && !landedAtBottom && lockedRef.current) {
        setLocked(false);
        animatingRef.current = false;
      }
    };

    const onScrollEnd = () => {
      const dist = el.scrollHeight - el.scrollTop - shownHeight();
      if (dist <= lockThreshold) {
        setLocked(true);
      }
    };

    // A scroll of the page fires at the document, not at its root element.
    const view = isPage ? doc.defaultView : null;
    const stopPageListeners: (() => void)[] = [];
    if (view != null) {
      const atDocument = (listener: () => void) => (event: Event) => {
        if (event.target === doc) {
          listener();
        }
      };
      stopPageListeners.push(
        subscribeInput(view, 'scroll', atDocument(onScroll)),
        subscribeInput(view, 'scrollend', atDocument(onScrollEnd)),
      );
    } else {
      el.addEventListener('scroll', onScroll, {passive: true});
      el.addEventListener('scrollend', onScrollEnd);
    }

    // Initial scroll to bottom — content already present at mount.
    requestAnimationFrame(() => {
      if (el.scrollHeight > el.clientHeight) {
        el.scrollTop = el.scrollHeight - el.clientHeight;
        lastScrollTopRef.current = el.scrollTop;
        initialFillPendingRef.current = false;
      }
    });

    return () => {
      for (const stop of stopPageListeners) {
        stop();
      }
      el.removeEventListener('scroll', onScroll);
      el.removeEventListener('scrollend', onScrollEnd);
      markFollowing(el, false);
    };
  }, [scrollRef, enabled, lockThreshold, buttonThreshold, setLocked]);

  return {
    isScrolledUp,
    isLocked,
    scrollToBottom,
    scrollToMessage,
    lock,
    unlock,
    scrollIfLocked,
    scrollToLastMessage,
  };
}