@ulearning/ai-sdk 0.0.0-stage → 1.0.0-next.0

package/src/primitives/thread/ThreadViewport.thread-scope.test.tsx

@@ -0,0 +1,58 @@
+// @vitest-environment jsdom
+
+import { cleanup, render } from "../../tests/vue";
+import { getByRole } from "@testing-library/dom";
+import { defineComponent } from "vue";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import { AuiConfig, AuiProvider } from "@ulearning/ai-store";
+import { resource, useResource } from "@ulearning/ai-tap";
+import { ExternalThread } from "@ulearning/ai-core/store";
+import { ThreadPrimitiveViewport } from "./ThreadViewport";
+
+const StandaloneThread = resource(function useStandaloneThread() {
+  return useResource(ExternalThread({ messages: [] }));
+});
+
+const Harness = defineComponent(
+  (props: { standalone: boolean }) => {
+    const config = AuiConfig({
+      thread: props.standalone
+        ? StandaloneThread()
+        : ExternalThread({ messages: [] }),
+    });
+    return () => (
+      <AuiProvider config={config}>
+        <ThreadPrimitiveViewport role="region" aria-label="Conversation">
+          Conversation content
+        </ThreadPrimitiveViewport>
+      </AuiProvider>
+    );
+  },
+  { props: ["standalone"] },
+);
+
+beforeEach(() => {
+  vi.stubGlobal(
+    "ResizeObserver",
+    class {
+      observe() {}
+      unobserve() {}
+      disconnect() {}
+    },
+  );
+});
+
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+});
+
+it.each([true, false])(
+  "renders a thread viewport with standalone=%s",
+  (standalone) => {
+    const view = render(<Harness standalone={standalone} />);
+    expect(
+      getByRole(view.container, "region", { name: "Conversation" }).textContent,
+    ).toBe("Conversation content");
+  },
+);

package/src/primitives/thread/ThreadViewport.tsx

@@ -0,0 +1,219 @@
+"use client";
+
+import {
+  computed,
+  defineComponent,
+  h,
+  type ComponentPublicInstance,
+  type MaybeRefOrGetter,
+  toValue,
+} from "vue";
+import { useForwardExpose } from "reka-ui";
+import { Primitive, type PrimitiveProps } from "../../utils/Primitive";
+import { useAuiState } from "@ulearning/ai-store";
+import { useIsomorphicLayoutEffect } from "@ulearning/ai-store/internal";
+import { useManagedRef } from "../../utils/hooks/useManagedRef";
+import { useThreadViewportAutoScroll } from "./useThreadViewportAutoScroll";
+import { ThreadPrimitiveViewportProvider } from "../../context/providers/ThreadViewportProvider";
+import { useSizeHandle } from "../../utils/hooks/useSizeHandle";
+import {
+  useThreadViewport,
+  useThreadViewportStore,
+} from "../../context/vue/ThreadViewportContext";
+import { useTopAnchorReserve } from "./topAnchor/useTopAnchorReserve";
+import {
+  getActiveTopAnchorAnchorId,
+  getActiveTopAnchorTargetId,
+  isTopAnchorTurnValid,
+} from "./topAnchor/topAnchorTurn";
+export namespace ThreadPrimitiveViewport {
+  export type Element = ComponentPublicInstance;
+  export type Props = PrimitiveProps<"div"> & {
+    /**
+     * Whether to automatically scroll to the bottom when new messages are added.
+     * When enabled, the viewport will automatically scroll to show the latest content.
+     *
+     * Default false if `turnAnchor` is "top", otherwise defaults to true.
+     */
+    autoScroll?: boolean | undefined;
+
+    /**
+     * Controls scroll anchoring behavior for new messages.
+     * - "bottom" (default): Messages anchor at the bottom, classic chat behavior.
+     * - "top": New user messages anchor at the top of the viewport for a focused reading experience.
+     */
+    turnAnchor?: "top" | "bottom" | undefined;
+
+    /**
+     * Clamps tall user messages so the assistant response stays in view.
+     *
+     * @default { tallerThan: "10em", visibleHeight: "6em" }
+     */
+    topAnchorMessageClamp?: {
+      /**
+       * Clamp messages taller than this. Supports `px`, `em`, and `rem`.
+       *
+       * @default "10em"
+       */
+      tallerThan?: string;
+      /**
+       * Visible portion of clamped messages. Supports `px`, `em`, and `rem`.
+       *
+       * @default "6em"
+       */
+      visibleHeight?: string;
+    };
+
+    /**
+     * Whether to scroll to bottom when a new run starts.
+     *
+     * Defaults to true.
+     */
+    scrollToBottomOnRunStart?: boolean | undefined;
+
+    /**
+     * Whether to scroll to bottom when thread history is first loaded.
+     *
+     * Defaults to true.
+     */
+    scrollToBottomOnInitialize?: boolean | undefined;
+
+    /**
+     * Whether to scroll to bottom when switching to a different thread.
+     *
+     * Defaults to true.
+     */
+    scrollToBottomOnThreadSwitch?: boolean | undefined;
+  };
+}
+
+const useTopAnchorTurn = (enabled: MaybeRefOrGetter<boolean>) => {
+  const threadViewportStore = useThreadViewportStore();
+  const activeAnchorId = useAuiState((s) =>
+    toValue(enabled) ? getActiveTopAnchorAnchorId(s.thread) : undefined,
+  );
+  const activeTargetId = useAuiState((s) =>
+    toValue(enabled) ? getActiveTopAnchorTargetId(s.thread) : undefined,
+  );
+  const topAnchorTurn = useThreadViewport((s) => s.topAnchorTurn);
+  const activeTurn = computed(() =>
+    activeAnchorId.value && activeTargetId.value
+      ? { anchorId: activeAnchorId.value, targetId: activeTargetId.value }
+      : null,
+  );
+  const topAnchorTurnIsValid = useAuiState(
+    (s) =>
+      toValue(enabled) &&
+      !!topAnchorTurn.value &&
+      isTopAnchorTurnValid(topAnchorTurn.value, s.thread.messages),
+  );
+
+  useIsomorphicLayoutEffect(
+    () => {
+      if (!topAnchorTurn.value || topAnchorTurnIsValid.value) return;
+      threadViewportStore.getState().setTopAnchorTurn(null);
+    },
+    () => [topAnchorTurn.value, topAnchorTurnIsValid.value],
+  );
+  useIsomorphicLayoutEffect(
+    () => {
+      if (!activeTurn.value) return;
+      const state = threadViewportStore.getState();
+      const current = state.topAnchorTurn;
+      if (
+        current?.anchorId === activeTurn.value.anchorId &&
+        current.targetId === activeTurn.value.targetId
+      )
+        return;
+      state.setTopAnchorTurn(activeTurn.value);
+    },
+    () => [activeTurn.value],
+  );
+};
+
+const viewportProps = [
+  "render",
+  "asChild",
+  "children",
+  "autoScroll",
+  "scrollToBottomOnRunStart",
+  "scrollToBottomOnInitialize",
+  "scrollToBottomOnThreadSwitch",
+  "turnAnchor",
+  "topAnchorMessageClamp",
+] as const;
+const ThreadPrimitiveViewportScrollable = defineComponent(
+  (props: ThreadPrimitiveViewport.Props, { attrs, slots }) => {
+    const { forwardRef } = useForwardExpose();
+    const autoScrollRef = useThreadViewportAutoScroll<HTMLElement>(() => props);
+    const registerSize = useThreadViewport((s) => s.registerViewport);
+    const viewportSizeRef = useSizeHandle(
+      registerSize,
+      (element) => element.clientHeight,
+    );
+    const registerElement = useThreadViewport((s) => s.registerViewportElement);
+    const viewportElementRef = useManagedRef<HTMLElement>((element) =>
+      registerElement.value(element),
+    );
+    const threadViewportStore = useThreadViewportStore();
+    const topAnchorEnabled =
+      threadViewportStore.getState().turnAnchor === "top";
+    useTopAnchorTurn(topAnchorEnabled);
+    useTopAnchorReserve(topAnchorEnabled);
+    const setElement = (instance: Element | ComponentPublicInstance | null) => {
+      forwardRef(instance);
+      const candidate = instance instanceof Element ? instance : instance?.$el;
+      const element = candidate instanceof HTMLElement ? candidate : null;
+      autoScrollRef(element);
+      viewportSizeRef(element);
+      viewportElementRef(element);
+    };
+    return () =>
+      h(
+        Primitive.div,
+        {
+          ...attrs,
+          render: props.render,
+          asChild: props.asChild,
+          children: props.children,
+          ref: setElement,
+        },
+        slots,
+      );
+  },
+  {
+    name: "ThreadPrimitive.ViewportScrollable",
+    inheritAttrs: false,
+    props: [...viewportProps],
+  },
+);
+
+/** A scrollable thread viewport with bottom or top turn anchoring. */
+export const ThreadPrimitiveViewport = defineComponent(
+  (props: ThreadPrimitiveViewport.Props, { attrs, slots }) => {
+    const { forwardRef } = useForwardExpose();
+    return () =>
+      h(
+        ThreadPrimitiveViewportProvider,
+        {
+          options: {
+            turnAnchor: props.turnAnchor,
+            topAnchorMessageClamp: props.topAnchorMessageClamp,
+          },
+        },
+        {
+          default: () =>
+            h(
+              ThreadPrimitiveViewportScrollable,
+              { ...attrs, ...props, ref: forwardRef },
+              slots,
+            ),
+        },
+      );
+  },
+  {
+    name: "ThreadPrimitive.Viewport",
+    inheritAttrs: false,
+    props: [...viewportProps],
+  },
+);

package/src/primitives/thread/ThreadViewportFooter.tsx

@@ -0,0 +1,46 @@
+"use client";
+
+import { defineComponent, h, type ComponentPublicInstance } from "vue";
+import { useForwardExpose } from "reka-ui";
+import { Primitive, type PrimitiveProps } from "../../utils/Primitive";
+import { useSizeHandle } from "../../utils/hooks/useSizeHandle";
+import { useThreadViewport } from "../../context/vue/ThreadViewportContext";
+
+export namespace ThreadPrimitiveViewportFooter {
+  export type Element = ComponentPublicInstance;
+  export type Props = PrimitiveProps<"div">;
+}
+
+/** Measures its height and margin; multiple footer insets are summed. */
+export const ThreadPrimitiveViewportFooter = defineComponent(
+  (props: ThreadPrimitiveViewportFooter.Props, { attrs, slots }) => {
+    const { forwardRef } = useForwardExpose();
+    const register = useThreadViewport((s) => s.registerContentInset);
+    const resizeRef = useSizeHandle(register, (element) => {
+      const marginTop = parseFloat(getComputedStyle(element).marginTop) || 0;
+      return element.offsetHeight + marginTop;
+    });
+    const setElement = (instance: Element | ComponentPublicInstance | null) => {
+      forwardRef(instance);
+      const candidate = instance instanceof Element ? instance : instance?.$el;
+      resizeRef(candidate instanceof HTMLElement ? candidate : null);
+    };
+    return () =>
+      h(
+        Primitive.div,
+        {
+          ...attrs,
+          render: props.render,
+          asChild: props.asChild,
+          children: props.children,
+          ref: setElement,
+        },
+        slots,
+      );
+  },
+  {
+    name: "ThreadPrimitive.ViewportFooter",
+    inheritAttrs: false,
+    props: ["render", "asChild", "children"],
+  },
+);

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,
+  };
+};