@assistant-ui/react 0.10.23 → 0.10.25

package/src/primitives/actionBar/ActionBarCopy.tsx

@@ -12,6 +12,30 @@ import {
 } from "../../context/react/MessageContext";
 import { useComposerRuntime } from "../../context";
 
+/**
+ * Hook that provides copy functionality for action bar buttons.
+ *
+ * This hook returns a callback function that copies message content to the clipboard,
+ * or null if copying is not available. It handles both regular message content and
+ * composer text when in editing mode.
+ *
+ * @param options Configuration options
+ * @param options.copiedDuration Duration in milliseconds to show the copied state
+ * @returns A copy callback function, or null if copying is disabled
+ *
+ * @example
+ * ```tsx
+ * function CustomCopyButton() {
+ *   const copy = useActionBarPrimitiveCopy({ copiedDuration: 2000 });
+ *
+ *   return (
+ *     <button onClick={copy} disabled={!copy}>
+ *       {copy ? "Copy" : "Cannot Copy"}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
 const useActionBarPrimitiveCopy = ({
   copiedDuration = 3000,
 }: { copiedDuration?: number | undefined } = {}) => {
@@ -44,9 +68,27 @@ const useActionBarPrimitiveCopy = ({
 
 export namespace ActionBarPrimitiveCopy {
   export type Element = HTMLButtonElement;
+  /**
+   * Props for the ActionBarPrimitive.Copy component.
+   * Inherits all button element props and action button functionality.
+   */
   export type Props = ActionButtonProps<typeof useActionBarPrimitiveCopy>;
 }
 
+/**
+ * A button component that copies message content to the clipboard.
+ *
+ * This component automatically handles copying message text to the clipboard
+ * and provides visual feedback through the data-copied attribute. It's disabled
+ * when there's no copyable content available.
+ *
+ * @example
+ * ```tsx
+ * <ActionBarPrimitive.Copy copiedDuration={2000}>
+ *   Copy Message
+ * </ActionBarPrimitive.Copy>
+ * ```
+ */
 export const ActionBarPrimitiveCopy = forwardRef<
   ActionBarPrimitiveCopy.Element,
   ActionBarPrimitiveCopy.Props

package/src/primitives/actionBar/ActionBarEdit.tsx

@@ -8,6 +8,27 @@ import {
 import { useCallback } from "react";
 import { useEditComposer, useMessageRuntime } from "../../context";
 
+/**
+ * Hook that provides edit functionality for action bar buttons.
+ *
+ * This hook returns a callback function that starts editing the current message,
+ * or null if editing is not available (e.g., already in editing mode).
+ *
+ * @returns An edit callback function, or null if editing is disabled
+ *
+ * @example
+ * ```tsx
+ * function CustomEditButton() {
+ *   const edit = useActionBarEdit();
+ *
+ *   return (
+ *     <button onClick={edit} disabled={!edit}>
+ *       {edit ? "Edit Message" : "Cannot Edit"}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
 const useActionBarEdit = () => {
   const messageRuntime = useMessageRuntime();
   const disabled = useEditComposer((c) => c.isEditing);
@@ -22,9 +43,26 @@ const useActionBarEdit = () => {
 
 export namespace ActionBarPrimitiveEdit {
   export type Element = ActionButtonElement;
+  /**
+   * Props for the ActionBarPrimitive.Edit component.
+   * Inherits all button element props and action button functionality.
+   */
   export type Props = ActionButtonProps<typeof useActionBarEdit>;
 }
 
+/**
+ * A button component that starts editing the current message.
+ *
+ * This component automatically handles starting the edit mode for the current message
+ * and is disabled when editing is not available (e.g., already in editing mode).
+ *
+ * @example
+ * ```tsx
+ * <ActionBarPrimitive.Edit>
+ *   Edit Message
+ * </ActionBarPrimitive.Edit>
+ * ```
+ */
 export const ActionBarPrimitiveEdit = createActionButton(
   "ActionBarPrimitive.Edit",
   useActionBarEdit,

package/src/primitives/actionBar/ActionBarReload.tsx

@@ -10,6 +10,27 @@ import { useMessageRuntime } from "../../context";
 import { useThreadRuntime } from "../../context/react/ThreadContext";
 import { useCombinedStore } from "../../utils/combined/useCombinedStore";
 
+/**
+ * Hook that provides reload functionality for action bar buttons.
+ *
+ * This hook returns a callback function that reloads/regenerates the current assistant message,
+ * or null if reloading is not available (e.g., thread is running, disabled, or message is not from assistant).
+ *
+ * @returns A reload callback function, or null if reloading is disabled
+ *
+ * @example
+ * ```tsx
+ * function CustomReloadButton() {
+ *   const reload = useActionBarReload();
+ *
+ *   return (
+ *     <button onClick={reload} disabled={!reload}>
+ *       {reload ? "Reload Message" : "Cannot Reload"}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
 const useActionBarReload = () => {
   const messageRuntime = useMessageRuntime();
   const threadRuntime = useThreadRuntime();
@@ -29,9 +50,27 @@ const useActionBarReload = () => {
 
 export namespace ActionBarPrimitiveReload {
   export type Element = ActionButtonElement;
+  /**
+   * Props for the ActionBarPrimitive.Reload component.
+   * Inherits all button element props and action button functionality.
+   */
   export type Props = ActionButtonProps<typeof useActionBarReload>;
 }
 
+/**
+ * A button component that reloads/regenerates the current assistant message.
+ *
+ * This component automatically handles reloading the current assistant message
+ * and is disabled when reloading is not available (e.g., thread is running,
+ * disabled, or message is not from assistant).
+ *
+ * @example
+ * ```tsx
+ * <ActionBarPrimitive.Reload>
+ *   Reload Message
+ * </ActionBarPrimitive.Reload>
+ * ```
+ */
 export const ActionBarPrimitiveReload = createActionButton(
   "ActionBarPrimitive.Reload",
   useActionBarReload,

package/src/primitives/actionBar/ActionBarRoot.tsx

@@ -12,12 +12,50 @@ type PrimitiveDivProps = ComponentPropsWithoutRef<typeof Primitive.div>;
 export namespace ActionBarPrimitiveRoot {
   export type Element = ComponentRef<typeof Primitive.div>;
   export type Props = PrimitiveDivProps & {
+    /**
+     * Whether to hide the action bar when the thread is running.
+     * @default false
+     */
     hideWhenRunning?: boolean | undefined;
+    /**
+     * Controls when the action bar should automatically hide.
+     * - "always": Always hide unless hovered
+     * - "not-last": Hide unless this is the last message
+     * - "never": Never auto-hide
+     * @default "never"
+     */
     autohide?: "always" | "not-last" | "never" | undefined;
+    /**
+     * Controls floating behavior when auto-hidden.
+     * - "always": Always float when hidden
+     * - "single-branch": Float only for single-branch messages
+     * - "never": Never float
+     * @default "never"
+     */
     autohideFloat?: "always" | "single-branch" | "never" | undefined;
   };
 }
 
+/**
+ * The root container for action bar components.
+ *
+ * This component provides intelligent visibility and floating behavior for action bars,
+ * automatically hiding and showing based on message state, hover status, and configuration.
+ * It supports floating mode for better UX when space is limited.
+ *
+ * @example
+ * ```tsx
+ * <ActionBarPrimitive.Root
+ *   hideWhenRunning={true}
+ *   autohide="not-last"
+ *   autohideFloat="single-branch"
+ * >
+ *   <ActionBarPrimitive.Copy />
+ *   <ActionBarPrimitive.Edit />
+ *   <ActionBarPrimitive.Reload />
+ * </ActionBarPrimitive.Root>
+ * ```
+ */
 export const ActionBarPrimitiveRoot = forwardRef<
   ActionBarPrimitiveRoot.Element,
   ActionBarPrimitiveRoot.Props

package/src/primitives/assistantModal/AssistantModalContent.tsx

@@ -10,6 +10,9 @@ export namespace AssistantModalPrimitiveContent {
   export type Props = ComponentPropsWithoutRef<
     typeof PopoverPrimitive.Content
   > & {
+    portalProps?:
+      | ComponentPropsWithoutRef<typeof PopoverPrimitive.Portal>
+      | undefined;
     dissmissOnInteractOutside?: boolean | undefined;
   };
 }
@@ -25,6 +28,7 @@ export const AssistantModalPrimitiveContent = forwardRef<
       align,
       onInteractOutside,
       dissmissOnInteractOutside = false,
+      portalProps,
       ...props
     }: ScopedProps<AssistantModalPrimitiveContent.Props>,
     forwardedRef,
@@ -32,7 +36,7 @@ export const AssistantModalPrimitiveContent = forwardRef<
     const scope = usePopoverScope(__scopeAssistantModal);
 
     return (
-      <PopoverPrimitive.Portal {...scope}>
+      <PopoverPrimitive.Portal {...scope} {...portalProps}>
         <PopoverPrimitive.Content
           {...scope}
           {...props}

package/src/primitives/attachment/AttachmentRoot.tsx

@@ -7,9 +7,27 @@ type PrimitiveDivProps = ComponentPropsWithoutRef<typeof Primitive.div>;
 
 export namespace AttachmentPrimitiveRoot {
   export type Element = ComponentRef<typeof Primitive.div>;
+  /**
+   * Props for the AttachmentPrimitive.Root component.
+   * Accepts all standard div element props.
+   */
   export type Props = PrimitiveDivProps;
 }
 
+/**
+ * The root container component for an attachment.
+ *
+ * This component provides the foundational wrapper for attachment-related components
+ * and content. It serves as the context provider for attachment state and actions.
+ *
+ * @example
+ * ```tsx
+ * <AttachmentPrimitive.Root>
+ *   <AttachmentPrimitive.Name />
+ *   <AttachmentPrimitive.Remove />
+ * </AttachmentPrimitive.Root>
+ * ```
+ */
 export const AttachmentPrimitiveRoot = forwardRef<
   AttachmentPrimitiveRoot.Element,
   AttachmentPrimitiveRoot.Props

package/src/primitives/branchPicker/BranchPickerCount.tsx

@@ -9,9 +9,26 @@ const useBranchPickerCount = () => {
 };
 
 export namespace BranchPickerPrimitiveCount {
+  /**
+   * Props for the BranchPickerPrimitive.Count component.
+   * This component takes no props.
+   */
   export type Props = Record<string, never>;
 }
 
+/**
+ * A component that displays the total number of branches for the current message.
+ *
+ * This component renders the branch count as plain text, useful for showing
+ * users how many alternative responses are available.
+ *
+ * @example
+ * ```tsx
+ * <div>
+ *   Branch <BranchPickerPrimitive.Count /> of {totalBranches}
+ * </div>
+ * ```
+ */
 export const BranchPickerPrimitiveCount: FC<
   BranchPickerPrimitiveCount.Props
 > = () => {

package/src/primitives/branchPicker/BranchPickerNext.tsx

@@ -25,9 +25,26 @@ const useBranchPickerNext = () => {
 
 export namespace BranchPickerPrimitiveNext {
   export type Element = ActionButtonElement;
+  /**
+   * Props for the BranchPickerPrimitive.Next component.
+   * Inherits all button element props and action button functionality.
+   */
   export type Props = ActionButtonProps<typeof useBranchPickerNext>;
 }
 
+/**
+ * A button component that navigates to the next branch in the message tree.
+ *
+ * This component automatically handles switching to the next available branch
+ * and is disabled when there are no more branches to navigate to.
+ *
+ * @example
+ * ```tsx
+ * <BranchPickerPrimitive.Next>
+ *   Next →
+ * </BranchPickerPrimitive.Next>
+ * ```
+ */
 export const BranchPickerPrimitiveNext = createActionButton(
   "BranchPickerPrimitive.Next",
   useBranchPickerNext,

package/src/primitives/branchPicker/BranchPickerPrevious.tsx

@@ -11,6 +11,27 @@ import {
   useMessageRuntime,
 } from "../../context/react/MessageContext";
 
+/**
+ * Hook that provides navigation to the previous branch functionality.
+ *
+ * This hook returns a callback function that switches to the previous branch
+ * in the message branch tree, or null if there is no previous branch available.
+ *
+ * @returns A previous branch callback function, or null if navigation is disabled
+ *
+ * @example
+ * ```tsx
+ * function CustomPreviousButton() {
+ *   const previous = useBranchPickerPrevious();
+ *
+ *   return (
+ *     <button onClick={previous} disabled={!previous}>
+ *       {previous ? "Previous Branch" : "No Previous Branch"}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
 const useBranchPickerPrevious = () => {
   const messageRuntime = useMessageRuntime();
   const disabled = useMessage((m) => m.branchNumber <= 1);
@@ -25,9 +46,26 @@ const useBranchPickerPrevious = () => {
 
 export namespace BranchPickerPrimitivePrevious {
   export type Element = ActionButtonElement;
+  /**
+   * Props for the BranchPickerPrimitive.Previous component.
+   * Inherits all button element props and action button functionality.
+   */
   export type Props = ActionButtonProps<typeof useBranchPickerPrevious>;
 }
 
+/**
+ * A button component that navigates to the previous branch in the message tree.
+ *
+ * This component automatically handles switching to the previous available branch
+ * and is disabled when there are no previous branches to navigate to.
+ *
+ * @example
+ * ```tsx
+ * <BranchPickerPrimitive.Previous>
+ *   ← Previous
+ * </BranchPickerPrimitive.Previous>
+ * ```
+ */
 export const BranchPickerPrimitivePrevious = createActionButton(
   "BranchPickerPrimitive.Previous",
   useBranchPickerPrevious,

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/index.ts

@@ -3,16 +3,24 @@ export * as AssistantModalPrimitive from "./assistantModal";
 export * as AttachmentPrimitive from "./attachment";
 export * as BranchPickerPrimitive from "./branchPicker";
 export * as ComposerPrimitive from "./composer";
-export * as ContentPartPrimitive from "./contentPart";
+export * as MessagePartPrimitive from "./messagePart";
 export * as ErrorPrimitive from "./error";
 export * as MessagePrimitive from "./message";
 export * as ThreadPrimitive from "./thread";
 export * as ThreadListPrimitive from "./threadList";
 export * as ThreadListItemPrimitive from "./threadListItem";
 
-export { useContentPartText } from "./contentPart/useContentPartText";
-export { useContentPartReasoning } from "./contentPart/useContentPartReasoning";
-export { useContentPartSource } from "./contentPart/useContentPartSource";
-export { useContentPartFile } from "./contentPart/useContentPartFile";
-export { useContentPartImage } from "./contentPart/useContentPartImage";
+export { useMessagePartText } from "./messagePart/useMessagePartText";
+export { useMessagePartReasoning } from "./messagePart/useMessagePartReasoning";
+export { useMessagePartSource } from "./messagePart/useMessagePartSource";
+export { useMessagePartFile } from "./messagePart/useMessagePartFile";
+export { useMessagePartImage } from "./messagePart/useMessagePartImage";
 export { useThreadViewportAutoScroll } from "./thread/useThreadViewportAutoScroll";
+
+// TODO remove in v0.11
+export * as ContentPartPrimitive from "./messagePart";
+export { useMessagePartText as useContentPartText } from "./messagePart/useMessagePartText";
+export { useMessagePartReasoning as useContentPartReasoning } from "./messagePart/useMessagePartReasoning";
+export { useMessagePartSource as useContentPartSource } from "./messagePart/useMessagePartSource";
+export { useMessagePartFile as useContentPartFile } from "./messagePart/useMessagePartFile";
+export { useMessagePartImage as useContentPartImage } from "./messagePart/useMessagePartImage";

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