@tanstack/ai-react 0.22.3 → 0.23.0

package/src/chat-ui/markdown-plugins.ts

@@ -0,0 +1,48 @@
+import remarkGfm from 'remark-gfm'
+import rehypeRaw from 'rehype-raw'
+import rehypeSanitize from 'rehype-sanitize'
+import rehypeHighlight from 'rehype-highlight'
+import type { Options as ReactMarkdownOptions } from 'react-markdown'
+
+export type PluggableList = NonNullable<ReactMarkdownOptions['remarkPlugins']>
+
+export const DEFAULT_REMARK_PLUGINS: PluggableList = [remarkGfm]
+export const DEFAULT_REHYPE_PLUGINS_BEFORE_USER: PluggableList = [
+  rehypeRaw,
+  rehypeHighlight,
+]
+export const DEFAULT_REHYPE_PLUGINS_AFTER_USER: PluggableList = [rehypeSanitize]
+
+export interface ResolveMarkdownPluginsOptions {
+  remarkPlugins?: PluggableList
+  rehypePlugins?: PluggableList
+  disableDefaultPlugins?: boolean
+}
+
+export interface ResolvedMarkdownPlugins {
+  remarkPlugins: PluggableList
+  rehypePlugins: PluggableList
+}
+
+export function resolveMarkdownPlugins(
+  options: ResolveMarkdownPluginsOptions,
+): ResolvedMarkdownPlugins {
+  const userRemark = options.remarkPlugins ?? []
+  const userRehype = options.rehypePlugins ?? []
+
+  if (options.disableDefaultPlugins) {
+    return {
+      remarkPlugins: [...userRemark],
+      rehypePlugins: [...userRehype],
+    }
+  }
+
+  return {
+    remarkPlugins: [...DEFAULT_REMARK_PLUGINS, ...userRemark],
+    rehypePlugins: [
+      ...DEFAULT_REHYPE_PLUGINS_BEFORE_USER,
+      ...userRehype,
+      ...DEFAULT_REHYPE_PLUGINS_AFTER_USER,
+    ],
+  }
+}

package/src/chat-ui/text-part.tsx

@@ -0,0 +1,97 @@
+import ReactMarkdown from 'react-markdown'
+import { resolveMarkdownPlugins } from './markdown-plugins'
+import type { Components } from 'react-markdown'
+import type { PluggableList } from './markdown-plugins'
+
+export interface TextPartProps {
+  /** The text content to render */
+  content: string
+  /** The role of the message (user, assistant, or system) - optional for standalone use */
+  role?: 'user' | 'assistant' | 'system'
+  /** Base className applied to all text parts */
+  className?: string
+  /** Additional className for user messages */
+  userClassName?: string
+  /** Additional className for assistant messages (also used for system messages) */
+  assistantClassName?: string
+  /**
+   * Additional remark plugins, appended after the defaults
+   * (or replacing them when `disableDefaultPlugins` is true).
+   */
+  remarkPlugins?: PluggableList
+  /**
+   * Additional rehype plugins. Inserted between the built-in
+   * `rehypeRaw`/`rehypeHighlight` and the trailing `rehypeSanitize`
+   * so sanitization always runs last. When `disableDefaultPlugins`
+   * is true, replaces the entire chain.
+   */
+  rehypePlugins?: PluggableList
+  /** react-markdown `components` overrides (e.g. custom `a`, `code`). */
+  components?: Components
+  /**
+   * Drop the built-in plugin defaults entirely. The consumer becomes
+   * responsible for syntax highlighting, GFM, raw HTML handling, and
+   * sanitization. Use with care — disabling defaults removes the
+   * built-in XSS sanitizer.
+   */
+  disableDefaultPlugins?: boolean
+}
+
+/**
+ * TextPart component - renders markdown text with syntax highlighting.
+ *
+ * @example Standalone usage
+ * ```tsx
+ * <TextPart
+ *   content="Hello **world**!"
+ *   role="user"
+ *   className="p-4 rounded"
+ *   userClassName="bg-blue-500"
+ *   assistantClassName="bg-gray-500"
+ * />
+ * ```
+ *
+ * @example Add a markdown plugin (e.g. CJK bold/emphasis support)
+ * ```tsx
+ * import remarkCjkFriendly from 'remark-cjk-friendly'
+ *
+ * <TextPart content={content} remarkPlugins={[remarkCjkFriendly]} />
+ * ```
+ */
+export function TextPart({
+  content,
+  role,
+  className = '',
+  userClassName = '',
+  assistantClassName = '',
+  remarkPlugins,
+  rehypePlugins,
+  components,
+  disableDefaultPlugins,
+}: TextPartProps) {
+  const roleClassName =
+    role === 'user'
+      ? userClassName
+      : role === 'assistant'
+        ? assistantClassName
+        : ''
+  const combinedClassName = [className, roleClassName].filter(Boolean).join(' ')
+
+  const resolved = resolveMarkdownPlugins({
+    remarkPlugins,
+    rehypePlugins,
+    disableDefaultPlugins,
+  })
+
+  return (
+    <div className={combinedClassName || undefined}>
+      <ReactMarkdown
+        remarkPlugins={resolved.remarkPlugins}
+        rehypePlugins={resolved.rehypePlugins}
+        components={components}
+      >
+        {content}
+      </ReactMarkdown>
+    </div>
+  )
+}

package/src/chat-ui/thinking-part.tsx

@@ -0,0 +1,83 @@
+import { useEffect, useState } from 'react'
+
+export interface ThinkingPartProps {
+  /** The thinking content to render */
+  content: string
+  /** Base className applied to thinking parts */
+  className?: string
+  /** Whether thinking is complete (has text content after) */
+  isComplete?: boolean
+}
+
+/**
+ * ThinkingPart component - renders thinking/reasoning content
+ *
+ * This component displays the model's internal reasoning process,
+ * typically shown in a collapsed or expandable format to distinguish
+ * it from the final response. It automatically collapses when thinking
+ * is complete.
+ *
+ * @example Standalone usage
+ * ```tsx
+ * <ThinkingPart
+ *   content="Let me think about this step by step..."
+ *   className="p-4 rounded bg-gray-100"
+ * />
+ * ```
+ *
+ * @example Usage in partRenderers
+ * ```tsx
+ * <ChatMessage
+ *   message={message}
+ *   partRenderers={{
+ *     thinking: ({ content, isComplete }) => (
+ *       <ThinkingPart
+ *         content={content}
+ *         isComplete={isComplete}
+ *         className="px-5 py-3 rounded-2xl bg-gray-800/50"
+ *       />
+ *     )
+ *   }}
+ * />
+ * ```
+ */
+export function ThinkingPart({
+  content,
+  className = '',
+  isComplete = false,
+}: ThinkingPartProps) {
+  const [isCollapsed, setIsCollapsed] = useState(false)
+
+  // Auto-collapse when thinking completes
+  useEffect(() => {
+    if (isComplete) {
+      setIsCollapsed(true)
+    }
+  }, [isComplete])
+
+  return (
+    <div
+      className={className || undefined}
+      data-part-type="thinking"
+      data-part-content
+    >
+      <button
+        onClick={() => setIsCollapsed(!isCollapsed)}
+        className="flex items-center gap-2 text-sm text-gray-400 hover:text-gray-300 transition-colors mb-2"
+        aria-expanded={!isCollapsed}
+        aria-label={isCollapsed ? 'Expand thinking' : 'Collapse thinking'}
+      >
+        <span className="text-xs">{isCollapsed ? '▶' : '▼'}</span>
+        <span className="italic">💭 Thinking...</span>
+        {isComplete && (
+          <span className="text-xs text-gray-500">(complete)</span>
+        )}
+      </button>
+      {!isCollapsed && (
+        <div className="text-gray-300 whitespace-pre-wrap font-mono text-sm">
+          {content}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/chat-ui/tool-approval.tsx

@@ -0,0 +1,132 @@
+import { useChatContext } from './chat'
+import type { ReactNode } from 'react'
+
+export interface ToolApprovalProps {
+  /** Tool call ID */
+  toolCallId: string
+  /** Tool name */
+  toolName: string
+  /** Parsed tool arguments/input */
+  input: any
+  /** Approval metadata */
+  approval: {
+    id: string
+    needsApproval: boolean
+    approved?: boolean
+  }
+  /** CSS class name */
+  className?: string
+  /** Custom render prop */
+  children?: (props: ToolApprovalRenderProps) => ReactNode
+}
+
+export interface ToolApprovalRenderProps {
+  /** Tool name */
+  toolName: string
+  /** Parsed input */
+  input: any
+  /** Approve the tool call */
+  onApprove: () => void
+  /** Deny the tool call */
+  onDeny: () => void
+  /** Whether user has responded */
+  hasResponded: boolean
+  /** User's decision (if responded) */
+  approved?: boolean
+}
+
+/**
+ * @deprecated Use `createChatUI()` interrupt components with `chat.interrupts`.
+ * Deprecated in 0.9.0. Removed in 1.0.0.
+ *
+ * Tool approval component - renders approve/deny buttons for tools that need approval
+ *
+ * @example
+ * ```tsx
+ * {part.approval && (
+ *   <ToolApproval
+ *     toolCallId={part.id}
+ *     toolName={part.name}
+ *     input={JSON.parse(part.arguments)}
+ *     approval={part.approval}
+ *   />
+ * )}
+ * ```
+ */
+export function ToolApproval({
+  toolCallId: _,
+  toolName,
+  input,
+  approval,
+  className,
+  children,
+}: ToolApprovalProps) {
+  const { addToolApprovalResponse } = useChatContext()
+
+  const handleApprove = () => {
+    void addToolApprovalResponse({
+      id: approval.id,
+      approved: true,
+    })
+  }
+
+  const handleDeny = () => {
+    void addToolApprovalResponse({
+      id: approval.id,
+      approved: false,
+    })
+  }
+
+  const hasResponded = approval.approved !== undefined
+
+  const renderProps: ToolApprovalRenderProps = {
+    toolName,
+    input,
+    onApprove: handleApprove,
+    onDeny: handleDeny,
+    hasResponded,
+    approved: approval.approved,
+  }
+
+  // Render prop pattern
+  if (children) {
+    return <>{children(renderProps)}</>
+  }
+
+  // Already responded - show decision
+  if (hasResponded) {
+    return (
+      <div
+        className={className}
+        data-tool-approval
+        data-approval-status={approval.approved ? 'approved' : 'denied'}
+      >
+        {approval.approved ? '✓ Approved' : '✗ Denied'}
+      </div>
+    )
+  }
+
+  // Default approval UI
+  return (
+    <div
+      className={className}
+      data-tool-approval
+      data-approval-status="pending"
+    >
+      <div data-approval-header>
+        <strong>{toolName}</strong> requires approval
+      </div>
+      <div data-approval-input>
+        <pre>{JSON.stringify(input, null, 2)}</pre>
+      </div>
+      <div data-approval-actions>
+        <button onClick={handleApprove} data-approval-approve>
+          Approve
+        </button>
+        <button onClick={handleDeny} data-approval-deny>
+          Deny
+        </button>
+      </div>
+    </div>
+  )
+}

package/src/chat-ui/tool-result-content.ts

@@ -0,0 +1,32 @@
+import type { UIMessage } from '../types'
+
+type ToolResultPart = Extract<
+  UIMessage['parts'][number],
+  { type: 'tool-result' }
+>
+
+/** `string | Array<ContentPart>` — a tool result's raw content. */
+type ToolResultContent = ToolResultPart['content']
+
+type ContentPartItem = Exclude<ToolResultContent, string>[number]
+
+/**
+ * Reduce a tool-result part's `content` to a plain string for rendering.
+ *
+ * Tool results carry `string | Array<ContentPart>` (multimodal results are
+ * normalized to an array of content parts upstream). The `ChatMessage`
+ * renderers operate on plain strings, so array content is flattened to the
+ * concatenation of its text parts. Non-text parts (image, audio, video,
+ * document) have no string form here and are skipped — matching the
+ * text-extraction behavior used elsewhere for `string | Array<ContentPart>`.
+ */
+export function toolResultContentToString(content: ToolResultContent): string {
+  if (typeof content === 'string') return content
+  return content
+    .filter(
+      (part): part is Extract<ContentPartItem, { type: 'text' }> =>
+        part.type === 'text',
+    )
+    .map((part) => part.content)
+    .join('')
+}

package/src/create-chat-hook.ts

@@ -0,0 +1,67 @@
+import { useChat as useUnboundChat } from './use-chat'
+import type {
+  AnyClientTool,
+  InterruptDefinition,
+  SchemaInput,
+} from '@tanstack/ai/client'
+import type { InferredClientContext } from '@tanstack/ai-client'
+import type { UseChatOptions } from './types'
+
+type ChatHookOverrides<
+  TTools extends ReadonlyArray<AnyClientTool>,
+  TSchema extends SchemaInput | undefined,
+  TContext,
+  TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>>,
+> = {
+  threadId?: string
+  live?: boolean
+  forwardedProps?: Record<string, any>
+  body?: Record<string, any>
+  initialMessages?: UseChatOptions<
+    TTools,
+    TSchema,
+    TContext,
+    TInterrupts
+  >['initialMessages']
+}
+
+/**
+ * Bind chat options once at module scope. The returned `useChat` hook
+ * creates a chat instance from those options.
+ *
+ * Pass per-call overrides for instance keys such as `threadId`,
+ * `initialMessages`, `live`, and `forwardedProps`. Do not change `tools`,
+ * `interrupts`, or `outputSchema` here. Those stay on the factory options.
+ *
+ * Rename the hook at the call site if you already import `useChat` from
+ * `@tanstack/ai-react`: `const { useChat: useAppChat } = createChatHook(chatOptions)`.
+ *
+ * @example
+ * ```tsx
+ * const { useChat } = createChatHook(chatOptions)
+ *
+ * function Support() {
+ *   const chat = useChat({ threadId: 'support-1' })
+ *   return <UI.Chat chat={chat} />
+ * }
+ * ```
+ */
+export function createChatHook<
+  const TTools extends ReadonlyArray<AnyClientTool> = any,
+  TSchema extends SchemaInput | undefined = undefined,
+  TContext = InferredClientContext<TTools>,
+  const TInterrupts extends ReadonlyArray<
+    InterruptDefinition<any, any, any, any>
+  > = readonly [],
+>(options: UseChatOptions<TTools, TSchema, TContext, TInterrupts>) {
+  function useChat(
+    overrides?: ChatHookOverrides<TTools, TSchema, TContext, TInterrupts>,
+  ) {
+    if (!overrides) {
+      return useUnboundChat(options)
+    }
+    return useUnboundChat({ ...options, ...overrides })
+  }
+
+  return { useChat }
+}

package/src/index.ts

@@ -1,4 +1,5 @@
 export { useChat } from './use-chat'
+export { createChatHook } from './create-chat-hook'
 export { useByok } from './use-byok'
 export { useRealtimeChat } from './use-realtime-chat'
 export { useMcpAppBridge } from './use-mcp-app-bridge'

package/src/ui.ts

@@ -0,0 +1,43 @@
+// Barrel entry for the `@tanstack/ai-react/ui` subpath. The JSX
+// implementation lives under `./chat-ui`; this `.ts` re-export exists so
+// kiira's dist->src resolution (which maps `dist/esm/ui.d.ts` to `src/ui.ts`,
+// never a directory index) can type-check docs snippets that import this
+// subpath.
+export {
+  createChatUI,
+  type ChatUIComponents,
+  type ChatUIFactoryConfig,
+  type ChatUIHost,
+  type ChatUIQueueItem,
+  type InputProps,
+  type InterruptProps,
+  type LayoutProps,
+  type MessageProps,
+  type PartProps,
+  type QueueProps,
+  type ToolProps,
+} from './chat-ui/create-ui'
+export { createChatHook } from './chat-ui/create-chat-hook'
+export {
+  createChatHookContexts,
+  type ChatUIContexts,
+} from './chat-ui/create-ui-contexts'
+export { Chat, useChatContext, type ChatProps } from './chat-ui/chat'
+export { ChatMessages, type ChatMessagesProps } from './chat-ui/chat-messages'
+export {
+  ChatMessage,
+  type ChatMessageProps,
+  type ToolCallRenderProps,
+} from './chat-ui/chat-message'
+export {
+  ChatInput,
+  type ChatInputProps,
+  type ChatInputRenderProps,
+} from './chat-ui/chat-input'
+export {
+  ToolApproval,
+  type ToolApprovalProps,
+  type ToolApprovalRenderProps,
+} from './chat-ui/tool-approval'
+export { TextPart, type TextPartProps } from './chat-ui/text-part'
+export { ThinkingPart, type ThinkingPartProps } from './chat-ui/thinking-part'