@anymux/ui-kit 0.1.0

package/src/file-browser/architecture.md

@@ -0,0 +1,645 @@
+# FileBrowser Architecture v2.0 - Integrated with TreeComponent and ListItemsComponent
+
+## Overview
+
+The FileBrowser v2.0 is a unified, extensible dual-panel file browser component that leverages existing TreeComponent and ListItemsComponent architectures. It provides a modern file exploration experience with a dedicated tree navigation panel (folders only) and a synchronized content panel (files and folders) that maintains consistent selection state.
+
+// AICODE-NOTE: Architecture updated to use existing TreeComponent and ListItemsComponent instead of custom implementations
+// AICODE-NOTE: Tree shows directories only, list shows all items, both are synchronized via shared selection state
+
+## Key Design Principles
+
+- **Component Reuse**: Leverages existing TreeComponent (left panel) and ListItemsComponent (right panel)
+- **File System Agnostic**: Works with any `@anymux/file-system` implementation
+- **Synchronized State**: Tree selection drives list content, list navigation updates tree selection
+- **Provider Bridge**: Custom providers bridge between `@anymux/file-system` and component providers
+- **Directory-Only Tree**: Tree shows only directories for hierarchical navigation
+- **Full Content List**: List shows all items (files and directories) in current selection
+- **MobX Reactive State**: Following strict MobX model guidelines for state synchronization
+
+## Architecture Overview
+
+```
+FileBrowser v2.0
+├── FileBrowserModel (Orchestrator)
+│   ├── FileSystemBridge (Adapter)
+│   │   └── IFileSystem (@anymux/file-system)
+│   ├── TreeProvider (Directory Tree)
+│   │   └── TreeComponent (Left Panel)
+│   ├── ListItemsProvider (Content List)
+│   │   └── ListItemsComponent (Right Panel)
+│   └── SelectionSynchronizer (State Coordinator)
+```
+
+## Core Components Integration
+
+### 1. FileBrowserModel (Orchestrator)
+**Location**: `/models/FileBrowserModel.ts`
+
+**Purpose**: Main orchestrator that manages both TreeComponent and ListItemsComponent, handling state synchronization and file system interactions.
+
+```typescript
+class FileBrowserModel {
+  // File system integration
+  fileSystem: IFileSystem
+  fileSystemBridge: FileSystemBridge
+  
+  // Component providers
+  treeProvider: FileSystemTreeProvider
+  listProvider: FileSystemListProvider
+  
+  // Models
+  treeModel: TreeModel
+  listModel: ListItemsModel
+  
+  // Synchronized state
+  currentPath: string = '/'
+  selectedPath: string | null = null
+  
+  constructor(fileSystem: IFileSystem) {
+    makeAutoObservable(this, {})
+    
+    this.fileSystem = fileSystem
+    this.fileSystemBridge = new FileSystemBridge(fileSystem)
+    
+    // Create providers that bridge to file system
+    this.treeProvider = new FileSystemTreeProvider(this.fileSystemBridge, {
+      showFilesInTree: false, // AICODE-NOTE: Tree shows directories only
+      onSelectionChange: this.handleTreeSelection
+    })
+    
+    this.listProvider = new FileSystemListProvider(this.fileSystemBridge, {
+      showAllItems: true, // AICODE-NOTE: List shows files and directories
+      onSelectionChange: this.handleListSelection,
+      onNavigation: this.handleListNavigation
+    })
+    
+    // Create component models
+    this.treeModel = new TreeModel(this.treeProvider)
+    this.listModel = new ListItemsModel(this.listProvider)
+  }
+  
+  // Synchronization actions
+  handleTreeSelection = (path: string) => {
+    this.selectedPath = path
+    this.currentPath = path
+    // Load list content for selected directory
+    this.listModel.setPath(path)
+  }
+  
+  handleListNavigation = (path: string) => {
+    this.currentPath = path
+    this.selectedPath = path
+    // Update tree to highlight the directory
+    this.treeModel.selectPath(path)
+    // Expand tree to make path visible
+    this.treeModel.expandToPath(path)
+  }
+  
+  handleListSelection = (selectedItems: ListItemData[]) => {
+    // If single directory selected, could auto-navigate (optional)
+    if (selectedItems.length === 1 && selectedItems[0].type === 'directory') {
+      // Optional: auto-navigate to directory
+      // this.handleListNavigation(selectedItems[0].path)
+    }
+  }
+}
+```
+
+### 2. FileSystemBridge (Adapter)
+**Location**: `/adapters/FileSystemBridge.ts`
+
+**Purpose**: Adapter that converts `@anymux/file-system` operations to data structures expected by TreeComponent and ListItemsComponent.
+
+```typescript
+interface FileSystemItem {
+  id: string
+  path: string
+  name: string
+  type: 'file' | 'directory'
+  size?: number
+  modified?: Date
+  isDirectory: boolean
+  children?: FileSystemItem[]
+}
+
+class FileSystemBridge {
+  constructor(private fileSystem: IFileSystem) {
+    makeAutoObservable(this, {})
+  }
+  
+  // Tree operations (directories only)
+  async loadDirectoryTree(path: string): Promise<FileSystemItem[]> {
+    const dirents = await this.fileSystem.readdir(path, { withFileTypes: true })
+    
+    return dirents
+      .filter(dirent => dirent.isDirectory()) // AICODE-NOTE: Filter to directories only for tree
+      .map(dirent => ({
+        id: `${path}/${dirent.name}`.replace(/\/\//g, '/'),
+        path: `${path}/${dirent.name}`.replace(/\/\//g, '/'),
+        name: dirent.name,
+        type: 'directory' as const,
+        isDirectory: true
+      }))
+  }
+  
+  // List operations (all items)
+  async loadDirectoryContents(path: string): Promise<FileSystemItem[]> {
+    const dirents = await this.fileSystem.readdir(path, { withFileTypes: true })
+    
+    const items = await Promise.all(
+      dirents.map(async (dirent) => {
+        const itemPath = `${path}/${dirent.name}`.replace(/\/\//g, '/')
+        let stats: Stats | null = null
+        
+        try {
+          stats = await this.fileSystem.stat(itemPath)
+        } catch (error) {
+          // Handle permission errors gracefully
+        }
+        
+        return {
+          id: itemPath,
+          path: itemPath,
+          name: dirent.name,
+          type: dirent.isDirectory() ? 'directory' as const : 'file' as const,
+          size: stats?.size,
+          modified: stats?.mtime,
+          isDirectory: dirent.isDirectory()
+        }
+      })
+    )
+    
+    // Sort: directories first, then files, both alphabetically
+    return items.sort((a, b) => {
+      if (a.type !== b.type) {
+        return a.type === 'directory' ? -1 : 1
+      }
+      return a.name.localeCompare(b.name)
+    })
+  }
+  
+  // File operations
+  async readFile(path: string): Promise<Buffer | string> {
+    return this.fileSystem.readFile(path)
+  }
+  
+  async writeFile(path: string, content: Buffer | string): Promise<void> {
+    return this.fileSystem.writeFile(path, content)
+  }
+  
+  async deleteItem(path: string, isDirectory: boolean): Promise<void> {
+    if (isDirectory) {
+      return this.fileSystem.rmdir(path, { recursive: true })
+    } else {
+      return this.fileSystem.unlink(path)
+    }
+  }
+  
+  async createDirectory(path: string): Promise<void> {
+    return this.fileSystem.mkdir(path, { recursive: true })
+  }
+  
+  async renameItem(oldPath: string, newPath: string): Promise<void> {
+    return this.fileSystem.rename(oldPath, newPath)
+  }
+}
+```
+
+### 3. FileSystemTreeProvider (Tree Integration)
+**Location**: `/providers/FileSystemTreeProvider.ts`
+
+**Purpose**: Bridges FileSystemBridge to TreeComponent provider interface, showing directories only.
+
+```typescript
+class FileSystemTreeProvider implements TreeProvider {
+  constructor(
+    private bridge: FileSystemBridge,
+    private options: {
+      showFilesInTree: boolean
+      onSelectionChange: (path: string) => void
+    }
+  ) {
+    makeAutoObservable(this, {})
+  }
+  
+  // TreeProvider implementation
+  async loadNodes(options?: TreeLoadOptions): Promise<TreeLoadResult> {
+    const rootItems = await this.bridge.loadDirectoryTree(options?.path || '/')
+    
+    const nodes: TreeNodeData[] = rootItems.map(item => ({
+      id: item.id,
+      text: item.name,
+      data: item,
+      hasChildren: true, // Assume directories have children
+      isExpanded: false,
+      icon: 'folder'
+    }))
+    
+    return {
+      nodes,
+      totalCount: nodes.length
+    }
+  }
+  
+  async loadChildren(nodeId: string): Promise<TreeNodeData[]> {
+    const items = await this.bridge.loadDirectoryTree(nodeId)
+    
+    return items.map(item => ({
+      id: item.id,
+      text: item.name,
+      data: item,
+      hasChildren: true,
+      isExpanded: false,
+      icon: 'folder'
+    }))
+  }
+  
+  // Selection handling
+  onSelectionChange = (selectedNodes: TreeNodeData[]) => {
+    if (selectedNodes.length > 0) {
+      const selectedNode = selectedNodes[0]
+      this.options.onSelectionChange(selectedNode.data.path)
+    }
+  }
+  
+  // Context menu for directories
+  getNodeContextMenu(node: TreeNodeData): ContextMenuItem[] {
+    return [
+      {
+        id: 'open',
+        label: 'Open',
+        icon: 'folder-open',
+        action: () => this.options.onSelectionChange(node.data.path)
+      },
+      { id: 'separator1', type: 'separator' },
+      {
+        id: 'new-folder',
+        label: 'New Folder',
+        icon: 'folder-plus',
+        action: () => this.createNewFolder(node.data.path)
+      },
+      { id: 'separator2', type: 'separator' },
+      {
+        id: 'rename',
+        label: 'Rename',
+        icon: 'edit',
+        action: () => this.renameDirectory(node.data.path)
+      },
+      {
+        id: 'delete',
+        label: 'Delete',
+        icon: 'trash',
+        action: () => this.deleteDirectory(node.data.path)
+      }
+    ]
+  }
+  
+  private async createNewFolder(parentPath: string) {
+    // Implementation for creating new folder
+  }
+  
+  private async renameDirectory(path: string) {
+    // Implementation for renaming directory
+  }
+  
+  private async deleteDirectory(path: string) {
+    // Implementation for deleting directory
+  }
+}
+```
+
+### 4. FileSystemListProvider (List Integration)
+**Location**: `/providers/FileSystemListProvider.ts`
+
+**Purpose**: Bridges FileSystemBridge to ListItemsComponent provider interface, showing all items with file previews and actions.
+
+```typescript
+class FileSystemListProvider implements ListItemsProvider {
+  currentPath: string = '/'
+  
+  constructor(
+    private bridge: FileSystemBridge,
+    private options: {
+      showAllItems: boolean
+      onSelectionChange: (items: ListItemData[]) => void
+      onNavigation: (path: string) => void
+    }
+  ) {
+    makeAutoObservable(this, {})
+  }
+  
+  setPath(path: string) {
+    this.currentPath = path
+  }
+  
+  // ListItemsProvider implementation
+  async loadItems(options?: ListLoadOptions): Promise<ListLoadResult> {
+    const items = await this.bridge.loadDirectoryContents(this.currentPath)
+    
+    const listItems: ListItemData[] = items.map(item => ({
+      id: item.id,
+      name: item.name,
+      type: item.type,
+      path: item.path,
+      size: item.size,
+      modified: item.modified,
+      isDirectory: item.isDirectory,
+      data: item,
+      // Thumbnails for images
+      thumbnailUrl: this.getThumbnailUrl(item),
+      // File type icons
+      icon: this.getFileIcon(item)
+    }))
+    
+    return {
+      items: listItems,
+      totalCount: listItems.length
+    }
+  }
+  
+  // View type support
+  getSupportedViewTypes(): ListViewType[] {
+    return [
+      LIST_VIEW_TYPE,
+      GRID_VIEW_TYPE,
+      DETAILS_VIEW_TYPE,
+      MASONRY_HORIZONTAL_VIEW_TYPE
+    ]
+  }
+  
+  // Double-click handling
+  onItemAction = async (item: ListItemData, action: string) => {
+    if (action === 'open' || action === 'double-click') {
+      if (item.isDirectory) {
+        // Navigate to directory
+        this.options.onNavigation(item.path)
+      } else {
+        // Open file (could trigger preview or download)
+        await this.openFile(item.path)
+      }
+    }
+  }
+  
+  // Selection handling
+  onSelectionChange = (selectedItems: ListItemData[]) => {
+    this.options.onSelectionChange(selectedItems)
+  }
+  
+  // Context menu for files and directories
+  getItemContextMenu(item: ListItemData): ContextMenuItem[] {
+    const baseMenu = [
+      {
+        id: 'open',
+        label: item.isDirectory ? 'Open' : 'Open',
+        icon: item.isDirectory ? 'folder-open' : 'eye',
+        action: () => this.onItemAction(item, 'open')
+      }
+    ]
+    
+    if (!item.isDirectory) {
+      baseMenu.push(
+        { id: 'separator1', type: 'separator' },
+        {
+          id: 'preview',
+          label: 'Preview',
+          icon: 'eye',
+          action: () => this.previewFile(item.path)
+        },
+        {
+          id: 'download',
+          label: 'Download',
+          icon: 'download',
+          action: () => this.downloadFile(item.path)
+        }
+      )
+    }
+    
+    baseMenu.push(
+      { id: 'separator2', type: 'separator' },
+      {
+        id: 'rename',
+        label: 'Rename',
+        icon: 'edit',
+        action: () => this.renameItem(item.path)
+      },
+      {
+        id: 'delete',
+        label: 'Delete',
+        icon: 'trash',
+        action: () => this.deleteItem(item.path, item.isDirectory)
+      }
+    )
+    
+    return baseMenu
+  }
+  
+  private getThumbnailUrl(item: FileSystemItem): string | undefined {
+    if (item.type === 'file' && this.isImageFile(item.name)) {
+      // Return thumbnail URL for image files
+      return `/api/thumbnail?path=${encodeURIComponent(item.path)}`
+    }
+    return undefined
+  }
+  
+  private getFileIcon(item: FileSystemItem): string {
+    if (item.isDirectory) return 'folder'
+    
+    const ext = item.name.split('.').pop()?.toLowerCase()
+    const iconMap: Record<string, string> = {
+      // Images
+      'jpg': '🖼️', 'jpeg': '🖼️', 'png': '🖼️', 'gif': '🖼️', 'svg': '🖼️',
+      // Documents
+      'txt': '📄', 'md': '📝', 'pdf': '📕', 'doc': '📘', 'docx': '📘',
+      // Code
+      'js': '📜', 'ts': '📜', 'tsx': '📜', 'jsx': '📜', 'json': '📋',
+      // Other
+      'zip': '📦', 'tar': '📦', 'gz': '📦'
+    }
+    
+    return iconMap[ext || ''] || '📄'
+  }
+  
+  private isImageFile(filename: string): boolean {
+    const ext = filename.split('.').pop()?.toLowerCase()
+    return ['jpg', 'jpeg', 'png', 'gif', 'svg', 'webp'].includes(ext || '')
+  }
+  
+  private async openFile(path: string) {
+    // Implementation for opening files
+  }
+  
+  private async previewFile(path: string) {
+    // Implementation for file preview
+  }
+  
+  private async downloadFile(path: string) {
+    // Implementation for file download
+  }
+  
+  private async renameItem(path: string) {
+    // Implementation for renaming items
+  }
+  
+  private async deleteItem(path: string, isDirectory: boolean) {
+    await this.bridge.deleteItem(path, isDirectory)
+    // Refresh the list
+    // Could trigger parent to reload
+  }
+}
+```
+
+## Component Layout
+
+### FileBrowser Component Structure
+```typescript
+// Main FileBrowser component that combines tree and list
+export const FileBrowser: React.FC<FileBrowserProps> = observer(({ 
+  fileSystem,
+  initialPath = '/',
+  className 
+}) => {
+  const [model] = useState(() => new FileBrowserModel(fileSystem))
+  
+  useEffect(() => {
+    model.setInitialPath(initialPath)
+  }, [initialPath])
+  
+  return (
+    <div className={cn("flex h-full w-full", className)}>
+      {/* Left Panel - Tree Navigation (Directories Only) */}
+      <div className="w-80 border-r bg-background">
+        <div className="p-2 border-b bg-muted/10">
+          <h3 className="text-sm font-medium">Folders</h3>
+        </div>
+        <Tree 
+          provider={model.treeProvider}
+          className="h-full"
+        />
+      </div>
+      
+      {/* Right Panel - Content List (All Items) */}
+      <div className="flex-1 flex flex-col min-w-0">
+        <div className="p-2 border-b bg-muted/10 flex items-center justify-between">
+          <div className="flex items-center gap-2">
+            <h3 className="text-sm font-medium">Contents</h3>
+            <Badge variant="outline" className="text-xs">
+              {model.currentPath}
+            </Badge>
+          </div>
+          <ViewTypeSelector
+            viewTypes={model.listProvider.getSupportedViewTypes()}
+            currentViewType={model.listModel.currentViewType}
+            onViewTypeChange={(viewType) => model.listModel.setViewType(viewType)}
+          />
+        </div>
+        <ListItems
+          provider={model.listProvider}
+          className="flex-1"
+        />
+      </div>
+    </div>
+  )
+})
+```
+
+## State Synchronization Flow
+
+### Tree Selection → List Update
+1. User clicks directory in tree
+2. TreeProvider calls `onSelectionChange(path)`
+3. FileBrowserModel.handleTreeSelection():
+   - Updates `currentPath` and `selectedPath`
+   - Calls `listModel.setPath(path)`
+   - Triggers list refresh for new directory
+
+### List Navigation → Tree Update
+1. User double-clicks directory in list
+2. ListProvider calls `onNavigation(path)`
+3. FileBrowserModel.handleListNavigation():
+   - Updates `currentPath` and `selectedPath`
+   - Calls `treeModel.selectPath(path)`
+   - Calls `treeModel.expandToPath(path)` to make selection visible
+
+### File Operations Coordination
+1. User performs file operation (delete, rename, etc.)
+2. Provider executes operation via FileSystemBridge
+3. Provider triggers refresh of affected components
+4. Both tree and list update to reflect changes
+
+## Integration with @anymux/file-system
+
+The FileBrowser is designed to work with any implementation of `@anymux/file-system`:
+
+```typescript
+// Usage with different file systems
+import { MemoryFileSystem } from '@anymux/file-system/mem-fs'
+import { NodeFileSystem } from '@anymux/file-system/node-fs'
+import { BrowserFileSystem } from '@anymux/file-system/browser-fs'
+
+// Memory file system for demos
+const memFs = new MemoryFileSystem()
+const fileBrowser1 = <FileBrowser fileSystem={memFs} />
+
+// Node.js file system for server
+const nodeFs = new NodeFileSystem()
+const fileBrowser2 = <FileBrowser fileSystem={nodeFs} />
+
+// Browser file system for web
+const browserFs = new BrowserFileSystem()
+const fileBrowser3 = <FileBrowser fileSystem={browserFs} />
+```
+
+## File System Adapter Pattern
+
+The FileSystemBridge acts as an adapter between the generic `@anymux/file-system` interface and the specific data structures needed by TreeComponent and ListItemsComponent. This allows:
+
+1. **File System Independence**: Any compatible file system can be used
+2. **Data Structure Mapping**: Converts Dirent/Stats to component-expected formats
+3. **Error Handling**: Graceful handling of permission errors and missing files
+4. **Performance Optimization**: Caching and batch operations where beneficial
+5. **Type Safety**: Strong typing throughout the component chain
+
+## Usage in apps/web/list-samples
+
+The FileBrowser will be integrated into the list-samples page as a demonstration:
+
+```typescript
+// In apps/web/app/(fixed)/list-samples/page.tsx
+import { FileBrowser } from '@anymux/fs-ui'
+import { MemoryFileSystem } from '@anymux/file-system/mem-fs'
+
+const ListSamplesPage = () => {
+  const [memFs] = useState(() => {
+    const fs = new MemoryFileSystem()
+    // Populate with sample data
+    return fs
+  })
+  
+  return (
+    <Tabs defaultValue="list-only">
+      <TabsList>
+        <TabsTrigger value="list-only">List Component Only</TabsTrigger>
+        <TabsTrigger value="file-browser">File Browser (Tree + List)</TabsTrigger>
+      </TabsList>
+      
+      <TabsContent value="list-only">
+        {/* Existing ListItems demo */}
+      </TabsContent>
+      
+      <TabsContent value="file-browser">
+        <FileBrowser fileSystem={memFs} />
+      </TabsContent>
+    </Tabs>
+  )
+}
+```
+
+This architecture provides:
+- ✅ **Component Reuse**: Leverages existing TreeComponent and ListItemsComponent
+- ✅ **File System Agnostic**: Works with any `@anymux/file-system` implementation  
+- ✅ **Synchronized Views**: Tree and list maintain consistent state
+- ✅ **Directory-Only Tree**: Tree shows folders only for navigation
+- ✅ **Full Content List**: List shows all items with rich interactions
+- ✅ **MobX Reactive**: All state changes are reactive and efficient
+- ✅ **Provider Pattern**: Clean separation of concerns with bridges/adapters 

package/src/file-browser/components/CreateItemDialog.tsx

@@ -0,0 +1,71 @@
+import React, { useState, useRef, useEffect } from 'react';
+import {
+  AlertDialog,
+  AlertDialogContent,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogCancel,
+} from '@anymux/ui/components/alert-dialog';
+import { Button } from '@anymux/ui/components/button';
+import { Input } from '@anymux/ui/components/input';
+
+interface CreateItemDialogProps {
+  type: 'file' | 'folder';
+  onConfirm: (name: string) => void;
+  onCancel: () => void;
+}
+
+export const CreateItemDialog: React.FC<CreateItemDialogProps> = ({
+  type,
+  onConfirm,
+  onCancel,
+}) => {
+  const [name, setName] = useState('');
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  useEffect(() => {
+    requestAnimationFrame(() => inputRef.current?.focus());
+  }, []);
+
+  const handleSubmit = () => {
+    const trimmed = name.trim();
+    if (trimmed) {
+      onConfirm(trimmed);
+    }
+  };
+
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    if (e.key === 'Enter') {
+      e.preventDefault();
+      handleSubmit();
+    }
+  };
+
+  return (
+    <AlertDialog open onOpenChange={(open) => { if (!open) onCancel(); }}>
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>New {type === 'folder' ? 'Folder' : 'File'}</AlertDialogTitle>
+          <AlertDialogDescription>
+            Enter a name for the new {type === 'folder' ? 'folder' : 'file'}.
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        <Input
+          ref={inputRef}
+          value={name}
+          onChange={(e) => setName(e.target.value)}
+          onKeyDown={handleKeyDown}
+          placeholder={type === 'folder' ? 'Folder name' : 'File name'}
+        />
+        <AlertDialogFooter>
+          <AlertDialogCancel>Cancel</AlertDialogCancel>
+          <Button onClick={handleSubmit} disabled={!name.trim()}>
+            Create
+          </Button>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  );
+};