@app-studio/web 0.9.41 → 0.9.43

package/docs/components/ChatInput.mdx

@@ -1,373 +1,425 @@
 # ChatInput
 
+A customizable chat input component with file upload support, mentions, suggestions, audio recording, and model selection.
 
 ### **Import**
-  ```tsx
-  import { ChatInput } from '@app-studio/web';
-  ```
+```tsx
+import { ChatInput } from '@app-studio/web';
+```
 
-### **Basic Usage**
+### **Default**
 ```tsx
 import React, { useState } from 'react';
 import { ChatInput } from '@app-studio/web';
-import { View } from '@app-studio/web';
 
-export const BasicChatInput = () => {
-  const [inputValue, setInputValue] = useState('');
+export const DefaultChatInput = () => {
+  const [files, setFiles] = useState<File[]>([]);
+  
+  return (
+    <ChatInput 
+      onSubmit={(message) => console.log('Message:', message)}
+      getPendingFiles={() => files}
+      clearPendingFiles={() => setFiles([])}
+    />
+  );
+};
+```
+
+### **onSubmit**
+Callback function when the form is submitted.
 
-  const handleSubmit = (message) => {
-    console.log('Message submitted:', message);
-    setInputValue('');
-  };
+- **Type:** `(message: string, options?: { model_name?: string; enable_thinking?: boolean }) => void`
+- **Required:** `true`
 
+```tsx
+import React, { useState } from 'react';
+import { ChatInput } from '@app-studio/web';
+
+export const SubmitChatInput = () => {
+  const [files, setFiles] = useState<File[]>([]);
+  
   return (
-    <View width="100%">
-      <ChatInput
-        onSubmit={handleSubmit}
-        value={inputValue}
-        onChange={setInputValue}
-        placeholder="Type your message here..."
-      />
-    </View>
+    <ChatInput 
+      onSubmit={(message, options) => {
+        console.log('Message:', message);
+        console.log('Model:', options?.model_name);
+        console.log('Thinking:', options?.enable_thinking);
+      }}
+      getPendingFiles={() => files}
+      clearPendingFiles={() => setFiles([])}
+    />
   );
 };
 ```
 
-### **File Upload & Attachments**
+### **placeholder**
+Placeholder text for the input.
 
-The ChatInput component uses the integrated Uploader component for seamless file handling:
+- **Type:** `string`
+- **Default:** `'Type a message...'`
 
 ```tsx
 import React, { useState } from 'react';
 import { ChatInput } from '@app-studio/web';
-import { View } from '@app-studio/web';
 
-export const ChatInputWithFileUploads = () => {
-  const [inputValue, setInputValue] = useState('');
+export const PlaceholderChatInput = () => {
+  const [files, setFiles] = useState<File[]>([]);
+  
+  return (
+    <ChatInput 
+      placeholder="Ask me anything..."
+      onSubmit={(message) => console.log(message)}
+      getPendingFiles={() => files}
+      clearPendingFiles={() => setFiles([])}
+    />
+  );
+};
+```
+
+### **loading**
+Whether the input is in a loading state.
+
+- **Type:** `boolean`
+- **Default:** `false`
 
-  const handleSubmit = (message, options) => {
-    console.log('Message submitted:', message);
-    console.log('Options:', options);
-    // Message will include file information automatically
-  };
+```tsx
+import React, { useState } from 'react';
+import { ChatInput } from '@app-studio/web';
 
+export const LoadingChatInput = () => {
+  const [files, setFiles] = useState<File[]>([]);
+  const [loading, setLoading] = useState(false);
+  
   return (
-    <View width="100%">
-      <ChatInput
-        onSubmit={handleSubmit}
-        value={inputValue}
-        onChange={setInputValue}
-        placeholder="Upload files and send a message..."
-        hideAttachments={false} // Show attachment button
-      />
-    </View>
+    <ChatInput 
+      loading={loading}
+      onSubmit={(message) => {
+        setLoading(true);
+        setTimeout(() => setLoading(false), 2000);
+      }}
+      getPendingFiles={() => files}
+      clearPendingFiles={() => setFiles([])}
+    />
   );
 };
 ```
 
-**File Upload Features:**
-- **Multiple File Selection**: Select multiple files at once using Ctrl/Cmd + click
-- **Drag & Drop Support**: Drop files directly into the chat input area
-- **File Size Validation**: 50MB maximum file size with automatic validation
-- **File Type Support**: All file types supported (images, documents, videos, etc.)
-- **Preview & Management**: View uploaded files and remove them before sending
-### **With Prompt Examples**
+### **disabled**
+Whether the input is disabled.
+
+- **Type:** `boolean`
+- **Default:** `false`
+
 ```tsx
 import React, { useState } from 'react';
 import { ChatInput } from '@app-studio/web';
-import { View } from '@app-studio/web';
-import { PromptExample } from '@app-studio/web';
-
-export const ChatInputWithPromptExamples = () => {
-  const [inputValue, setInputValue] = useState('');
-
-  // Example prompt suggestions
-  const promptExamples: PromptExample[] = [
-    { id: '1', text: 'Tell me a joke' },
-    { id: '2', text: 'What is the weather today?' },
-    { id: '3', text: 'How do I create a React component?' },
-    { id: '4', text: 'Write a poem about coding' },
-  ];
 
-  const handleSubmit = (message) => {
-    console.log('Message submitted:', message);
-    setInputValue('');
-  };
+export const DisabledChatInput = () => {
+  const [files, setFiles] = useState<File[]>([]);
+  
+  return (
+    <ChatInput 
+      disabled
+      onSubmit={(message) => console.log(message)}
+      getPendingFiles={() => files}
+      clearPendingFiles={() => setFiles([])}
+    />
+  );
+};
+```
+
+### **value & onChange**
+Controlled input value.
 
-  const handlePromptSelect = (example) => {
-    console.log('Prompt selected:', example);
-  };
+- **Type:** `string` & `(value: string) => void`
 
+```tsx
+import React, { useState } from 'react';
+import { ChatInput } from '@app-studio/web';
+
+export const ControlledChatInput = () => {
+  const [value, setValue] = useState('');
+  const [files, setFiles] = useState<File[]>([]);
+  
   return (
-    <View width="100%">
-      <ChatInput
-        onSubmit={handleSubmit}
-        value={inputValue}
-        onChange={setInputValue}
-        promptExamples={promptExamples}
-        onPromptExampleSelect={handlePromptSelect}
-      />
-    </View>
+    <ChatInput 
+      value={value}
+      onChange={setValue}
+      onSubmit={(message) => {
+        console.log(message);
+        setValue('');
+      }}
+      getPendingFiles={() => files}
+      clearPendingFiles={() => setFiles([])}
+    />
   );
 };
 ```
 
-### **Drag & Drop File Upload**
+### **hideAttachments**
+Whether to hide the attachment button.
 
-The ChatInput supports drag & drop functionality for easy file uploads:
+- **Type:** `boolean`
+- **Default:** `false`
 
 ```tsx
 import React, { useState } from 'react';
 import { ChatInput } from '@app-studio/web';
-import { View } from '@app-studio/web';
 
-export const ChatInputWithDragDrop = () => {
-  const [inputValue, setInputValue] = useState('');
+export const NoAttachmentsChatInput = () => {
+  const [files, setFiles] = useState<File[]>([]);
+  
+  return (
+    <ChatInput 
+      hideAttachments
+      onSubmit={(message) => console.log(message)}
+      getPendingFiles={() => files}
+      clearPendingFiles={() => setFiles([])}
+    />
+  );
+};
+```
+
+### **enableAudioRecording**
+Enable audio recording button.
+
+- **Type:** `boolean`
+- **Default:** `false`
 
-  const handleSubmit = (message, options) => {
-    console.log('Message with files:', message);
-    // Files are automatically processed and included
-  };
+```tsx
+import React, { useState } from 'react';
+import { ChatInput } from '@app-studio/web';
 
+export const AudioChatInput = () => {
+  const [files, setFiles] = useState<File[]>([]);
+  
   return (
-    <View width="100%">
-      <ChatInput
-        onSubmit={handleSubmit}
-        value={inputValue}
-        onChange={setInputValue}
-        placeholder="Drag files here or click the attachment button..."
-      />
-    </View>
+    <ChatInput 
+      enableAudioRecording
+      onAudioRecordingStart={() => console.log('Recording started')}
+      onAudioRecordingStop={(audio) => console.log('Audio blob:', audio)}
+      onSubmit={(message) => console.log(message)}
+      getPendingFiles={() => files}
+      clearPendingFiles={() => setFiles([])}
+    />
   );
 };
 ```
 
-**Drag & Drop Features:**
-- **Visual Feedback**: Input area highlights when files are dragged over
-- **Multiple Files**: Drop multiple files at once for batch upload
-- **File Validation**: Automatic size and type validation during drop
-- **Error Handling**: Clear feedback for invalid files or size limits
+### **suggestions**
+List of suggestions for auto-completion.
+
+- **Type:** `Suggestion[]`
 
-### **Custom Styling**
 ```tsx
-import React from 'react';
+import React, { useState } from 'react';
 import { ChatInput } from '@app-studio/web';
-import { View } from '@app-studio/web';
-
-export const StyledChatInput = () => {
-  const handleSubmit = (message) => {
-    console.log('Message submitted:', message);
-  };
 
+export const SuggestionsChatInput = () => {
+  const [files, setFiles] = useState<File[]>([]);
+  
+  const suggestions = [
+    { text: 'How do I...', value: 'how-to' },
+    { text: 'What is...', value: 'what-is' },
+    { text: 'Can you help me...', value: 'help' },
+  ];
+  
   return (
-    <View width="100%">
-      <ChatInput
-        onSubmit={handleSubmit}
-        placeholder="Type a message..."
-        shape="pillShaped"
-        variant="outline"
-        views={{
-          container: {
-            backgroundColor: 'color.purple.50',
-          },
-          content: {
-            borderColor: 'color.purple.200',
-          },
-          submitButton: {
-            backgroundColor: 'color.purple.500',
-          },
-        }}
-      />
-    </View>
+    <ChatInput 
+      suggestions={suggestions}
+      onSubmit={(message) => console.log(message)}
+      getPendingFiles={() => files}
+      clearPendingFiles={() => setFiles([])}
+    />
   );
 };
 ```
 
-### **With Agent Controls**
+### **mentionData**
+Data for mention auto-completion.
+
+- **Type:** `Array<{ id: string; name: string; avatar?: string; description?: string }>`
+
 ```tsx
 import React, { useState } from 'react';
 import { ChatInput } from '@app-studio/web';
-import { View } from '@app-studio/web';
-
-export const ChatInputWithAgent = () => {
-  const [isAgentRunning, setIsAgentRunning] = useState(false);
 
-  const handleSubmit = (message, options) => {
-    console.log('Message submitted:', message);
-    console.log('Options:', options);
+export const MentionsChatInput = () => {
+  const [files, setFiles] = useState<File[]>([]);
+  
+  const mentionData = [
+    { id: '1', name: 'John Doe', avatar: '/avatars/john.jpg' },
+    { id: '2', name: 'Jane Smith', avatar: '/avatars/jane.jpg' },
+    { id: '3', name: 'Bob Johnson', description: 'Developer' },
+  ];
+  
+  return (
+    <ChatInput 
+      mentionData={mentionData}
+      mentionTrigger="@"
+      onMentionSelect={(mention) => console.log('Mentioned:', mention)}
+      onSubmit={(message) => console.log(message)}
+      getPendingFiles={() => files}
+      clearPendingFiles={() => setFiles([])}
+    />
+  );
+};
+```
 
-    // Start the agent
-    setIsAgentRunning(true);
+### **promptExamples**
+List of prompt examples to display.
 
-    // Simulate agent running for 5 seconds
-    setTimeout(() => {
-      setIsAgentRunning(false);
-    }, 5000);
-  };
+- **Type:** `PromptExample[]`
 
-  const handleStopAgent = () => {
-    console.log('Agent stopped');
-    setIsAgentRunning(false);
-  };
+```tsx
+import React, { useState } from 'react';
+import { ChatInput } from '@app-studio/web';
 
+export const PromptExamplesChatInput = () => {
+  const [files, setFiles] = useState<File[]>([]);
+  
+  const promptExamples = [
+    { title: 'Write a story', prompt: 'Write a short story about...' },
+    { title: 'Explain a concept', prompt: 'Explain quantum physics in simple terms' },
+    { title: 'Code help', prompt: 'Help me debug this code...' },
+  ];
+  
   return (
-    <View width="100%">
-      <ChatInput
-        onSubmit={handleSubmit}
-        isAgentRunning={isAgentRunning}
-        onStopAgent={handleStopAgent}
-      />
-    </View>
+    <ChatInput 
+      promptExamples={promptExamples}
+      onPromptExampleSelect={(example) => console.log('Selected:', example)}
+      onSubmit={(message) => console.log(message)}
+      getPendingFiles={() => files}
+      clearPendingFiles={() => setFiles([])}
+    />
   );
 };
 ```
 
-### **Props**
-
-| Prop | Type | Default | Description |
-| ---- | ---- | ------- | ----------- |
-| onSubmit | `(message: string, options?: { model_name?: string; enable_thinking?: boolean }) => void` | required | Callback function when the form is submitted |
-| placeholder | string | 'Say what you want and Kimmy will surprise you' | Placeholder text for the input |
-| loading | boolean | false | Whether the input is in a loading state |
-| disabled | boolean | false | Whether the input is disabled |
-| isAgentRunning | boolean | false | Whether an agent is currently running |
-| onStopAgent | `() => void` | undefined | Callback function to stop the agent |
-| autoFocus | boolean | true | Whether to auto focus the input |
-| value | string | undefined | Controlled value for the input |
-| onChange | `(value: string) => void` | undefined | Callback function when the input value changes |
-| onFileBrowse | `() => void` | undefined | Callback function when the file browser is opened |
-| sandboxId | string | undefined | ID of the sandbox |
-| hideAttachments | boolean | false | Whether to hide the attachment button |
-| title | string | undefined | Title for the chat input |
-| showGuideTip | boolean | false | Whether to show the guide tip |
-| guideVideoUrl | string | undefined | URL for the guide video |
-| onGuideClose | `() => void` | undefined | Callback function when the guide tip is closed |
-| promptExamples | `PromptExample[]` | [] | List of prompt examples |
-| onPromptExampleSelect | `(example: PromptExample) => void` | undefined | Callback function when a prompt example is selected |
-| size | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | 'md' | Size of the chat input |
-| shape | `'default' \| 'sharp' \| 'rounded' \| 'pillShaped'` | 'rounded' | Shape of the chat input |
-| variant | `'default' \| 'outline' \| 'none'` | 'default' | Visual variant of the chat input |
-| views | object | {} | Custom styling for different parts of the component |
-
-### **File Upload Integration**
-
-The ChatInput component integrates seamlessly with the Uploader component:
-
-- **Automatic File Processing**: Files are automatically processed and added to the message
-- **File Size Validation**: 50MB maximum file size with clear error messages
-- **Multiple File Support**: Upload multiple files simultaneously
-- **Drag & Drop Integration**: Full drag and drop support with visual feedback
-
-### **Customization**
-
-The ChatInput component can be customized using the `views` prop:
+### **isAgentRunning & onStopAgent**
+Agent running state and stop callback.
+
+- **Type:** `boolean` & `() => void`
 
 ```tsx
-<ChatInput
-  // ...other props
-  views={{
-    container: { /* styles for the main container */ },
-    content: { /* styles for the content wrapper */ },
-    editableInput: { /* styles for the editable input */ },
-    header: { /* styles for the header */ },
-    title: { /* styles for the title */ },
-    guideTip: { /* styles for the guide tip */ },
-    promptExamples: { /* styles for the prompt examples container */ },
-    promptExampleItem: { /* styles for each prompt example item */ },
-    attachments: { /* styles for the attachments container */ },
-    attachmentItem: { /* styles for each attachment item */ },
-    attachmentName: { /* styles for attachment file names */ },
-    attachmentSize: { /* styles for attachment file sizes */ },
-    attachmentRemove: { /* styles for attachment remove buttons */ },
-    submitButton: { /* styles for the submit button */ },
-    fileButton: { /* styles for the file upload button */ },
-  }}
-/>
+import React, { useState } from 'react';
+import { ChatInput } from '@app-studio/web';
+
+export const AgentChatInput = () => {
+  const [files, setFiles] = useState<File[]>([]);
+  const [isRunning, setIsRunning] = useState(false);
+  
+  return (
+    <ChatInput 
+      isAgentRunning={isRunning}
+      onStopAgent={() => {
+        console.log('Stopping agent');
+        setIsRunning(false);
+      }}
+      onSubmit={(message) => {
+        console.log(message);
+        setIsRunning(true);
+      }}
+      getPendingFiles={() => files}
+      clearPendingFiles={() => setFiles([])}
+    />
+  );
+};
 ```
 
-### **Accessibility**
+### **size**
+Size of the input.
 
-The ChatInput component implements the following accessibility features:
+- **Type:** `Size`
+- **Default:** `'md'`
+- **Possible Values:** `'xs' | 'sm' | 'md' | 'lg' | 'xl'`
 
-- Keyboard navigation for submitting messages (Enter key)
-- ARIA attributes for interactive elements
-- Focus management for the input field
-- Proper contrast for text and buttons
+```tsx
+import React, { useState } from 'react';
+import { ChatInput } from '@app-studio/web';
+import { Vertical } from 'app-studio';
 
-### **Best Practices**
+export const SizedChatInputs = () => {
+  const [files, setFiles] = useState<File[]>([]);
+  
+  return (
+    <Vertical gap={15}>
+      {['sm', 'md', 'lg'].map((size) => (
+        <ChatInput 
+          key={size}
+          size={size as any}
+          onSubmit={(message) => console.log(message)}
+          getPendingFiles={() => files}
+          clearPendingFiles={() => setFiles([])}
+        />
+      ))}
+    </Vertical>
+  );
+};
+```
 
-**General Usage:**
-- Provide clear placeholder text to guide users
-- Use the `loading` state to indicate when a message is being processed
-- Implement proper error handling for message submission
-- Provide feedback to users when messages are sent successfully
+### **variant**
+Variant of the input.
 
-**File Upload Best Practices:**
-- Handle file uploads appropriately on the server side
-- Validate file types and sizes on both client and server
-- Provide clear feedback for file upload errors
-- Consider implementing file preview functionality
+- **Type:** `Variant`
+- **Possible Values:** `'default' | 'outlined' | 'filled'`
 
+```tsx
+import React, { useState } from 'react';
+import { ChatInput } from '@app-studio/web';
+import { Vertical } from 'app-studio';
 
-**Accessibility Considerations:**
-- Ensure file upload buttons are keyboard accessible
-- Use proper ARIA labels for interactive elements
-- Test with screen readers for file upload functionality
+export const VariantChatInputs = () => {
+  const [files, setFiles] = useState<File[]>([]);
+  
+  return (
+    <Vertical gap={15}>
+      {['default', 'outlined', 'filled'].map((variant) => (
+        <ChatInput 
+          key={variant}
+          variant={variant as any}
+          onSubmit={(message) => console.log(message)}
+          getPendingFiles={() => files}
+          clearPendingFiles={() => setFiles([])}
+        />
+      ))}
+    </Vertical>
+  );
+};
+```
 
-### **Demo & Testing**
+### **views**
+Custom styles for different parts of the chat input.
 
-The ChatInput component includes a demo page with simulate upload functionality for testing:
+- **Type:** `ChatInputStyles`
 
 ```tsx
-// Available in src/pages/chat.page.tsx
 import React, { useState } from 'react';
 import { ChatInput } from '@app-studio/web';
-import { Button } from '@app-studio/web';
-
-export const ChatInputDemo = () => {
-  const [isSimulatingUpload, setIsSimulatingUpload] = useState(false);
-  const [simulationProgress, setSimulationProgress] = useState(0);
-
-  const simulateUpload = () => {
-    // Creates mock files for testing
-    const mockFiles = [
-      new File(['content'], 'document.pdf', { type: 'application/pdf' }),
-      new File(['content'], 'image.jpg', { type: 'image/jpeg' }),
-      new File(['content'], 'spreadsheet.xlsx', { type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' }),
-    ];
-
-    setIsSimulatingUpload(true);
-    setSimulationProgress(0);
-
-    const interval = setInterval(() => {
-      setSimulationProgress((prev) => {
-        if (prev >= 100) {
-          clearInterval(interval);
-          setIsSimulatingUpload(false);
-          console.log('Upload simulation completed!');
-          return 100;
-        }
-        return prev + 10;
-      });
-    }, 300);
-  };
 
+export const StyledChatInput = () => {
+  const [files, setFiles] = useState<File[]>([]);
+  
   return (
-    <>
-      <Button onClick={simulateUpload} disabled={isSimulatingUpload}>
-        {isSimulatingUpload ? `Uploading... ${simulationProgress}%` : 'Simulate Upload'}
-      </Button>
-
-      <ChatInput
-        onSubmit={(message) => console.log('Message:', message)}
-      />
-    </>
+    <ChatInput 
+      onSubmit={(message) => console.log(message)}
+      getPendingFiles={() => files}
+      clearPendingFiles={() => setFiles([])}
+      views={{
+        container: {
+          borderRadius: 16,
+          borderColor: '#3b82f6',
+        },
+        input: {
+          fontSize: 16,
+          padding: 12,
+        },
+        button: {
+          backgroundColor: '#3b82f6',
+        }
+      }}
+    />
   );
 };
 ```
 
-**Demo Features:**
-- **Simulate Upload**: Test file upload functionality without real files
-- **Progress Tracking**: Visual progress indication during simulation
-- **Mock File Generation**: Creates realistic test files with proper MIME types
-- **Console Logging**: Detailed logging for debugging and testing