@assistant-ui/react 0.12.27 → 0.14.0

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

@@ -0,0 +1,131 @@
+import { describe, expect, it } from "vitest";
+import {
+  computeTopAnchorReserve,
+  computeTopAnchorTargetScrollTop,
+} from "./computeTopAnchorSlack";
+
+const makeElement = ({
+  top = 0,
+  height = 0,
+  scrollTop = 0,
+  scrollHeight = 0,
+  clientHeight = 0,
+  offsetHeight = height,
+  offsetTop = top,
+  offsetParent = null,
+}: {
+  top?: number;
+  height?: number;
+  scrollTop?: number;
+  scrollHeight?: number;
+  clientHeight?: number;
+  offsetHeight?: number;
+  offsetTop?: number;
+  offsetParent?: HTMLElement | null;
+}) =>
+  ({
+    scrollTop,
+    scrollHeight,
+    clientHeight,
+    offsetHeight,
+    offsetTop,
+    offsetParent,
+    getBoundingClientRect: () => ({
+      top,
+      height,
+    }),
+  }) as HTMLElement;
+
+describe("computeTopAnchorTargetScrollTop", () => {
+  it("uses layout offset geometry instead of the anchor's transformed visual position", () => {
+    const viewport = makeElement({ offsetTop: 0 });
+    const anchor = makeElement({
+      top: 160,
+      height: 60,
+      offsetTop: 156,
+      offsetParent: viewport,
+    });
+
+    expect(
+      computeTopAnchorTargetScrollTop({
+        viewport,
+        anchor,
+        tallerThan: 160,
+        visibleHeight: 96,
+      }),
+    ).toBe(156);
+  });
+
+  it("over-scrolls tall anchors so only visibleHeight is visible", () => {
+    const viewport = makeElement({ offsetTop: 0 });
+    const anchor = makeElement({ height: 240, offsetTop: 200 });
+
+    // 240 > 160 threshold => keep 96 visible => over-scroll by 240 - 96 = 144
+    expect(
+      computeTopAnchorTargetScrollTop({
+        viewport,
+        anchor,
+        tallerThan: 160,
+        visibleHeight: 96,
+      }),
+    ).toBe(200 + 144);
+  });
+});
+
+describe("computeTopAnchorReserve", () => {
+  it("reserves only the extra height needed to make the anchor target reachable", () => {
+    const viewport = makeElement({
+      offsetTop: 0,
+      scrollTop: 0,
+      scrollHeight: 560,
+      clientHeight: 400,
+    });
+    const anchor = makeElement({ height: 64, offsetTop: 220 });
+    const reserve = makeElement({ offsetHeight: 0 });
+
+    expect(
+      computeTopAnchorReserve({
+        viewport,
+        anchor,
+        reserve,
+        tallerThan: 160,
+        visibleHeight: 96,
+      }),
+    ).toBe(60);
+  });
+
+  it("shrinks as the response content grows", () => {
+    const anchor = makeElement({ height: 64, offsetTop: 220 });
+    const reserve = makeElement({ offsetHeight: 60 });
+
+    expect(
+      computeTopAnchorReserve({
+        viewport: makeElement({
+          offsetTop: 0,
+          scrollTop: 0,
+          scrollHeight: 620,
+          clientHeight: 400,
+        }),
+        anchor,
+        reserve,
+        tallerThan: 160,
+        visibleHeight: 96,
+      }),
+    ).toBe(60);
+
+    expect(
+      computeTopAnchorReserve({
+        viewport: makeElement({
+          offsetTop: 0,
+          scrollTop: 0,
+          scrollHeight: 680,
+          clientHeight: 400,
+        }),
+        anchor,
+        reserve,
+        tallerThan: 160,
+        visibleHeight: 96,
+      }),
+    ).toBe(0);
+  });
+});

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

@@ -0,0 +1,94 @@
+"use client";
+
+export type ComputeTopAnchorTargetOptions = {
+  viewport: HTMLElement;
+  anchor: HTMLElement;
+  tallerThan: number;
+  visibleHeight: number;
+};
+
+export type ComputeTopAnchorReserveOptions = ComputeTopAnchorTargetOptions & {
+  reserve: HTMLElement;
+};
+
+type ComputeTopAnchorSlackOptions = ComputeTopAnchorTargetOptions & {
+  scrollHeight: number;
+};
+
+const getDocumentOffsetTop = (element: HTMLElement): number => {
+  let top = 0;
+  let current: HTMLElement | null = element;
+
+  while (current) {
+    top += current.offsetTop;
+    current = current.offsetParent as HTMLElement | null;
+  }
+
+  return top;
+};
+
+const getLayoutOffsetTop = (
+  element: HTMLElement,
+  ancestor: HTMLElement,
+): number => {
+  // Use layout geometry, not visual rects, so entrance transforms/animations
+  // on the anchor do not shift the scroll target while they settle.
+  let top = 0;
+  let current: HTMLElement | null = element;
+
+  while (current && current !== ancestor) {
+    top += current.offsetTop;
+    current = current.offsetParent as HTMLElement | null;
+  }
+
+  if (current === ancestor) return top;
+
+  return getDocumentOffsetTop(element) - getDocumentOffsetTop(ancestor);
+};
+
+/**
+ * Compute the scroll position that pins the anchor (last user message) to the
+ * top of the viewport. For tall user messages the anchor is intentionally
+ * over-scrolled so only `visibleHeight` of it remains visible, leaving room
+ * for the assistant message below.
+ *
+ * Depends only on the anchor's offset within the scroll content; never reads
+ * `viewport.scrollHeight` (which is volatile while the assistant message
+ * streams in).
+ */
+export const computeTopAnchorTargetScrollTop = ({
+  viewport,
+  anchor,
+  tallerThan,
+  visibleHeight,
+}: ComputeTopAnchorTargetOptions): number => {
+  const anchorTop = getLayoutOffsetTop(anchor, viewport);
+  const anchorHeight = anchor.offsetHeight;
+  const visibleAnchorHeight =
+    anchorHeight <= tallerThan ? anchorHeight : visibleHeight;
+
+  return anchorTop + Math.max(0, anchorHeight - visibleAnchorHeight);
+};
+
+const computeTopAnchorSlack = ({
+  scrollHeight,
+  ...targetOptions
+}: ComputeTopAnchorSlackOptions): number => {
+  const { viewport } = targetOptions;
+  const targetScrollTop = computeTopAnchorTargetScrollTop(targetOptions);
+  const targetScrollHeight = targetScrollTop + viewport.clientHeight;
+
+  return Math.max(0, targetScrollHeight - scrollHeight);
+};
+
+export const computeTopAnchorReserve = ({
+  viewport,
+  reserve,
+  ...targetOptions
+}: ComputeTopAnchorReserveOptions): number => {
+  return computeTopAnchorSlack({
+    viewport,
+    ...targetOptions,
+    scrollHeight: viewport.scrollHeight - reserve.offsetHeight,
+  });
+};

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

@@ -0,0 +1,50 @@
+"use client";
+
+export const createReserveObservers = (onChange: () => void) => {
+  const resizeObserver = new ResizeObserver(onChange);
+  const mutationObserver = new MutationObserver(onChange);
+
+  let observedViewport: HTMLElement | null = null;
+  let observedAnchor: HTMLElement | null = null;
+  let observedTarget: HTMLElement | null = null;
+
+  const disconnect = () => {
+    resizeObserver.disconnect();
+    mutationObserver.disconnect();
+    observedViewport = null;
+    observedAnchor = null;
+    observedTarget = null;
+  };
+
+  return {
+    target: (
+      viewport: HTMLElement,
+      anchor: HTMLElement,
+      target: HTMLElement,
+    ) => {
+      if (
+        observedViewport === viewport &&
+        observedAnchor === anchor &&
+        observedTarget === target
+      ) {
+        return;
+      }
+
+      disconnect();
+
+      resizeObserver.observe(viewport);
+      resizeObserver.observe(anchor);
+      resizeObserver.observe(target);
+      mutationObserver.observe(target, {
+        childList: true,
+        subtree: true,
+        characterData: true,
+      });
+
+      observedViewport = viewport;
+      observedAnchor = anchor;
+      observedTarget = target;
+    },
+    disconnect,
+  };
+};

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

@@ -0,0 +1,131 @@
+// @vitest-environment jsdom
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  mountTopAnchorReserve,
+  type TopAnchorStore,
+} from "./mountTopAnchorReserve";
+
+class ResizeObserverMock {
+  observe = vi.fn();
+  disconnect = vi.fn();
+}
+
+class MutationObserverMock {
+  observe = vi.fn();
+  disconnect = vi.fn();
+}
+
+const defineReadonlyNumber = (
+  element: HTMLElement,
+  key: "clientHeight" | "scrollHeight" | "offsetHeight" | "offsetTop",
+  value: number,
+) => {
+  Object.defineProperty(element, key, { configurable: true, value });
+};
+
+const makeStore = (state: ReturnType<TopAnchorStore["getState"]>) => {
+  const listeners = new Set<() => void>();
+
+  return {
+    store: {
+      getState: () => state,
+      subscribe: (listener: () => void) => {
+        listeners.add(listener);
+        return () => listeners.delete(listener);
+      },
+    } satisfies TopAnchorStore,
+    setState: (nextState: ReturnType<TopAnchorStore["getState"]>) => {
+      state = nextState;
+      for (const listener of listeners) listener();
+    },
+  };
+};
+
+const numericClamp = { tallerThan: 160, visibleHeight: 96 };
+
+describe("mountTopAnchorReserve", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.stubGlobal("ResizeObserver", ResizeObserverMock);
+    vi.stubGlobal("MutationObserver", MutationObserverMock);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+    document.body.replaceChildren();
+  });
+
+  it("adds enough stable reserve after the active assistant turn to make the top anchor reachable", () => {
+    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);
+
+    defineReadonlyNumber(viewport, "offsetTop", 0);
+    defineReadonlyNumber(viewport, "clientHeight", 400);
+    defineReadonlyNumber(viewport, "scrollHeight", 560);
+    defineReadonlyNumber(anchor, "offsetTop", 220);
+    defineReadonlyNumber(anchor, "offsetHeight", 64);
+    viewport.scrollTo = vi.fn();
+
+    const { store } = makeStore({
+      turnAnchor: "top",
+      element: { viewport, anchor, target },
+      targetConfig: numericClamp,
+    });
+
+    mountTopAnchorReserve(store);
+    vi.runOnlyPendingTimers();
+
+    const reserve = reserveHost.querySelector(
+      "[data-aui-top-anchor-reserve]",
+    ) as HTMLElement;
+
+    expect(reserve).not.toBe(null);
+    expect(reserve.previousElementSibling).toBe(target);
+    expect(reserve.style.height).toBe("60px");
+  });
+
+  it("does not repeat the smooth top-anchor scroll for the same message", () => {
+    const viewport = document.createElement("div");
+    const anchor = document.createElement("div");
+    const target = document.createElement("div");
+    document.body.append(target);
+
+    defineReadonlyNumber(viewport, "offsetTop", 0);
+    defineReadonlyNumber(viewport, "clientHeight", 400);
+    defineReadonlyNumber(viewport, "scrollHeight", 560);
+    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,
+    });
+
+    mountTopAnchorReserve(store);
+    vi.runOnlyPendingTimers();
+
+    expect(viewport.scrollTo).not.toHaveBeenCalled();
+
+    vi.runOnlyPendingTimers();
+
+    expect(viewport.scrollTo).toHaveBeenCalledTimes(1);
+
+    setState({
+      turnAnchor: "top",
+      element: { viewport, anchor, target },
+      targetConfig: numericClamp,
+    });
+    vi.runOnlyPendingTimers();
+
+    expect(viewport.scrollTo).toHaveBeenCalledTimes(1);
+  });
+});

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

@@ -0,0 +1,127 @@
+"use client";
+
+import {
+  computeTopAnchorReserve,
+  computeTopAnchorTargetScrollTop,
+} from "./computeTopAnchorSlack";
+import { createReserveObservers } from "./createReserveObservers";
+import {
+  createReserveElement,
+  getAnchorId,
+  setReserveHeight,
+  snapScrollTop,
+} from "./topAnchorUtils";
+
+/**
+ * Minimal slice of `ThreadViewportStore` that the top-anchor reserve needs.
+ * Decoupling from the full store keeps `mountTopAnchorReserve` testable in
+ * isolation and re-usable from any consumer that can adapt to this shape.
+ */
+export type TopAnchorStore = {
+  getState(): {
+    turnAnchor: "top" | "bottom";
+    element: {
+      viewport: HTMLElement | null;
+      anchor: HTMLElement | null;
+      target: HTMLElement | null;
+    };
+    targetConfig: {
+      tallerThan: number;
+      visibleHeight: number;
+    } | null;
+  };
+  subscribe(fn: () => void): () => void;
+};
+
+const createFrameScheduler = (fn: () => void) => {
+  let frame: number | null = null;
+
+  return {
+    schedule: () => {
+      if (frame !== null) return;
+      frame = requestAnimationFrame(() => {
+        frame = null;
+        fn();
+      });
+    },
+    cancel: () => {
+      if (frame !== null) {
+        cancelAnimationFrame(frame);
+        frame = null;
+      }
+    },
+  };
+};
+
+export const mountTopAnchorReserve = (store: TopAnchorStore) => {
+  let reserve: HTMLElement | null = null;
+  let lastScrolledAnchorId: string | undefined;
+
+  function apply() {
+    const state = store.getState();
+    const { viewport, anchor, target } = state.element;
+    const clamp = state.targetConfig;
+
+    if (
+      state.turnAnchor !== "top" ||
+      !viewport ||
+      !anchor ||
+      !target ||
+      !clamp
+    ) {
+      observers.disconnect();
+      if (reserve) {
+        setReserveHeight(reserve, 0);
+        reserve.remove();
+      }
+      return;
+    }
+
+    reserve ??= createReserveElement();
+
+    if (
+      reserve.parentElement !== target.parentElement ||
+      reserve.previousElementSibling !== target
+    ) {
+      target.after(reserve);
+    }
+
+    observers.target(viewport, anchor, target);
+
+    const reserveChanged = setReserveHeight(
+      reserve,
+      computeTopAnchorReserve({ viewport, anchor, reserve, ...clamp }),
+    );
+
+    if (reserveChanged) {
+      scheduler.schedule();
+      return;
+    }
+
+    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) lastScrolledAnchorId = anchorId;
+  }
+
+  const scheduler = createFrameScheduler(apply);
+  const observers = createReserveObservers(scheduler.schedule);
+
+  scheduler.schedule();
+  const unsubscribe = store.subscribe(scheduler.schedule);
+
+  return () => {
+    scheduler.cancel();
+    unsubscribe();
+    observers.disconnect();
+    reserve?.remove();
+  };
+};

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

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import {
+  getActiveTopAnchorAnchorId,
+  getActiveTopAnchorTargetId,
+  getActiveTopAnchorTurn,
+} from "./topAnchorTurn";
+
+describe("topAnchorTurn", () => {
+  it("does not activate history-loaded messages", () => {
+    const messages = [
+      { id: "user-1", role: "user" },
+      { id: "assistant-1", role: "assistant" },
+    ];
+
+    expect(getActiveTopAnchorTurn({ isRunning: false, messages })).toBe(null);
+  });
+
+  it("activates the live user/assistant pair while running", () => {
+    const messages = [
+      { id: "assistant-1", role: "assistant" },
+      { id: "user-2", role: "user" },
+      { id: "assistant-2", role: "assistant" },
+    ];
+
+    expect(getActiveTopAnchorTurn({ isRunning: true, messages })).toEqual({
+      anchorId: "user-2",
+      targetId: "assistant-2",
+    });
+    expect(getActiveTopAnchorAnchorId({ isRunning: true, messages })).toBe(
+      "user-2",
+    );
+    expect(getActiveTopAnchorTargetId({ isRunning: true, messages })).toBe(
+      "assistant-2",
+    );
+  });
+
+  it("ignores running states without a trailing user/assistant pair", () => {
+    const messages = [
+      { id: "user-1", role: "user" },
+      { id: "assistant-1", role: "assistant" },
+      { id: "user-2", role: "user" },
+    ];
+
+    expect(getActiveTopAnchorTurn({ isRunning: true, messages })).toBe(null);
+  });
+});

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

@@ -0,0 +1,30 @@
+"use client";
+
+type TopAnchorTurnMessage = {
+  readonly id: string;
+  readonly role: string;
+};
+
+export const getActiveTopAnchorTurn = ({
+  isRunning,
+  messages,
+}: {
+  readonly isRunning: boolean;
+  readonly messages: readonly TopAnchorTurnMessage[];
+}) => {
+  if (!isRunning) return null;
+
+  const target = messages.at(-1);
+  const anchor = messages.at(-2);
+  if (anchor?.role !== "user" || target?.role !== "assistant") return null;
+
+  return { anchorId: anchor.id, targetId: target.id };
+};
+
+export const getActiveTopAnchorAnchorId = (
+  options: Parameters<typeof getActiveTopAnchorTurn>[0],
+) => getActiveTopAnchorTurn(options)?.anchorId;
+
+export const getActiveTopAnchorTargetId = (
+  options: Parameters<typeof getActiveTopAnchorTurn>[0],
+) => getActiveTopAnchorTurn(options)?.targetId;

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

@@ -0,0 +1,58 @@
+"use client";
+
+/**
+ * Convert a supported CSS length string (`px`, `em`, `rem`) into pixels,
+ * resolving font-relative units against the supplied element's computed style.
+ * Unsupported or malformed values disable the tall-message clamp.
+ *
+ * Part of the top-anchor package's public input contract: consumers may pass
+ * clamp configuration as supported CSS-length strings, and this function is the
+ * single place that converts them into the pixel values the package operates on.
+ */
+export const parseCssLength = (value: string, element: HTMLElement): number => {
+  const match = value.trim().match(/^(\d+(?:\.\d+)?|\.\d+)(em|px|rem)$/);
+  if (!match) return Number.POSITIVE_INFINITY;
+
+  const num = Number(match[1]);
+  const unit = match[2];
+
+  if (unit === "px") return num;
+  if (unit === "em") {
+    const fontSize = parseFloat(getComputedStyle(element).fontSize) || 16;
+    return num * fontSize;
+  }
+  if (unit === "rem") {
+    const rootFontSize =
+      parseFloat(getComputedStyle(document.documentElement).fontSize) || 16;
+    return num * rootFontSize;
+  }
+  return Number.POSITIVE_INFINITY;
+};
+
+export const getAnchorId = (anchor: HTMLElement) => anchor.dataset.messageId;
+
+export const createReserveElement = () => {
+  const reserve = document.createElement("div");
+  reserve.dataset.auiTopAnchorReserve = "";
+  reserve.style.height = "0px";
+  reserve.style.flexShrink = "0";
+  reserve.style.pointerEvents = "none";
+  reserve.setAttribute("aria-hidden", "true");
+
+  return reserve;
+};
+
+export const setReserveHeight = (reserve: HTMLElement, height: number) => {
+  const nextHeight = `${height}px`;
+  if (reserve.style.height !== nextHeight) {
+    reserve.style.height = nextHeight;
+    return true;
+  }
+
+  return false;
+};
+
+export const snapScrollTop = (top: number) => {
+  const pixelRatio = window.devicePixelRatio || 1;
+  return Math.round(top * pixelRatio) / pixelRatio;
+};

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

@@ -0,0 +1,19 @@
+"use client";
+
+import { useLayoutEffect } from "react";
+import { useThreadViewportStore } from "../../../context/react/ThreadViewportContext";
+import { mountTopAnchorReserve } from "./mountTopAnchorReserve";
+
+/**
+ * Mounts the top-turn-anchor reserve element against the active
+ * `ThreadViewport` store. Call this from inside the scrollable viewport so
+ * the reserve `<div>` is appended next to the streaming assistant message.
+ */
+export const useTopAnchorReserve = (enabled: boolean) => {
+  const threadViewportStore = useThreadViewportStore();
+
+  useLayoutEffect(() => {
+    if (!enabled) return;
+    return mountTopAnchorReserve(threadViewportStore);
+  }, [enabled, threadViewportStore]);
+};