@assistant-ui/react 0.15.20 → 0.15.22

package/src/primitives/selectionToolbar/SelectionToolbarRoot.tsx

@@ -9,10 +9,12 @@ import {
   forwardRef,
   useContext,
   useEffect,
+  useRef,
   useState,
 } from "react";
 import { createPortal } from "react-dom";
 import { getSelectionMessageId } from "../../utils/getSelectionMessageId";
+import { useThreadRootElementRef } from "../thread/ThreadRootElementContext";
 
 type SelectionInfo = {
   text: string;
@@ -33,9 +35,9 @@ export namespace SelectionToolbarPrimitiveRoot {
 /**
  * A floating toolbar that appears when text is selected within a message.
  *
- * Listens for mouse and keyboard selection events, validates that the
- * selection is within a single message, and renders a positioned portal
- * near the selection. Prevents mousedown from clearing the selection.
+ * Listens for browser selection changes, validates that the selection is
+ * within a single message, and renders a positioned portal near the
+ * selection. Prevents mousedown from clearing the selection.
  *
  * @example
  * ```tsx
@@ -49,10 +51,18 @@ export const SelectionToolbarPrimitiveRoot = forwardRef<
   SelectionToolbarPrimitiveRoot.Props
 >(({ onMouseDown, style, ...props }, forwardedRef) => {
   const [info, setInfo] = useState<SelectionInfo | null>(null);
+  const threadRootRef = useThreadRootElementRef();
+  const warnedAboutMissingThreadRootRef = useRef(false);
 
   useEffect(() => {
+    // Read the selection on the next frame so the browser has settled it.
+    let pendingFrame: number | null = null;
+    let isMouseDragging = false;
+
     const checkSelection = () => {
-      requestAnimationFrame(() => {
+      if (pendingFrame !== null) cancelAnimationFrame(pendingFrame);
+      pendingFrame = requestAnimationFrame(() => {
+        pendingFrame = null;
         const sel = window.getSelection();
         if (!sel || sel.isCollapsed) {
           setInfo(null);
@@ -65,7 +75,19 @@ export const SelectionToolbarPrimitiveRoot = forwardRef<
           return;
         }
 
-        const messageId = getSelectionMessageId(sel);
+        if (threadRootRef && !threadRootRef.current) {
+          if (
+            process.env.NODE_ENV !== "production" &&
+            !warnedAboutMissingThreadRootRef.current
+          ) {
+            warnedAboutMissingThreadRootRef.current = true;
+            console.warn(
+              "[SelectionToolbarPrimitive.Root] ThreadPrimitive.Root did not provide a DOM element, so the selection cannot be scoped to its thread. Ensure a custom root child forwards its ref.",
+            );
+          }
+        }
+
+        const messageId = getSelectionMessageId(sel, threadRootRef?.current);
         if (!messageId) {
           setInfo(null);
           return;
@@ -77,29 +99,61 @@ export const SelectionToolbarPrimitiveRoot = forwardRef<
       });
     };
 
-    const handleSelectionCollapse = () => {
+    const handleSelectionChange = () => {
       const sel = window.getSelection();
       if (!sel || sel.isCollapsed) {
+        if (pendingFrame !== null) {
+          cancelAnimationFrame(pendingFrame);
+          pendingFrame = null;
+        }
         setInfo(null);
+        return;
       }
+
+      if (!isMouseDragging) checkSelection();
     };
 
     const handleScroll = () => {
+      if (pendingFrame !== null) {
+        cancelAnimationFrame(pendingFrame);
+        pendingFrame = null;
+      }
       setInfo(null);
     };
 
-    document.addEventListener("mouseup", checkSelection);
-    document.addEventListener("keyup", checkSelection);
-    document.addEventListener("selectionchange", handleSelectionCollapse);
+    const handleMouseDown = () => {
+      isMouseDragging = true;
+    };
+
+    const handleMouseUp = () => {
+      isMouseDragging = false;
+      checkSelection();
+    };
+
+    const handleMouseCancel = () => {
+      isMouseDragging = false;
+    };
+
+    document.addEventListener("mousedown", handleMouseDown, true);
+    document.addEventListener("mouseup", handleMouseUp, true);
+    document.addEventListener("dragend", handleMouseUp, true);
+    // A context menu can consume the mouseup of the press that opened it.
+    document.addEventListener("contextmenu", handleMouseCancel, true);
+    window.addEventListener("blur", handleMouseCancel);
+    document.addEventListener("selectionchange", handleSelectionChange);
     document.addEventListener("scroll", handleScroll, true);
 
     return () => {
-      document.removeEventListener("mouseup", checkSelection);
-      document.removeEventListener("keyup", checkSelection);
-      document.removeEventListener("selectionchange", handleSelectionCollapse);
+      if (pendingFrame !== null) cancelAnimationFrame(pendingFrame);
+      document.removeEventListener("mousedown", handleMouseDown, true);
+      document.removeEventListener("mouseup", handleMouseUp, true);
+      document.removeEventListener("dragend", handleMouseUp, true);
+      document.removeEventListener("contextmenu", handleMouseCancel, true);
+      window.removeEventListener("blur", handleMouseCancel);
+      document.removeEventListener("selectionchange", handleSelectionChange);
       document.removeEventListener("scroll", handleScroll, true);
     };
-  }, []);
+  }, [threadRootRef]);
 
   if (!info) return null;
 

package/src/primitives/thread/ThreadRoot.tsx

@@ -6,8 +6,11 @@ import {
   forwardRef,
   type ComponentPropsWithoutRef,
   useEffect,
+  useRef,
 } from "react";
 import { useAui } from "@assistant-ui/store";
+import { useComposedRefs } from "radix-ui/internal";
+import { ThreadRootElementContext } from "./ThreadRootElementContext";
 
 export namespace ThreadPrimitiveRoot {
   export type Element = ComponentRef<typeof Primitive.div>;
@@ -43,6 +46,8 @@ export const ThreadPrimitiveRoot = forwardRef<
   ThreadPrimitiveRoot.Props
 >((props, ref) => {
   const aui = useAui();
+  const rootRef = useRef<ThreadPrimitiveRoot.Element>(null);
+  const composedRef = useComposedRefs(ref, rootRef);
 
   useEffect(() => {
     const handleKeyDown = (event: KeyboardEvent) => {
@@ -70,7 +75,11 @@ export const ThreadPrimitiveRoot = forwardRef<
     };
   }, [aui]);
 
-  return <Primitive.div {...props} ref={ref} />;
+  return (
+    <ThreadRootElementContext.Provider value={rootRef}>
+      <Primitive.div {...props} ref={composedRef} />
+    </ThreadRootElementContext.Provider>
+  );
 });
 
 ThreadPrimitiveRoot.displayName = "ThreadPrimitive.Root";

package/src/primitives/thread/ThreadRootElementContext.ts

@@ -0,0 +1,10 @@
+"use client";
+
+import { createContext, type RefObject, useContext } from "react";
+
+export const ThreadRootElementContext = createContext<
+  RefObject<HTMLElement | null> | undefined
+>(undefined);
+
+export const useThreadRootElementRef = () =>
+  useContext(ThreadRootElementContext);

package/src/primitives/thread/topAnchor/mountTopAnchorReserve.test.ts

@@ -7,6 +7,10 @@ import {
 } from "./mountTopAnchorReserve";
 
 class ResizeObserverMock {
+  static callbacks: (() => void)[] = [];
+  constructor(callback: () => void) {
+    ResizeObserverMock.callbacks.push(callback);
+  }
   observe = vi.fn();
   disconnect = vi.fn();
 }
@@ -48,6 +52,7 @@ const activeTopAnchorTurn = { anchorId: "user-1", targetId: "assistant-1" };
 describe("mountTopAnchorReserve", () => {
   beforeEach(() => {
     vi.useFakeTimers();
+    ResizeObserverMock.callbacks = [];
     vi.stubGlobal("ResizeObserver", ResizeObserverMock);
     vi.stubGlobal("MutationObserver", MutationObserverMock);
   });
@@ -331,6 +336,197 @@ describe("mountTopAnchorReserve", () => {
     expect(reserve.style.height).toBe("0px");
   });
 
+  const mountPinnedViewport = () => {
+    const viewport = document.createElement("div");
+    const anchor = document.createElement("div");
+    const target = document.createElement("div");
+    const reserveHost = document.createElement("div");
+    reserveHost.append(target);
+    document.body.append(reserveHost);
+
+    let naturalScrollHeight = 560;
+
+    defineReadonlyNumber(viewport, "offsetTop", 0);
+    defineReadonlyNumber(viewport, "clientHeight", 400);
+    Object.defineProperty(viewport, "scrollHeight", {
+      configurable: true,
+      get: () => {
+        const reserve = document.querySelector<HTMLElement>(
+          "[data-aui-top-anchor-reserve]",
+        );
+        return (
+          naturalScrollHeight + Number.parseFloat(reserve?.style.height || "0")
+        );
+      },
+    });
+    defineReadonlyNumber(anchor, "offsetTop", 220);
+    defineReadonlyNumber(anchor, "offsetHeight", 64);
+    anchor.dataset.messageId = "msg-1";
+    viewport.scrollTo = vi.fn();
+
+    const { store, setState } = makeStore({
+      turnAnchor: "top",
+      element: { viewport, anchor, target },
+      targetConfig: numericClamp,
+      topAnchorTurn: activeTopAnchorTurn,
+    });
+
+    const unmount = mountTopAnchorReserve(store);
+    vi.runOnlyPendingTimers();
+
+    const reserve = reserveHost.querySelector<HTMLElement>(
+      "[data-aui-top-anchor-reserve]",
+    )!;
+    Object.defineProperty(reserve, "offsetHeight", {
+      configurable: true,
+      get: () => Number.parseFloat(reserve.style.height || "0"),
+    });
+    vi.runOnlyPendingTimers();
+
+    expect(viewport.scrollTo).toHaveBeenCalledTimes(1);
+    expect(viewport.scrollTo).toHaveBeenLastCalledWith({
+      top: 220,
+      behavior: "smooth",
+    });
+
+    viewport.scrollTop = 220;
+    viewport.dispatchEvent(new Event("scroll"));
+
+    return {
+      viewport,
+      anchor,
+      target,
+      store,
+      setState,
+      unmount,
+      notifyLayout: () => ResizeObserverMock.callbacks.at(-1)!(),
+      setNaturalScrollHeight: (height: number) => {
+        naturalScrollHeight = height;
+      },
+    };
+  };
+
+  it("restores the pre-clamp position when the old offset becomes unreachable", () => {
+    const { viewport, setNaturalScrollHeight } = mountPinnedViewport();
+
+    setNaturalScrollHeight(400);
+    viewport.scrollTop = 60;
+    viewport.dispatchEvent(new Event("scroll"));
+    setNaturalScrollHeight(560);
+    vi.runOnlyPendingTimers();
+
+    expect(viewport.scrollTo).toHaveBeenCalledTimes(2);
+    expect(viewport.scrollTo).toHaveBeenLastCalledWith({
+      top: 220,
+      behavior: "instant",
+    });
+  });
+
+  it("does not undo a reachable scrollIntoView movement", () => {
+    const { viewport, target, notifyLayout } = mountPinnedViewport();
+    target.scrollIntoView = vi.fn(() => {
+      viewport.scrollTop = 100;
+      viewport.dispatchEvent(new Event("scroll"));
+    });
+
+    target.scrollIntoView();
+    notifyLayout();
+    vi.runOnlyPendingTimers();
+
+    expect(viewport.scrollTo).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not undo reachable focus scrolling", () => {
+    const { viewport, target, notifyLayout } = mountPinnedViewport();
+    const input = document.createElement("input");
+    target.append(input);
+
+    input.focus();
+    viewport.scrollTop = 100;
+    viewport.dispatchEvent(new Event("scroll"));
+    notifyLayout();
+    vi.runOnlyPendingTimers();
+
+    expect(viewport.scrollTo).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not restore an out-of-range movement that did not land at the maximum", () => {
+    const { viewport, setNaturalScrollHeight, notifyLayout } =
+      mountPinnedViewport();
+
+    setNaturalScrollHeight(400);
+    viewport.scrollTop = 40;
+    viewport.dispatchEvent(new Event("scroll"));
+    setNaturalScrollHeight(560);
+    notifyLayout();
+    vi.runOnlyPendingTimers();
+
+    expect(viewport.scrollTo).toHaveBeenCalledTimes(1);
+  });
+
+  it("restores at most once per anchor turn", () => {
+    const { viewport, setNaturalScrollHeight, notifyLayout } =
+      mountPinnedViewport();
+
+    setNaturalScrollHeight(400);
+    viewport.scrollTop = 60;
+    viewport.dispatchEvent(new Event("scroll"));
+    setNaturalScrollHeight(560);
+    vi.runOnlyPendingTimers();
+    expect(viewport.scrollTo).toHaveBeenCalledTimes(2);
+
+    viewport.scrollTop = 220;
+    viewport.dispatchEvent(new Event("scroll"));
+    setNaturalScrollHeight(400);
+    viewport.scrollTop = 60;
+    viewport.dispatchEvent(new Event("scroll"));
+    setNaturalScrollHeight(560);
+    notifyLayout();
+    vi.runOnlyPendingTimers();
+
+    expect(viewport.scrollTo).toHaveBeenCalledTimes(2);
+  });
+
+  it("drops a pending restore across an anchor-gap thread transition", () => {
+    const { viewport, setState, setNaturalScrollHeight } =
+      mountPinnedViewport();
+
+    setNaturalScrollHeight(400);
+    viewport.scrollTop = 60;
+    viewport.dispatchEvent(new Event("scroll"));
+
+    setState({
+      turnAnchor: "top",
+      element: { viewport, anchor: null, target: null },
+      targetConfig: null,
+      topAnchorTurn: activeTopAnchorTurn,
+    });
+    vi.runOnlyPendingTimers();
+
+    const nextAnchor = document.createElement("div");
+    const nextTarget = document.createElement("div");
+    document.body.append(nextTarget);
+    defineReadonlyNumber(nextAnchor, "offsetTop", 480);
+    defineReadonlyNumber(nextAnchor, "offsetHeight", 64);
+    nextAnchor.dataset.messageId = "msg-2";
+
+    setState({
+      turnAnchor: "top",
+      element: { viewport, anchor: nextAnchor, target: nextTarget },
+      targetConfig: numericClamp,
+      topAnchorTurn: { anchorId: "user-2", targetId: "assistant-2" },
+    });
+    setNaturalScrollHeight(560);
+    vi.runOnlyPendingTimers();
+    vi.runOnlyPendingTimers();
+
+    expect(viewport.scrollTo).toHaveBeenCalledTimes(2);
+    expect(viewport.scrollTo).toHaveBeenLastCalledWith({
+      top: 480,
+      behavior: "smooth",
+    });
+  });
+
   it("does not repeat the smooth top-anchor scroll for the same message", () => {
     const viewport = document.createElement("div");
     const anchor = document.createElement("div");

package/src/primitives/thread/topAnchor/mountTopAnchorReserve.ts

@@ -61,13 +61,67 @@ export const mountTopAnchorReserve = (store: TopAnchorStore) => {
   let reserve: HTMLElement | null = null;
   let lastScrolledAnchorId: string | undefined;
 
+  let listenedViewport: HTMLElement | null = null;
+  let lastScrollTop = 0;
+  let restoreScrollTop: number | null = null;
+  let restoredThisTurn = false;
+  let lastAppliedTarget: number | null = null;
+
+  const clearRestore = () => {
+    restoreScrollTop = null;
+    lastAppliedTarget = null;
+  };
+
+  const wasPinnedAtLastScroll = () =>
+    lastAppliedTarget !== null &&
+    Math.abs(lastScrollTop - lastAppliedTarget) <= 1;
+
+  const handleScroll = () => {
+    const viewport = listenedViewport;
+    if (!viewport) return;
+    const scrollTop = viewport.scrollTop;
+    const maxScrollTop = Math.max(
+      0,
+      viewport.scrollHeight - viewport.clientHeight,
+    );
+    // A range clamp starts beyond the new maximum and lands on it.
+    const isRangeClamp =
+      scrollTop < lastScrollTop &&
+      lastScrollTop > maxScrollTop + 1 &&
+      Math.abs(scrollTop - maxScrollTop) <= 1;
+
+    if (isRangeClamp && wasPinnedAtLastScroll() && !restoredThisTurn) {
+      restoreScrollTop ??= lastScrollTop;
+      scheduler.schedule();
+    }
+
+    lastScrollTop = scrollTop;
+  };
+
+  const listenViewport = (viewport: HTMLElement | null) => {
+    if (listenedViewport === viewport) return;
+    if (listenedViewport) {
+      listenedViewport.removeEventListener("scroll", handleScroll);
+    }
+    listenedViewport = viewport;
+    restoredThisTurn = false;
+    clearRestore();
+    if (viewport) {
+      viewport.addEventListener("scroll", handleScroll, { passive: true });
+      lastScrollTop = viewport.scrollTop;
+    }
+  };
+
   function apply() {
     const state = store.getState();
     const { viewport, anchor, target } = state.element;
     const clamp = state.targetConfig;
 
+    listenViewport(state.turnAnchor === "top" ? viewport : null);
+
     if (state.turnAnchor !== "top" || !viewport) {
       observers.disconnect();
+      clearRestore();
       if (reserve) {
         setReserveHeight(reserve, 0);
         reserve.remove();
@@ -80,6 +134,7 @@ export const mountTopAnchorReserve = (store: TopAnchorStore) => {
       // trailing turn (followed at most by pending user messages), so reaching
       // here means the anchor gap is transient and the next run is imminent.
       observers.disconnect();
+      clearRestore();
       if (
         reserve?.parentElement &&
         reserve.parentElement.lastElementChild !== reserve
@@ -91,6 +146,7 @@ export const mountTopAnchorReserve = (store: TopAnchorStore) => {
 
     if (!anchor || !target || !clamp) {
       observers.disconnect();
+      clearRestore();
       if (reserve) {
         setReserveHeight(reserve, 0);
         reserve.remove();
@@ -120,17 +176,33 @@ export const mountTopAnchorReserve = (store: TopAnchorStore) => {
     }
 
     const anchorId = getAnchorId(anchor);
-    if (anchorId !== undefined && lastScrolledAnchorId === anchorId) return;
-
     const targetScrollTop = snapScrollTop(
       computeTopAnchorTargetScrollTop({ viewport, anchor, ...clamp }),
     );
 
-    if (Math.abs(viewport.scrollTop - targetScrollTop) > 1) {
-      viewport.scrollTo({ top: targetScrollTop, behavior: "smooth" });
+    if (anchorId === undefined || anchorId !== lastScrolledAnchorId) {
+      restoreScrollTop = null;
+      restoredThisTurn = false;
+      if (Math.abs(viewport.scrollTop - targetScrollTop) > 1) {
+        viewport.scrollTo({ top: targetScrollTop, behavior: "smooth" });
+      }
+      if (anchorId !== undefined) lastScrolledAnchorId = anchorId;
+    } else if (restoreScrollTop !== null && lastAppliedTarget !== null) {
+      // Restore the anchor-relative position: if content above the anchor
+      // changed height and the browser already adjusted scrollTop to match
+      // (scroll anchoring), the desired offset equals the current one and
+      // this is a no-op.
+      const desired = snapScrollTop(
+        restoreScrollTop + (targetScrollTop - lastAppliedTarget),
+      );
+      restoreScrollTop = null;
+      restoredThisTurn = true;
+      if (Math.abs(viewport.scrollTop - desired) > 1) {
+        viewport.scrollTo({ top: desired, behavior: "instant" });
+      }
     }
 
-    if (anchorId !== undefined) lastScrolledAnchorId = anchorId;
+    lastAppliedTarget = targetScrollTop;
   }
 
   const scheduler = createFrameScheduler(apply);
@@ -143,6 +215,7 @@ export const mountTopAnchorReserve = (store: TopAnchorStore) => {
     scheduler.cancel();
     unsubscribe();
     observers.disconnect();
+    listenViewport(null);
     reserve?.remove();
   };
 };