@tanstack/ai-solid 0.19.4 → 0.21.0

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

@@ -0,0 +1,261 @@
+import { For, Show } from 'solid-js'
+import { ThinkingPart } from './thinking-part'
+import type { JSX } from 'solid-js'
+import type { UIMessage } from '../types'
+
+export interface ToolCallRenderProps {
+  id: string
+  name: string
+  arguments: string
+  state: string
+  approval?: any
+  output?: any
+}
+
+/** @deprecated Use `createChatUI()` Message instead. Deprecated in 0.8.0. Removed in 1.0.0. */
+export interface ChatMessageProps {
+  /** The message to render */
+  message: UIMessage
+  /** Base CSS class name */
+  class?: string
+  /** Additional class for user messages */
+  userClass?: string
+  /** Additional class for assistant messages */
+  assistantClass?: string
+  /** Custom renderer for text parts */
+  textPartRenderer?: (props: { content: string }) => JSX.Element
+  /** Custom renderer for thinking parts */
+  thinkingPartRenderer?: (props: {
+    content: string
+    isComplete?: boolean
+  }) => JSX.Element
+  /** Named tool renderers - use the tool name as the key */
+  toolsRenderer?: Record<string, (props: ToolCallRenderProps) => JSX.Element>
+  /** Default tool renderer when tool name not found in toolsRenderer */
+  defaultToolRenderer?: (props: ToolCallRenderProps) => JSX.Element
+  /** Custom renderer for tool result parts */
+  toolResultRenderer?: (props: {
+    toolCallId: string
+    content: string
+    state: string
+  }) => JSX.Element
+}
+
+/**
+ * @deprecated Use `createChatUI()` Message instead. Deprecated in 0.8.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}
+ *   class="flex"
+ *   userClass="justify-end"
+ *   assistantClass="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(props: ChatMessageProps) {
+  // Combine classes based on role
+  const roleClass = () =>
+    props.message.role === 'user'
+      ? (props.userClass ?? '')
+      : (props.assistantClass ?? '')
+
+  const combinedClass = () =>
+    [props.class ?? '', roleClass()].filter(Boolean).join(' ')
+
+  return (
+    <div
+      class={combinedClass() || undefined}
+      data-message-id={props.message.id}
+      data-message-role={props.message.role}
+      data-message-created={props.message.createdAt?.toISOString()}
+    >
+      <For each={props.message.parts}>
+        {(part, index) => {
+          // Check if thinking is complete (if there's a text part after this thinking part)
+          const isThinkingComplete = () =>
+            part.type === 'thinking' &&
+            props.message.parts
+              .slice(index() + 1)
+              .some((p) => p.type === 'text')
+
+          return (
+            <MessagePart
+              part={part}
+              isThinkingComplete={isThinkingComplete()}
+              textPartRenderer={props.textPartRenderer}
+              thinkingPartRenderer={props.thinkingPartRenderer}
+              toolsRenderer={props.toolsRenderer}
+              defaultToolRenderer={props.defaultToolRenderer}
+              toolResultRenderer={props.toolResultRenderer}
+            />
+          )
+        }}
+      </For>
+    </div>
+  )
+}
+
+function MessagePart(props: {
+  part: any
+  isThinkingComplete?: boolean
+  textPartRenderer?: ChatMessageProps['textPartRenderer']
+  thinkingPartRenderer?: ChatMessageProps['thinkingPartRenderer']
+  toolsRenderer?: ChatMessageProps['toolsRenderer']
+  defaultToolRenderer?: ChatMessageProps['defaultToolRenderer']
+  toolResultRenderer?: ChatMessageProps['toolResultRenderer']
+}) {
+  // Text part
+  if (props.part.type === 'text') {
+    if (props.textPartRenderer) {
+      return <>{props.textPartRenderer({ content: props.part.content })}</>
+    }
+    return (
+      <div data-part-type="text" data-part-content>
+        {props.part.content}
+      </div>
+    )
+  }
+
+  // Thinking part
+  if (props.part.type === 'thinking') {
+    if (props.thinkingPartRenderer) {
+      return (
+        <>
+          {props.thinkingPartRenderer({
+            content: props.part.content,
+            isComplete: props.isThinkingComplete,
+          })}
+        </>
+      )
+    }
+    return (
+      <ThinkingPart
+        content={props.part.content}
+        isComplete={props.isThinkingComplete}
+      />
+    )
+  }
+
+  // Tool call part
+  if (props.part.type === 'tool-call') {
+    const toolProps: ToolCallRenderProps = {
+      id: props.part.id,
+      name: props.part.name,
+      arguments: props.part.arguments,
+      state: props.part.state,
+      approval: props.part.approval,
+      output: props.part.output,
+    }
+
+    // Check if there's a specific renderer for this tool
+    if (props.toolsRenderer?.[props.part.name]) {
+      return <>{props.toolsRenderer[props.part.name]?.(toolProps)}</>
+    }
+
+    // Use default tool renderer if provided
+    if (props.defaultToolRenderer) {
+      return <>{props.defaultToolRenderer(toolProps)}</>
+    }
+
+    // Fallback to built-in default renderer
+    return (
+      <div
+        data-part-type="tool-call"
+        data-tool-name={props.part.name}
+        data-tool-state={props.part.state}
+        data-tool-id={props.part.id}
+      >
+        <div data-tool-header>
+          <strong>{props.part.name}</strong>
+          <span data-tool-state-badge>{props.part.state}</span>
+        </div>
+        <Show when={props.part.arguments}>
+          <div data-tool-arguments>
+            <pre>{props.part.arguments}</pre>
+          </div>
+        </Show>
+        <Show when={props.part.approval}>
+          <div data-tool-approval>
+            {props.part.approval.approved !== undefined
+              ? props.part.approval.approved
+                ? '✓ Approved'
+                : '✗ Denied'
+              : '⏳ Awaiting approval...'}
+          </div>
+        </Show>
+        <Show when={props.part.output}>
+          <div data-tool-output>
+            <pre>{JSON.stringify(props.part.output, null, 2)}</pre>
+          </div>
+        </Show>
+      </div>
+    )
+  }
+
+  // Tool result part
+  if (props.part.type === 'tool-result') {
+    if (props.toolResultRenderer) {
+      return (
+        <>
+          {props.toolResultRenderer({
+            toolCallId: props.part.toolCallId,
+            content: props.part.content,
+            state: props.part.state,
+          })}
+        </>
+      )
+    }
+
+    return (
+      <div
+        data-part-type="tool-result"
+        data-tool-call-id={props.part.toolCallId}
+        data-tool-result-state={props.part.state}
+      >
+        <div data-tool-result-content>{props.part.content}</div>
+      </div>
+    )
+  }
+
+  return null
+}

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

@@ -0,0 +1,91 @@
+import { For, Show, createEffect } from 'solid-js'
+import { useChatContext } from './chat'
+import { ChatMessage } from './chat-message'
+import type { JSX } from 'solid-js'
+import type { UIMessage } from '../types'
+
+/** @deprecated Use `createChatUI()` Messages instead. Deprecated in 0.8.0. Removed in 1.0.0. */
+export interface ChatMessagesProps {
+  /** Custom render function for each message */
+  children?: (message: UIMessage, index: number) => JSX.Element
+  /** CSS class name */
+  class?: string
+  /** Element to show when there are no messages */
+  emptyState?: JSX.Element
+  /** Element to show while loading the first message */
+  loadingState?: JSX.Element
+  /** Custom error renderer */
+  errorState?: (props: {
+    error: Error
+    reload: () => Promise<void>
+  }) => JSX.Element
+  /** Auto-scroll to bottom on new messages */
+  autoScroll?: boolean
+}
+
+/**
+ * @deprecated Use `createChatUI()` Messages instead. Deprecated in 0.8.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(props: ChatMessagesProps) {
+  const { messages, isLoading, error, reload } = useChatContext()
+  let containerRef: HTMLDivElement | undefined
+
+  // Auto-scroll to bottom on new messages
+  createEffect(() => {
+    // Track messages to trigger effect on change
+    messages()
+    if ((props.autoScroll ?? true) && containerRef) {
+      containerRef.scrollTop = containerRef.scrollHeight
+    }
+  })
+
+  return (
+    <Show
+      when={!error() || !props.errorState}
+      fallback={(() => {
+        const err = error()
+        return err ? <>{props.errorState?.({ error: err, reload })}</> : null
+      })()}
+    >
+      <Show
+        when={!isLoading() || messages().length > 0 || !props.loadingState}
+        fallback={<>{props.loadingState}</>}
+      >
+        <Show
+          when={messages().length > 0 || !props.emptyState}
+          fallback={<>{props.emptyState}</>}
+        >
+          <div
+            ref={(el) => {
+              containerRef = el
+            }}
+            class={props.class}
+            data-chat-messages
+            data-message-count={messages().length}
+          >
+            <For each={messages()}>
+              {(message, index) =>
+                props.children ? (
+                  <div data-message-id={message.id}>
+                    {props.children(message, index())}
+                  </div>
+                ) : (
+                  <ChatMessage message={message} />
+                )
+              }
+            </For>
+          </div>
+        </Show>
+      </Show>
+    </Show>
+  )
+}

package/src/chat-ui/chat.tsx

@@ -0,0 +1,95 @@
+import { createContext, useContext } from 'solid-js'
+import type { ConnectionAdapter } from '@tanstack/ai-client'
+import { useChat } from '../use-chat'
+import type { JSX } from 'solid-js'
+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().useChat()` instead. Deprecated in 0.8.0. Removed in 1.0.0. */
+export function useChatContext(): UseChatReturn {
+  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.8.0. Removed in 1.0.0. */
+export interface ChatProps {
+  /** Child components (Chat.Messages, Chat.Input, etc.) */
+  children: JSX.Element
+  /** CSS class name for the root element */
+  class?: 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
+  /** Client-side tools with execute functions */
+  tools?: Array<any>
+  /** Custom tool components registry for rendering */
+  toolComponents?: Record<
+    string,
+    (props: { input: any; output?: any }) => JSX.Element
+  >
+}
+
+/**
+ * @deprecated Since 0.8.0. Use `createChatHook()` from `@tanstack/ai-solid/ui` instead.
+ * See https://tanstack.com/ai/latest/docs/ui/solid
+ * 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(props: ChatProps) {
+  const chat = useChat({
+    connection: props.connection,
+    ...(props.initialMessages !== undefined && {
+      initialMessages: props.initialMessages,
+    }),
+    ...(props.id !== undefined && { id: props.id }),
+    ...(props.body !== undefined && { body: props.body }),
+    ...(props.onResponse !== undefined && { onResponse: props.onResponse }),
+    ...(props.onChunk !== undefined && { onChunk: props.onChunk }),
+    ...(props.onFinish !== undefined && { onFinish: props.onFinish }),
+    ...(props.onError !== undefined && { onError: props.onError }),
+    ...(props.tools !== undefined && { tools: props.tools }),
+  })
+
+  return (
+    <ChatContext.Provider value={chat}>
+      <div class={props.class} data-chat-root>
+        {props.children}
+      </div>
+    </ChatContext.Provider>
+  )
+}

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

@@ -0,0 +1,77 @@
+import type { Component } from 'solid-js'
+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.
+ * Context `useChatContext` reads that instance. Part and interrupt
+ * widgets take `part` / `interrupt` as props.
+ *
+ * Pass instance overrides such as `threadId` into `useAppChat()`.
+ */
+export function createChatHook<
+  const TOptions,
+  TInput extends Component<any> | undefined =
+    | Component<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>
+
+    function AppChat() {
+      return <ui.Chat chat={chat} />
+    }
+
+    return Object.assign(chat, { AppChat }) as ChatUIHost<TOptions> & {
+      AppChat: Component
+    }
+  }
+
+  return {
+    useAppChat,
+    useChatContext: ui.useChatContext,
+  }
+}

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

@@ -0,0 +1,52 @@
+import { createContext, useContext } from 'solid-js'
+import type { Context } from 'solid-js'
+import type {
+  ChatUIInterrupt,
+  ChatUISelectedPart,
+} from '@tanstack/ai-client/ui'
+import type { UseChatReturn } from '../types'
+
+export interface ChatUIContexts {
+  chatContext: Context<UseChatReturn<any, any, any> | undefined>
+  partContext: Context<ChatUISelectedPart | undefined>
+  interruptContext: Context<ChatUIInterrupt | undefined>
+  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. Call this when a widget file cannot import the `createChatHook`
+ * result, or when nested chats need isolated providers.
+ *
+ * Prefer `useChatContext` from `createChatHook` when you can import that
+ * result. Part and interrupt widgets take `part` / `interrupt` as props.
+ */
+export function createChatHookContexts(): ChatUIContexts {
+  const chatContext = createContext<UseChatReturn<any, any, any> | undefined>(
+    undefined,
+  )
+  const partContext = createContext<ChatUISelectedPart | undefined>(undefined)
+  const interruptContext = createContext<ChatUIInterrupt | undefined>(undefined)
+
+  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()