@tanstack/ai-preact 0.14.4 → 0.16.0

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

@@ -0,0 +1,98 @@
+import { useMemo, useRef } from 'preact/compat'
+import type { ComponentType } from 'preact/compat'
+import type { InferredClientContext } from '@tanstack/ai-client'
+import type { ChatUIInterruptsOf, 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>,
+  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 'preact/compat'
+import type { Context } from 'preact/compat'
+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> | null>
+  partContext: Context<ChatUISelectedPart | null>
+  interruptContext: Context<ChatUIInterrupt | null>
+  useChatContext: () => UseChatReturn<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> | 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()