@assistant-ui/react 0.10.23 → 0.10.25

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";

package/src/runtimes/adapters/attachment/AttachmentAdapter.ts

@@ -4,12 +4,68 @@ import {
   CompleteAttachment,
 } from "../../../types/AttachmentTypes";
 
+/**
+ * Interface for handling file attachments in the assistant runtime.
+ *
+ * AttachmentAdapter provides methods for managing file attachments throughout
+ * their lifecycle: adding, processing, removing, and sending attachments with messages.
+ *
+ * @example
+ * ```tsx
+ * const imageAdapter: AttachmentAdapter = {
+ *   accept: "image/*",
+ *
+ *   async add({ file }) {
+ *     return {
+ *       id: generateId(),
+ *       type: "image",
+ *       name: file.name,
+ *       file,
+ *       status: { type: "uploading" }
+ *     };
+ *   },
+ *
+ *   async remove(attachment) {
+ *     // Clean up resources
+ *   },
+ *
+ *   async send(attachment) {
+ *     const url = await uploadFile(attachment.file);
+ *     return { ...attachment, url, status: { type: "complete" } };
+ *   }
+ * };
+ * ```
+ */
 export type AttachmentAdapter = {
+  /**
+   * MIME type pattern for accepted file types (e.g., "image/*", "text/plain").
+   */
   accept: string;
 
+  /**
+   * Processes a file when it's added as an attachment.
+   *
+   * @param state - Object containing the file to process
+   * @param state.file - The File object to be attached
+   * @returns Promise or AsyncGenerator yielding PendingAttachment states
+   */
   add(state: {
     file: File;
   }): Promise<PendingAttachment> | AsyncGenerator<PendingAttachment, void>;
+
+  /**
+   * Removes an attachment and cleans up associated resources.
+   *
+   * @param attachment - The attachment to remove
+   * @returns Promise that resolves when removal is complete
+   */
   remove(attachment: Attachment): Promise<void>;
+
+  /**
+   * Finalizes an attachment for sending with a message.
+   *
+   * @param attachment - The pending attachment to finalize
+   * @returns Promise resolving to the complete attachment
+   */
   send(attachment: PendingAttachment): Promise<CompleteAttachment>;
 };

package/src/runtimes/adapters/feedback/FeedbackAdapter.ts

@@ -1,10 +1,43 @@
 import { ThreadMessage } from "../../../types/AssistantTypes";
 
+/**
+ * Feedback data structure for rating messages.
+ */
 type FeedbackAdapterFeedback = {
+  /** The message being rated */
   message: ThreadMessage;
+  /** The type of feedback being provided */
   type: "positive" | "negative";
 };
 
+/**
+ * Interface for handling user feedback on assistant messages.
+ *
+ * FeedbackAdapter allows users to provide positive or negative feedback
+ * on assistant responses, which can be used for analytics, model improvement,
+ * or user experience tracking.
+ *
+ * @example
+ * ```tsx
+ * const feedbackAdapter: FeedbackAdapter = {
+ *   submit: (feedback) => {
+ *     console.log(`User gave ${feedback.type} feedback on message:`, feedback.message.id);
+ *
+ *     // Send to analytics service
+ *     analytics.track('message_feedback', {
+ *       messageId: feedback.message.id,
+ *       feedbackType: feedback.type,
+ *       messageContent: feedback.message.content
+ *     });
+ *   }
+ * };
+ * ```
+ */
 export type FeedbackAdapter = {
+  /**
+   * Submits user feedback for a message.
+   *
+   * @param feedback - The feedback data containing message and rating type
+   */
   submit: (feedback: FeedbackAdapterFeedback) => void;
 };

package/src/runtimes/adapters/speech/SpeechAdapterTypes.ts

@@ -1,24 +1,71 @@
 import { Unsubscribe } from "../../../types";
 
+/**
+ * Types and interfaces for speech synthesis (text-to-speech) functionality.
+ */
 export namespace SpeechSynthesisAdapter {
+  /**
+   * Status of a speech synthesis operation.
+   */
   export type Status =
     | {
+        /** Speech is starting or currently running */
         type: "starting" | "running";
       }
     | {
+        /** Speech has ended */
         type: "ended";
+        /** Reason why speech ended */
         reason: "finished" | "cancelled" | "error";
+        /** Error details if speech ended due to error */
         error?: unknown;
       };
 
+  /**
+   * Represents a single speech utterance with control and status tracking.
+   */
   export type Utterance = {
+    /** Current status of the utterance */
     status: Status;
+    /** Cancel the current speech */
     cancel: () => void;
+    /** Subscribe to status changes */
     subscribe: (callback: () => void) => Unsubscribe;
   };
 }
 
+/**
+ * Interface for text-to-speech functionality.
+ *
+ * SpeechSynthesisAdapter provides the ability to convert text content
+ * into spoken audio, with status tracking and cancellation support.
+ *
+ * @example
+ * ```tsx
+ * const speechAdapter: SpeechSynthesisAdapter = {
+ *   speak: (text) => {
+ *     const utterance = new SpeechSynthesisUtterance(text);
+ *     speechSynthesis.speak(utterance);
+ *
+ *     return {
+ *       status: { type: "starting" },
+ *       cancel: () => speechSynthesis.cancel(),
+ *       subscribe: (callback) => {
+ *         utterance.addEventListener('end', callback);
+ *         return () => utterance.removeEventListener('end', callback);
+ *       }
+ *     };
+ *   }
+ * };
+ * ```
+ */
 export type SpeechSynthesisAdapter = {
+  /**
+   * Converts text to speech and returns an utterance object for control.
+   *
+   * @param text - The text content to speak
+   * @returns An utterance object with status and control methods
+   */
   speak: (text: string) => SpeechSynthesisAdapter.Utterance;
 };
 

package/src/runtimes/core/BaseThreadRuntimeCore.tsx

@@ -36,6 +36,7 @@ export abstract class BaseThreadRuntimeCore implements ThreadRuntimeCore {
   protected readonly repository = new MessageRepository();
   public abstract get adapters(): BaseThreadAdapters | undefined;
   public abstract get isDisabled(): boolean;
+  public abstract get isLoading(): boolean;
   public abstract get suggestions(): readonly ThreadSuggestion[];
   public abstract get extras(): unknown;
 

package/src/runtimes/core/ThreadListRuntimeCore.tsx

@@ -13,6 +13,7 @@ type ThreadListItemCoreState = {
 };
 
 export type ThreadListRuntimeCore = {
+  readonly isLoading: boolean;
   mainThreadId: string;
   newThreadId: string | undefined;
 

package/src/runtimes/core/ThreadRuntimeCore.tsx

@@ -101,6 +101,7 @@ export type ThreadRuntimeCore = Readonly<{
 
   capabilities: Readonly<RuntimeCapabilities>;
   isDisabled: boolean;
+  isLoading: boolean;
   messages: readonly ThreadMessage[];
   state: ReadonlyJSONValue;
   suggestions: readonly ThreadSuggestion[];

package/src/runtimes/external-store/ExternalStoreAdapter.tsx

@@ -20,6 +20,7 @@ export type ExternalStoreThreadListAdapter = {
    * @deprecated This API is still under active development and might change without notice.
    */
   threadId?: string | undefined;
+  isLoading?: boolean | undefined;
   threads?: readonly ExternalStoreThreadData<"regular">[] | undefined;
   archivedThreads?: readonly ExternalStoreThreadData<"archived">[] | undefined;
   /**
@@ -51,6 +52,7 @@ type ExternalStoreMessageConverterAdapter<T> = {
 type ExternalStoreAdapterBase<T> = {
   isDisabled?: boolean | undefined;
   isRunning?: boolean | undefined;
+  isLoading?: boolean | undefined;
   messages: readonly T[];
   suggestions?: readonly ThreadSuggestion[] | undefined;
   extras?: unknown;

package/src/runtimes/external-store/ExternalStoreThreadListRuntimeCore.tsx

@@ -24,6 +24,10 @@ export class ExternalStoreThreadListRuntimeCore
   private _threads: readonly string[] = DEFAULT_THREADS;
   private _archivedThreads: readonly string[] = EMPTY_ARRAY;
 
+  public get isLoading() {
+    return this.adapter.isLoading ?? false;
+  }
+
   public get newThreadId() {
     return undefined;
   }

package/src/runtimes/external-store/ExternalStoreThreadRuntimeCore.tsx

@@ -53,6 +53,9 @@ export class ExternalStoreThreadRuntimeCore
 
   private _messages!: readonly ThreadMessage[];
   public isDisabled!: boolean;
+  public get isLoading() {
+    return this._store.isLoading ?? false;
+  }
 
   public override get messages() {
     return this._messages;

package/src/runtimes/external-store/ThreadMessageLike.tsx

@@ -2,21 +2,21 @@ import { parsePartialJsonObject } from "assistant-stream/utils";
 import { generateId } from "../../internal";
 import {
   MessageStatus,
-  TextContentPart,
-  ImageContentPart,
+  TextMessagePart,
+  ImageMessagePart,
   ThreadMessage,
-  ThreadAssistantContentPart,
+  ThreadAssistantMessagePart,
   ThreadAssistantMessage,
-  ThreadUserContentPart,
+  ThreadUserMessagePart,
   ThreadUserMessage,
   ThreadSystemMessage,
   CompleteAttachment,
-  FileContentPart,
-  Unstable_AudioContentPart,
+  FileMessagePart,
+  Unstable_AudioMessagePart,
 } from "../../types";
 import {
-  ReasoningContentPart,
-  SourceContentPart,
+  ReasoningMessagePart,
+  SourceMessagePart,
   ThreadStep,
 } from "../../types/AssistantTypes";
 import { ReadonlyJSONObject, ReadonlyJSONValue } from "assistant-stream/utils";
@@ -26,12 +26,12 @@ export type ThreadMessageLike = {
   readonly content:
     | string
     | readonly (
-        | TextContentPart
-        | ReasoningContentPart
-        | SourceContentPart
-        | ImageContentPart
-        | FileContentPart
-        | Unstable_AudioContentPart
+        | TextMessagePart
+        | ReasoningMessagePart
+        | SourceMessagePart
+        | ImageMessagePart
+        | FileMessagePart
+        | Unstable_AudioMessagePart
         | {
             readonly type: "tool-call";
             readonly toolCallId?: string;
@@ -91,7 +91,7 @@ export const fromThreadMessageLike = (
         ...common,
         role,
         content: content
-          .map((part): ThreadAssistantContentPart | null => {
+          .map((part): ThreadAssistantMessagePart | null => {
             const type = part.type;
             switch (type) {
               case "text":
@@ -126,7 +126,7 @@ export const fromThreadMessageLike = (
               default: {
                 const unhandledType: "image" | "audio" = type;
                 throw new Error(
-                  `Unsupported assistant content part type: ${unhandledType}`,
+                  `Unsupported assistant message part type: ${unhandledType}`,
                 );
               }
             }
@@ -146,7 +146,7 @@ export const fromThreadMessageLike = (
       return {
         ...common,
         role,
-        content: content.map((part): ThreadUserContentPart => {
+        content: content.map((part): ThreadUserMessagePart => {
           const type = part.type;
           switch (type) {
             case "text":
@@ -158,7 +158,7 @@ export const fromThreadMessageLike = (
             default: {
               const unhandledType: "tool-call" | "reasoning" | "source" = type;
               throw new Error(
-                `Unsupported user content part type: ${unhandledType}`,
+                `Unsupported user message part type: ${unhandledType}`,
               );
             }
           }
@@ -172,13 +172,13 @@ export const fromThreadMessageLike = (
     case "system":
       if (content.length !== 1 || content[0]!.type !== "text")
         throw new Error(
-          "System messages must have exactly one text content part.",
+          "System messages must have exactly one text message part.",
         );
 
       return {
         ...common,
         role,
-        content: content as [TextContentPart],
+        content: content as [TextMessagePart],
         metadata: {
           custom: metadata?.custom ?? {},
         },

package/src/runtimes/external-store/createMessageConverter.tsx

@@ -1,6 +1,6 @@
 "use client";
 import { ThreadState } from "../../api";
-import { useContentPart, useMessage } from "../../context";
+import { useMessagePart, useMessage } from "../../context";
 import { ThreadMessage } from "../../types";
 import {
   useExternalMessageConverter,
@@ -50,13 +50,13 @@ export const createMessageConverter = <T extends object>(
       return first;
     },
     useOriginalMessages: () => {
-      const contentPartMessages = useContentPart<T[]>({
+      const MessagePartMessages = useMessagePart<T[]>({
         optional: true,
         selector: getExternalStoreMessages,
       });
 
       const messageMessages = useMessage<T[]>(getExternalStoreMessages);
-      const messages = contentPartMessages ?? messageMessages;
+      const messages = MessagePartMessages ?? messageMessages;
       if (messages.length === 0) throw new Error("No original messages found");
       return messages;
     },

package/src/runtimes/external-store/external-message-converter.tsx

@@ -8,7 +8,7 @@ import {
 } from "./getExternalStoreMessage";
 import { fromThreadMessageLike, ThreadMessageLike } from "./ThreadMessageLike";
 import { getAutoStatus, isAutoStatus } from "./auto-status";
-import { ToolCallContentPart } from "../../types";
+import { ToolCallMessagePart } from "../../types";
 
 export namespace useExternalMessageConverter {
   export type Message =
@@ -61,7 +61,7 @@ const joinExternalMessages = (
       if (toolCallIdx !== -1) {
         const toolCall = assistantMessage.content[
           toolCallIdx
-        ]! as ToolCallContentPart;
+        ]! as ToolCallMessagePart;
         if (output.toolName) {
           if (toolCall.toolName !== output.toolName)
             throw new Error(

package/src/runtimes/local/ChatModelAdapter.tsx

@@ -1,25 +1,25 @@
 import type {
-  FileContentPart,
+  FileMessagePart,
   MessageStatus,
-  ReasoningContentPart,
+  ReasoningMessagePart,
   RunConfig,
-  SourceContentPart,
-  TextContentPart,
-  ThreadAssistantContentPart,
+  SourceMessagePart,
+  TextMessagePart,
+  ThreadAssistantMessagePart,
   ThreadMessage,
   ThreadStep,
-  ToolCallContentPart,
+  ToolCallMessagePart,
 } from "../../types/AssistantTypes";
 import type { ModelContext } from "../../model-context/ModelContextTypes";
 import { ReadonlyJSONValue } from "assistant-stream/utils";
 
 export type ChatModelRunUpdate = {
-  readonly content: readonly ThreadAssistantContentPart[];
+  readonly content: readonly ThreadAssistantMessagePart[];
   readonly metadata?: Record<string, unknown>;
 };
 
 export type ChatModelRunResult = {
-  readonly content?: readonly ThreadAssistantContentPart[] | undefined;
+  readonly content?: readonly ThreadAssistantMessagePart[] | undefined;
   readonly status?: MessageStatus | undefined;
   readonly metadata?: {
     readonly unstable_state?: ReadonlyJSONValue;
@@ -32,11 +32,11 @@ export type ChatModelRunResult = {
 
 export type CoreChatModelRunResult = Omit<ChatModelRunResult, "content"> & {
   readonly content: readonly (
-    | TextContentPart
-    | ReasoningContentPart
-    | ToolCallContentPart
-    | SourceContentPart
-    | FileContentPart
+    | TextMessagePart
+    | ReasoningMessagePart
+    | ToolCallMessagePart
+    | SourceMessagePart
+    | FileMessagePart
   )[];
 };
 

package/src/runtimes/local/LocalRuntimeOptions.tsx

@@ -4,7 +4,7 @@ import { ThreadMessageLike } from "../external-store";
 import { FeedbackAdapter } from "../adapters/feedback/FeedbackAdapter";
 import { SpeechSynthesisAdapter } from "../adapters/speech/SpeechAdapterTypes";
 import { ChatModelAdapter } from "./ChatModelAdapter";
-import { AssistantCloud } from "../../cloud";
+import { AssistantCloud } from "assistant-cloud";
 import { SuggestionAdapter } from "../adapters";
 
 export type LocalRuntimeOptionsBase = {

package/src/runtimes/local/LocalThreadListRuntimeCore.tsx

@@ -16,6 +16,10 @@ export class LocalThreadListRuntimeCore
     this._mainThread = _threadFactory();
   }
 
+  public get isLoading() {
+    return false;
+  }
+
   public getMainThreadRuntimeCore() {
     return this._mainThread;
   }