@lantos1618/better-ui 0.3.1 → 0.4.0

package/README.md

@@ -10,7 +10,12 @@
 
 Better UI provides a clean, fluent API for creating tools that AI assistants can execute. Define input/output schemas with Zod, implement server and client logic separately, and render results with React components.
 
-**Key differentiator**: Unlike other AI tool libraries, Better UI includes **view integration** - tools can render their own results in UI.
+**Key differentiators**:
+- **View integration** - tools render their own results in UI (no other framework does this)
+- **Multi-provider support** - OpenAI, Anthropic, Google Gemini, OpenRouter
+- **Streaming tool views** - progressive partial data rendering
+- **Pre-made chat components** - drop-in `<Chat />` with automatic tool view rendering
+- **Server infrastructure** - rate limiting, caching, Next.js/Express adapters
 
 ## Installation
 
@@ -40,12 +45,127 @@ weather.server(async ({ city }) => {
 // View for rendering results (our differentiator!)
 weather.view((data) => (
   <div className="weather-card">
-    <span>{data.temp}°</span>
+    <span>{data.temp}</span>
     <span>{data.condition}</span>
   </div>
 ));
 ```
 
+## Drop-in Chat UI
+
+```tsx
+import { Chat } from '@lantos1618/better-ui/components';
+
+function App() {
+  return (
+    <Chat
+      endpoint="/api/chat"
+      tools={{ weather, search, counter }}
+      className="h-[600px]"
+      placeholder="Ask something..."
+    />
+  );
+}
+```
+
+Or compose your own layout:
+
+```tsx
+import { ChatProvider, Thread, Composer } from '@lantos1618/better-ui/components';
+
+function App() {
+  return (
+    <ChatProvider endpoint="/api/chat" tools={tools}>
+      <div className="flex flex-col h-screen">
+        <Thread className="flex-1 overflow-y-auto" />
+        <Composer placeholder="Type a message..." />
+      </div>
+    </ChatProvider>
+  );
+}
+```
+
+Tool results in chat automatically render using the tool's `.view()` component.
+
+## Multi-Provider Support
+
+```typescript
+import { createProvider } from '@lantos1618/better-ui';
+
+// OpenAI
+const provider = createProvider({ provider: 'openai', model: 'gpt-4o' });
+
+// Anthropic
+const provider = createProvider({ provider: 'anthropic', model: 'claude-4-sonnet' });
+
+// Google Gemini
+const provider = createProvider({ provider: 'google', model: 'gemini-2.5-pro' });
+
+// OpenRouter (access any model)
+const provider = createProvider({
+  provider: 'openrouter',
+  model: 'anthropic/claude-4-sonnet',
+  apiKey: process.env.OPENROUTER_API_KEY,
+});
+```
+
+Use with the chat handler:
+
+```typescript
+import { streamText, convertToModelMessages } from 'ai';
+import { createProvider } from '@lantos1618/better-ui';
+
+const provider = createProvider({ provider: 'openai', model: 'gpt-4o' });
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+  const result = streamText({
+    model: provider.model(),
+    messages: convertToModelMessages(messages),
+    tools: {
+      weather: weatherTool.toAITool(),
+    },
+  });
+  return result.toUIMessageStreamResponse();
+}
+```
+
+## Streaming Tool Views
+
+Tools can stream partial results progressively:
+
+```typescript
+import { useToolStream } from '@lantos1618/better-ui';
+
+// Define a streaming tool
+const analysis = tool({
+  name: 'analysis',
+  input: z.object({ query: z.string() }),
+  output: z.object({ summary: z.string(), score: z.number() }),
+});
+
+analysis.stream(async ({ query }, { stream }) => {
+  stream({ summary: 'Analyzing...' });       // Partial update
+  const result = await analyzeData(query);
+  stream({ summary: result.summary });        // More data
+  return { summary: result.summary, score: result.score }; // Final
+});
+
+// In a component:
+function AnalysisWidget({ query }) {
+  const { data, streaming, loading, execute } = useToolStream(analysis);
+
+  return (
+    <div>
+      <button onClick={() => execute({ query })}>Analyze</button>
+      {loading && <p>Starting...</p>}
+      {streaming && <p>Streaming: {data?.summary}</p>}
+      {data?.score && <p>Score: {data.score}</p>}
+    </div>
+  );
+}
+```
+
 ## Core Concepts
 
 ### 1. Tool Definition
@@ -79,7 +199,6 @@ The `.client()` method defines what happens when called from the browser. If not
 
 ```typescript
 myTool.client(async ({ query }, ctx) => {
-  // Custom client logic: caching, optimistic updates, etc.
   const cached = ctx.cache.get(query);
   if (cached) return cached;
 
@@ -95,13 +214,27 @@ myTool.client(async ({ query }, ctx) => {
 The `.view()` method defines how to render the tool's results:
 
 ```typescript
-myTool.view((data, { loading, error }) => {
+myTool.view((data, { loading, error, streaming }) => {
   if (loading) return <Spinner />;
   if (error) return <Error message={error.message} />;
+  if (streaming) return <PartialResults data={data} />;
   return <Results items={data.results} />;
 });
 ```
 
+### 5. Streaming
+
+The `.stream()` method enables progressive partial updates:
+
+```typescript
+myTool.stream(async ({ query }, { stream }) => {
+  stream({ status: 'searching...' });
+  const results = await search(query);
+  stream({ results, status: 'done' });
+  return { results, status: 'done', count: results.length };
+});
+```
+
 ## Fluent Builder Alternative
 
 ```typescript
@@ -110,152 +243,119 @@ const search = tool('search')
   .input(z.object({ query: z.string() }))
   .output(z.object({ results: z.array(z.string()) }))
   .server(async ({ query }) => ({ results: await db.search(query) }))
+  .stream(async ({ query }, { stream }) => {
+    stream({ results: [] });
+    const results = await db.search(query);
+    return { results };
+  })
   .view((data) => <ResultsList items={data.results} />);
 ```
 
-## React Usage
+## React Hooks
+
+### `useTool(tool, input?, options?)`
 
 ```typescript
 import { useTool } from '@lantos1618/better-ui';
 
-function WeatherWidget({ city }) {
-  const { data, loading, error, execute } = useTool(weather);
-
-  return (
-    <div>
-      <button onClick={() => execute({ city })}>Get Weather</button>
-      {loading && <Spinner />}
-      {error && <div>Error: {error.message}</div>}
-      {data && <weather.View data={data} />}
-    </div>
-  );
-}
-
-// Or with auto-execution
-function WeatherWidget({ city }) {
-  const { data, loading } = useTool(weather, { city }, { auto: true });
-  return <weather.View data={data} loading={loading} />;
-}
+const {
+  data,      // Result data
+  loading,   // Loading state
+  error,     // Error if any
+  execute,   // Execute function
+  reset,     // Reset state
+  executed,  // Has been executed
+} = useTool(myTool, initialInput, {
+  auto: false,
+  onSuccess: (data) => {},
+  onError: (error) => {},
+});
 ```
 
-## AI Integration
-
-### With Vercel AI SDK
+### `useToolStream(tool, options?)`
 
 ```typescript
-import { streamText } from 'ai';
-import { openai } from '@ai-sdk/openai';
-
-export async function POST(req: Request) {
-  const { messages } = await req.json();
+import { useToolStream } from '@lantos1618/better-ui';
 
-  const result = await streamText({
-    model: openai('gpt-4'),
-    messages,
-    tools: {
-      weather: weather.toAITool(),
-      search: search.toAITool(),
-    },
-  });
-
-  return result.toDataStreamResponse();
-}
+const {
+  data,       // Progressive partial data
+  finalData,  // Complete validated data (when done)
+  streaming,  // True while receiving partial updates
+  loading,    // True before first chunk
+  error,
+  execute,
+  reset,
+} = useToolStream(myTool);
 ```
 
-## API Reference
-
-### `tool(config)` or `tool(name)`
-
-Create a new tool with object config or fluent builder.
+### `useTools(tools, options?)`
 
 ```typescript
-// Object config
-const t = tool({
-  name: string,
-  description?: string,
-  input: ZodSchema,
-  output?: ZodSchema,
-  tags?: string[],
-  cache?: { ttl: number, key?: (input) => string },
-});
-
-// Fluent builder
-const t = tool('name')
-  .description(string)
-  .input(ZodSchema)
-  .output(ZodSchema)
-  .tags(...string[])
-  .cache({ ttl, key? });
-```
+import { useTools } from '@lantos1618/better-ui';
 
-### `.server(handler)`
+const tools = useTools({ weather, search });
 
-Define server-side implementation.
+await tools.weather.execute({ city: 'London' });
+await tools.search.execute({ query: 'restaurants' });
 
-```typescript
-t.server(async (input, ctx) => {
-  // ctx.env, ctx.headers, ctx.user, ctx.session available
-  return result;
-});
+tools.weather.data;    // Weather result
+tools.search.loading;  // Search loading state
 ```
 
-### `.client(handler)`
+## Chat Components
 
-Define client-side implementation (optional).
+Import from `@lantos1618/better-ui/components`:
 
-```typescript
-t.client(async (input, ctx) => {
-  // ctx.cache, ctx.fetch, ctx.optimistic available
-  return result;
-});
-```
+| Component | Description |
+|-----------|-------------|
+| `Chat` | All-in-one chat component (ChatProvider + Thread + Composer) |
+| `ChatProvider` | Context provider wrapping AI SDK's `useChat` |
+| `Thread` | Message list with auto-scroll |
+| `Message` | Single message with automatic tool view rendering |
+| `Composer` | Input form with send button |
+| `ToolResult` | Renders a tool's `.View` in chat context |
 
-### `.view(component)`
+All components accept `className` for styling customization.
 
-Define React component for rendering results.
+## Providers
 
-```typescript
-t.view((data, { loading, error }) => <Component data={data} />);
-```
+| Provider | Package Required | Example Model |
+|----------|-----------------|---------------|
+| OpenAI | `@ai-sdk/openai` (included) | `gpt-4o`, `gpt-5.2` |
+| Anthropic | `@ai-sdk/anthropic` (optional) | `claude-4-sonnet` |
+| Google | `@ai-sdk/google` (optional) | `gemini-2.5-pro` |
+| OpenRouter | `@ai-sdk/openai` (included) | `anthropic/claude-4-sonnet` |
 
-### `useTool(tool, input?, options?)`
-
-React hook for executing tools.
-
-```typescript
-const {
-  data,      // Result data
-  loading,   // Loading state
-  error,     // Error if any
-  execute,   // Execute function
-  reset,     // Reset state
-  executed,  // Has been executed
-} = useTool(myTool, initialInput, {
-  auto: false,      // Auto-execute on mount
-  onSuccess: (data) => {},
-  onError: (error) => {},
-});
+```bash
+# Optional providers
+npm install @ai-sdk/anthropic  # For Anthropic
+npm install @ai-sdk/google     # For Google Gemini
 ```
 
 ## Project Structure
 
 ```
 src/
-  tool.tsx          # Core tool() API
+  tool.tsx            # Core tool() API with streaming
   react/
-    useTool.ts      # React hook
-  index.ts          # Main exports
-
-app/
-  demo/             # Demo page
-  api/chat/         # Chat API route
-  api/tools/        # Tool execution API
-
-lib/
-  tools.tsx         # Example tool definitions
-
-docs/
-  API_V2.md         # Full API documentation
+    useTool.ts        # React hooks (useTool, useTools)
+    useToolStream.ts  # Streaming hook
+  components/
+    Chat.tsx          # All-in-one chat component
+    ChatProvider.tsx   # Chat context provider
+    Thread.tsx        # Message list
+    Message.tsx       # Single message
+    Composer.tsx      # Input form
+    ToolResult.tsx    # Tool view renderer
+  providers/
+    openai.ts         # OpenAI adapter
+    anthropic.ts      # Anthropic adapter
+    google.ts         # Google Gemini adapter
+    openrouter.ts     # OpenRouter adapter
+  adapters/
+    nextjs.ts         # Next.js route handlers
+    express.ts        # Express middleware
+  index.ts            # Main exports
 ```
 
 ## Development
@@ -266,6 +366,7 @@ npm run dev          # Run dev server
 npm run build:lib    # Build library
 npm run build        # Build everything
 npm run type-check   # TypeScript check
+npm test             # Run tests
 ```
 
 ## License

package/dist/ThemeProvider-BYeqWMsn.d.mts

@@ -0,0 +1,187 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+import { UIMessage, ChatStatus } from 'ai';
+import { T as Tool } from './tool-Ca2x-VNK.mjs';
+import { P as PersistenceAdapter, T as Thread$1 } from './types-CAOfGUPH.mjs';
+
+interface ToolStateEntry {
+    output: unknown;
+    loading: boolean;
+    error: string | null;
+    version: number;
+    toolName?: string;
+    /** HITL confirmation status */
+    status?: 'pending' | 'confirmed' | 'rejected';
+    /** Entity group key — "toolName:groupKey(input)" — groups related calls */
+    entityId?: string;
+    /** Raw tool input, stored for conditional confirm checks */
+    toolInput?: unknown;
+    /** Auto-incrementing insertion order (store-assigned) */
+    seqNo?: number;
+}
+interface ToolStateStore {
+    get: (toolCallId: string) => ToolStateEntry | undefined;
+    set: (toolCallId: string, entry: ToolStateEntry) => void;
+    /** Remove all entries (e.g. when switching threads) */
+    clear: () => void;
+    subscribe: (toolCallId: string, listener: () => void) => () => void;
+    subscribeAll: (listener: () => void) => () => void;
+    getSnapshot: () => Map<string, ToolStateEntry>;
+    /** Returns Map with highest-seqNo entry per entityId + all ungrouped entries */
+    getLatestPerEntity: () => Map<string, ToolStateEntry>;
+    /** Returns the oldest (lowest seqNo) entry with the given entityId — the "anchor" */
+    findAnchor: (entityId: string) => {
+        toolCallId: string;
+        entry: ToolStateEntry;
+    } | undefined;
+}
+declare function createToolStateStore(): ToolStateStore;
+declare function useToolState(store: ToolStateStore, toolCallId: string): ToolStateEntry | undefined;
+
+/** Parsed tool part from a UIMessage */
+interface ToolPartInfo {
+    toolName: string;
+    toolCallId: string;
+    state: string;
+    output: unknown;
+}
+interface ChatContextValue {
+    messages: UIMessage[];
+    sendMessage: (text: string) => void;
+    isLoading: boolean;
+    status: ChatStatus;
+    tools: Record<string, Tool>;
+    executeToolDirect: (toolName: string, toolInput: Record<string, unknown>, toolCallId: string) => Promise<void>;
+    getOnAction: (toolCallId: string, toolName: string) => (input: Record<string, unknown>) => void;
+    toolStateStore: ToolStateStore;
+    /** Approve and execute a HITL tool, then feed result back to AI */
+    confirmTool: (toolCallId: string, toolName: string, toolInput: Record<string, unknown>) => Promise<void>;
+    /** Reject a HITL tool and notify AI */
+    rejectTool: (toolCallId: string, toolName: string) => Promise<void>;
+    /** Retry a failed tool execution */
+    retryTool: (toolCallId: string, toolName: string, toolInput: unknown) => void;
+    /** Available threads (only when persistence is configured) */
+    threads?: Thread$1[];
+    /** Current thread ID */
+    threadId?: string;
+    /** Create a new thread (only when persistence is configured) */
+    createThread?: (title?: string) => Promise<Thread$1>;
+    /** Switch to a different thread (only when persistence is configured) */
+    switchThread?: (threadId: string) => Promise<void>;
+    /** Delete a thread (only when persistence is configured) */
+    deleteThread?: (threadId: string) => Promise<void>;
+}
+interface ChatProviderProps {
+    endpoint?: string;
+    tools: Record<string, Tool>;
+    toolStateStore?: ToolStateStore;
+    /** Persistence adapter for thread/message storage */
+    persistence?: PersistenceAdapter;
+    /** Active thread ID (used with persistence) */
+    threadId?: string;
+    children: React.ReactNode;
+}
+/**
+ * Hook to access chat context. Must be used within a ChatProvider.
+ */
+declare function useChatContext(): ChatContextValue;
+declare function ChatProvider({ endpoint, tools, toolStateStore: externalStore, persistence, threadId, children }: ChatProviderProps): react_jsx_runtime.JSX.Element;
+
+interface ThreadProps {
+    className?: string;
+    emptyMessage?: string;
+    suggestions?: string[];
+}
+/**
+ * Message list with auto-scroll.
+ * Renders messages from ChatContext, maps over messages, renders text parts and tool parts.
+ */
+declare function Thread({ className, emptyMessage, suggestions }: ThreadProps): react_jsx_runtime.JSX.Element;
+
+interface MessageProps {
+    message: UIMessage;
+    tools: Record<string, Tool>;
+    toolStateStore: ToolStateStore;
+    getOnAction: (toolCallId: string, toolName: string) => (input: Record<string, unknown>) => void;
+    onConfirm?: (toolCallId: string, toolName: string, toolInput: Record<string, unknown>) => void;
+    onReject?: (toolCallId: string, toolName: string) => void;
+    onRetry?: (toolCallId: string, toolName: string, toolInput: unknown) => void;
+    className?: string;
+}
+/**
+ * Renders a single UIMessage.
+ * - User messages: right-aligned bubble (plain text)
+ * - Assistant messages: left-aligned bubble (rendered markdown)
+ * - Tool parts: renders tool.View automatically
+ */
+declare function Message({ message, tools, toolStateStore, getOnAction, onConfirm, onReject, onRetry, className }: MessageProps): react_jsx_runtime.JSX.Element | null;
+
+interface ComposerProps {
+    className?: string;
+    placeholder?: string;
+}
+/**
+ * Input form with text input and send button.
+ * Uses ChatContext to send messages. Disabled during loading.
+ */
+declare function Composer({ className, placeholder }: ComposerProps): react_jsx_runtime.JSX.Element;
+
+interface ToolResultProps {
+    toolName: string;
+    toolCallId: string;
+    output: unknown;
+    toolInput?: unknown;
+    hasResult: boolean;
+    /** Tool part state from the AI SDK (e.g. 'partial-call', 'call', 'output-available') */
+    toolPartState?: string;
+    toolStateStore: ToolStateStore;
+    tools: Record<string, Tool>;
+    getOnAction: (toolCallId: string, toolName: string) => (input: Record<string, unknown>) => void;
+    onConfirm?: (toolCallId: string, toolName: string, toolInput: Record<string, unknown>) => void;
+    onReject?: (toolCallId: string, toolName: string) => void;
+    onRetry?: (toolCallId: string, toolName: string, toolInput: unknown) => void;
+    className?: string;
+}
+/**
+ * Renders a tool's View component given tool name and output.
+ * Uses the tool state store for in-place updates (e.g. counter clicks),
+ * falling back to message part state.
+ *
+ * For HITL tools (confirm: true), renders a confirmation card when
+ * the tool is awaiting user approval.
+ *
+ * Supports groupKey-based in-place updates: when an older call (anchor) with
+ * the same entityId exists, followup calls update the anchor's data and render nothing.
+ */
+declare function ToolResult({ toolName, toolCallId, output, toolInput, hasResult, toolPartState, toolStateStore, tools, getOnAction, onConfirm, onReject, onRetry, className, }: ToolResultProps): react_jsx_runtime.JSX.Element | null;
+
+interface ChatProps {
+    endpoint?: string;
+    tools: Record<string, Tool>;
+    className?: string;
+    placeholder?: string;
+    emptyMessage?: string;
+    suggestions?: string[];
+}
+/**
+ * Convenience all-in-one chat component.
+ * Combines ChatProvider + Thread + Composer into a single drop-in component.
+ */
+declare function Chat({ endpoint, tools, className, placeholder, emptyMessage, suggestions, }: ChatProps): react_jsx_runtime.JSX.Element;
+
+interface ThemeProviderProps {
+    /** Theme name — sets data-theme attribute. Default: 'dark' */
+    theme?: string;
+    /** Override individual CSS variables */
+    variables?: Record<string, string>;
+    /** Additional CSS class */
+    className?: string;
+    children: React.ReactNode;
+}
+/**
+ * Wraps children with a themed container.
+ * Sets `data-theme` for CSS variable scoping and applies inline variable overrides.
+ */
+declare function ThemeProvider({ theme, variables, className, children, }: ThemeProviderProps): react_jsx_runtime.JSX.Element;
+
+export { type ChatProviderProps as C, type MessageProps as M, type ToolPartInfo as T, type ThreadProps as a, type ComposerProps as b, type ToolResultProps as c, type ChatProps as d, type ThemeProviderProps as e, type ToolStateStore as f, type ToolStateEntry as g, ChatProvider as h, Thread as i, Message as j, Composer as k, ToolResult as l, Chat as m, createToolStateStore as n, useToolState as o, ThemeProvider as p, useChatContext as u };