@app-studio/web 0.9.17 → 0.9.19

package/docs/api-reference/README.md

@@ -0,0 +1,103 @@
+# API Reference
+
+This section provides detailed API documentation for all components in the App Studio Web Component Library.
+
+## Component Categories
+
+- [Layout Components](#layout-components)
+- [Form Components](#form-components)
+- [Navigation Components](#navigation-components)
+- [Feedback Components](#feedback-components)
+- [Data Display Components](#data-display-components)
+- [Utility Components](#utility-components)
+- [Interactive Components](#interactive-components)
+
+## Layout Components
+
+- [View](./layout/view.md) - Base container component
+- [Horizontal](./layout/horizontal.md) - Horizontal flex container
+- [Vertical](./layout/vertical.md) - Vertical flex container
+- [Center](./layout/center.md) - Centered flex container
+- [AspectRatio](./layout/aspect-ratio.md) - Container with fixed aspect ratio
+- [Separator](./layout/separator.md) - Visual or semantic separator
+- [Resizable](./layout/resizable.md) - Resizable container
+
+## Form Components
+
+- [Checkbox](./form/checkbox.md) - Checkbox input
+- [ChatInput](./form/chat-input.md) - Chat input with file uploads and prompt examples
+- [Radio](./form/radio.md) - Radio input
+- [Select](./form/select.md) - Select dropdown
+- [Switch](./form/switch.md) - Toggle switch
+- [TextArea](./form/text-area.md) - Multi-line text input
+- [TextField](./form/text-field.md) - Single-line text input
+- [OTPInput](./form/otp-input.md) - One-time password input
+
+## Navigation Components
+
+- [Accordion](./navigation/accordion.md) - Expandable content sections
+- [Menubar](./navigation/menubar.md) - Horizontal menu
+- [NavigationMenu](./navigation/navigation-menu.md) - Navigation menu
+- [Pagination](./navigation/pagination.md) - Page navigation
+- [Sidebar](./navigation/sidebar.md) - Side navigation
+- [Tabs](./navigation/tabs.md) - Tabbed interface
+
+## Feedback Components
+
+- [Alert](./feedback/alert.md) - Informational message
+- [Modal](./feedback/modal.md) - Dialog box
+- [Toast](./feedback/toast.md) - Temporary notification
+- [Tooltip](./feedback/tooltip.md) - Contextual information
+
+## Data Display Components
+
+- [Avatar](./data-display/avatar.md) - User or entity representation
+- [Badge](./data-display/badge.md) - Small count or status indicator
+- [Card](./data-display/card.md) - Content container
+- [Table](./data-display/table.md) - Tabular data
+- [Chart](./data-display/chart.md) - Data visualization
+- [Flow](./data-display/flow.md) - Interactive workflow diagrams and flowcharts
+- [Tree](./data-display/tree.md) - Hierarchical tree structure
+
+## Utility Components
+
+- [Button](./utility/button.md) - Interactive button
+- [Gradient](./utility/gradient.md) - Gradient background
+- [Loader](./utility/loader.md) - Loading indicator
+- [Text](./utility/text.md) - Text display
+
+## Interactive Components
+
+- [Carousel](./interactive/carousel.md) - Slideshow
+- [ContextMenu](./interactive/context-menu.md) - Right-click menu
+- [DropdownMenu](./interactive/dropdown-menu.md) - Dropdown menu
+- [HoverCard](./interactive/hover-card.md) - Card that appears on hover
+- [Slider](./interactive/slider.md) - Range input
+- [Toggle](./interactive/toggle.md) - Toggle button
+- [ToggleGroup](./interactive/toggle-group.md) - Group of toggle buttons
+
+## Component API Structure
+
+Each component's API documentation follows a consistent structure:
+
+1. **Import** - How to import the component
+2. **Props** - Detailed list of props with types and descriptions
+3. **Examples** - Basic usage examples
+4. **Variants** - Available variants and their usage
+5. **Compound Components** - Sub-components (if applicable)
+6. **Accessibility** - Accessibility features and considerations
+7. **Best Practices** - Recommended usage patterns
+
+## Generating API Documentation
+
+Component API documentation is automatically generated using the `bot-doc` tool. To regenerate documentation for a component:
+
+```bash
+npm run bot-doc -- ComponentName src/components/ComponentName
+```
+
+To regenerate documentation for all components:
+
+```bash
+npm run create-docs
+```

package/docs/api-reference/data-display/flow.md

@@ -0,0 +1,220 @@
+# Flow
+
+The Flow component is used to create interactive workflow diagrams and flowcharts with support for node connections, drag-and-drop functionality, and viewport controls.
+
+## Import
+
+```jsx
+import { Flow } from '@app-studio/web';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| nodes | FlowNode[] | [] | Array of nodes in the flow |
+| edges | NodeConnection[] | [] | Array of edges/connections between nodes |
+| size | 'sm' \| 'md' \| 'lg' | 'md' | Size of the flow nodes |
+| variant | 'default' \| 'outline' \| 'filled' | 'default' | Visual variant of the flow nodes |
+| direction | 'horizontal' \| 'vertical' | 'vertical' | Direction of the flow layout |
+| showControls | boolean | true | Whether to show viewport controls (zoom in/out, reset) |
+| allowAddingNodes | boolean | true | Whether to allow adding new nodes |
+| allowDraggingNodes | boolean | true | Whether to allow dragging nodes |
+| selectedNodeId | string | undefined | ID of the currently selected node |
+| onNodeSelect | (nodeId: string \| null) => void | undefined | Callback when a node is selected |
+| onNodesChange | (nodes: FlowNode[]) => void | undefined | Callback when nodes change |
+| onEdgesChange | (edges: NodeConnection[]) => void | undefined | Callback when edges change |
+| onNodeAdd | (node: FlowNode) => void | undefined | Callback when a node is added |
+| onNodeDragStart | (nodeId: string) => void | undefined | Callback when node dragging starts |
+| onNodeDrag | (nodeId: string, position: NodePosition) => void | undefined | Callback during node dragging |
+| onNodeDragEnd | (nodeId: string, position: NodePosition) => void | undefined | Callback when node dragging ends |
+| viewport | FlowViewport | { zoom: 1, x: 0, y: 0 } | Current viewport state (zoom level and position) |
+| onViewportChange | (viewport: FlowViewport) => void | undefined | Callback when viewport changes |
+| views | object | {} | Custom styling for different parts of the component |
+
+## Node Structure
+
+The `FlowNode` interface defines the structure of nodes in the Flow component:
+
+```tsx
+interface FlowNode {
+  id: string;
+  type?: 'default' | 'start' | 'end' | 'decision' | 'process' | string;
+  position: { x: number; y: number };
+  data?: {
+    label?: string;
+    subtitle?: string;
+    icon?: React.ReactNode;
+    number?: number;
+    [key: string]: any;
+  };
+  selected?: boolean;
+  isDragging?: boolean;
+  draggable?: boolean;
+  style?: ViewProps;
+}
+```
+
+## Edge Structure
+
+The `NodeConnection` interface defines the structure of edges in the Flow component:
+
+```tsx
+interface NodeConnection {
+  id: string;
+  source: string;
+  target: string;
+  label?: string;
+  style?: ViewProps;
+}
+```
+
+## Examples
+
+### Basic Usage
+
+```jsx
+import React, { useState } from 'react';
+import { Flow } from '@app-studio/web';
+import { View } from 'app-studio';
+
+export const BasicFlow = () => {
+  // Initial nodes and edges
+  const [nodes, setNodes] = useState([
+    {
+      id: 'node-1',
+      position: { x: 50, y: 50 },
+      data: { 
+        label: 'Start Node', 
+        subtitle: 'Begin here' 
+      },
+    },
+    {
+      id: 'node-2',
+      position: { x: 50, y: 200 },
+      data: { 
+        label: 'Process Node', 
+        subtitle: 'Do something' 
+      },
+    },
+  ]);
+
+  const [edges, setEdges] = useState([
+    { id: 'edge-1-2', source: 'node-1', target: 'node-2' },
+  ]);
+
+  return (
+    <View height="400px" border="1px solid" borderColor="color.gray.200" borderRadius={8}>
+      <Flow
+        nodes={nodes}
+        edges={edges}
+        onNodesChange={setNodes}
+        onEdgesChange={setEdges}
+      />
+    </View>
+  );
+};
+```
+
+### With Node Addition
+
+```jsx
+import React, { useState } from 'react';
+import { Flow } from '@app-studio/web';
+import { View } from 'app-studio';
+
+export const FlowWithNodeAddition = () => {
+  const [nodes, setNodes] = useState([
+    {
+      id: 'node-1',
+      position: { x: 50, y: 50 },
+      data: { label: 'Start', subtitle: 'Begin workflow' },
+    },
+    {
+      id: 'node-2',
+      position: { x: 50, y: 200 },
+      data: { label: 'Process', subtitle: 'Do something' },
+    },
+  ]);
+
+  const [edges, setEdges] = useState([
+    { id: 'edge-1-2', source: 'node-1', target: 'node-2' },
+  ]);
+
+  const [selectedNodeId, setSelectedNodeId] = useState(null);
+
+  return (
+    <View height="400px" border="1px solid" borderColor="color.gray.200" borderRadius={8}>
+      <Flow
+        nodes={nodes}
+        edges={edges}
+        onNodesChange={setNodes}
+        onEdgesChange={setEdges}
+        selectedNodeId={selectedNodeId}
+        onNodeSelect={setSelectedNodeId}
+        allowAddingNodes={true}
+        onNodeAdd={(newNode) => {
+          setNodes((prevNodes) => [...prevNodes, newNode]);
+        }}
+      />
+    </View>
+  );
+};
+```
+
+## Compound Components
+
+The Flow component uses a compound component pattern with the following sub-components:
+
+```jsx
+// These are primarily for potential direct use or a more componentized future version
+Flow.Node       // Renders a single node
+Flow.Edge       // Renders a connection between nodes
+Flow.Controls   // Renders viewport controls
+Flow.AddNodeButton // Renders a button to add a new node
+```
+
+## Customization
+
+The Flow component can be customized using the `views` prop:
+
+```jsx
+<Flow
+  // ...other props
+  views={{
+    container: { /* styles for the main flow container */ },
+    node: {
+      container: { /* styles for the node's root View */ },
+      content: { /* styles for the content wrapper inside the node */ },
+      icon: { /* styles for the node's icon View */ },
+    },
+    edge: {
+      path: { /* styles for the SVG path */ },
+      label: { /* styles for the edge label */ },
+    },
+    controls: {
+      container: { /* styles for the controls container */ },
+      button: { /* styles for individual control buttons */ },
+    },
+    addNodeButton: { /* styles for the add node button */ },
+  }}
+/>
+```
+
+## Accessibility
+
+The Flow component implements the following accessibility features:
+
+- Keyboard navigation for selecting nodes
+- ARIA attributes for interactive elements
+- Focus management for controls and nodes
+- Proper contrast for node and edge colors
+
+## Best Practices
+
+- Provide clear labels and subtitles for nodes to improve understanding
+- Use consistent node types and styling for similar functionality
+- Implement proper error handling for node and edge operations
+- Consider viewport size when determining initial node positions
+- Use the `onNodeAdd` callback to validate new node positions
+- Implement undo/redo functionality for node operations when needed

package/docs/api-reference/data-display/tree.md

@@ -0,0 +1,210 @@
+# Tree
+
+The Tree component is used for displaying hierarchical data with expandable/collapsible nodes. It supports both a compound component pattern and a data-driven approach.
+
+## Import
+
+```jsx
+import { Tree } from '@app-studio/web';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| children | React.ReactNode | undefined | Child elements for compound component pattern (e.g., `<Tree.Item />`) |
+| items | TreeNode[] | undefined | Data-driven approach: array of tree nodes |
+| size | 'sm' \| 'md' \| 'lg' | 'md' | Size of the tree items |
+| variant | 'default' \| 'outline' \| 'filled' | 'default' | Visual variant of the tree items |
+| defaultExpandedItems | string[] | [] | IDs of initially expanded items (uncontrolled mode) |
+| expandedItems | string[] | undefined | IDs of expanded items (controlled mode) |
+| onExpandedItemsChange | (expandedItems: string[]) => void | undefined | Callback when expanded items change |
+| onItemSelect | (itemId: string, item?: TreeNode) => void | undefined | Callback when an item is selected |
+| selectedItem | string | undefined | ID of the currently selected item (controlled mode) |
+| defaultSelectedItem | string | undefined | ID of the initially selected item (uncontrolled mode) |
+| multiSelect | boolean | false | Whether to allow multiple selection |
+| allowDragAndDrop | boolean | false | Whether to enable drag and drop functionality |
+| dragHandleIcon | React.ReactNode | undefined | Custom icon to use for the drag handle |
+| onItemsReorder | (items: TreeNode[]) => void | undefined | Callback when items are reordered via drag and drop |
+| onDragStart | (itemId: string, event: React.DragEvent) => void | undefined | Callback when drag starts on an item |
+| onDragEnd | (itemId: string) => void | undefined | Callback when drag ends |
+| views | object | {} | Custom styling for different parts of the component |
+
+## TreeNode Structure
+
+The `TreeNode` interface defines the structure of nodes in the data-driven approach:
+
+```tsx
+interface TreeNode {
+  id: string;
+  label: string;
+  icon?: React.ReactNode;
+  children?: TreeNode[];
+  disabled?: boolean;
+  data?: any;
+  style?: ViewProps;
+  isDragging?: boolean;
+  draggable?: boolean;
+}
+```
+
+## Examples
+
+### Compound Component Pattern
+
+```jsx
+import React from 'react';
+import { Tree } from '@app-studio/web';
+import { FolderIcon, FileIcon } from '@app-studio/web';
+
+export const CompoundTree = () => {
+  return (
+    <Tree defaultExpandedItems={['parent-1']}>
+      <Tree.Item value="parent-1" icon={<FolderIcon />}>
+        <Tree.ItemLabel>Parent Item 1</Tree.ItemLabel>
+        <Tree.ItemContent>
+          <Tree.Item value="child-1-1" icon={<FileIcon />}>
+            <Tree.ItemLabel>Child Item 1.1</Tree.ItemLabel>
+          </Tree.Item>
+          <Tree.Item value="child-1-2" icon={<FileIcon />}>
+            <Tree.ItemLabel>Child Item 1.2</Tree.ItemLabel>
+          </Tree.Item>
+        </Tree.ItemContent>
+      </Tree.Item>
+      <Tree.Item value="parent-2" icon={<FolderIcon />}>
+        <Tree.ItemLabel>Parent Item 2</Tree.ItemLabel>
+        <Tree.ItemContent>
+          <Tree.Item value="child-2-1" icon={<FileIcon />}>
+            <Tree.ItemLabel>Child Item 2.1</Tree.ItemLabel>
+          </Tree.Item>
+        </Tree.ItemContent>
+      </Tree.Item>
+    </Tree>
+  );
+};
+```
+
+### Data-Driven Approach
+
+```jsx
+import React from 'react';
+import { Tree } from '@app-studio/web';
+import { FolderIcon, FileIcon } from '@app-studio/web';
+
+export const DataDrivenTree = () => {
+  const treeNodes = [
+    {
+      id: 'parent-1',
+      label: 'Parent Item 1',
+      icon: <FolderIcon />,
+      children: [
+        { id: 'child-1-1', label: 'Child Item 1.1', icon: <FileIcon /> },
+        { id: 'child-1-2', label: 'Child Item 1.2', icon: <FileIcon /> }
+      ]
+    },
+    {
+      id: 'parent-2',
+      label: 'Parent Item 2',
+      icon: <FolderIcon />,
+      children: [
+        { id: 'child-2-1', label: 'Child Item 2.1', icon: <FileIcon /> }
+      ]
+    }
+  ];
+
+  return (
+    <Tree 
+      items={treeNodes} 
+      defaultExpandedItems={['parent-1']} 
+      onItemSelect={(itemId, item) => console.log(`Selected: ${itemId}`, item)}
+    />
+  );
+};
+```
+
+### With Drag and Drop
+
+```jsx
+import React, { useState } from 'react';
+import { Tree } from '@app-studio/web';
+import { FolderIcon, FileIcon } from '@app-studio/web';
+
+export const DraggableTree = () => {
+  const [menuItems, setMenuItems] = useState([
+    {
+      id: 'menu-1',
+      label: 'Menu Item 1',
+      icon: <FolderIcon />,
+      children: [
+        { id: 'submenu-1-1', label: 'Submenu Item 1.1', icon: <FileIcon /> }
+      ]
+    },
+    {
+      id: 'menu-2',
+      label: 'Menu Item 2',
+      icon: <FolderIcon />,
+      children: [
+        { id: 'submenu-2-1', label: 'Submenu Item 2.1', icon: <FileIcon /> }
+      ]
+    }
+  ]);
+
+  return (
+    <Tree
+      items={menuItems}
+      allowDragAndDrop={true}
+      onItemsReorder={setMenuItems}
+      onDragStart={(itemId) => console.log(`Started dragging: ${itemId}`)}
+      onDragEnd={(itemId) => console.log(`Finished dragging: ${itemId}`)}
+    />
+  );
+};
+```
+
+## Compound Components
+
+The Tree component uses a compound component pattern with the following sub-components:
+
+```jsx
+Tree.Item       // Represents a tree node
+Tree.ItemLabel  // The clickable label part of a tree node
+Tree.ItemContent // Container for child nodes
+```
+
+## Customization
+
+The Tree component can be customized using the `views` prop:
+
+```jsx
+<Tree
+  // ...other props
+  views={{
+    container: { /* styles for the root container */ },
+    item: { /* styles for each tree item */ },
+    itemLabel: { /* styles for the clickable label part */ },
+    itemContent: { /* styles for the children wrapper */ },
+    icon: { /* styles for the item's main icon */ },
+    expandIcon: { /* styles for the expand/collapse chevron icon */ },
+    draggedItem: { /* styles for the item being dragged */ },
+    dragHandle: { /* styles for the drag handle icon */ },
+  }}
+/>
+```
+
+## Accessibility
+
+The Tree component implements the following accessibility features:
+
+- Keyboard navigation for expanding/collapsing nodes
+- ARIA attributes for tree structure
+- Focus management for interactive elements
+- Proper contrast for selected and hovered states
+
+## Best Practices
+
+- Use consistent icons for similar node types
+- Provide clear labels for all nodes
+- Implement proper error handling for drag and drop operations
+- Consider the depth of your tree structure (avoid deeply nested trees)
+- Use the `onItemSelect` callback to handle item selection
+- Implement undo/redo functionality for drag and drop operations when needed