@app-studio/web 0.9.31 → 0.9.33

package/docs/components/Tree.mdx

@@ -0,0 +1,340 @@
+# Tree
+
+A component for displaying hierarchical data with expandable/collapsible nodes. Supports both a compound component pattern and a data-driven approach.
+
+### **Import**
+  ```tsx
+  import { Tree } from '@app-studio/web';
+  ```
+
+### **Default**
+```tsx
+import React from 'react';
+import { Tree } from '@app-studio/web';
+import { Text, Vertical } from 'app-studio';
+import { FolderIcon, FileIcon, DocumentIcon } from '@app-studio/web';
+
+export const DefaultTree = () => {
+  return (
+    <Vertical gap={20} width="100%" maxWidth={400}>
+      <Text marginBottom={10} fontWeight="bold">
+        Default Tree (Compound)
+      </Text>
+      <Tree
+        defaultExpandedItems={['files', 'documents']}
+        onItemSelect={(itemId, itemData) =>
+          console.log(`Compound item selected: ${itemId}`, itemData)
+        }
+      >
+        <Tree.Item value="files" icon={<FolderIcon size={16} />}>
+          <Tree.ItemLabel>Files</Tree.ItemLabel>
+          <Tree.ItemContent>
+            <Tree.Item value="documents" icon={<FolderIcon size={16} />}>
+              <Tree.ItemLabel>Documents</Tree.ItemLabel>
+              <Tree.ItemContent>
+                <Tree.Item value="doc1" icon={<DocumentIcon size={16} />}>
+                  <Tree.ItemLabel>Document 1.docx</Tree.ItemLabel>
+                </Tree.Item>
+                <Tree.Item value="doc2" icon={<DocumentIcon size={16} />}>
+                  <Tree.ItemLabel>Document 2.pdf</Tree.ItemLabel>
+                </Tree.Item>
+              </Tree.ItemContent>
+            </Tree.Item>
+            <Tree.Item value="images" icon={<FolderIcon size={16} />}>
+              <Tree.ItemLabel>Images</Tree.ItemLabel>
+              <Tree.ItemContent>
+                <Tree.Item value="img1" icon={<FileIcon size={16} />}>
+                  <Tree.ItemLabel>image1.jpg</Tree.ItemLabel>
+                </Tree.Item>
+                <Tree.Item value="img2" icon={<FileIcon size={16} />}>
+                  <Tree.ItemLabel>image2.png</Tree.ItemLabel>
+                </Tree.Item>
+              </Tree.ItemContent>
+            </Tree.Item>
+          </Tree.ItemContent>
+        </Tree.Item>
+      </Tree>
+    </Vertical>
+  );
+};
+```
+
+### **Data-Driven**
+```tsx
+import React from 'react';
+import { Tree } from '@app-studio/web';
+import { Text, Vertical } from 'app-studio';
+import { FolderIcon, FileIcon, DocumentIcon } from '@app-studio/web';
+import { TreeNode } from '@app-studio/web';
+
+export const DataDrivenTree = () => {
+  const treeData: TreeNode[] = [
+    {
+      id: 'files',
+      label: 'Files',
+      icon: <FolderIcon size={16} />,
+      children: [
+        {
+          id: 'documents',
+          label: 'Documents',
+          icon: <FolderIcon size={16} />,
+          children: [
+            {
+              id: 'doc1',
+              label: 'Document 1.docx',
+              icon: <DocumentIcon size={16} />,
+            },
+            {
+              id: 'doc2',
+              label: 'Document 2.pdf',
+              icon: <DocumentIcon size={16} />,
+            },
+          ],
+        },
+        {
+          id: 'images',
+          label: 'Images',
+          icon: <FolderIcon size={16} />,
+          children: [
+            {
+              id: 'img1',
+              label: 'image1.jpg',
+              icon: <FileIcon size={16} />,
+            },
+            {
+              id: 'img2',
+              label: 'image2.png',
+              icon: <FileIcon size={16} />,
+            },
+          ],
+        },
+        {
+          id: 'videos',
+          label: 'Videos (Empty)',
+          icon: <FolderIcon size={16} />,
+          children: [], // Example of an empty expandable folder
+        },
+        {
+          id: 'report',
+          label: 'Annual Report.docx',
+          icon: <DocumentIcon size={16} />,
+        },
+      ],
+    },
+  ];
+
+  return (
+    <Vertical gap={20} width="100%" maxWidth={400}>
+      <Text marginBottom={10} fontWeight="bold">
+        Data-Driven Tree
+      </Text>
+      <Tree
+        items={treeData}
+        defaultExpandedItems={['files', 'documents']}
+        onItemSelect={(itemId, itemData) =>
+          console.log(`Selected item: ${itemId}`, itemData)
+        }
+      />
+    </Vertical>
+  );
+};
+```
+
+### **With Drag and Drop**
+```tsx
+import React, { useState } from 'react';
+import { Tree } from '@app-studio/web';
+import { Text, View, Vertical } from 'app-studio';
+import { FolderIcon, FileIcon, DragHandleIcon } from '@app-studio/web';
+import { TreeNode } from '@app-studio/web';
+
+const CustomDragHandleIcon = () => (
+  <DragHandleIcon size={16} color="color.gray.400" />
+);
+
+export const DraggableTree = () => {
+  const [expandedItems, setExpandedItems] = useState(['menu-1', 'menu-2']);
+  
+  const [items, setItems] = useState<TreeNode[]>([
+    {
+      id: 'menu-1',
+      label: 'Menu Item 1',
+      icon: <FolderIcon size={16} />,
+      children: [
+        { 
+          id: 'submenu-1-1', 
+          label: 'Submenu Item 1.1', 
+          icon: <FileIcon size={16} /> 
+        }
+      ]
+    },
+    {
+      id: 'menu-2',
+      label: 'Menu Item 2',
+      icon: <FolderIcon size={16} />,
+      children: [
+        { 
+          id: 'submenu-2-1', 
+          label: 'Submenu Item 2.1', 
+          icon: <FileIcon size={16} /> 
+        }
+      ]
+    }
+  ]);
+
+  const handleItemsReorder = (newItems: TreeNode[]) => {
+    setItems(newItems);
+    console.log('Items reordered:', newItems);
+  };
+
+  const handleDragStart = (itemId: string) => {
+    console.log(`Started dragging: ${itemId}`);
+  };
+
+  const handleDragEnd = (itemId: string) => {
+    console.log(`Finished dragging: ${itemId}`);
+  };
+
+  return (
+    <View width="300px">
+      <Tree
+        items={items}
+        expandedItems={expandedItems}
+        onExpandedItemsChange={setExpandedItems}
+        allowDragAndDrop={true}
+        dragHandleIcon={<CustomDragHandleIcon />}
+        onItemsReorder={handleItemsReorder}
+        onDragStart={handleDragStart}
+        onDragEnd={handleDragEnd}
+      />
+    </View>
+  );
+};
+```
+
+### **Variants and Sizes**
+```tsx
+import React from 'react';
+import { Tree } from '@app-studio/web';
+import { Text, Horizontal, Vertical } from 'app-studio';
+import { FolderIcon, FileIcon } from '@app-studio/web';
+import { TreeNode } from '@app-studio/web';
+
+export const TreeVariants = () => {
+  const treeData: TreeNode[] = [
+    {
+      id: 'root-fx',
+      label: 'Project',
+      icon: <FolderIcon size={16} />,
+      children: [
+        {
+          id: 'src-fx',
+          label: 'src',
+          icon: <FolderIcon size={16} />,
+          children: [
+            {
+              id: 'components-fx',
+              label: 'components',
+              icon: <FileIcon size={16} />,
+            },
+            {
+              id: 'utils-fx',
+              label: 'utils',
+              icon: <FileIcon size={16} />,
+            },
+          ],
+        },
+        {
+          id: 'public-fx',
+          label: 'public',
+          icon: <FolderIcon size={16} />,
+        },
+      ],
+    },
+  ];
+
+  return (
+    <Vertical gap={20}>
+      <Horizontal gap={30} alignItems="flex-start" flexWrap="wrap">
+        <Vertical gap={10}>
+          <Text fontWeight="medium">Default Variant</Text>
+          <Tree
+            items={treeData}
+            defaultExpandedItems={['root-fx', 'src-fx']}
+            variant="default"
+          />
+        </Vertical>
+
+        <Vertical gap={10}>
+          <Text fontWeight="medium">Outline Variant</Text>
+          <Tree
+            items={treeData}
+            defaultExpandedItems={['root-fx', 'src-fx']}
+            variant="outline"
+          />
+        </Vertical>
+
+        <Vertical gap={10}>
+          <Text fontWeight="medium">Filled Variant</Text>
+          <Tree
+            items={treeData}
+            defaultExpandedItems={['root-fx', 'src-fx']}
+            variant="filled"
+          />
+        </Vertical>
+      </Horizontal>
+
+      <Horizontal gap={30} alignItems="flex-start" flexWrap="wrap">
+        <Vertical gap={10}>
+          <Text fontWeight="medium">Small Size</Text>
+          <Tree
+            items={treeData}
+            defaultExpandedItems={['root-fx', 'src-fx']}
+            size="sm"
+          />
+        </Vertical>
+
+        <Vertical gap={10}>
+          <Text fontWeight="medium">Medium Size (Default)</Text>
+          <Tree
+            items={treeData}
+            defaultExpandedItems={['root-fx', 'src-fx']}
+            size="md"
+          />
+        </Vertical>
+
+        <Vertical gap={10}>
+          <Text fontWeight="medium">Large Size</Text>
+          <Tree
+            items={treeData}
+            defaultExpandedItems={['root-fx', 'src-fx']}
+            size="lg"
+          />
+        </Vertical>
+      </Horizontal>
+    </Vertical>
+  );
+};
+```
+
+### **Props**
+
+| Prop | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| children | React.ReactNode | undefined | Child elements for compound component pattern |
+| 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 |