@melony/react 0.1.12 → 0.1.14

package/README.md

@@ -1,237 +1,98 @@
 # @melony/react
 
-React components and hooks for building AI chat interfaces with Melony.
+React UI + providers/hooks for building chat experiences on top of **Melony’s event stream**, including automatic rendering for **Server‑Driven UI (SDUI)** (`event.ui`).
 
 ## Installation
 
 ```bash
-npm install @melony/react
+npm install @melony/react melony react
 ```
 
-## Quick Start
+## Quick start
 
 ```tsx
-import { MelonyStoreProvider, Thread, ThreadSidebar, useMelony } from "@melony/react";
+import React from "react";
+import { MelonyClient, createHttpTransport } from "melony/client";
+import { MelonyClientProvider, Thread } from "@melony/react";
 
-function ThreadApp() {
-  const { threads, activeThreadId, messages, isLoading } = useMelony();
-
-  return (
-    <div style={{ display: 'flex', height: '100vh' }}>
-      <ThreadSidebar threads={threads} activeThreadId={activeThreadId} />
-      <Thread messages={messages} isLoading={isLoading} />
-    </div>
-  );
-}
+const client = new MelonyClient(createHttpTransport("/api/chat"));
 
 export default function App() {
   return (
-    <MelonyStoreProvider api="/api/chat">
-      <ThreadApp />
-    </MelonyStoreProvider>
+    <MelonyClientProvider client={client}>
+      <Thread />
+    </MelonyClientProvider>
   );
 }
 ```
 
-## Architecture
-
-Melony React uses an **event-based architecture** where all actions are dispatched as events:
-
-```tsx
-const { dispatchEvent } = useMelony();
-
-// Create a thread
-dispatchEvent({ type: 'createThread' });
-
-// Switch thread
-dispatchEvent({ type: 'switchThread', data: { threadId: 'abc' } });
-
-// Send a message
-dispatchEvent({
-  type: 'sendMessage',
-  data: {
-    role: 'user',
-    content: [{ type: 'text', data: { content: 'Hello!' } }]
-  }
-});
-```
-
-## Core Components
-
-### `MelonyStoreProvider`
-
-The main provider that manages threads, messages, and API communication.
-
-```tsx
-<MelonyStoreProvider
-  api="/api/chat"
-  onLoadHistory={async (threadId) => {
-    // Load message history when switching threads
-    const res = await fetch(`/api/threads/${threadId}/messages`);
-    return res.json();
-  }}
-  onThreadsChange={(threads) => {
-    // Persist threads (e.g., to localStorage)
-    localStorage.setItem('threads', JSON.stringify(threads));
-  }}
-  onEvent={(event) => {
-    // Handle custom events
-    console.log('Event:', event.type);
-  }}
->
-  <App />
-</MelonyStoreProvider>
-```
-
-### `Thread`
+### Send a message from UI
 
-The main thread interface component.
+`Thread` already wires this up, but if you want manual control:
 
 ```tsx
-<Thread
-  messages={messages}
-  isLoading={isLoading}
-  placeholder="Type a message..."
-  components={{
-    // Custom components for Server-Driven UI
-    'weather-card': WeatherCard,
-  }}
-/>
-```
-
-### `ThreadSidebar`
-
-Sidebar showing list of conversation threads.
+import { useMelony } from "@melony/react";
 
-```tsx
-<ThreadSidebar
-  threads={threads}
-  activeThreadId={activeThreadId}
-  width={280}
-/>
+function Controls() {
+  const { sendEvent, isLoading } = useMelony();
+  return (
+    <button
+      disabled={isLoading}
+      onClick={() =>
+        sendEvent({ type: "text", role: "user", data: { content: "Hello!" } })
+      }
+    >
+      Send
+    </button>
+  );
+}
 ```
 
-## Hooks
-
-### `useMelony()`
-
-Main hook to access store state and dispatch events.
-
-```tsx
-const {
-  // State
-  threads,           // Thread[] - all threads
-  activeThreadId,    // string | null
-  activeThread,      // Thread | undefined
-  messages,          // ChatMessage[] - messages in active thread
-  isLoading,         // boolean
-  error,             // Error | null
-  
-  // Methods
-  dispatchEvent,     // (event: Event) => void
-  getThread,         // (id: string) => Thread | undefined
-  getThreadMessages, // (id: string) => ChatMessage[]
-} = useMelony();
-```
+## Components
 
-### `useDispatchedEvent()`
+- **`Thread`**: a full chat thread (composer + message list + streaming).
+- **`ChatSidebar`**: a sidebar-style chat UI container.
+- **`ChatFull` / `ChatPopup`**: ready-to-embed layouts (see exports).
+- **`UIRenderer`**: renders SDUI `UINode` trees from `melony`.
 
-Listen to events dispatched through the system.
+## Providers & hooks
 
-```tsx
-useDispatchedEvent((event) => {
-  if (event.type === 'sendMessage') {
-    console.log('Message sent!');
-  }
-});
-```
+- **`MelonyClientProvider`** + **`useMelony()`**
+  - wraps a `MelonyClient` from `melony/client`
+  - exposes `events`, `messages`, `isLoading`, `error`, and `sendEvent()`
 
-## Event Types
+- **`ThreadProvider`** + **`useThreads()`** (optional)
+  - adds “thread list / active thread” state
+  - you bring a `ThreadService` (load threads, load events, delete thread, etc.)
 
-| Event | Data | Description |
-|-------|------|-------------|
-| `createThread` | `{ initialMessage?, title? }` | Create a new thread |
-| `switchThread` | `{ threadId }` | Switch to a thread |
-| `deleteThread` | `{ threadId }` | Delete a thread |
-| `updateThreadTitle` | `{ threadId, title }` | Update thread title |
-| `sendMessage` | `{ role, content, threadId? }` | Send a message |
-| `clearThread` | `{ threadId? }` | Clear thread messages |
+- **`AuthProvider`** + **`useAuth()`** (optional)
+  - plug in an `AuthService` (login/logout/me/token) for authenticated apps
 
-## UI Components
+## SDUI (Server‑Driven UI)
 
-Layout: `Row`, `Col`, `Box`, `Spacer`, `Divider`, `List`, `ListItem`  
-Content: `Text`, `Heading`, `Image`, `Icon`, `Badge`, `Chart`  
-Forms: `Button`, `Input`, `Textarea`, `Select`, `Checkbox`, `RadioGroup`, `Form`, `Label`  
-Containers: `Card`
+If the backend yields events with `event.ui`, Melony React renders them automatically inside assistant messages.
 
-## Server-Driven UI
+Backend example:
 
-Components can render UI from server events:
+```ts
+import { ui } from "melony";
 
-```tsx
-// Server sends:
 yield {
-  type: 'ui',
-  ui: {
-    type: 'card',
-    props: { title: 'Weather' },
-    children: [
-      { type: 'text', props: { value: '72°F' } }
-    ]
-  }
+  type: "ui",
+  ui: ui.card({
+    title: "Weather",
+    children: [ui.text("72°F and sunny")],
+  }),
 };
-
-// Renderer automatically displays the Card with Text
-```
-
-## Theming
-
-```tsx
-<MelonyStoreProvider
-  api="/api/chat"
-  theme={{
-    colors: {
-      primary: '#6366f1',
-      background: '#ffffff',
-    },
-    radius: {
-      md: '8px',
-    },
-  }}
->
-  <App />
-</MelonyStoreProvider>
 ```
 
-## Migration from Legacy Hooks
-
-If you're using the deprecated hooks (`useMelonyRuntime`, `useMelonyThread`, `useMelonyThreads`):
-
-```tsx
-// Before:
-const { messages, sendMessage } = useMelonyThread({ api: '/api/chat' });
-const { threads, createThread } = useMelonyThreads({ threads, activeThreadId });
-
-// After:
-// 1. Wrap with MelonyStoreProvider
-// 2. Use useMelony()
-const { messages, threads, dispatchEvent } = useMelony();
-
-// Send message via event
-dispatchEvent({
-  type: 'sendMessage',
-  data: { role: 'user', content: [...] }
-});
-
-// Create thread via event  
-dispatchEvent({ type: 'createThread' });
-```
+Frontend: no extra work — it shows up in the message stream.
 
 ## Development
 
 ```bash
-pnpm build      # Build
-pnpm dev        # Watch mode
-pnpm typecheck  # Type check
-pnpm clean      # Clean dist
+pnpm build
+pnpm dev
+pnpm typecheck
+pnpm clean
 ```