@assistant-ui/react 0.10.23 → 0.10.24

package/src/primitives/branchPicker/BranchPickerRoot.tsx

@@ -7,10 +7,32 @@ import { If } from "../message";
 export namespace BranchPickerPrimitiveRoot {
   export type Element = ComponentRef<typeof Primitive.div>;
   export type Props = ComponentPropsWithoutRef<typeof Primitive.div> & {
+    /**
+     * Whether to hide the branch picker when there's only one branch available.
+     * When true, the component will only render when multiple branches exist.
+     * @default false
+     */
     hideWhenSingleBranch?: boolean | undefined;
   };
 }
 
+/**
+ * The root container for branch picker components.
+ *
+ * This component provides a container for branch navigation controls,
+ * with optional conditional rendering based on the number of available branches.
+ * It integrates with the message branching system to allow users to navigate
+ * between different response variations.
+ *
+ * @example
+ * ```tsx
+ * <BranchPickerPrimitive.Root hideWhenSingleBranch={true}>
+ *   <BranchPickerPrimitive.Previous />
+ *   <BranchPickerPrimitive.Count />
+ *   <BranchPickerPrimitive.Next />
+ * </BranchPickerPrimitive.Root>
+ * ```
+ */
 export const BranchPickerPrimitiveRoot = forwardRef<
   BranchPickerPrimitiveRoot.Element,
   BranchPickerPrimitiveRoot.Props

package/src/primitives/composer/ComposerAttachments.tsx

@@ -79,13 +79,17 @@ export const ComposerPrimitiveAttachments: FC<
 > = ({ components }) => {
   const attachmentsCount = useComposer((s) => s.attachments.length);
 
-  return Array.from({ length: attachmentsCount }, (_, index) => (
-    <ComposerAttachment
-      key={index}
-      attachmentIndex={index}
-      components={components}
-    />
-  ));
+  const attachmentElements = useMemo(() => {
+    return Array.from({ length: attachmentsCount }, (_, index) => (
+      <ComposerAttachment
+        key={index}
+        attachmentIndex={index}
+        components={components}
+      />
+    ));
+  }, [attachmentsCount, components]);
+
+  return attachmentElements;
 };
 
 ComposerPrimitiveAttachments.displayName = "ComposerPrimitive.Attachments";

package/src/primitives/composer/ComposerCancel.tsx

@@ -22,9 +22,26 @@ const useComposerCancel = () => {
 
 export namespace ComposerPrimitiveCancel {
   export type Element = ActionButtonElement;
+  /**
+   * Props for the ComposerPrimitive.Cancel component.
+   * Inherits all button element props and action button functionality.
+   */
   export type Props = ActionButtonProps<typeof useComposerCancel>;
 }
 
+/**
+ * A button component that cancels the current message composition.
+ *
+ * This component automatically handles the cancel functionality and is disabled
+ * when canceling is not available.
+ *
+ * @example
+ * ```tsx
+ * <ComposerPrimitive.Cancel>
+ *   Cancel
+ * </ComposerPrimitive.Cancel>
+ * ```
+ */
 export const ComposerPrimitiveCancel = createActionButton(
   "ComposerPrimitive.Cancel",
   useComposerCancel,

package/src/primitives/composer/ComposerInput.tsx

@@ -26,16 +26,60 @@ import { useThreadListItemRuntime } from "../../context/react/ThreadListItemCont
 export namespace ComposerPrimitiveInput {
   export type Element = HTMLTextAreaElement;
   export type Props = TextareaAutosizeProps & {
+    /**
+     * Whether to render as a child component using Slot.
+     * When true, the component will merge its props with its child.
+     */
     asChild?: boolean | undefined;
+    /**
+     * Whether to submit the message when Enter is pressed (without Shift).
+     * @default true
+     */
     submitOnEnter?: boolean | undefined;
+    /**
+     * Whether to cancel message composition when Escape is pressed.
+     * @default true
+     */
     cancelOnEscape?: boolean | undefined;
+    /**
+     * Whether to automatically focus the input when a new run starts.
+     * @default true
+     */
     unstable_focusOnRunStart?: boolean | undefined;
+    /**
+     * Whether to automatically focus the input when scrolling to bottom.
+     * @default true
+     */
     unstable_focusOnScrollToBottom?: boolean | undefined;
+    /**
+     * Whether to automatically focus the input when switching threads.
+     * @default true
+     */
     unstable_focusOnThreadSwitched?: boolean | undefined;
+    /**
+     * Whether to automatically add pasted files as attachments.
+     * @default true
+     */
     addAttachmentOnPaste?: boolean | undefined;
   };
 }
 
+/**
+ * A text input component for composing messages.
+ *
+ * This component provides a rich text input experience with automatic resizing,
+ * keyboard shortcuts, file paste support, and intelligent focus management.
+ * It integrates with the composer context to manage message state and submission.
+ *
+ * @example
+ * ```tsx
+ * <ComposerPrimitive.Input
+ *   placeholder="Type your message..."
+ *   submitOnEnter={true}
+ *   addAttachmentOnPaste={true}
+ * />
+ * ```
+ */
 export const ComposerPrimitiveInput = forwardRef<
   ComposerPrimitiveInput.Element,
   ComposerPrimitiveInput.Props

package/src/primitives/composer/ComposerRoot.tsx

@@ -12,9 +12,28 @@ import { useComposerSend } from "./ComposerSend";
 
 export namespace ComposerPrimitiveRoot {
   export type Element = ComponentRef<typeof Primitive.form>;
+  /**
+   * Props for the ComposerPrimitive.Root component.
+   * Accepts all standard form element props.
+   */
   export type Props = ComponentPropsWithoutRef<typeof Primitive.form>;
 }
 
+/**
+ * The root form container for message composition.
+ *
+ * This component provides a form wrapper that handles message submission when the form
+ * is submitted (e.g., via Enter key or submit button). It automatically prevents the
+ * default form submission and triggers the composer's send functionality.
+ *
+ * @example
+ * ```tsx
+ * <ComposerPrimitive.Root>
+ *   <ComposerPrimitive.Input placeholder="Type your message..." />
+ *   <ComposerPrimitive.Send>Send</ComposerPrimitive.Send>
+ * </ComposerPrimitive.Root>
+ * ```
+ */
 export const ComposerPrimitiveRoot = forwardRef<
   ComposerPrimitiveRoot.Element,
   ComposerPrimitiveRoot.Props

package/src/primitives/composer/ComposerSend.tsx

@@ -29,9 +29,27 @@ export const useComposerSend = () => {
 
 export namespace ComposerPrimitiveSend {
   export type Element = ActionButtonElement;
+  /**
+   * Props for the ComposerPrimitive.Send component.
+   * Inherits all button element props and action button functionality.
+   */
   export type Props = ActionButtonProps<typeof useComposerSend>;
 }
 
+/**
+ * A button component that sends the current message in the composer.
+ *
+ * This component automatically handles the send functionality and is disabled
+ * when sending is not available (e.g., when the thread is running, the composer
+ * is empty, or not in editing mode).
+ *
+ * @example
+ * ```tsx
+ * <ComposerPrimitive.Send>
+ *   Send Message
+ * </ComposerPrimitive.Send>
+ * ```
+ */
 export const ComposerPrimitiveSend = createActionButton(
   "ComposerPrimitive.Send",
   useComposerSend,

package/src/primitives/contentPart/ContentPartImage.tsx

@@ -6,9 +6,28 @@ import { useContentPartImage } from "./useContentPartImage";
 
 export namespace ContentPartPrimitiveImage {
   export type Element = ComponentRef<typeof Primitive.img>;
+  /**
+   * Props for the ContentPartPrimitive.Image component.
+   * Accepts all standard img element props.
+   */
   export type Props = ComponentPropsWithoutRef<typeof Primitive.img>;
 }
 
+/**
+ * Renders an image from the current content part context.
+ *
+ * This component displays image content from the current content part,
+ * automatically setting the src attribute from the content part's image data.
+ *
+ * @example
+ * ```tsx
+ * <ContentPartPrimitive.Image
+ *   alt="Generated image"
+ *   className="message-image"
+ *   style={{ maxWidth: '100%' }}
+ * />
+ * ```
+ */
 export const ContentPartPrimitiveImage = forwardRef<
   ContentPartPrimitiveImage.Element,
   ContentPartPrimitiveImage.Props

package/src/primitives/contentPart/ContentPartText.tsx

@@ -16,11 +16,36 @@ export namespace ContentPartPrimitiveText {
     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 content part with optional smooth streaming.
+ *
+ * This component displays text content from the current content part context,
+ * with support for smooth streaming animation that shows text appearing
+ * character by character as it's generated.
+ *
+ * @example
+ * ```tsx
+ * <ContentPartPrimitive.Text
+ *   smooth={true}
+ *   component="p"
+ *   className="message-text"
+ * />
+ * ```
+ */
 export const ContentPartPrimitiveText = forwardRef<
   ContentPartPrimitiveText.Element,
   ContentPartPrimitiveText.Props

package/src/primitives/message/MessageAttachments.tsx

@@ -80,13 +80,17 @@ export const MessagePrimitiveAttachments: FC<
     return message.attachments.length;
   });
 
-  return Array.from({ length: attachmentsCount }, (_, index) => (
-    <MessageAttachment
-      key={index}
-      attachmentIndex={index}
-      components={components}
-    />
-  ));
+  const attachmentElements = useMemo(() => {
+    return Array.from({ length: attachmentsCount }, (_, index) => (
+      <MessageAttachment
+        key={index}
+        attachmentIndex={index}
+        components={components}
+      />
+    ));
+  }, [attachmentsCount, components]);
+
+  return attachmentElements;
 };
 
 MessagePrimitiveAttachments.displayName = "MessagePrimitive.Attachments";

package/src/primitives/message/MessageContent.tsx

@@ -30,23 +30,40 @@ import { ContentPartStatus } from "../../types/AssistantTypes";
 
 export namespace MessagePrimitiveContent {
   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?: EmptyContentPartComponent | undefined;
+          /** Component for rendering text content */
           Text?: TextContentPartComponent | undefined;
+          /** Component for rendering reasoning content (typically hidden) */
           Reasoning?: ReasoningContentPartComponent | undefined;
+          /** Component for rendering source content */
           Source?: SourceContentPartComponent | undefined;
+          /** Component for rendering image content */
           Image?: ImageContentPartComponent | undefined;
+          /** Component for rendering file content */
           File?: FileContentPartComponent | undefined;
+          /** Component for rendering audio content (experimental) */
           Unstable_Audio?: Unstable_AudioContentPartComponent | undefined;
+          /** Configuration for tool call rendering */
           tools?:
             | {
+                /** Map of tool names to their specific components */
                 by_name?:
                   | Record<string, ToolCallContentPartComponent | undefined>
                   | undefined;
+                /** Fallback component for unregistered tools */
                 Fallback?: ComponentType<ToolCallContentPartProps> | undefined;
               }
             | {
+                /** Override component that handles all tool calls */
                 Override: ComponentType<ToolCallContentPartProps>;
               }
             | undefined;
@@ -212,30 +229,49 @@ const EmptyContent = memo(
     prev.components?.Text === next.components?.Text,
 );
 
+/**
+ * Renders the content 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.Content
+ *   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 MessagePrimitiveContent: FC<MessagePrimitiveContent.Props> = ({
   components,
 }) => {
   const contentLength = useMessage((s) => s.content.length);
 
-  if (contentLength === 0) {
-    return (
-      <>
-        <EmptyContent components={components} />
-      </>
-    );
-  }
+  const contentElements = useMemo(() => {
+    if (contentLength === 0) {
+      return <EmptyContent components={components} />;
+    }
+    return Array.from({ length: contentLength }, (_, index) => (
+      <MessageContentPart
+        key={index}
+        partIndex={index}
+        components={components}
+      />
+    ));
+  }, [contentLength, components]);
 
-  return (
-    <>
-      {Array.from({ length: contentLength }, (_, index) => (
-        <MessageContentPart
-          key={index}
-          partIndex={index}
-          components={components}
-        />
-      ))}
-    </>
-  );
+  return <>{contentElements}</>;
 };
 
 MessagePrimitiveContent.displayName = "MessagePrimitive.Content";

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/thread/ThreadMessages.tsx

@@ -8,25 +8,51 @@ import { ThreadMessage as ThreadMessageType } from "../../types";
 
 export namespace ThreadPrimitiveMessages {
   export type Props = {
+    /**
+     * Component configuration for rendering different types of messages and composers.
+     *
+     * You can provide either:
+     * 1. A single `Message` component that handles all message types
+     * 2. Specific components for `UserMessage` and `AssistantMessage` (with optional `SystemMessage`)
+     *
+     * Optional edit composer components can be provided to customize the editing experience
+     * for different message types when users edit their messages.
+     */
     components:
       | {
+          /** Component used to render all message types */
           Message: ComponentType;
+          /** Component used when editing any message type */
           EditComposer?: ComponentType | undefined;
+          /** Component used when editing user messages specifically */
           UserEditComposer?: ComponentType | undefined;
+          /** Component used when editing assistant messages specifically */
           AssistantEditComposer?: ComponentType | undefined;
+          /** Component used when editing system messages specifically */
           SystemEditComposer?: ComponentType | undefined;
+          /** Component used to render user messages specifically */
           UserMessage?: ComponentType | undefined;
+          /** Component used to render assistant messages specifically */
           AssistantMessage?: ComponentType | undefined;
+          /** Component used to render system messages specifically */
           SystemMessage?: ComponentType | undefined;
         }
       | {
+          /** Component used to render all message types (fallback) */
           Message?: ComponentType | undefined;
+          /** Component used when editing any message type */
           EditComposer?: ComponentType | undefined;
+          /** Component used when editing user messages specifically */
           UserEditComposer?: ComponentType | undefined;
+          /** Component used when editing assistant messages specifically */
           AssistantEditComposer?: ComponentType | undefined;
+          /** Component used when editing system messages specifically */
           SystemEditComposer?: ComponentType | undefined;
+          /** Component used to render user messages */
           UserMessage: ComponentType;
+          /** Component used to render assistant messages */
           AssistantMessage: ComponentType;
+          /** Component used to render system messages */
           SystemMessage?: ComponentType | undefined;
         };
   };
@@ -140,15 +166,37 @@ const ThreadMessage = memo(
     isComponentsSame(prev.components, next.components),
 );
 
+/**
+ * Renders all messages in the current thread using the provided component configuration.
+ *
+ * This component automatically renders all messages in the thread, providing the appropriate
+ * message context for each message. It handles different message types (user, assistant, system)
+ * and supports editing mode through the provided edit composer components.
+ *
+ * @example
+ * ```tsx
+ * <ThreadPrimitive.Messages
+ *   components={{
+ *     UserMessage: MyUserMessage,
+ *     AssistantMessage: MyAssistantMessage,
+ *     EditComposer: MyEditComposer
+ *   }}
+ * />
+ * ```
+ */
 export const ThreadPrimitiveMessagesImpl: FC<ThreadPrimitiveMessages.Props> = ({
   components,
 }) => {
   const messagesLength = useThread((t) => t.messages.length);
-  if (messagesLength === 0) return null;
 
-  return Array.from({ length: messagesLength }, (_, index) => (
-    <ThreadMessage key={index} messageIndex={index} components={components} />
-  ));
+  const messageElements = useMemo(() => {
+    if (messagesLength === 0) return null;
+    return Array.from({ length: messagesLength }, (_, index) => (
+      <ThreadMessage key={index} messageIndex={index} components={components} />
+    ));
+  }, [messagesLength, components]);
+
+  return messageElements;
 };
 
 ThreadPrimitiveMessagesImpl.displayName = "ThreadPrimitive.Messages";

package/src/primitives/thread/ThreadRoot.tsx

@@ -5,9 +5,28 @@ import { type ComponentRef, forwardRef, ComponentPropsWithoutRef } from "react";
 
 export namespace ThreadPrimitiveRoot {
   export type Element = ComponentRef<typeof Primitive.div>;
+  /**
+   * Props for the ThreadPrimitive.Root component.
+   * Accepts all standard div element props.
+   */
   export type Props = ComponentPropsWithoutRef<typeof Primitive.div>;
 }
 
+/**
+ * The root container component for a thread.
+ *
+ * This component serves as the foundational wrapper for all thread-related components.
+ * It provides the basic structure and context needed for thread functionality.
+ *
+ * @example
+ * ```tsx
+ * <ThreadPrimitive.Root>
+ *   <ThreadPrimitive.Viewport>
+ *     <ThreadPrimitive.Messages components={{ Message: MyMessage }} />
+ *   </ThreadPrimitive.Viewport>
+ * </ThreadPrimitive.Root>
+ * ```
+ */
 export const ThreadPrimitiveRoot = forwardRef<
   ThreadPrimitiveRoot.Element,
   ThreadPrimitiveRoot.Props

package/src/primitives/thread/ThreadViewport.tsx

@@ -9,6 +9,11 @@ import { ThreadViewportProvider } from "../../context/providers/ThreadViewportPr
 export namespace ThreadPrimitiveViewport {
   export type Element = ComponentRef<typeof Primitive.div>;
   export type Props = ComponentPropsWithoutRef<typeof Primitive.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 true
+     */
     autoScroll?: boolean | undefined;
   };
 }
@@ -33,6 +38,20 @@ const ThreadPrimitiveViewportScrollable = forwardRef<
 ThreadPrimitiveViewportScrollable.displayName =
   "ThreadPrimitive.ViewportScrollable";
 
+/**
+ * A scrollable viewport container for thread messages.
+ *
+ * This component provides a scrollable area for displaying thread messages with
+ * automatic scrolling capabilities. It manages the viewport state and provides
+ * context for child components to access viewport-related functionality.
+ *
+ * @example
+ * ```tsx
+ * <ThreadPrimitive.Viewport autoScroll={true}>
+ *   <ThreadPrimitive.Messages components={{ Message: MyMessage }} />
+ * </ThreadPrimitive.Viewport>
+ * ```
+ */
 export const ThreadPrimitiveViewport = forwardRef<
   ThreadPrimitiveViewport.Element,
   ThreadPrimitiveViewport.Props

package/src/primitives/threadList/ThreadListItems.tsx

@@ -58,14 +58,18 @@ export const ThreadListPrimitiveItems: FC<ThreadListPrimitiveItems.Props> = ({
     archived ? s.archivedThreads.length : s.threads.length,
   );
 
-  return Array.from({ length: contentLength }, (_, index) => (
-    <ThreadListItem
-      key={index}
-      partIndex={index}
-      archived={archived}
-      components={components}
-    />
-  ));
+  const listElements = useMemo(() => {
+    return Array.from({ length: contentLength }, (_, index) => (
+      <ThreadListItem
+        key={index}
+        partIndex={index}
+        archived={archived}
+        components={components}
+      />
+    ));
+  }, [contentLength, archived, components]);
+
+  return listElements;
 };
 
 ThreadListPrimitiveItems.displayName = "ThreadListPrimitive.Items";