@v0-sdk/react 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2025 Vercel, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -1,5 +1,7 @@
 # @v0-sdk/react
 
+> **⚠️ Developer Preview**: This SDK is currently in beta and is subject to change. Use in production at your own risk.
+
 React components for rendering content from the v0 Platform API.
 
 ## Installation
@@ -17,14 +19,14 @@ pnpm add @v0-sdk/react
 ### Basic Usage
 
 ```tsx
-import { V0MessageRenderer } from '@v0-sdk/react'
+import { Message } from '@v0-sdk/react'
 
 function ChatMessage({ apiResponse }) {
   // Parse the content from the API response
   const content = JSON.parse(apiResponse.content)
 
   return (
-    <V0MessageRenderer
+    <Message
       content={content}
       messageId={apiResponse.id}
       role={apiResponse.role}
@@ -35,37 +37,121 @@ function ChatMessage({ apiResponse }) {
 
 ### With Streaming
 
+The package provides built-in support for streaming responses from v0 API:
+
 ```tsx
-import { V0MessageRenderer } from '@v0-sdk/react'
+import { StreamingMessage } from '@v0-sdk/react'
+import { createClient } from 'v0-sdk'
 
-function StreamingMessage({ apiResponse, isStreaming }) {
-  const content = JSON.parse(apiResponse.content)
+const v0 = createClient()
+
+function ChatDemo() {
+  const [stream, setStream] = useState<ReadableStream<Uint8Array> | null>(null)
+
+  const handleSendMessage = async (message: string) => {
+    const response = await v0.chats.create({
+      message,
+      responseMode: 'experimental_stream',
+    })
+    setStream(response)
+  }
 
   return (
-    <V0MessageRenderer
-      content={content}
-      messageId={apiResponse.id}
-      role={apiResponse.role}
-      streaming={isStreaming}
-      isLastMessage={true}
-    />
+    <div>
+      {stream && (
+        <StreamingMessage
+          stream={stream}
+          messageId="demo-message"
+          role="assistant"
+          onComplete={(content) => console.log('Stream complete:', content)}
+        />
+      )}
+    </div>
   )
 }
 ```
 
-### Custom Styling
+### Using the Streaming Hook
+
+For more control, use the `useStreamingMessage` hook directly:
 
 ```tsx
-import { V0MessageRenderer } from '@v0-sdk/react'
+import { useStreamingMessage, Message } from '@v0-sdk/react'
+
+function CustomStreamingComponent({
+  stream,
+}: {
+  stream: ReadableStream<Uint8Array>
+}) {
+  const { content, isStreaming, error, isComplete } =
+    useStreamingMessage(stream)
+
+  if (error) return <div>Error: {error}</div>
+
+  return (
+    <div>
+      <div>Status: {isStreaming ? 'Streaming...' : 'Complete'}</div>
+      <Message
+        content={content}
+        streaming={isStreaming}
+        isLastMessage={true}
+        messageId="custom-streaming"
+        role="assistant"
+      />
+    </div>
+  )
+}
+```
+
+### Custom Component Styling
+
+The `Message` component supports custom component renderers for complete control over styling and behavior:
+
+```tsx
+import { Message, CodeBlock, MathPart } from '@v0-sdk/react'
+
+// Custom code block with syntax highlighting
+function CustomCodeBlock({ language, code, className }) {
+  return (
+    <div className="my-code-block">
+      <div className="code-header">{language}</div>
+      <pre className={className}>
+        <code>{code}</code>
+      </pre>
+    </div>
+  )
+}
+
+// Custom math renderer
+function CustomMathPart({ content, inline, className }) {
+  return (
+    <span className={`my-math ${inline ? 'inline' : 'block'} ${className}`}>
+      {content}
+    </span>
+  )
+}
 
 function StyledMessage({ apiResponse }) {
   const content = JSON.parse(apiResponse.content)
 
   return (
-    <V0MessageRenderer
+    <Message
       content={content}
       messageId={apiResponse.id}
       role={apiResponse.role}
+      components={{
+        CodeBlock: CustomCodeBlock,
+        MathPart: CustomMathPart,
+        // Style HTML elements with simple className objects
+        p: { className: 'my-paragraph-styles' },
+        h1: { className: 'my-heading-styles' },
+        // Or use custom components for full control
+        blockquote: ({ children, ...props }) => (
+          <div className="my-custom-blockquote" {...props}>
+            {children}
+          </div>
+        ),
+      }}
       className="my-custom-message-styles"
     />
   )
@@ -74,7 +160,7 @@ function StyledMessage({ apiResponse }) {
 
 ## API Reference
 
-### V0MessageRenderer
+### Message
 
 The main component for rendering v0 Platform API message content.
 
@@ -87,7 +173,69 @@ The main component for rendering v0 Platform API message content.
 | `role`          | `'user' \| 'assistant' \| 'system' \| 'tool'` | `'assistant'` | Role of the message sender                                                   |
 | `streaming`     | `boolean`                                     | `false`       | Whether the message is currently being streamed                              |
 | `isLastMessage` | `boolean`                                     | `false`       | Whether this is the last message in the conversation                         |
-| `className`     | `string`                                      | `undefined`   | Custom className for styling                                                 |
+| `className`     | `string`                                      | `undefined`   | Custom className for styling the root container                              |
+| `components`    | `ComponentOverrides`                          | `undefined`   | Custom component renderers (see Custom Components section)                   |
+
+### Individual Components
+
+You can also use individual components directly:
+
+```tsx
+import {
+  CodeBlock,
+  MathPart,
+  ThinkingSection,
+  TaskSection,
+  CodeProjectPart
+} from '@v0-sdk/react'
+
+// Use components directly
+<CodeBlock language="javascript" code="console.log('Hello')" />
+<MathPart content="E = mc^2" inline />
+<ThinkingSection title="Planning" thought="Let me think about this..." />
+```
+
+#### CodeBlock
+
+| Prop        | Type              | Default      | Description                                  |
+| ----------- | ----------------- | ------------ | -------------------------------------------- |
+| `language`  | `string`          | **required** | Programming language for syntax highlighting |
+| `code`      | `string`          | **required** | The code content to display                  |
+| `filename`  | `string`          | `undefined`  | Optional filename to display                 |
+| `className` | `string`          | `undefined`  | Custom styling                               |
+| `children`  | `React.ReactNode` | `undefined`  | Custom content (overrides code prop)         |
+
+#### MathPart
+
+| Prop          | Type              | Default      | Description                             |
+| ------------- | ----------------- | ------------ | --------------------------------------- |
+| `content`     | `string`          | **required** | The mathematical expression             |
+| `inline`      | `boolean`         | `false`      | Whether to render inline or as block    |
+| `displayMode` | `boolean`         | `undefined`  | Alternative to inline for display mode  |
+| `className`   | `string`          | `undefined`  | Custom styling                          |
+| `children`    | `React.ReactNode` | `undefined`  | Custom content (overrides content prop) |
+
+#### ThinkingSection
+
+| Prop         | Type         | Default     | Description                  |
+| ------------ | ------------ | ----------- | ---------------------------- |
+| `title`      | `string`     | `undefined` | Section title                |
+| `thought`    | `string`     | `undefined` | The thinking content         |
+| `duration`   | `number`     | `undefined` | Duration in milliseconds     |
+| `collapsed`  | `boolean`    | `false`     | Whether section is collapsed |
+| `onCollapse` | `() => void` | `undefined` | Collapse toggle handler      |
+| `className`  | `string`     | `undefined` | Custom styling               |
+
+#### TaskSection
+
+| Prop         | Type         | Default     | Description                  |
+| ------------ | ------------ | ----------- | ---------------------------- |
+| `title`      | `string`     | `undefined` | Section title                |
+| `type`       | `string`     | `undefined` | Task type                    |
+| `parts`      | `any[]`      | `undefined` | Task content parts           |
+| `collapsed`  | `boolean`    | `false`     | Whether section is collapsed |
+| `onCollapse` | `() => void` | `undefined` | Collapse toggle handler      |
+| `className`  | `string`     | `undefined` | Custom styling               |
 
 ### Types
 
@@ -99,16 +247,17 @@ type MessageBinaryFormat = [number, ...any[]][]
 
 The binary format for message content as returned by the v0 Platform API. Each row is a tuple where the first element is the type and the rest are data.
 
-#### V0MessageRendererProps
+#### MessageProps
 
 ```typescript
-interface V0MessageRendererProps {
+interface MessageProps {
   content: MessageBinaryFormat
   messageId?: string
   role?: 'user' | 'assistant' | 'system' | 'tool'
   streaming?: boolean
   isLastMessage?: boolean
   className?: string
+  components?: ComponentOverrides
 }
 ```
 
@@ -117,50 +266,61 @@ interface V0MessageRendererProps {
 ### Supported Content Types
 
 - **Markdown/Text Content**: Paragraphs, headings, lists, links, emphasis, code spans, etc.
-- **Code Blocks**: Syntax-highlighted code blocks with support for 25+ programming languages
-- **Mathematical Expressions**: Inline and block math using KaTeX
-- **Extensible**: Easy to extend with additional content types
-
-### Syntax Highlighting
-
-Code blocks are automatically syntax-highlighted using Prism.js with support for:
-
-- JavaScript/TypeScript
-- Python, Java, C/C++, C#
-- PHP, Ruby, Go, Rust
-- Swift, Kotlin, Scala
-- SQL, JSON, YAML
-- Markdown, CSS/SCSS
-- Bash/Shell scripts
-- And many more...
-
-### Math Rendering
+- **Code Blocks**: Syntax-highlighted code blocks with filename support
+- **Mathematical Expressions**: Inline and block math expressions
+- **Thinking Sections**: Collapsible reasoning/thinking content
+- **Task Sections**: Structured task and workflow content
+- **Code Projects**: Multi-file code project display
+- **Rich Components**: Full component customization support
 
-Mathematical expressions are rendered using KaTeX:
+### Component Customization
 
-- Inline math: `$E = mc^2$`
-- Block math: `$$\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}$$`
+The `components` prop allows you to override any part of the rendering:
 
-## CSS Styling
+```tsx
+// Simple className-based styling
+<Message
+  content={content}
+  components={{
+    p: { className: 'my-paragraph' },
+    h1: { className: 'text-2xl font-bold' }
+  }}
+/>
+
+// Full component replacement
+<Message
+  content={content}
+  components={{
+    CodeBlock: MyCustomCodeBlock,
+    MathPart: MyCustomMathRenderer,
+    ThinkingSection: MyCustomThinking
+  }}
+/>
+```
 
-The component uses Tailwind CSS classes by default. You can:
+### Default Styling
 
-1. **Use Tailwind CSS**: The component works out of the box with Tailwind
-2. **Custom CSS**: Override styles using the `className` prop
-3. **CSS Modules**: Import your own styles and pass via `className`
+The components use Tailwind CSS classes by default but can work with any CSS framework:
 
-### Required CSS
+1. **Tailwind CSS**: Works out of the box
+2. **Custom CSS**: Use the `className` prop and `components` overrides
+3. **CSS Modules**: Pass CSS module classes via `className` and `components`
+4. **Styled Components**: Wrap components with styled-components
 
-Make sure to include KaTeX CSS for math rendering:
+## Backward Compatibility
 
-```css
-@import 'katex/dist/katex.min.css';
-```
+The package maintains backward compatibility with previous versions:
 
-Or import it in your JavaScript:
+```tsx
+// These all work and refer to the same component
+import { Message } from '@v0-sdk/react'
+import { MessageRenderer } from '@v0-sdk/react'
+import { V0MessageRenderer } from '@v0-sdk/react'
 
-```javascript
-import 'katex/dist/katex.min.css'
+// These are all equivalent
+<Message content={content} />
+<MessageRenderer content={content} />
+<V0MessageRenderer content={content} />
 ```
 
 ## Examples
@@ -168,8 +328,7 @@ import 'katex/dist/katex.min.css'
 ### Complete Chat Interface
 
 ```tsx
-import { V0MessageRenderer } from '@v0-sdk/react'
-import 'katex/dist/katex.min.css'
+import { Message } from '@v0-sdk/react'
 
 function ChatInterface({ messages }) {
   return (
@@ -184,7 +343,7 @@ function ChatInterface({ messages }) {
               <span className="role">{message.role}</span>
               <span className="timestamp">{message.createdAt}</span>
             </div>
-            <V0MessageRenderer
+            <Message
               content={content}
               messageId={message.id}
               role={message.role}
@@ -199,17 +358,75 @@ function ChatInterface({ messages }) {
 }
 ```
 
+### Custom Theme Example
+
+```tsx
+import { Message, CodeBlock, MathPart } from '@v0-sdk/react'
+
+// Dark theme code block
+function DarkCodeBlock({ language, code, filename }) {
+  return (
+    <div className="bg-gray-900 rounded-lg overflow-hidden">
+      {filename && (
+        <div className="bg-gray-800 px-4 py-2 text-gray-300 text-sm">
+          {filename}
+        </div>
+      )}
+      <div className="bg-gray-700 px-2 py-1 text-xs text-gray-400">
+        {language}
+      </div>
+      <pre className="p-4 text-green-400 overflow-x-auto">
+        <code>{code}</code>
+      </pre>
+    </div>
+  )
+}
+
+// Elegant math renderer
+function ElegantMath({ content, inline }) {
+  return (
+    <span
+      className={`
+      ${inline ? 'mx-1' : 'block text-center my-4'}
+      font-serif text-blue-600
+    `}
+    >
+      {content}
+    </span>
+  )
+}
+
+function ThemedChat({ apiResponse }) {
+  const content = JSON.parse(apiResponse.content)
+
+  return (
+    <Message
+      content={content}
+      components={{
+        CodeBlock: DarkCodeBlock,
+        MathPart: ElegantMath,
+        h1: { className: 'text-3xl font-bold text-gray-800 mb-4' },
+        h2: { className: 'text-2xl font-semibold text-gray-700 mb-3' },
+        p: { className: 'text-gray-600 leading-relaxed mb-4' },
+        blockquote: { className: 'border-l-4 border-blue-500 pl-4 italic' },
+      }}
+      className="max-w-4xl mx-auto p-6"
+    />
+  )
+}
+```
+
 ### Error Handling
 
 ```tsx
-import { V0MessageRenderer } from '@v0-sdk/react'
+import { Message } from '@v0-sdk/react'
 
 function SafeMessageRenderer({ apiResponse }) {
   try {
     const content = JSON.parse(apiResponse.content)
 
     return (
-      <V0MessageRenderer
+      <Message
         content={content}
         messageId={apiResponse.id}
         role={apiResponse.role}
@@ -217,17 +434,44 @@ function SafeMessageRenderer({ apiResponse }) {
     )
   } catch (error) {
     console.error('Failed to parse message content:', error)
-
-    return <div className="error-message">Failed to render message content</div>
+    return (
+      <div className="error-message p-4 bg-red-50 border border-red-200 rounded">
+        <p className="text-red-700">Failed to render message content</p>
+        <pre className="text-xs text-red-600 mt-2 overflow-x-auto">
+          {error.message}
+        </pre>
+      </div>
+    )
   }
 }
 ```
 
+## TypeScript
+
+The package is written in TypeScript and includes comprehensive type definitions. All components and props are fully typed for the best development experience.
+
+```tsx
+import type {
+  MessageProps,
+  CodeBlockProps,
+  MathPartProps,
+  MessageBinaryFormat,
+} from '@v0-sdk/react'
+
+// Type-safe usage
+const myMessage: MessageProps = {
+  content: parsedContent,
+  role: 'assistant',
+  streaming: false,
+}
+```
+
 ## Requirements
 
 - React 18+ or React 19+
 - Modern browser with ES2020+ support
+- TypeScript 4.5+ (if using TypeScript)
 
 ## License
 
-MIT
+Apache 2.0