@tanstack/ai-react 0.22.4 → 0.24.0

package/src/chat-ui/chat-message.tsx

@@ -0,0 +1,271 @@
+import { ThinkingPart } from './thinking-part'
+import { toolResultContentToString } from './tool-result-content'
+import type { ReactNode } from 'react'
+import type { UIMessage } from '../types'
+
+export interface ToolCallRenderProps {
+  id: string
+  name: string
+  arguments: string
+  state: string
+  approval?: any
+  output?: any
+}
+
+export interface ChatMessageProps {
+  /** The message to render */
+  message: UIMessage
+  /** Base CSS class name */
+  className?: string
+  /** Additional className for user messages */
+  userClassName?: string
+  /** Additional className for assistant messages */
+  assistantClassName?: string
+  /** Custom renderer for text parts */
+  textPartRenderer?: (props: { content: string }) => ReactNode
+  /** Custom renderer for thinking parts */
+  thinkingPartRenderer?: (props: {
+    content: string
+    isComplete?: boolean
+  }) => ReactNode
+  /** Named tool renderers - use the tool name as the key */
+  toolsRenderer?: Record<string, (props: ToolCallRenderProps) => ReactNode>
+  /** Default tool renderer when tool name not found in toolsRenderer */
+  defaultToolRenderer?: (props: ToolCallRenderProps) => ReactNode
+  /** Custom renderer for tool result parts */
+  toolResultRenderer?: (props: {
+    toolCallId: string
+    content: string
+    state: string
+  }) => ReactNode
+}
+
+/**
+ * @deprecated Use `createChatUI()` Message instead. Deprecated in 0.9.0. Removed in 1.0.0.
+ *
+ * Message component - renders a single message with all its parts
+ *
+ * This component natively understands TanStack AI's parts-based message format:
+ * - thinking parts: rendered as collapsible thinking/reasoning sections (auto-collapses when complete)
+ * - text parts: rendered as content
+ * - tool-call parts: rendered with state, approvals, etc.
+ * - tool-result parts: rendered with results
+ *
+ * @example Basic usage
+ * ```tsx
+ * <Chat.Message message={message} />
+ * ```
+ *
+ * @example With role-based styling
+ * ```tsx
+ * <ChatMessage
+ *   message={message}
+ *   className="flex"
+ *   userClassName="justify-end"
+ *   assistantClassName="justify-start"
+ * />
+ * ```
+ *
+ * @example With custom thinking renderer
+ * ```tsx
+ * <ChatMessage
+ *   message={message}
+ *   thinkingPartRenderer={({ content, isComplete }) => (
+ *     <details open={!isComplete}>
+ *       <summary>💭 Thinking...</summary>
+ *       <pre>{content}</pre>
+ *     </details>
+ *   )}
+ * />
+ * ```
+ *
+ * @example With named tool renderers
+ * ```tsx
+ * <ChatMessage
+ *   message={message}
+ *   toolsRenderer={{
+ *     recommendGuitar: ({ id, arguments: args }) => <GuitarCard {...JSON.parse(args)} />,
+ *     weatherLookup: ({ id, arguments: args }) => <WeatherWidget {...JSON.parse(args)} />,
+ *   }}
+ *   defaultToolRenderer={() => null}
+ * />
+ * ```
+ */
+export function ChatMessage({
+  message,
+  className = '',
+  userClassName = '',
+  assistantClassName = '',
+  textPartRenderer,
+  thinkingPartRenderer,
+  toolsRenderer,
+  defaultToolRenderer,
+  toolResultRenderer,
+}: ChatMessageProps) {
+  // Combine classes based on role
+  const roleClassName =
+    message.role === 'user' ? userClassName : assistantClassName
+
+  const combinedClassName = [className, roleClassName].filter(Boolean).join(' ')
+
+  return (
+    <div
+      className={combinedClassName || undefined}
+      data-message-id={message.id}
+      data-message-role={message.role}
+      data-message-created={message.createdAt?.toISOString()}
+    >
+      {message.parts.map((part, index) => {
+        // Check if thinking is complete (if there's a text part after this thinking part)
+        const isThinkingComplete =
+          part.type === 'thinking' &&
+          message.parts.slice(index + 1).some((p) => p.type === 'text')
+
+        return (
+          <MessagePart
+            key={`${message.id}-part-${index}`}
+            part={part}
+            isThinkingComplete={isThinkingComplete}
+            textPartRenderer={textPartRenderer}
+            thinkingPartRenderer={thinkingPartRenderer}
+            toolsRenderer={toolsRenderer}
+            defaultToolRenderer={defaultToolRenderer}
+            toolResultRenderer={toolResultRenderer}
+          />
+        )
+      })}
+    </div>
+  )
+}
+
+function MessagePart({
+  part,
+  isThinkingComplete,
+  textPartRenderer,
+  thinkingPartRenderer,
+  toolsRenderer,
+  defaultToolRenderer,
+  toolResultRenderer,
+}: {
+  part: UIMessage['parts'][number]
+  isThinkingComplete?: boolean
+  textPartRenderer?: ChatMessageProps['textPartRenderer']
+  thinkingPartRenderer?: ChatMessageProps['thinkingPartRenderer']
+  toolsRenderer?: ChatMessageProps['toolsRenderer']
+  defaultToolRenderer?: ChatMessageProps['defaultToolRenderer']
+  toolResultRenderer?: ChatMessageProps['toolResultRenderer']
+}) {
+  // Text part
+  if (part.type === 'text') {
+    if (textPartRenderer) {
+      return <>{textPartRenderer({ content: part.content })}</>
+    }
+    return (
+      <div data-part-type="text" data-part-content>
+        {part.content}
+      </div>
+    )
+  }
+
+  // Thinking part
+  if (part.type === 'thinking') {
+    if (thinkingPartRenderer) {
+      return (
+        <>
+          {thinkingPartRenderer({
+            content: part.content,
+            isComplete: isThinkingComplete,
+          })}
+        </>
+      )
+    }
+    return (
+      <ThinkingPart content={part.content} isComplete={isThinkingComplete} />
+    )
+  }
+
+  // Tool call part
+  if (part.type === 'tool-call') {
+    const toolProps: ToolCallRenderProps = {
+      id: part.id,
+      name: part.name,
+      arguments: part.arguments,
+      state: part.state,
+      approval: part.approval,
+      output: part.output,
+    }
+
+    // Check if there's a specific renderer for this tool
+    if (toolsRenderer?.[part.name]) {
+      return <>{toolsRenderer[part.name]?.(toolProps)}</>
+    }
+
+    // Use default tool renderer if provided
+    if (defaultToolRenderer) {
+      return <>{defaultToolRenderer(toolProps)}</>
+    }
+
+    // Fallback to built-in default renderer
+    return (
+      <div
+        data-part-type="tool-call"
+        data-tool-name={part.name}
+        data-tool-state={part.state}
+        data-tool-id={part.id}
+      >
+        <div data-tool-header>
+          <strong>{part.name}</strong>
+          <span data-tool-state-badge>{part.state}</span>
+        </div>
+        {part.arguments && (
+          <div data-tool-arguments>
+            <pre>{part.arguments}</pre>
+          </div>
+        )}
+        {part.approval && (
+          <div data-tool-approval>
+            {part.approval.approved !== undefined
+              ? part.approval.approved
+                ? '✓ Approved'
+                : '✗ Denied'
+              : '⏳ Awaiting approval...'}
+          </div>
+        )}
+        {part.output && (
+          <div data-tool-output>
+            <pre>{JSON.stringify(part.output, null, 2)}</pre>
+          </div>
+        )}
+      </div>
+    )
+  }
+
+  // Tool result part
+  if (part.type === 'tool-result') {
+    const toolResultContent = toolResultContentToString(part.content)
+
+    if (toolResultRenderer) {
+      return (
+        <>
+          {toolResultRenderer({
+            toolCallId: part.toolCallId,
+            content: toolResultContent,
+            state: part.state,
+          })}
+        </>
+      )
+    }
+
+    return (
+      <div
+        data-part-type="tool-result"
+        data-tool-call-id={part.toolCallId}
+        data-tool-result-state={part.state}
+      >
+        <div data-tool-result-content>{toolResultContent}</div>
+      </div>
+    )
+  }
+
+  return null
+}

package/src/chat-ui/chat-messages.tsx

@@ -0,0 +1,89 @@
+import { useEffect, useRef } from 'react'
+import { useChatContext } from './chat'
+import { ChatMessage } from './chat-message'
+import type { ReactNode } from 'react'
+import type { UIMessage } from '../types'
+
+/** @deprecated Use `createChatUI()` Messages instead. Deprecated in 0.9.0. Removed in 1.0.0. */
+export interface ChatMessagesProps {
+  /** Custom render function for each message */
+  children?: (message: UIMessage, index: number) => ReactNode
+  /** CSS class name */
+  className?: string
+  /** Element to show when there are no messages */
+  emptyState?: ReactNode
+  /** Element to show while loading the first message */
+  loadingState?: ReactNode
+  /** Custom error renderer */
+  errorState?: (props: {
+    error: Error
+    reload: () => Promise<void>
+  }) => ReactNode
+  /** Auto-scroll to bottom on new messages */
+  autoScroll?: boolean
+}
+
+/**
+ * @deprecated Use `createChatUI()` Messages instead. Deprecated in 0.9.0. Removed in 1.0.0.
+ *
+ * Messages container - renders all messages in the conversation
+ *
+ * @example
+ * ```tsx
+ * <Chat.Messages>
+ *   {(message) => <Chat.Message message={message} />}
+ * </Chat.Messages>
+ * ```
+ */
+export function ChatMessages({
+  children,
+  className,
+  emptyState,
+  loadingState,
+  errorState,
+  autoScroll = true,
+}: ChatMessagesProps) {
+  const { messages, isLoading, error, reload } = useChatContext()
+  const containerRef = useRef<HTMLDivElement>(null)
+
+  // Auto-scroll to bottom on new messages
+  useEffect(() => {
+    if (autoScroll && containerRef.current) {
+      containerRef.current.scrollTop = containerRef.current.scrollHeight
+    }
+  }, [messages, autoScroll])
+
+  // Error state
+  if (error && errorState) {
+    return <>{errorState({ error, reload })}</>
+  }
+
+  // Loading state (only show if no messages yet)
+  if (isLoading && messages.length === 0 && loadingState) {
+    return <>{loadingState}</>
+  }
+
+  // Empty state
+  if (messages.length === 0 && emptyState) {
+    return <>{emptyState}</>
+  }
+
+  return (
+    <div
+      ref={containerRef}
+      className={className}
+      data-chat-messages
+      data-message-count={messages.length}
+    >
+      {messages.map((message, index) =>
+        children ? (
+          <div key={message.id} data-message-id={message.id}>
+            {children(message, index)}
+          </div>
+        ) : (
+          <ChatMessage key={message.id} message={message} />
+        ),
+      )}
+    </div>
+  )
+}

package/src/chat-ui/chat.tsx

@@ -0,0 +1,98 @@
+import { createContext, useContext } from 'react'
+import type { ConnectionAdapter } from '@tanstack/ai-client'
+import { useChat } from '../use-chat'
+import type { ReactNode } from 'react'
+import type { UIMessage, UseChatReturn } from '../types'
+
+/**
+ * Chat context - provides chat state to all child components
+ */
+const ChatContext = createContext<UseChatReturn | null>(null)
+
+/**
+ * Hook to access chat context
+ * @throws Error if used outside of Chat component
+ */
+/** @deprecated Use `createChatUI().useChatContext()` instead. Deprecated in 0.9.0. Removed in 1.0.0. */
+export function useChatContext() {
+  const context = useContext(ChatContext)
+  if (!context) {
+    throw new Error(
+      "Chat components must be wrapped in <Chat>. Make sure you're using Chat.Messages, Chat.Input, etc. inside a <Chat> component.",
+    )
+  }
+  return context
+}
+
+/** @deprecated Use `createChatUI()` Chat/Provider instead. Deprecated in 0.9.0. Removed in 1.0.0. */
+export interface ChatProps {
+  /** Child components (Chat.Messages, Chat.Input, etc.) */
+  children: ReactNode
+  /** CSS class name for the root element */
+  className?: string
+  /** Connection adapter for communicating with your API */
+  connection: ConnectionAdapter
+  /** Initial messages to display */
+  initialMessages?: Array<UIMessage>
+  /** Custom message ID generator */
+  id?: string
+  /** Additional body data to send with requests */
+  body?: any
+  /** Callback when a response is received */
+  onResponse?: (response?: Response) => void | Promise<void>
+  /** Callback when each chunk arrives */
+  onChunk?: (chunk: any) => void
+  /** Callback when a message is complete */
+  onFinish?: (message: UIMessage) => void
+  /** Callback when an error occurs */
+  onError?: (error: Error) => void
+  /** Custom tool components registry */
+  tools?: Record<string, React.ComponentType<{ input: any; output?: any }>>
+}
+
+/**
+ * @deprecated Since 0.9.0. Use `createChatHook()` from `@tanstack/ai-react/ui` instead.
+ * See https://tanstack.com/ai/latest/docs/ui/react
+ * Removed in 1.0.0.
+ *
+ * Root Chat component - provides context for all chat subcomponents
+ *
+ * @example
+ * ```tsx
+ * <Chat connection={fetchServerSentEvents("/api/chat")}>
+ *   <Chat.Messages />
+ *   <Chat.Input />
+ * </Chat>
+ * ```
+ */
+export function Chat({
+  children,
+  className,
+  connection,
+  initialMessages,
+  id,
+  body,
+  onResponse,
+  onChunk,
+  onFinish,
+  onError,
+}: ChatProps) {
+  const chat = useChat({
+    connection,
+    ...(initialMessages !== undefined ? { initialMessages } : {}),
+    ...(id !== undefined ? { id } : {}),
+    ...(body !== undefined ? { body } : {}),
+    ...(onResponse !== undefined ? { onResponse } : {}),
+    ...(onChunk !== undefined ? { onChunk } : {}),
+    ...(onFinish !== undefined ? { onFinish } : {}),
+    ...(onError !== undefined ? { onError } : {}),
+  })
+
+  return (
+    <ChatContext.Provider value={chat}>
+      <div className={className} data-chat-root>
+        {children}
+      </div>
+    </ChatContext.Provider>
+  )
+}

package/src/chat-ui/create-chat-hook.tsx

@@ -0,0 +1,103 @@
+import { useMemo, useRef } from 'react'
+import type { ComponentType } from 'react'
+import type { InferredClientContext } from '@tanstack/ai-client'
+import type {
+  ChatUIInterruptsOf,
+  ChatUISchemaOf,
+  ChatUIToolsOf,
+} from '@tanstack/ai-client/ui'
+import { useChat as useUnboundChat } from '../use-chat'
+import type { UseChatOptions } from '../types'
+import { createChatUI } from './create-ui'
+import type { ChatUIFactoryConfig, ChatUIHost, InputProps } from './create-ui'
+
+type HeadlessOptions<TOptions> = UseChatOptions<
+  ChatUIToolsOf<TOptions>,
+  ChatUISchemaOf<TOptions>,
+  InferredClientContext<ChatUIToolsOf<TOptions>>,
+  ChatUIInterruptsOf<TOptions>
+>
+
+type ChatInstanceOverrides<TOptions> = {
+  threadId?: string
+  live?: boolean
+  forwardedProps?: Record<string, any>
+  body?: Record<string, any>
+  initialMessages?: HeadlessOptions<TOptions>['initialMessages']
+}
+
+/**
+ * Bind chat options and UI widgets once at module scope.
+ *
+ * This matches Form `createFormHook` and Table `createTableHook`. The
+ * returned `useAppChat` creates a chat instance. `chat.AppChat` renders it.
+ * `useChatContext` reads that instance. Part and interrupt widgets take
+ * `part` / `interrupt` as props. Do not read those from context.
+ *
+ * Pass instance overrides such as `threadId` into `useAppChat()`.
+ *
+ * @example
+ * ```tsx
+ * const { useAppChat, useChatContext } = createChatHook({
+ *   options: chatOptions,
+ *   components: { layout: ChatLayout, message: ChatMessage },
+ *   partsComponents: { fallback: FallbackPart },
+ *   toolsComponents: { getWeather: WeatherTool, purchaseItem: PurchaseTool },
+ *   interruptsComponents: { generic: { choosePlan: ChoosePlan } },
+ * })
+ *
+ * function Support() {
+ *   const chat = useAppChat({ threadId: 'support-1' })
+ *   return <chat.AppChat />
+ * }
+ * ```
+ */
+export function createChatHook<
+  const TOptions,
+  TInput extends ComponentType<any> | undefined =
+    | ComponentType<InputProps<NoInfer<TOptions>>>
+    | undefined,
+>({
+  options,
+  ...chatComponents
+}: {
+  options: TOptions
+} & ChatUIFactoryConfig<NoInfer<TOptions>, TInput>) {
+  const ui = createChatUI(
+    options,
+    chatComponents as ChatUIFactoryConfig<NoInfer<TOptions>, TInput>,
+  )
+
+  function useAppChat(overrides?: ChatInstanceOverrides<TOptions>) {
+    const chat = (
+      overrides
+        ? useUnboundChat({
+            ...(options as HeadlessOptions<TOptions>),
+            ...overrides,
+          })
+        : useUnboundChat(options as HeadlessOptions<TOptions>)
+    ) as ChatUIHost<TOptions>
+
+    // `useChat` returns a fresh object on every render. The mixed Chat
+    // component must stay stable, or React remounts the tree on each
+    // update. Read the current instance from a ref.
+    const chatRef = useRef(chat)
+    chatRef.current = chat
+
+    const AppChat = useMemo(() => {
+      function AppChatImpl() {
+        return <ui.Chat chat={chatRef.current} />
+      }
+      return AppChatImpl
+    }, [])
+
+    return Object.assign(chat, { AppChat }) as ChatUIHost<TOptions> & {
+      AppChat: ComponentType
+    }
+  }
+
+  return {
+    useAppChat,
+    useChatContext: ui.useChatContext,
+  }
+}

package/src/chat-ui/create-ui-contexts.tsx

@@ -0,0 +1,57 @@
+import { createContext, useContext } from 'react'
+import type { Context } from 'react'
+import type {
+  ChatUIInterrupt,
+  ChatUISelectedPart,
+} from '@tanstack/ai-client/ui'
+import type { UseChatReturn } from '../types'
+
+/**
+ * Scoped chat, part, and interrupt contexts plus matching context hooks.
+ * Pass these into {@link createChatHook} when widgets live in other files, or
+ * when two chat trees nest and must not share the default contexts.
+ */
+export interface ChatUIContexts {
+  chatContext: Context<UseChatReturn<any, any, any> | null>
+  partContext: Context<ChatUISelectedPart | null>
+  interruptContext: Context<ChatUIInterrupt | null>
+  useChatContext: () => UseChatReturn<any, any, any>
+}
+
+/**
+ * Create a fresh set of chat UI contexts. This matches Form
+ * `createFormHookContexts` and Table `createTableHookContexts`.
+ *
+ * Most apps can skip this. `createChatHook` uses shared module contexts by
+ * default. The hooks on this object are the escape hatch for a widget file
+ * that cannot import the `createChatHook` result (circular import), or for
+ * nested chats that need isolated providers.
+ *
+ * Prefer the `useChatContext` hook returned from `createChatHook` when you
+ * can import that result. That hook knows the `chatComponents` types. Part
+ * and interrupt widgets take `part` / `interrupt` as props.
+ */
+export function createChatHookContexts(): ChatUIContexts {
+  const chatContext = createContext<UseChatReturn<any, any, any> | null>(null)
+  const partContext = createContext<ChatUISelectedPart | null>(null)
+  const interruptContext = createContext<ChatUIInterrupt | null>(null)
+
+  function useChatContext() {
+    const chat = useContext(chatContext)
+    if (!chat) {
+      throw new Error(
+        '`useChatContext` must be used within `UI.Provider` or `UI.Chat`.',
+      )
+    }
+    return chat
+  }
+
+  return {
+    chatContext,
+    partContext,
+    interruptContext,
+    useChatContext,
+  }
+}
+
+export const defaultChatUIContexts = createChatHookContexts()