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

package/src/primitives/message/MessagePartsGrouped.tool-interaction.test.tsx

@@ -0,0 +1,97 @@
+// @vitest-environment jsdom
+import { defineComponent, h } from "vue";
+import { cleanup, render } from "../../tests/vue";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  AssistantRuntimeProvider,
+  useExternalStoreRuntime,
+  useAssistantToolUI,
+  type ToolCallMessagePartProps,
+} from "@ulearning/ai-core/vue";
+import { ThreadPrimitiveMessages } from "../thread/ThreadMessages";
+import { MessagePrimitiveUnstable_PartsGroupedByParentId as MessagePrimitiveParts } from "./MessagePartsGrouped";
+
+const interaction = { type: "action" as const, payload: { choice: "retry" } };
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+describe("MessagePrimitive.Unstable_PartsGrouped", () => {
+  it.each(["override", "registered"] as const)(
+    "forwards unstable_recordInteraction to the %s tool UI",
+    async (kind) => {
+      vi.spyOn(Date, "now").mockReturnValue(123);
+      const recordInteraction = vi.fn(async () => {});
+      const Tool = defineComponent(
+        (props: Pick<ToolCallMessagePartProps, "unstable_recordInteraction">) =>
+          () =>
+            h(
+              "button",
+              {
+                onClick: () => props.unstable_recordInteraction?.(interaction),
+              },
+              "retry",
+            ),
+        { props: ["unstable_recordInteraction"] },
+      );
+      const Register = defineComponent({
+        setup() {
+          useAssistantToolUI({ toolName: "weather", render: Tool });
+          return () => null;
+        },
+      });
+      const Message = () =>
+        h(MessagePrimitiveParts, {
+          components: kind === "override" ? { tools: { Override: Tool } } : {},
+        });
+      const App = defineComponent({
+        setup() {
+          const runtime = useExternalStoreRuntime({
+            messages: [
+              {
+                id: "message-1",
+                role: "assistant" as const,
+                content: [
+                  {
+                    type: "tool-call" as const,
+                    toolCallId: "call-1",
+                    toolName: "weather",
+                    args: {},
+                    argsText: "{}",
+                    result: {},
+                  },
+                ],
+              },
+            ],
+            convertMessage: (message) => message,
+            onNew: async () => {},
+            unstable_onRecordToolInteraction: recordInteraction,
+          });
+          return () =>
+            h(
+              AssistantRuntimeProvider,
+              { runtime },
+              {
+                default: () => [
+                  kind === "registered" ? h(Register) : null,
+                  h(ThreadPrimitiveMessages, { components: { Message } }),
+                ],
+              },
+            );
+        },
+      });
+      const view = render(h(App));
+      await vi.waitFor(() =>
+        expect(view.container.querySelector("button")).not.toBeNull(),
+      );
+      view.container.querySelector("button")!.click();
+      await vi.waitFor(() =>
+        expect(recordInteraction).toHaveBeenCalledExactlyOnceWith({
+          messageId: "message-1",
+          toolCallId: "call-1",
+          interaction: { ...interaction, occurredAt: 123 },
+        }),
+      );
+    },
+  );
+});

package/src/primitives/message/MessagePartsGrouped.tsx

@@ -0,0 +1,374 @@
+"use client";
+
+import {
+  computed,
+  defineComponent,
+  h,
+  type Component,
+  type ComponentPublicInstance,
+  type PublicProps,
+} from "vue";
+import { useAuiState } from "@ulearning/ai-store";
+import { PartByIndexProvider } from "../../context/providers/PartByIndexProvider";
+import { TextMessagePartProvider } from "../../context/providers/TextMessagePartProvider";
+import { MessagePartPrimitiveText } from "../messagePart/MessagePartText";
+import { MessagePartPrimitiveImage } from "../messagePart/MessagePartImage";
+import {
+  MessagePartComponent,
+  type Unstable_AudioMessagePartComponent,
+  type DataMessagePartComponent,
+  type EmptyMessagePartComponent,
+  type TextMessagePartComponent,
+  type ImageMessagePartComponent,
+  type SourceMessagePartComponent,
+  type ToolCallMessagePartComponent,
+  type FileMessagePartComponent,
+  type ReasoningMessagePartComponent,
+} from "@ulearning/ai-core/vue";
+import { MessagePartPrimitiveInProgress } from "../messagePart/MessagePartInProgress";
+import type { MessagePartStatus } from "@ulearning/ai-core";
+import { getMessagePartKeys } from "@ulearning/ai-core/internal";
+
+type MessagePartGroup = {
+  groupKey: string | undefined;
+  indices: number[];
+};
+
+export type GroupingFunction = (parts: readonly any[]) => MessagePartGroup[];
+
+/**
+ * Groups message parts by their parent ID.
+ * Parts without a parent ID appear in their chronological position as individual groups.
+ * Parts with the same parent ID are grouped together at the position of their first occurrence.
+ */
+const groupMessagePartsByParentId: GroupingFunction = (
+  parts: readonly any[],
+): MessagePartGroup[] => {
+  // Map maintains insertion order, so groups appear in order of first occurrence
+  const groupMap = new Map<string | number, number[]>();
+
+  // Process each part in order
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i];
+    const parentId = part?.parentId as string | undefined;
+
+    // For parts without parentId, assign a unique group ID to maintain their position
+    const groupId = parentId ?? i;
+
+    // Get or create the indices array for this group
+    const indices = groupMap.get(groupId) ?? [];
+    indices.push(i);
+    groupMap.set(groupId, indices);
+  }
+
+  // Convert map to array of groups
+  const groups: MessagePartGroup[] = [];
+  for (const [groupId, indices] of groupMap) {
+    // Extract parentId (undefined for ungrouped parts)
+    const groupKey = typeof groupId === "string" ? groupId : undefined;
+    groups.push({ groupKey, indices });
+  }
+
+  return groups;
+};
+
+/**
+ * @deprecated Prefer `<MessagePrimitive.GroupedParts>` for adjacent
+ * grouping — it dispatches all rendering through one `switch (part.type)`
+ * and supports nested group paths. Keep this primitive only for
+ * non-adjacent clustering (e.g., gathering parts with the same parent-id
+ * across the message).
+ */
+export namespace MessagePrimitiveUnstable_PartsGrouped {
+  export type Props = {
+    /**
+     * Function that takes an array of message parts and returns an array of groups.
+     * Each group contains a key (for identification) and an array of indices.
+     *
+     * @example
+     * ```tsx
+     * // Group by parent ID (default behavior)
+     * groupingFunction={(parts) => {
+     *   const groups = new Map<string | number, number[]>();
+     *   parts.forEach((part, i) => {
+     *     const key = part.parentId ?? i;
+     *     const indices = groups.get(key) ?? [];
+     *     indices.push(i);
+     *     groups.set(key, indices);
+     *   });
+     *   return Array.from(groups.entries()).map(([key, indices]) => ({
+     *     groupKey: typeof key === "string" ? key : undefined,
+     *     indices
+     *   }));
+     * }}
+     * ```
+     *
+     * @example
+     * ```tsx
+     * // Group by tool name
+     * import { groupMessagePartsByToolName } from "@ulearning/ai-sdk";
+     *
+     * <MessagePrimitive.Unstable_PartsGrouped
+     *   groupingFunction={groupMessagePartsByToolName}
+     *   components={{
+     *     Group: ({ key, indices, children }) => {
+     *       if (!key) return <>{children}</>;
+     *       return (
+     *         <div className="tool-group">
+     *           <h4>Tool: {key}</h4>
+     *           {children}
+     *         </div>
+     *       );
+     *     }
+     *   }}
+     * />
+     * ```
+     */
+    groupingFunction: GroupingFunction;
+
+    /**
+     * Component configuration for rendering different types of message content.
+     *
+     * You can provide custom components for each content type (text, image, file, etc.)
+     * and configure tool rendering behavior. If not provided, default components will be used.
+     */
+    components:
+      | {
+          /** Component for rendering empty messages */
+          Empty?: EmptyMessagePartComponent | undefined;
+          /** Component for rendering text content */
+          Text?: TextMessagePartComponent | undefined;
+          /** Component for rendering reasoning content (typically hidden) */
+          Reasoning?: ReasoningMessagePartComponent | undefined;
+          /** Component for rendering source content */
+          Source?: SourceMessagePartComponent | undefined;
+          /** Component for rendering image content */
+          Image?: ImageMessagePartComponent | undefined;
+          /** Component for rendering file content */
+          File?: FileMessagePartComponent | undefined;
+          /**
+           * Component for rendering audio content.
+           *
+           * @deprecated Render audio through the `File` slot instead, branching
+           * on an `audio/*` mime type.
+           */
+          Unstable_Audio?: Unstable_AudioMessagePartComponent | undefined;
+          /** Configuration for data part rendering */
+          data?:
+            | {
+                /** Map data event names to specific components */
+                by_name?:
+                  | Record<string, DataMessagePartComponent | undefined>
+                  | undefined;
+                /** Fallback component for unmatched data events */
+                Fallback?: DataMessagePartComponent | undefined;
+              }
+            | undefined;
+          /** Configuration for tool call rendering */
+          tools?:
+            | {
+                /** Map of tool names to their specific components */
+                by_name?:
+                  | Record<string, ToolCallMessagePartComponent | undefined>
+                  | undefined;
+                /** Fallback component for unregistered tools */
+                Fallback?: ToolCallMessagePartComponent | undefined;
+              }
+            | {
+                /** Override component that handles all tool calls */
+                Override: ToolCallMessagePartComponent;
+              }
+            | undefined;
+
+          /**
+           * Component for rendering grouped message parts.
+           *
+           * When provided, this component will automatically wrap message parts that share
+           * the same group key as determined by the groupingFunction.
+           *
+           * The component receives:
+           * - `groupKey`: The group key (or undefined for ungrouped parts)
+           * - `indices`: Array of indices for the parts in this group
+           * - `children`: The rendered message part components
+           *
+           * @example
+           * ```tsx
+           * // Collapsible group
+           * Group: ({ groupKey, indices, children }) => {
+           *   if (!groupKey) return <>{children}</>;
+           *   return (
+           *     <details className="message-group">
+           *       <summary>
+           *         Group {groupKey} ({indices.length} parts)
+           *       </summary>
+           *       <div className="group-content">
+           *         {children}
+           *       </div>
+           *     </details>
+           *   );
+           * }
+           * ```
+           *
+           * @param groupKey - The group key (undefined for ungrouped parts)
+           * @param indices - Array of indices for the parts in this group
+           * @param children - Rendered message part components to display within the group
+           */
+          Group?:
+            | Component
+            | (new (
+                props: {
+                  groupKey: string | undefined;
+                  indices: number[];
+                } & PublicProps,
+              ) => ComponentPublicInstance);
+        }
+      | undefined;
+  };
+}
+
+const defaultComponents = {
+  Text: defineComponent({
+    setup: () => () =>
+      h("p", { style: { whiteSpace: "pre-line" } }, [
+        h(MessagePartPrimitiveText),
+        h(MessagePartPrimitiveInProgress, null, {
+          default: () =>
+            h("span", { style: { fontFamily: "revert" } }, " \u25CF"),
+        }),
+      ]),
+  }),
+  Reasoning: () => null,
+  Source: () => null,
+  Image: defineComponent({ setup: () => () => h(MessagePartPrimitiveImage) }),
+  File: () => null,
+  Unstable_Audio: () => null,
+  Group: defineComponent({
+    inheritAttrs: false,
+    setup:
+      (_, { slots }) =>
+      () =>
+        slots.default?.(),
+  }),
+} satisfies MessagePrimitiveUnstable_PartsGrouped.Props["components"];
+
+const EmptyPartFallback = defineComponent(
+  (props: { status: MessagePartStatus; component: TextMessagePartComponent }) =>
+    () =>
+      h(
+        TextMessagePartProvider,
+        { text: "", isRunning: props.status.type === "running" },
+        {
+          default: () =>
+            h(props.component, {
+              type: "text",
+              text: "",
+              status: props.status,
+            }),
+        },
+      ),
+  { props: ["status", "component"] },
+);
+const COMPLETE_STATUS: MessagePartStatus = Object.freeze({ type: "complete" });
+const EmptyParts = defineComponent(
+  (props: {
+    components: MessagePrimitiveUnstable_PartsGrouped.Props["components"];
+  }) => {
+    const status = useAuiState(
+      (s) => (s.message.status ?? COMPLETE_STATUS) as MessagePartStatus,
+    );
+    return () =>
+      props.components?.Empty
+        ? h(props.components.Empty, { status: status.value })
+        : h(EmptyPartFallback, {
+            status: status.value,
+            component: props.components?.Text ?? defaultComponents.Text,
+          });
+  },
+  { props: ["components"] },
+);
+
+/**
+ * Non-adjacent clustering retains first-occurrence order and identified part keys.
+ * @deprecated Prefer MessagePrimitive.GroupedParts for adjacent grouping. This
+ * primitive retains non-adjacent clustering for existing callers.
+ */
+export const MessagePrimitiveUnstable_PartsGrouped = defineComponent(
+  (props: MessagePrimitiveUnstable_PartsGrouped.Props) => {
+    const parts = useAuiState((s) => s.message.parts);
+    const groups = computed(() =>
+      parts.value.length ? props.groupingFunction(parts.value) : [],
+    );
+    const keys = computed(() => getMessagePartKeys(parts.value));
+    const leafComponents = computed(() => ({
+      ...props.components,
+      Text: props.components?.Text ?? defaultComponents.Text,
+      Reasoning: props.components?.Reasoning ?? defaultComponents.Reasoning,
+      Image: props.components?.Image ?? defaultComponents.Image,
+      Source: props.components?.Source ?? defaultComponents.Source,
+      File: props.components?.File ?? defaultComponents.File,
+      Unstable_Audio:
+        props.components?.Unstable_Audio ?? defaultComponents.Unstable_Audio,
+    }));
+    return () => {
+      if (!parts.value.length)
+        return h(EmptyParts, { components: props.components });
+      const Group = props.components?.Group ?? defaultComponents.Group;
+      return groups.value.map((group, groupIndex) => {
+        const identity = keys.value[group.indices[0]!];
+        return h(
+          Group,
+          {
+            key: JSON.stringify([
+              "group",
+              group.groupKey ?? null,
+              identity?.includes(":") ? `id:${identity}` : groupIndex,
+            ]),
+            groupKey: group.groupKey,
+            indices: group.indices,
+          },
+          {
+            default: () =>
+              group.indices.map((index) =>
+                h(
+                  PartByIndexProvider,
+                  {
+                    key: keys.value[index]!,
+                    index,
+                  },
+                  {
+                    default: () =>
+                      h(MessagePartComponent, {
+                        components: leafComponents.value,
+                      }),
+                  },
+                ),
+              ),
+          },
+        );
+      });
+    };
+  },
+  {
+    name: "MessagePrimitive.Unstable_PartsGrouped",
+    props: ["groupingFunction", "components"],
+  },
+);
+
+/** @deprecated Use MessagePrimitive.Unstable_PartsGrouped for more flexibility. */
+export const MessagePrimitiveUnstable_PartsGroupedByParentId = defineComponent(
+  (
+    props: Omit<
+      MessagePrimitiveUnstable_PartsGrouped.Props,
+      "groupingFunction"
+    >,
+  ) =>
+    () =>
+      h(MessagePrimitiveUnstable_PartsGrouped, {
+        ...props,
+        groupingFunction: groupMessagePartsByParentId,
+      }),
+  {
+    name: "MessagePrimitive.Unstable_PartsGroupedByParentId",
+    props: ["components"],
+  },
+);

package/src/primitives/message/MessageRoot.anchors.test.ts

@@ -0,0 +1,167 @@
+// @vitest-environment jsdom
+import { defineComponent, h, nextTick, shallowRef } from "vue";
+import { afterEach, expect, it, vi } from "vitest";
+import { flushTapSync } from "@ulearning/ai-tap";
+import {
+  AssistantRuntimeProvider,
+  ThreadPrimitiveMessages,
+  useExternalStoreRuntime,
+} from "@ulearning/ai-core/vue";
+import type { ThreadMessageLike } from "@ulearning/ai-core";
+import { useAui } from "@ulearning/ai-store";
+import { cleanup, render } from "../../tests/vue";
+import { ThreadPrimitiveViewportProvider } from "../../context/providers/ThreadViewportProvider";
+import { useThreadViewportStore } from "../../context/vue/ThreadViewportContext";
+import { MessagePrimitiveRoot } from "./MessageRoot";
+
+afterEach(cleanup);
+
+it("releases top anchor and target registrations when the active turn changes and when its owner unmounts", async () => {
+  const running = shallowRef(true);
+  const messages: ThreadMessageLike[] = [
+    {
+      id: "earlier",
+      role: "assistant",
+      content: "previous",
+      status: { type: "complete", reason: "stop" },
+    },
+    { id: "anchor", role: "user", content: "next" },
+    {
+      id: "target",
+      role: "assistant",
+      content: "answer",
+      status: { type: "running" },
+    },
+  ];
+  let viewport!: NonNullable<ReturnType<typeof useThreadViewportStore>>;
+  const Message = defineComponent({
+    setup: () => () => h(MessagePrimitiveRoot),
+  });
+  const Rows = defineComponent({
+    setup() {
+      const store = useThreadViewportStore();
+      if (!store) throw new Error("Expected viewport provider");
+      viewport = store;
+      return () => h(ThreadPrimitiveMessages, { components: { Message } });
+    },
+  });
+  const view = render(
+    h(
+      defineComponent({
+        setup() {
+          const runtime = useExternalStoreRuntime(() => ({
+            messages,
+            convertMessage: (message: ThreadMessageLike) => message,
+            onNew: async () => {},
+            isRunning: running.value,
+          }));
+          return () =>
+            h(
+              AssistantRuntimeProvider,
+              { runtime },
+              {
+                default: () =>
+                  h(
+                    ThreadPrimitiveViewportProvider,
+                    {
+                      options: {
+                        turnAnchor: "top",
+                        topAnchorMessageClamp: {
+                          tallerThan: "200px",
+                          visibleHeight: "100px",
+                        },
+                      },
+                    },
+                    { default: () => h(Rows) },
+                  ),
+              },
+            );
+        },
+      }),
+    ),
+  );
+  await nextTick();
+  const anchor = view.container.querySelector<HTMLElement>(
+    '[data-message-id="anchor"]',
+  )!;
+  const target = view.container.querySelector<HTMLElement>(
+    '[data-message-id="target"]',
+  )!;
+  expect(viewport.getState().element.anchor).toBe(anchor);
+  expect(viewport.getState().element.target).toBe(target);
+  expect(viewport.getState().targetConfig).toEqual({
+    tallerThan: 200,
+    visibleHeight: 100,
+  });
+  viewport
+    .getState()
+    .setTopAnchorTurn({ anchorId: "anchor", targetId: "target" });
+  flushTapSync(() => {
+    running.value = false;
+  });
+  await nextTick();
+  expect(viewport.getState().element.anchor).toBe(anchor);
+  expect(viewport.getState().element.target).toBe(target);
+  viewport.getState().setTopAnchorTurn(null);
+  await nextTick();
+  expect(viewport.getState().element.anchor).toBeNull();
+  expect(viewport.getState().element.target).toBeNull();
+  expect(viewport.getState().targetConfig).toBeNull();
+  viewport
+    .getState()
+    .setTopAnchorTurn({ anchorId: "anchor", targetId: "target" });
+  await nextTick();
+  view.unmount();
+  expect(viewport.getState().element.anchor).toBeNull();
+  expect(viewport.getState().element.target).toBeNull();
+  expect(viewport.getState().targetConfig).toBeNull();
+});
+
+it("detaches hover listeners and ignores a late event from a removed message element", async () => {
+  const shown = shallowRef(true);
+  let aui!: ReturnType<typeof useAui>;
+  const Message = defineComponent({
+    setup() {
+      aui = useAui();
+      return () => (shown.value ? h(MessagePrimitiveRoot) : null);
+    },
+  });
+  const view = render(
+    h(
+      defineComponent({
+        setup() {
+          const runtime = useExternalStoreRuntime({
+            messages: [{ id: "message", role: "assistant", content: "text" }],
+            convertMessage: (message: ThreadMessageLike) => message,
+            onNew: async () => {},
+          });
+          return () =>
+            h(
+              AssistantRuntimeProvider,
+              { runtime },
+              {
+                default: () =>
+                  h(ThreadPrimitiveViewportProvider, null, {
+                    default: () =>
+                      h(ThreadPrimitiveMessages, { components: { Message } }),
+                  }),
+              },
+            );
+        },
+      }),
+    ),
+  );
+  await nextTick();
+  const element = view.container.querySelector<HTMLElement>(
+    '[data-message-id="message"]',
+  )!;
+  flushTapSync(() => element.dispatchEvent(new MouseEvent("mouseenter")));
+  await nextTick();
+  expect(aui.message.getState().isHovering).toBe(true);
+  shown.value = false;
+  await nextTick();
+  await vi.waitFor(() => expect(aui.message.getState().isHovering).toBe(false));
+  flushTapSync(() => element.dispatchEvent(new MouseEvent("mouseenter")));
+  await nextTick();
+  expect(aui.message.getState().isHovering).toBe(false);
+});