@app-studio/web 0.9.18 → 0.9.20

package/docs/api-reference/form/chat-input.md

@@ -0,0 +1,210 @@
+# ChatInput
+
+The ChatInput component is a customizable chat input field with support for file uploads, prompt examples, and reference images.
+
+## Import
+
+```jsx
+import { ChatInput } from '@app-studio/web';
+```
+
+## 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 |
+| showReferenceImageButton | boolean | false | Whether to show the reference image button |
+| onReferenceImageClick | () => void | undefined | Callback function when the reference image button is clicked |
+| 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 |
+
+## Interfaces
+
+### PromptExample
+
+```tsx
+interface PromptExample {
+  id: string;
+  text: string;
+}
+```
+
+### UploadedFile
+
+```tsx
+interface UploadedFile {
+  name: string;
+  path: string;
+  size: number;
+  type: string;
+  localUrl?: string;
+}
+```
+
+### ChatInputHandles
+
+```tsx
+interface ChatInputHandles {
+  getPendingFiles: () => File[];
+  clearPendingFiles: () => void;
+}
+```
+
+## Examples
+
+### Basic Usage
+
+```jsx
+import React, { useState } from 'react';
+import { ChatInput } from '@app-studio/web';
+import { View } from 'app-studio';
+
+export const BasicChatInput = () => {
+  const [inputValue, setInputValue] = useState('');
+
+  const handleSubmit = (message) => {
+    console.log('Message submitted:', message);
+    setInputValue('');
+  };
+
+  return (
+    <View width="100%">
+      <ChatInput
+        onSubmit={handleSubmit}
+        value={inputValue}
+        onChange={setInputValue}
+        placeholder="Type your message here..."
+      />
+    </View>
+  );
+};
+```
+
+### With Prompt Examples
+
+```jsx
+import React, { useState } from 'react';
+import { ChatInput } from '@app-studio/web';
+import { View } from 'app-studio';
+
+export const ChatInputWithPromptExamples = () => {
+  const [inputValue, setInputValue] = useState('');
+
+  // Example prompt suggestions
+  const promptExamples = [
+    { 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?' },
+  ];
+
+  const handleSubmit = (message) => {
+    console.log('Message submitted:', message);
+    setInputValue('');
+  };
+
+  return (
+    <View width="100%">
+      <ChatInput
+        onSubmit={handleSubmit}
+        value={inputValue}
+        onChange={setInputValue}
+        promptExamples={promptExamples}
+      />
+    </View>
+  );
+};
+```
+
+### With File Uploads
+
+```jsx
+import React, { useRef } from 'react';
+import { ChatInput, ChatInputHandles } from '@app-studio/web';
+import { View } from 'app-studio';
+
+export const ChatInputWithFileUploads = () => {
+  const chatInputRef = useRef<ChatInputHandles>(null);
+
+  const handleSubmit = (message) => {
+    // Get any pending files
+    const pendingFiles = chatInputRef.current?.getPendingFiles() || [];
+    console.log('Message submitted:', message);
+    console.log('Pending files:', pendingFiles);
+    
+    // Clear pending files after submission
+    chatInputRef.current?.clearPendingFiles();
+  };
+
+  return (
+    <View width="100%">
+      <ChatInput
+        ref={chatInputRef}
+        onSubmit={handleSubmit}
+        hideAttachments={false}
+      />
+    </View>
+  );
+};
+```
+
+## Customization
+
+The ChatInput component can be customized using the `views` prop:
+
+```jsx
+<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 */ },
+    referenceImageButton: { /* styles for the reference image button */ },
+    referenceImageModal: { /* styles for the reference image modal */ },
+    attachments: { /* styles for the attachments container */ },
+    attachmentItem: { /* styles for each attachment item */ },
+    submitButton: { /* styles for the submit button */ },
+    fileButton: { /* styles for the file button */ },
+  }}
+/>
+```
+
+## Accessibility
+
+The ChatInput component implements the following accessibility features:
+
+- Keyboard navigation for submitting messages (Enter key)
+- ARIA attributes for interactive elements
+- Focus management for the input field
+- Proper contrast for text and buttons
+
+## Best Practices
+
+- Provide clear placeholder text to guide users
+- Handle file uploads appropriately on the server side
+- Implement proper error handling for message submission
+- Use the `loading` state to indicate when a message is being processed
+- Provide feedback to users when messages are sent successfully

package/docs/api-reference/utility/button.md

@@ -0,0 +1,145 @@
+# Button
+
+The Button component is used to trigger an action or event.
+
+## Import
+
+```jsx
+import { Button } from '@app-studio/web';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| variant | 'filled' \| 'outline' \| 'ghost' \| 'link' | 'filled' | The visual style of the button |
+| size | 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' | 'md' | The size of the button |
+| shape | 'sharp' \| 'rounded' \| 'pillShaped' | 'rounded' | The shape of the button |
+| iconPosition | 'left' \| 'right' \| 'top' \| 'bottom' | 'left' | The position of the icon relative to the button text |
+| loaderPosition | 'left' \| 'right' | 'left' | The position of the loader relative to the button text |
+| backgroundColor | string | - | The background color of the button |
+| color | string | - | The color of the button text |
+| isAuto | boolean | false | Whether the button should automatically adjust its width |
+| isFilled | boolean | false | Whether the button should fill its container width |
+| isDisabled | boolean | false | Whether the button is disabled |
+| isLoading | boolean | false | Whether the button is in a loading state |
+| isIconRounded | boolean | false | Whether the icon should have rounded corners |
+| icon | React.ReactNode | - | The icon to display in the button |
+| children | React.ReactNode | - | The content of the button |
+| to | string | - | The URL to navigate to when the button is clicked (turns the button into a link) |
+| isExternal | boolean | false | Whether the link should open in a new tab |
+| shadow | Shadow | - | The shadow style of the button |
+| onClick | () => void | - | The function to call when the button is clicked |
+| views | ButtonStyles | {} | Custom styles for different parts of the button |
+| themeMode | 'light' \| 'dark' | - | Optional theme mode override |
+
+## Examples
+
+### Basic Button
+
+```jsx
+<Button onClick={() => alert('Button clicked!')}>Click Me</Button>
+```
+
+### Button Variants
+
+```jsx
+<>
+  <Button variant="filled">Filled</Button>
+  <Button variant="outline">Outline</Button>
+  <Button variant="ghost">Ghost</Button>
+  <Button variant="link">Link</Button>
+</>
+```
+
+### Button Sizes
+
+```jsx
+<>
+  <Button size="xs">Extra Small</Button>
+  <Button size="sm">Small</Button>
+  <Button size="md">Medium</Button>
+  <Button size="lg">Large</Button>
+  <Button size="xl">Extra Large</Button>
+</>
+```
+
+### Button with Icon
+
+```jsx
+import { DustBinIcon } from '@app-studio/web';
+
+<Button icon={<DustBinIcon widthHeight={16} />}>Delete</Button>
+```
+
+### Button with Icon Position
+
+```jsx
+import { DustBinIcon } from '@app-studio/web';
+
+<>
+  <Button icon={<DustBinIcon widthHeight={16} />} iconPosition="left">Left Icon</Button>
+  <Button icon={<DustBinIcon widthHeight={16} />} iconPosition="right">Right Icon</Button>
+  <Button icon={<DustBinIcon widthHeight={16} />} iconPosition="top">Top Icon</Button>
+  <Button icon={<DustBinIcon widthHeight={16} />} iconPosition="bottom">Bottom Icon</Button>
+</>
+```
+
+### Loading Button
+
+```jsx
+<Button isLoading>Loading</Button>
+```
+
+### Disabled Button
+
+```jsx
+<Button isDisabled>Disabled</Button>
+```
+
+### Link Button
+
+```jsx
+<Button to="/dashboard" variant="link">Go to Dashboard</Button>
+```
+
+### External Link Button
+
+```jsx
+<Button to="https://example.com" isExternal variant="link">External Link</Button>
+```
+
+### Custom Styled Button
+
+```jsx
+<Button
+  views={{
+    container: {
+      backgroundColor: '#6200ee',
+      borderRadius: 8,
+      boxShadow: '0 4px 6px rgba(0, 0, 0, 0.1)',
+    },
+  }}
+>
+  Custom Styled Button
+</Button>
+```
+
+## Accessibility
+
+The Button component:
+
+- Uses the native `<button>` element for proper keyboard navigation and screen reader support
+- Supports the `aria-disabled` attribute when disabled
+- Maintains proper focus states for keyboard users
+- Uses appropriate color contrast for text and background
+
+## Best Practices
+
+- Use clear, concise text that describes the action
+- Use the appropriate variant for the context (primary actions should use 'filled')
+- Include an icon only when it adds meaning or clarity
+- Avoid using too many buttons in close proximity
+- Use consistent button styles throughout your application
+- Consider the visual hierarchy of multiple buttons (primary, secondary actions)
+- Use the `isLoading` state for actions that take time to complete

package/docs/api-reference/utility/title.md

@@ -0,0 +1,301 @@
+# Title
+
+The Title component is used for rendering animated and highlighted titles in hero sections and other prominent areas of the UI.
+
+## Import
+
+```jsx
+import { Title } from '@app-studio/web';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| children | React.ReactNode | - | The main text content of the title |
+| highlightText | string \| string[] | - | Text to be highlighted within the title. If not provided, no highlighting will be applied |
+| highlightStyle | 'background' \| 'underline' \| 'gradient' \| 'outline' \| 'glow' | 'background' | The visual style of the highlighted text |
+| highlightColor | string | 'theme.primary' | The color of the highlighted text or background |
+| highlightSecondaryColor | string | - | The secondary color for gradient highlights |
+| size | 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'xl' \| 'xl' \| 'xl' \| 'xl' \| '6xl' | 'xl' | The size of the title |
+| centered | boolean | false | Whether to center the title |
+| animate | AnimationProps \| AnimationProps[] | - | Animation for the title. This should be an animation object with properties like from, to, duration, etc. |
+| highlightAnimate | AnimationProps \| AnimationProps[] | - | Animation specifically for the highlighted text |
+| alternateHighlightText | string[] | [] | Array of strings to cycle through, replacing the text specified in highlightText |
+| alternateAnimation | boolean | false | Whether to animate the alternating highlight text |
+| alternateDuration | number | 3000 | Duration in milliseconds for each alternating highlight text |
+| highlightTypewriter | boolean | false | Whether to apply a typewriter effect to the highlighted text |
+| highlightTypewriterDuration | number | 3000 | Duration in milliseconds for the typewriter effect |
+| views | TitleStyles | {} | Custom styles for different parts of the title |
+| themeMode | 'light' \| 'dark' | - | Optional theme mode override |
+
+## Examples
+
+### Basic Title
+
+```jsx
+<Title>Simple Hero Title</Title>
+```
+
+### Title Sizes
+
+```jsx
+<>
+  <Title size="xs">Extra Small Title (xs)</Title>
+  <Title size="sm">Small Title (sm)</Title>
+  <Title size="md">Medium Title (md)</Title>
+  <Title size="lg">Large Title (lg)</Title>
+  <Title size="xl">Extra Large Title (xl - default)</Title>
+  <Title size="xl">2XL Title</Title>
+  <Title size="xl">3XL Title</Title>
+  <Title size="xl">4XL Title</Title>
+  <Title size="xl">5XL Title</Title>
+  <Title size="6xl">6XL Title</Title>
+</>
+```
+
+### Highlighted Title
+
+```jsx
+<Title 
+  highlightText="highlighted" 
+  highlightStyle="background" 
+  highlightColor="theme.primary"
+>
+  Text with highlighted words
+</Title>
+```
+
+### Highlight Styles
+
+```jsx
+<>
+  <Title
+    highlightText="background"
+    highlightStyle="background"
+    highlightColor="theme.primary"
+  >
+    Text with background highlight
+  </Title>
+
+  <Title
+    highlightText="underlined"
+    highlightStyle="underline"
+    highlightColor="theme.secondary"
+  >
+    Text with underlined highlight
+  </Title>
+
+  <Title
+    highlightText="gradient"
+    highlightStyle="gradient"
+    highlightColor="theme.primary"
+    highlightSecondaryColor="theme.secondary"
+  >
+    Text with gradient highlight
+  </Title>
+
+  <Title
+    highlightText="outline"
+    highlightStyle="outline"
+    highlightColor="theme.primary"
+  >
+    Text with outline highlight
+  </Title>
+
+  <Title
+    highlightText="glow"
+    highlightStyle="glow"
+    highlightColor="theme.primary"
+  >
+    Text with glow highlight
+  </Title>
+</>
+```
+
+### Multiple Highlights
+
+```jsx
+<Title
+  highlightText={['multiple', 'highlights']}
+  highlightStyle="background"
+  highlightColor="theme.primary"
+>
+  Text with multiple highlights in the same sentence
+</Title>
+```
+
+### Animated Title
+
+```jsx
+<Title
+  animate={{
+    from: { opacity: 0 },
+    to: { opacity: 1 },
+    duration: '1.5s',
+    iterationCount: '1',
+  }}
+>
+  Fade In Animation
+</Title>
+```
+
+### Animated Highlight
+
+```jsx
+<Title
+  highlightText="animated highlight"
+  highlightStyle="background"
+  highlightColor="theme.primary"
+  highlightAnimate={{
+    from: { opacity: 0, transform: 'scale(0.9)' },
+    to: { opacity: 1, transform: 'scale(1)' },
+    duration: '0.5s',
+    delay: '0.2s',
+  }}
+>
+  Text with animated highlight
+</Title>
+```
+
+### Alternating Highlight Text
+
+```jsx
+<Title
+  highlightText="changing"
+  alternateHighlightText={[
+    'innovative',
+    'powerful',
+    'flexible',
+    'intuitive',
+  ]}
+  alternateAnimation={true}
+  alternateDuration={2000}
+  highlightStyle="background"
+  highlightColor="theme.primary"
+>
+  Our changing solution for your business
+</Title>
+```
+
+### Typewriter Effect
+
+```jsx
+<Title
+  highlightText="typewriter"
+  highlightStyle="background"
+  highlightColor="theme.primary"
+  highlightTypewriter={true}
+  highlightTypewriterDuration={1500}
+>
+  This text has a typewriter effect on the highlighted word
+</Title>
+```
+
+### Responsive Title
+
+```jsx
+<Title
+  media={{
+    mobile: {
+      fontSize: 32,
+      lineHeight: '40px',
+    },
+    tablet: {
+      fontSize: 48,
+      lineHeight: '56px',
+    },
+    desktop: {
+      fontSize: 64,
+      lineHeight: '72px',
+    },
+  }}
+  highlightText="Responsive"
+  highlightStyle="background"
+  highlightColor="theme.primary"
+>
+  Responsive Title Example
+</Title>
+```
+
+### Custom Styling
+
+```jsx
+<Title
+  views={{
+    container: {
+      fontFamily: 'Georgia, serif',
+      letterSpacing: '0.05em',
+      textTransform: 'uppercase',
+    },
+    highlight: {
+      borderRadius: '8px',
+      padding: '0 12px',
+    },
+  }}
+  highlightText="Custom"
+  highlightStyle="background"
+  highlightColor="color.purple.500"
+>
+  Title with Custom Styling
+</Title>
+```
+
+### Hero Section Example
+
+```jsx
+<View
+  backgroundColor="color.gray.50"
+  padding={48}
+  borderRadius={8}
+  width="100%"
+>
+  <Vertical gap={24} maxWidth={800} marginX="auto">
+    <Title
+      size="xl"
+      animate={{
+        from: { opacity: 0 },
+        to: { opacity: 1 },
+        duration: '1s',
+        iterationCount: '1',
+      }}
+      highlightText="Platform"
+      highlightStyle="gradient"
+      highlightColor="theme.primary"
+      highlightSecondaryColor="theme.secondary"
+      centered
+    >
+      Welcome to Our Platform
+    </Title>
+
+    <Text
+      textAlign="center"
+      color="color.gray.600"
+      fontSize={20}
+      lineHeight={28}
+    >
+      Build beautiful, responsive, and interactive user interfaces with our
+      powerful component library.
+    </Text>
+  </Vertical>
+</View>
+```
+
+## Accessibility
+
+The Title component:
+
+- Uses semantic heading elements (`<h1>`) for proper document structure
+- Maintains proper color contrast for highlighted text
+- Supports keyboard navigation and focus management
+- Works with screen readers by using appropriate ARIA attributes
+
+## Best Practices
+
+- Use the Title component for main headings and important text that needs emphasis
+- Choose highlight styles that maintain good contrast with the background
+- Use animations sparingly to avoid distracting users
+- Consider using responsive sizing for different screen sizes
+- Limit the use of alternating text to avoid confusion
+- Ensure that any animations respect user preferences for reduced motion
+- Use semantic colors from the theme system rather than hardcoded values