@assistant-ui/react 0.10.23 → 0.10.25

package/src/primitives/message/MessageParts.tsx

@@ -0,0 +1,423 @@
+"use client";
+
+import {
+  type ComponentType,
+  type FC,
+  memo,
+  PropsWithChildren,
+  useMemo,
+} from "react";
+import {
+  TextMessagePartProvider,
+  useMessagePart,
+  useMessagePartRuntime,
+  useToolUIs,
+} from "../../context";
+import {
+  useMessage,
+  useMessageRuntime,
+} from "../../context/react/MessageContext";
+import { MessagePartRuntimeProvider } from "../../context/providers/MessagePartRuntimeProvider";
+import { MessagePartPrimitiveText } from "../messagePart/MessagePartText";
+import { MessagePartPrimitiveImage } from "../messagePart/MessagePartImage";
+import type {
+  Unstable_AudioMessagePartComponent,
+  EmptyMessagePartComponent,
+  TextMessagePartComponent,
+  ImageMessagePartComponent,
+  SourceMessagePartComponent,
+  ToolCallMessagePartComponent,
+  ToolCallMessagePartProps,
+  FileMessagePartComponent,
+  ReasoningMessagePartComponent,
+} from "../../types/MessagePartComponentTypes";
+import { MessagePartPrimitiveInProgress } from "../messagePart/MessagePartInProgress";
+import { MessagePartStatus } from "../../types/AssistantTypes";
+import { useShallow } from "zustand/shallow";
+
+type MessagePartRange =
+  | { type: "single"; index: number }
+  | { type: "toolGroup"; startIndex: number; endIndex: number };
+
+/**
+ * Groups consecutive tool-call message parts into ranges.
+ * Always groups tool calls, even if there's only one.
+ */
+const groupMessageParts = (
+  messageTypes: readonly string[],
+): MessagePartRange[] => {
+  const ranges: MessagePartRange[] = [];
+  let currentToolGroupStart = -1;
+
+  for (let i = 0; i < messageTypes.length; i++) {
+    const type = messageTypes[i];
+
+    if (type === "tool-call") {
+      // Start a new tool group if we haven't started one
+      if (currentToolGroupStart === -1) {
+        currentToolGroupStart = i;
+      }
+    } else {
+      // End current tool group if it exists
+      if (currentToolGroupStart !== -1) {
+        ranges.push({
+          type: "toolGroup",
+          startIndex: currentToolGroupStart,
+          endIndex: i - 1,
+        });
+        currentToolGroupStart = -1;
+      }
+
+      // Add non-tool-call part individually
+      ranges.push({ type: "single", index: i });
+    }
+  }
+
+  // Handle any remaining tool group at the end
+  if (currentToolGroupStart !== -1) {
+    ranges.push({
+      type: "toolGroup",
+      startIndex: currentToolGroupStart,
+      endIndex: messageTypes.length - 1,
+    });
+  }
+
+  return ranges;
+};
+
+const useMessagePartsGroups = (): MessagePartRange[] => {
+  const messageTypes = useMessage(
+    useShallow((m) => m.content.map((c) => c.type)),
+  );
+
+  return useMemo(() => {
+    if (messageTypes.length === 0) {
+      return [];
+    }
+    return groupMessageParts(messageTypes);
+  }, [messageTypes]);
+};
+
+export namespace MessagePrimitiveParts {
+  export type Props = {
+    /**
+     * 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 (experimental) */
+          Unstable_Audio?: Unstable_AudioMessagePartComponent | 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?: ComponentType<ToolCallMessagePartProps> | undefined;
+              }
+            | {
+                /** Override component that handles all tool calls */
+                Override: ComponentType<ToolCallMessagePartProps>;
+              }
+            | undefined;
+
+          /**
+           * Component for rendering grouped consecutive tool calls.
+           *
+           * When provided, this component will automatically wrap consecutive tool-call
+           * message parts, allowing you to create collapsible sections, custom styling,
+           * or other grouped presentations for multiple tool calls.
+           *
+           * The component receives:
+           * - `startIndex`: The index of the first tool call in the group
+           * - `endIndex`: The index of the last tool call in the group
+           * - `children`: The rendered tool call components
+           *
+           * @example
+           * ```tsx
+           * // Collapsible tool group
+           * ToolGroup: ({ startIndex, endIndex, children }) => (
+           *   <details className="tool-group">
+           *     <summary>
+           *       {endIndex - startIndex + 1} tool calls
+           *     </summary>
+           *     <div className="tool-group-content">
+           *       {children}
+           *     </div>
+           *   </details>
+           * )
+           * ```
+           *
+           * @example
+           * ```tsx
+           * // Custom styled tool group with header
+           * ToolGroup: ({ startIndex, endIndex, children }) => (
+           *   <div className="border rounded-lg p-4 my-2">
+           *     <div className="text-sm text-gray-600 mb-2">
+           *       Tool execution #{startIndex + 1}-{endIndex + 1}
+           *     </div>
+           *     <div className="space-y-2">
+           *       {children}
+           *     </div>
+           *   </div>
+           * )
+           * ```
+           *
+           * @param startIndex - Index of the first tool call in the group
+           * @param endIndex - Index of the last tool call in the group
+           * @param children - Rendered tool call components to display within the group
+           *
+           * @deprecated This feature is still experimental and subject to change.
+           */
+          ToolGroup?: ComponentType<
+            PropsWithChildren<{ startIndex: number; endIndex: number }>
+          >;
+        }
+      | undefined;
+  };
+}
+
+const ToolUIDisplay = ({
+  Fallback,
+  ...props
+}: {
+  Fallback: ToolCallMessagePartComponent | undefined;
+} & ToolCallMessagePartProps) => {
+  const Render = useToolUIs((s) => s.getToolUI(props.toolName)) ?? Fallback;
+  if (!Render) return null;
+  return <Render {...props} />;
+};
+
+const defaultComponents = {
+  Text: () => (
+    <p style={{ whiteSpace: "pre-line" }}>
+      <MessagePartPrimitiveText />
+      <MessagePartPrimitiveInProgress>
+        <span style={{ fontFamily: "revert" }}>{" \u25CF"}</span>
+      </MessagePartPrimitiveInProgress>
+    </p>
+  ),
+  Reasoning: () => null,
+  Source: () => null,
+  Image: () => <MessagePartPrimitiveImage />,
+  File: () => null,
+  Unstable_Audio: () => null,
+  ToolGroup: ({ children }) => children,
+} satisfies MessagePrimitiveParts.Props["components"];
+
+type MessagePartComponentProps = {
+  components: MessagePrimitiveParts.Props["components"];
+};
+
+const MessagePartComponent: FC<MessagePartComponentProps> = ({
+  components: {
+    Text = defaultComponents.Text,
+    Reasoning = defaultComponents.Reasoning,
+    Image = defaultComponents.Image,
+    Source = defaultComponents.Source,
+    File = defaultComponents.File,
+    Unstable_Audio: Audio = defaultComponents.Unstable_Audio,
+    tools = {},
+  } = {},
+}) => {
+  const MessagePartRuntime = useMessagePartRuntime();
+
+  const part = useMessagePart();
+
+  const type = part.type;
+  if (type === "tool-call") {
+    const addResult = (result: any) => MessagePartRuntime.addToolResult(result);
+    if ("Override" in tools)
+      return <tools.Override {...part} addResult={addResult} />;
+    const Tool = tools.by_name?.[part.toolName] ?? tools.Fallback;
+    return <ToolUIDisplay {...part} Fallback={Tool} addResult={addResult} />;
+  }
+
+  if (part.status.type === "requires-action")
+    throw new Error("Encountered unexpected requires-action status");
+
+  switch (type) {
+    case "text":
+      return <Text {...part} />;
+
+    case "reasoning":
+      return <Reasoning {...part} />;
+
+    case "source":
+      return <Source {...part} />;
+
+    case "image":
+      // eslint-disable-next-line jsx-a11y/alt-text
+      return <Image {...part} />;
+
+    case "file":
+      return <File {...part} />;
+
+    case "audio":
+      return <Audio {...part} />;
+
+    default:
+      const unhandledType: never = type;
+      throw new Error(`Unknown message part type: ${unhandledType}`);
+  }
+};
+
+type MessagePartProps = {
+  partIndex: number;
+  components: MessagePrimitiveParts.Props["components"];
+};
+
+const MessagePartImpl: FC<MessagePartProps> = ({ partIndex, components }) => {
+  const messageRuntime = useMessageRuntime();
+  const runtime = useMemo(
+    () => messageRuntime.getMessagePartByIndex(partIndex),
+    [messageRuntime, partIndex],
+  );
+
+  return (
+    <MessagePartRuntimeProvider runtime={runtime}>
+      <MessagePartComponent components={components} />
+    </MessagePartRuntimeProvider>
+  );
+};
+
+const MessagePart = memo(
+  MessagePartImpl,
+  (prev, next) =>
+    prev.partIndex === next.partIndex &&
+    prev.components?.Text === next.components?.Text &&
+    prev.components?.Reasoning === next.components?.Reasoning &&
+    prev.components?.Source === next.components?.Source &&
+    prev.components?.Image === next.components?.Image &&
+    prev.components?.File === next.components?.File &&
+    prev.components?.Unstable_Audio === next.components?.Unstable_Audio &&
+    prev.components?.tools === next.components?.tools &&
+    prev.components?.ToolGroup === next.components?.ToolGroup,
+);
+
+const COMPLETE_STATUS: MessagePartStatus = Object.freeze({
+  type: "complete",
+});
+
+const EmptyPartFallback: FC<{
+  status: MessagePartStatus;
+  component: TextMessagePartComponent;
+}> = ({ status, component: Component }) => {
+  return (
+    <TextMessagePartProvider text="" isRunning={status.type === "running"}>
+      <Component type="text" text="" status={status} />
+    </TextMessagePartProvider>
+  );
+};
+
+const EmptyPartsImpl: FC<MessagePartComponentProps> = ({ components }) => {
+  const status =
+    useMessage((s) => s.status as MessagePartStatus) ?? COMPLETE_STATUS;
+
+  if (components?.Empty) return <components.Empty status={status} />;
+
+  return (
+    <EmptyPartFallback
+      status={status}
+      component={components?.Text ?? defaultComponents.Text}
+    />
+  );
+};
+
+const EmptyParts = memo(
+  EmptyPartsImpl,
+  (prev, next) =>
+    prev.components?.Empty === next.components?.Empty &&
+    prev.components?.Text === next.components?.Text,
+);
+
+/**
+ * Renders the parts of a message with support for multiple content types.
+ *
+ * This component automatically handles different types of message content including
+ * text, images, files, tool calls, and more. It provides a flexible component
+ * system for customizing how each content type is rendered.
+ *
+ * @example
+ * ```tsx
+ * <MessagePrimitive.Parts
+ *   components={{
+ *     Text: ({ text }) => <p className="message-text">{text}</p>,
+ *     Image: ({ image }) => <img src={image} alt="Message image" />,
+ *     tools: {
+ *       by_name: {
+ *         calculator: CalculatorTool,
+ *         weather: WeatherTool,
+ *       },
+ *       Fallback: DefaultToolComponent
+ *     }
+ *   }}
+ * />
+ * ```
+ */
+export const MessagePrimitiveParts: FC<MessagePrimitiveParts.Props> = ({
+  components,
+}) => {
+  const contentLength = useMessage((s) => s.content.length);
+  const messageRanges = useMessagePartsGroups();
+
+  const partsElements = useMemo(() => {
+    if (contentLength === 0) {
+      return <EmptyParts components={components} />;
+    }
+
+    return messageRanges.map((range) => {
+      if (range.type === "single") {
+        return (
+          <MessagePart
+            key={range.index}
+            partIndex={range.index}
+            components={components}
+          />
+        );
+      } else {
+        const ToolGroupComponent =
+          components!.ToolGroup ?? defaultComponents.ToolGroup;
+        return (
+          <ToolGroupComponent
+            key={range.startIndex}
+            startIndex={range.startIndex}
+            endIndex={range.endIndex}
+          >
+            {Array.from(
+              { length: range.endIndex - range.startIndex + 1 },
+              (_, i) => (
+                <MessagePart
+                  key={i}
+                  partIndex={range.startIndex + i}
+                  components={components}
+                />
+              ),
+            )}
+          </ToolGroupComponent>
+        );
+      }
+    });
+  }, [messageRanges, components, contentLength]);
+
+  return <>{partsElements}</>;
+};
+
+MessagePrimitiveParts.displayName = "MessagePrimitive.Parts";

package/src/primitives/message/MessageRoot.tsx

@@ -41,9 +41,31 @@ const useIsHoveringRef = () => {
 
 export namespace MessagePrimitiveRoot {
   export type Element = ComponentRef<typeof Primitive.div>;
+  /**
+   * Props for the MessagePrimitive.Root component.
+   * Accepts all standard div element props.
+   */
   export type Props = ComponentPropsWithoutRef<typeof Primitive.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.
+ *
+ * @example
+ * ```tsx
+ * <MessagePrimitive.Root>
+ *   <MessagePrimitive.Content />
+ *   <ActionBarPrimitive.Root>
+ *     <ActionBarPrimitive.Copy />
+ *     <ActionBarPrimitive.Edit />
+ *   </ActionBarPrimitive.Root>
+ * </MessagePrimitive.Root>
+ * ```
+ */
 export const MessagePrimitiveRoot = forwardRef<
   MessagePrimitiveRoot.Element,
   MessagePrimitiveRoot.Props

package/src/primitives/message/index.ts

@@ -1,5 +1,6 @@
 export { MessagePrimitiveRoot as Root } from "./MessageRoot";
+export { MessagePrimitiveParts as Parts } from "./MessageParts";
+export { MessagePrimitiveParts as Content } from "./MessageParts";
 export { MessagePrimitiveIf as If } from "./MessageIf";
-export { MessagePrimitiveContent as Content } from "./MessageContent";
 export { MessagePrimitiveAttachments as Attachments } from "./MessageAttachments";
 export { MessagePrimitiveError as Error } from "./MessageError";

package/src/primitives/messagePart/MessagePartImage.tsx

@@ -0,0 +1,39 @@
+"use client";
+
+import { Primitive } from "@radix-ui/react-primitive";
+import { type ComponentRef, forwardRef, ComponentPropsWithoutRef } from "react";
+import { useMessagePartImage } from "./useMessagePartImage";
+
+export namespace MessagePartPrimitiveImage {
+  export type Element = ComponentRef<typeof Primitive.img>;
+  /**
+   * Props for the MessagePartPrimitive.Image component.
+   * Accepts all standard img element props.
+   */
+  export type Props = ComponentPropsWithoutRef<typeof Primitive.img>;
+}
+
+/**
+ * Renders an image from the current message part context.
+ *
+ * This component displays image content from the current message part,
+ * automatically setting the src attribute from the message part's image data.
+ *
+ * @example
+ * ```tsx
+ * <MessagePartPrimitive.Image
+ *   alt="Generated image"
+ *   className="message-image"
+ *   style={{ maxWidth: '100%' }}
+ * />
+ * ```
+ */
+export const MessagePartPrimitiveImage = forwardRef<
+  MessagePartPrimitiveImage.Element,
+  MessagePartPrimitiveImage.Props
+>((props, forwardedRef) => {
+  const { image } = useMessagePartImage();
+  return <Primitive.img src={image} {...props} ref={forwardedRef} />;
+});
+
+MessagePartPrimitiveImage.displayName = "MessagePartPrimitive.Image";

package/src/primitives/messagePart/MessagePartInProgress.tsx

@@ -0,0 +1,19 @@
+"use client";
+
+import { FC, PropsWithChildren } from "react";
+import { useMessagePart } from "../../context";
+
+export namespace MessagePartPrimitiveInProgress {
+  export type Props = PropsWithChildren;
+}
+
+// TODO should this be renamed to IsRunning?
+export const MessagePartPrimitiveInProgress: FC<
+  MessagePartPrimitiveInProgress.Props
+> = ({ children }) => {
+  const isInProgress = useMessagePart((c) => c.status.type === "running");
+
+  return isInProgress ? children : null;
+};
+
+MessagePartPrimitiveInProgress.displayName = "MessagePartPrimitive.InProgress";

package/src/primitives/messagePart/MessagePartText.tsx

@@ -0,0 +1,62 @@
+"use client";
+
+import { Primitive } from "@radix-ui/react-primitive";
+import {
+  type ComponentRef,
+  forwardRef,
+  ComponentPropsWithoutRef,
+  ElementType,
+} from "react";
+import { useMessagePartText } from "./useMessagePartText";
+import { useSmooth } from "../../utils/smooth/useSmooth";
+
+export namespace MessagePartPrimitiveText {
+  export type Element = ComponentRef<typeof Primitive.span>;
+  export type Props = Omit<
+    ComponentPropsWithoutRef<typeof Primitive.span>,
+    "children" | "asChild"
+  > & {
+    /**
+     * Whether to enable smooth text streaming animation.
+     * When enabled, text appears with a typing effect as it streams in.
+     * @default true
+     */
+    smooth?: boolean;
+    /**
+     * The HTML element or React component to render as.
+     * @default "span"
+     */
+    component?: ElementType;
+  };
+}
+
+/**
+ * Renders the text content of a message part with optional smooth streaming.
+ *
+ * This component displays text content from the current message part context,
+ * with support for smooth streaming animation that shows text appearing
+ * character by character as it's generated.
+ *
+ * @example
+ * ```tsx
+ * <MessagePartPrimitive.Text
+ *   smooth={true}
+ *   component="p"
+ *   className="message-text"
+ * />
+ * ```
+ */
+export const MessagePartPrimitiveText = forwardRef<
+  MessagePartPrimitiveText.Element,
+  MessagePartPrimitiveText.Props
+>(({ smooth = true, component: Component = "span", ...rest }, forwardedRef) => {
+  const { text, status } = useSmooth(useMessagePartText(), smooth);
+
+  return (
+    <Component data-status={status.type} {...rest} ref={forwardedRef}>
+      {text}
+    </Component>
+  );
+});
+
+MessagePartPrimitiveText.displayName = "MessagePartPrimitive.Text";

package/src/primitives/messagePart/index.ts

@@ -0,0 +1,3 @@
+export { MessagePartPrimitiveText as Text } from "./MessagePartText";
+export { MessagePartPrimitiveImage as Image } from "./MessagePartImage";
+export { MessagePartPrimitiveInProgress as InProgress } from "./MessagePartInProgress";

package/src/primitives/messagePart/useMessagePartFile.tsx

@@ -0,0 +1,18 @@
+"use client";
+
+import { MessagePartState } from "../../api/MessagePartRuntime";
+import { useMessagePart } from "../../context/react/MessagePartContext";
+import { FileMessagePart } from "../../types";
+
+export const useMessagePartFile = () => {
+  const file = useMessagePart((c) => {
+    if (c.type !== "file")
+      throw new Error(
+        "MessagePartFile can only be used inside file message parts.",
+      );
+
+    return c as MessagePartState & FileMessagePart;
+  });
+
+  return file;
+};

package/src/primitives/messagePart/useMessagePartImage.tsx

@@ -0,0 +1,18 @@
+"use client";
+
+import { MessagePartState } from "../../api/MessagePartRuntime";
+import { useMessagePart } from "../../context/react/MessagePartContext";
+import { ImageMessagePart } from "../../types";
+
+export const useMessagePartImage = () => {
+  const image = useMessagePart((c) => {
+    if (c.type !== "image")
+      throw new Error(
+        "MessagePartImage can only be used inside image message parts.",
+      );
+
+    return c as MessagePartState & ImageMessagePart;
+  });
+
+  return image;
+};

package/src/primitives/messagePart/useMessagePartReasoning.tsx

@@ -0,0 +1,18 @@
+"use client";
+
+import { MessagePartState } from "../../api/MessagePartRuntime";
+import { useMessagePart } from "../../context/react/MessagePartContext";
+import { ReasoningMessagePart } from "../../types";
+
+export const useMessagePartReasoning = () => {
+  const text = useMessagePart((c) => {
+    if (c.type !== "reasoning")
+      throw new Error(
+        "MessagePartReasoning can only be used inside reasoning message parts.",
+      );
+
+    return c as MessagePartState & ReasoningMessagePart;
+  });
+
+  return text;
+};

package/src/primitives/messagePart/useMessagePartSource.tsx

@@ -0,0 +1,18 @@
+"use client";
+
+import { MessagePartState } from "../../api/MessagePartRuntime";
+import { useMessagePart } from "../../context/react/MessagePartContext";
+import { SourceMessagePart } from "../../types";
+
+export const useMessagePartSource = () => {
+  const source = useMessagePart((c) => {
+    if (c.type !== "source")
+      throw new Error(
+        "MessagePartSource can only be used inside source message parts.",
+      );
+
+    return c as MessagePartState & SourceMessagePart;
+  });
+
+  return source;
+};

package/src/primitives/messagePart/useMessagePartText.tsx

@@ -0,0 +1,18 @@
+"use client";
+
+import { MessagePartState } from "../../api/MessagePartRuntime";
+import { useMessagePart } from "../../context/react/MessagePartContext";
+import { TextMessagePart, ReasoningMessagePart } from "../../types";
+
+export const useMessagePartText = () => {
+  const text = useMessagePart((c) => {
+    if (c.type !== "text" && c.type !== "reasoning")
+      throw new Error(
+        "MessagePartText can only be used inside text or reasoning message parts.",
+      );
+
+    return c as MessagePartState & (TextMessagePart | ReasoningMessagePart);
+  });
+
+  return text;
+};