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

package/src/primitives/message/MessageRoot.test.tsx

@@ -0,0 +1,272 @@
+// @vitest-environment jsdom
+
+import { act, cleanup, render } from "../../tests/vue";
+import {
+  computed,
+  createSSRApp,
+  defineComponent,
+  h,
+  inject,
+  nextTick,
+  provide,
+  type App,
+  type InjectionKey,
+  type Ref,
+  type VNode,
+} from "vue";
+import { renderToString } from "@vue/server-renderer";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type {
+  ChatModelAdapter,
+  ThreadMessageLike,
+  ThreadMessage,
+} from "@ulearning/ai-core";
+import {
+  AssistantRuntimeProvider,
+  ThreadListItemRuntimeProvider,
+  useExternalStoreRuntime,
+  useLocalRuntime,
+} from "@ulearning/ai-core/vue";
+import { useAuiState } from "@ulearning/ai-store";
+import {
+  ThreadPrimitiveMessageByIndex,
+  ThreadPrimitiveMessages,
+} from "../thread/ThreadMessages";
+import { ThreadPrimitiveRoot } from "../thread/ThreadRoot";
+import { ThreadPrimitiveViewportProvider } from "../../context/providers/ThreadViewportProvider";
+import { MessagePrimitiveRoot } from "./MessageRoot";
+
+const messages: ThreadMessageLike[] = [
+  {
+    id: "message-1",
+    role: "assistant",
+    content: [{ type: "text", text: "Hello" }],
+  },
+];
+
+const initialMessages: readonly ThreadMessageLike[] = [
+  { role: "user", content: "Hydrated message" },
+];
+
+const chatModel: ChatModelAdapter = {
+  run: async () => ({ content: [] }),
+};
+
+class TestResizeObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+
+const VisibilityContext: InjectionKey<Ref<boolean>> = Symbol("test.visibility");
+const Message = defineComponent({
+  setup() {
+    const visible = inject(VisibilityContext)!;
+    const isHovering = useAuiState((s) => s.message.isHovering);
+    return () => [
+      visible.value ? h(MessagePrimitiveRoot) : null,
+      h("span", {
+        "data-testid": "hover-state",
+        "data-hovering": isHovering.value,
+      }),
+    ];
+  },
+});
+const Example = defineComponent<{ visible?: boolean }>(
+  (props) => {
+    const runtime = useExternalStoreRuntime({
+      messages,
+      convertMessage: (message) => message,
+      onNew: async () => {},
+    });
+    provide(
+      VisibilityContext,
+      computed(() => props.visible ?? true),
+    );
+    return () =>
+      h(
+        AssistantRuntimeProvider,
+        { runtime },
+        {
+          default: () =>
+            h(ThreadPrimitiveRoot, null, {
+              default: () =>
+                h(ThreadPrimitiveViewportProvider, null, {
+                  default: () =>
+                    h(ThreadPrimitiveMessageByIndex, {
+                      index: 0,
+                      components: { Message },
+                    }),
+                }),
+            }),
+        },
+      );
+  },
+  { props: ["visible"] },
+);
+const HydrationMessage = () =>
+  h(MessagePrimitiveRoot, { "data-testid": "hydration-message" });
+type LocalThreadProps = {
+  onRuntime: (runtime: ReturnType<typeof useLocalRuntime>) => void;
+  turnAnchor: "bottom" | "top";
+};
+const LocalThread = defineComponent<LocalThreadProps>(
+  (props) => {
+    const runtime = useLocalRuntime(chatModel, { initialMessages });
+    props.onRuntime(runtime);
+    return () =>
+      h(
+        AssistantRuntimeProvider,
+        { runtime },
+        {
+          default: () =>
+            h(ThreadPrimitiveRoot, null, {
+              default: () =>
+                h(
+                  ThreadPrimitiveViewportProvider,
+                  { options: { turnAnchor: props.turnAnchor } },
+                  {
+                    default: () =>
+                      h(ThreadPrimitiveMessages, {
+                        components: { Message: HydrationMessage },
+                      }),
+                  },
+                ),
+            }),
+        },
+      );
+  },
+  { props: ["onRuntime", "turnAnchor"] },
+);
+const NestedLocalRuntime = defineComponent<LocalThreadProps>(
+  (props) => {
+    const host = useExternalStoreRuntime<ThreadMessage>({
+      messages: [],
+      onNew: async () => {},
+    });
+    return () =>
+      h(
+        AssistantRuntimeProvider,
+        { runtime: host },
+        {
+          default: () =>
+            h(
+              ThreadListItemRuntimeProvider,
+              { runtime: host.threads.mainItem },
+              { default: () => h(LocalThread, props) },
+            ),
+        },
+      );
+  },
+  { props: ["onRuntime", "turnAnchor"] },
+);
+const renderOnServer = async (node: VNode) => {
+  vi.stubGlobal("document", undefined);
+  try {
+    return await renderToString(createSSRApp({ render: () => node }));
+  } finally {
+    vi.unstubAllGlobals();
+  }
+};
+
+beforeEach(() => {
+  vi.stubGlobal("ResizeObserver", TestResizeObserver);
+});
+
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+const mockHoveredElement = () => {
+  const matches = HTMLElement.prototype.matches;
+  vi.spyOn(HTMLElement.prototype, "matches").mockImplementation(function (
+    this: HTMLElement,
+    selector,
+  ) {
+    return selector === ":hover" || matches.call(this, selector);
+  });
+};
+
+describe("MessagePrimitiveRoot", () => {
+  it.each(["bottom", "top"] as const)(
+    "hydrates nested local message ids with %s anchoring",
+    async (turnAnchor) => {
+      let serverRuntime: ReturnType<typeof useLocalRuntime> | undefined;
+      const html = await renderOnServer(
+        h(NestedLocalRuntime, {
+          onRuntime: (runtime) => {
+            serverRuntime = runtime;
+          },
+          turnAnchor,
+        }),
+      );
+      const serverMessageId = serverRuntime!.thread.getState().messages[0]!.id;
+      const container = document.createElement("div");
+      container.innerHTML = html;
+      vi.stubGlobal("ResizeObserver", TestResizeObserver);
+
+      let clientRuntime: ReturnType<typeof useLocalRuntime> | undefined;
+      const errors = vi.spyOn(console, "error").mockImplementation(() => {});
+      let root: App | undefined;
+      await act(async () => {
+        root = createSSRApp({
+          render: () =>
+            h(NestedLocalRuntime, {
+              onRuntime: (runtime) => {
+                clientRuntime = runtime;
+              },
+              turnAnchor,
+            }),
+        });
+        root.mount(container);
+        await nextTick();
+      });
+
+      const clientMessageId = clientRuntime!.thread.getState().messages[0]!.id;
+      const domMessageId = container
+        .querySelector("[data-testid='hydration-message']")!
+        .getAttribute("data-message-id");
+
+      expect(clientMessageId).toBe(serverMessageId);
+      expect(domMessageId).toBe(clientMessageId);
+      expect(
+        errors.mock.calls.some((args) =>
+          args.some((value) => String(value).includes("data-message-id")),
+        ),
+      ).toBe(false);
+
+      await act(async () => root?.unmount());
+    },
+  );
+
+  it("synchronizes hover state while mounted", async () => {
+    mockHoveredElement();
+
+    const view = render(h(Example));
+    await act(() => Promise.resolve());
+    await vi.waitFor(() =>
+      expect(
+        view.getByTestId("hover-state").getAttribute("data-hovering"),
+      ).toBe("true"),
+    );
+
+    expect(view.getByTestId("hover-state").getAttribute("data-hovering")).toBe(
+      "true",
+    );
+    view.unmount();
+  });
+
+  it("does not restore hover state after unmount", async () => {
+    mockHoveredElement();
+
+    const view = render(h(Example));
+    await view.rerender(h(Example, { visible: false }));
+    await act(() => Promise.resolve());
+
+    expect(view.getByTestId("hover-state").getAttribute("data-hovering")).toBe(
+      "false",
+    );
+  });
+});

package/src/primitives/message/MessageRoot.tsx

@@ -0,0 +1,145 @@
+"use client";
+
+import { defineComponent, h, type ComponentPublicInstance } from "vue";
+import { useForwardExpose } from "reka-ui";
+import { Primitive, type PrimitiveProps } from "../../utils/Primitive";
+import { useAui, useAuiState } from "@ulearning/ai-store";
+import { useManagedRef } from "../../utils/hooks/useManagedRef";
+import {
+  useThreadViewport,
+  useThreadViewportStore,
+} from "../../context/vue/ThreadViewportContext";
+import { parseCssLength } from "../thread/topAnchor/topAnchorUtils";
+
+export namespace MessagePrimitiveRoot {
+  export type Element = ComponentPublicInstance;
+  export type Props = PrimitiveProps<"div">;
+}
+
+/**
+ * The root container component for a message.
+ *
+ * This component provides the foundational wrapper for message content and handles
+ * hover state management for the message. It automatically tracks when the user
+ * is hovering over the message, which can be used by child components like action bars.
+ *
+ * When `turnAnchor="top"` is set on the viewport, this component automatically
+ * registers itself as the top-anchor user message (when it's the previous user
+ * message) or as the top-anchor target (when it's the streaming assistant
+ * response). No additional component is required.
+ *
+ * @example
+ * ```tsx
+ * <MessagePrimitive.Root>
+ *   <MessagePrimitive.Content />
+ *   <ActionBarPrimitive.Root>
+ *     <ActionBarPrimitive.Copy />
+ *     <ActionBarPrimitive.Edit />
+ *   </ActionBarPrimitive.Root>
+ * </MessagePrimitive.Root>
+ * ```
+ */
+export const MessagePrimitiveRoot = defineComponent<MessagePrimitiveRoot.Props>(
+  (props, { attrs, slots }) => {
+    const { forwardRef } = useForwardExpose();
+    const aui = useAui();
+    const viewport = useThreadViewportStore();
+    const top = viewport.getState().turnAnchor === "top";
+    const message = useAuiState(() => aui.message);
+    const messageId = useAuiState((s) => s.message.id);
+    const hovering = useManagedRef<HTMLElement>((element) => {
+      const owner = message.value;
+      let active = true;
+      const enter = () => owner.setIsHovering(true);
+      const leave = () => owner.setIsHovering(false);
+      element.addEventListener("mouseenter", enter);
+      element.addEventListener("mouseleave", leave);
+      if (element.matches(":hover"))
+        queueMicrotask(() => {
+          if (active) enter();
+        });
+      return () => {
+        active = false;
+        element.removeEventListener("mouseenter", enter);
+        element.removeEventListener("mouseleave", leave);
+        owner.setIsHovering(false);
+      };
+    });
+    const anchorId = top
+      ? useThreadViewport((s) => s.topAnchorTurn?.anchorId)
+      : undefined;
+    const targetId = top
+      ? useThreadViewport((s) => s.topAnchorTurn?.targetId)
+      : undefined;
+    const anchor = top
+      ? useAuiState(
+          (s) =>
+            s.message.role === "user" &&
+            s.message.index > 0 &&
+            s.message.index === s.thread.messages.length - 2 &&
+            s.thread.messages.at(-1)?.role === "assistant" &&
+            (s.message.id === anchorId?.value || s.thread.isRunning),
+        )
+      : undefined;
+    const target = top
+      ? useAuiState(
+          (s) =>
+            s.message.isLast &&
+            s.message.role === "assistant" &&
+            s.message.index >= 1 &&
+            s.thread.messages.at(s.message.index - 1)?.role === "user" &&
+            (s.message.id === targetId?.value || s.thread.isRunning),
+        )
+      : undefined;
+    const manageAnchor = top
+      ? useManagedRef<HTMLElement>((element) => {
+          if (anchor?.value)
+            return viewport.getState().registerAnchorElement(element);
+          return undefined;
+        })
+      : undefined;
+    const manageTarget = top
+      ? useManagedRef<HTMLElement>((element) => {
+          if (!target?.value) return undefined;
+          const state = viewport.getState();
+          const clamp = state.topAnchorMessageClamp;
+          return state.registerAnchorTargetElement(element, {
+            tallerThan: parseCssLength(clamp.tallerThan, element),
+            visibleHeight: parseCssLength(clamp.visibleHeight, element),
+          });
+        })
+      : undefined;
+    const setElement = (instance: Element | ComponentPublicInstance | null) => {
+      forwardRef(instance);
+      const candidate = instance instanceof Element ? instance : instance?.$el;
+      const element = candidate instanceof HTMLElement ? candidate : null;
+      hovering(element);
+      manageAnchor?.(element);
+      manageTarget?.(element);
+    };
+    return () =>
+      h(
+        Primitive.div,
+        {
+          ...attrs,
+          render: props.render,
+          asChild: props.asChild,
+          children: props.children,
+          ref: setElement,
+          "data-message-id": messageId.value,
+          ...(top
+            ? {
+                "data-aui-top-anchor-user": anchor?.value ? "" : undefined,
+                "data-aui-top-anchor-target": target?.value ? "" : undefined,
+              }
+            : {}),
+        },
+        slots,
+      );
+  },
+  {
+    name: "MessagePrimitive.Root",
+    inheritAttrs: false,
+    props: ["render", "asChild", "children"],
+  },
+);

package/src/primitives/message.ts

@@ -0,0 +1,15 @@
+export { MessagePrimitiveRoot as Root } from "./message/MessageRoot";
+export { MessagePrimitiveParts as Parts } from "./message/MessageParts";
+export { MessagePrimitivePartByIndex as PartByIndex } from "./message/MessageParts";
+export { MessagePrimitiveParts as Content } from "./message/MessageParts";
+export { MessagePrimitiveIf as If } from "./message/MessageIf";
+export { MessagePrimitiveAttachments as Attachments } from "./message/MessageAttachments";
+export { MessagePrimitiveAttachmentByIndex as AttachmentByIndex } from "./message/MessageAttachments";
+export { MessagePrimitiveQuote as Quote } from "@ulearning/ai-core/vue";
+export { MessagePrimitiveError as Error } from "./message/MessageError";
+export { MessagePrimitiveGroupedParts as GroupedParts } from "@ulearning/ai-core/vue";
+export { MessagePrimitiveGenerativeUI as GenerativeUI } from "@ulearning/ai-core/vue";
+export {
+  MessagePrimitiveUnstable_PartsGrouped as Unstable_PartsGrouped,
+  MessagePrimitiveUnstable_PartsGroupedByParentId as Unstable_PartsGroupedByParentId,
+} from "./message/MessagePartsGrouped";

package/src/primitives/messagePart/MessagePartImage.tsx

@@ -0,0 +1,29 @@
+"use client";
+
+import { defineComponent, h, type ComponentPublicInstance } from "vue";
+import { useForwardExpose } from "reka-ui";
+import { Primitive, type PrimitiveProps } from "../../utils/Primitive";
+import { useMessagePartImage } from "./useMessagePartImage";
+
+export namespace MessagePartPrimitiveImage {
+  export type Element = ComponentPublicInstance;
+  export type Props = PrimitiveProps<"img">;
+}
+
+export const MessagePartPrimitiveImage = defineComponent(
+  (props: MessagePartPrimitiveImage.Props, { attrs, slots }) => {
+    const part = useMessagePartImage();
+    const { forwardRef } = useForwardExpose();
+    return () =>
+      h(
+        Primitive.img,
+        { src: part.value.image, ...attrs, ...props, ref: forwardRef },
+        slots,
+      );
+  },
+  {
+    name: "MessagePartPrimitive.Image",
+    inheritAttrs: false,
+    props: ["render", "asChild", "children"],
+  },
+);

package/src/primitives/messagePart/MessagePartInProgress.ts

@@ -0,0 +1,3 @@
+"use client";
+
+export { MessagePartPrimitiveInProgress } from "@ulearning/ai-core/vue";

package/src/primitives/messagePart/MessagePartText.test.tsx

@@ -0,0 +1,114 @@
+// @vitest-environment jsdom
+import {
+  defineComponent,
+  h,
+  shallowRef,
+  type ComponentPublicInstance,
+} from "vue";
+import { afterEach, describe, expect, it } from "vitest";
+import { nextTick } from "vue";
+import { flushTapSync } from "@ulearning/ai-tap";
+import { cleanup, render } from "../../tests/vue";
+import { TextMessagePartProvider } from "../../context/providers/TextMessagePartProvider";
+import { MessagePartPrimitiveText } from "./MessagePartText";
+
+afterEach(cleanup);
+describe("MessagePartPrimitive.Text", () => {
+  it("renders text in the supplied element and composes its props and refs", async () => {
+    const ref = shallowRef<ComponentPublicInstance | null>(null);
+    const targetRef = shallowRef<HTMLElement | null>(null);
+    const text = shallowRef("Hello");
+    const running = shallowRef(false);
+    const { container } = render(
+      h(
+        defineComponent({
+          setup: () => () =>
+            h(
+              TextMessagePartProvider,
+              {
+                text: text.value,
+                isRunning: running.value,
+              },
+              {
+                default: () =>
+                  h(MessagePartPrimitiveText, {
+                    smooth: false,
+                    render: h("mark", { ref: targetRef, class: "target" }),
+                    class: "text",
+                    ref,
+                  }),
+              },
+            ),
+        }),
+      ),
+    );
+    const element = container.querySelector("mark")!;
+    expect(element.textContent).toBe("Hello");
+    expect(element.tagName).toBe("MARK");
+    expect(element.classList.contains("target")).toBe(true);
+    expect(element.classList.contains("text")).toBe(true);
+    expect(element.getAttribute("data-status")).toBe("complete");
+    expect(element.hasAttribute("render")).toBe(false);
+    expect(ref.value?.$el).toBe(element);
+    expect(targetRef.value).toBe(element);
+    flushTapSync(() => {
+      text.value = "Hello again";
+      running.value = true;
+    });
+    await nextTick();
+    const updated = container.querySelector("mark")!;
+    expect(updated.textContent).toBe("Hello again");
+    expect(updated.tagName).toBe("MARK");
+    expect(updated.getAttribute("data-status")).toBe("running");
+  });
+  it("keeps the default span and explicit component behavior", () => {
+    const spanRef = shallowRef<ComponentPublicInstance | null>(null);
+    const componentRef = shallowRef<ComponentPublicInstance | null>(null);
+    const { container } = render(
+      h(
+        defineComponent({
+          setup: () => () =>
+            h(
+              TextMessagePartProvider,
+              {
+                text: "Hello",
+              },
+              {
+                default: () => [
+                  h(MessagePartPrimitiveText, { ref: spanRef }),
+                  h(MessagePartPrimitiveText, {
+                    component: "p",
+                    ref: componentRef,
+                  }),
+                  h(MessagePartPrimitiveText, {
+                    component: "p",
+                    render: h("mark"),
+                  }),
+                  h(MessagePartPrimitiveText, {
+                    component: "p",
+                    render: undefined,
+                  }),
+                ],
+              },
+            ),
+        }),
+      ),
+    );
+    expect(spanRef.value?.$el.tagName).toBe("SPAN");
+    expect(spanRef.value?.$el.getAttribute("data-status")).toBe("complete");
+    expect(componentRef.value?.$el.tagName).toBe("P");
+    expect([...container.children].map((text) => text.tagName)).toEqual([
+      "SPAN",
+      "P",
+      "MARK",
+      "P",
+    ]);
+    expect(container.querySelector("mark")!.hasAttribute("render")).toBe(false);
+    expect([...container.children].map((text) => text.textContent)).toEqual([
+      "Hello",
+      "Hello",
+      "Hello",
+      "Hello",
+    ]);
+  });
+});

package/src/primitives/messagePart/MessagePartText.tsx

@@ -0,0 +1,54 @@
+"use client";
+
+import {
+  defineComponent,
+  h,
+  isVNode,
+  type Component,
+  type ComponentPublicInstance,
+  type IntrinsicElementAttributes,
+} from "vue";
+import { useForwardExpose } from "reka-ui";
+import {
+  Primitive,
+  renderSlot,
+  type PrimitiveProps,
+} from "../../utils/Primitive";
+import { useMessagePartText } from "./useMessagePartText";
+import { useSmooth, type SmoothOptions } from "../../utils/smooth/useSmooth";
+
+export namespace MessagePartPrimitiveText {
+  export type Element = ComponentPublicInstance;
+  export type Props = Omit<PrimitiveProps<"span">, "children" | "asChild"> & {
+    /** Defaults to true; respects prefers-reduced-motion. */
+    smooth?: boolean | SmoothOptions;
+    /** The element or Vue component to render; render takes precedence. */
+    component?: keyof IntrinsicElementAttributes | Component;
+  };
+}
+
+export const MessagePartPrimitiveText = defineComponent(
+  (props: MessagePartPrimitiveText.Props, { attrs }) => {
+    const state = useSmooth(useMessagePartText(), () => props.smooth ?? true);
+    const { forwardRef } = useForwardExpose();
+    return () => {
+      const { smooth: _, component = Primitive.span, render, ...rest } = props;
+      const merged = {
+        "data-status": state.value.status.type,
+        ...attrs,
+        ...rest,
+        ref: forwardRef,
+      };
+      if (render && isVNode(render))
+        return renderSlot(render, state.value.text, merged);
+      return typeof component === "string"
+        ? h(component, merged, state.value.text)
+        : h(component, merged, { default: () => state.value.text });
+    };
+  },
+  {
+    name: "MessagePartPrimitive.Text",
+    inheritAttrs: false,
+    props: ["smooth", "component", "render"],
+  },
+);