@anymux/ui-kit 0.1.0

package/src/tree/architecture.md

@@ -0,0 +1,530 @@
+# TreeComponent Architecture
+
+## Overview
+
+The TreeComponent is a reusable, high-performance tree component built with React, MobX, and TypeScript. It provides a flexible, accessible, and extensible tree interface that can work with any data source through the Provider pattern. The provider can work with or without React, supporting both web and non-web environments.
+
+**🔄 Migration Status**: This TreeComponent is designed to replace the existing FileBrowser TreeView components. Once fully implemented and tested, it will replace the legacy tree components in the FileBrowser system, providing better performance, accessibility, and maintainability.
+
+## Design Principles
+
+- **Provider-Driven Architecture**: TreeProvider model drives ALL behavior (selection, drag-drop, virtualization)
+- **Direct Provider Injection**: No registry pattern - provider passed directly to Tree component
+- **MobX Best Practices**: 
+  - Use `makeAutoObservable(this, {})` in constructors (NO decorators)
+  - Use `flow` for async actions
+  - Use `observable.map()` instead of plain Map for reactive collections
+  - Use composition over inheritance
+- **All State in Provider**: multiSelect, dragDrop, virtualization configured in provider
+- **Callback-Based**: Tree component calls provider callbacks for all interactions
+- **Node-Level Customization**: Per-node context menus and render overrides
+- **Environment Agnostic**: Provider works with and without React
+- **Component Composition**: Small, focused components for maintainability
+- **Accessibility First**: Full ARIA support for screen readers and keyboard navigation
+- **Performance**: Virtualization support for large trees
+- **Type Safety**: Comprehensive TypeScript coverage
+
+## MobX Best Practices (CRITICAL)
+
+**⚠️ STRICT REQUIREMENTS - These patterns must be followed exactly:**
+
+### 1. No Decorators - Use makeAutoObservable
+```typescript
+// ❌ NEVER use decorators
+class TreeModel {
+  @observable nodes = []
+  @action selectNode() {}
+}
+
+// ✅ ALWAYS use makeAutoObservable
+class TreeModel {
+  nodes = []
+  
+  constructor() {
+    makeAutoObservable(this, {}); // Empty overrides object
+  }
+  
+  selectNode() {} // Automatically becomes action
+}
+```
+
+### 2. Observable Collections - Use observable.map()
+```typescript
+// ❌ NEVER use plain Map/Set
+selectedNodes = new Map<string, TreeNodeData>()
+expandedNodes = new Set<string>()
+
+// ✅ ALWAYS use observable.map()
+selectedNodes = observable.map<string, TreeNodeData>()
+expandedNodes = observable.map<string, boolean>()
+```
+
+### 3. Async Actions - Use flow
+```typescript
+// ❌ NEVER use async/await directly in actions
+async loadNodes() {
+  this.isLoading = true;
+  const result = await api.loadNodes();
+  this.nodes = result; // ⚠️ Not in action!
+}
+
+// ✅ ALWAYS use flow for async operations
+loadNodes = flow(function* (this: TreeModel) {
+  this.isLoading = true;
+  const result = yield api.loadNodes();
+  this.nodes = result; // ✅ Automatically in action
+});
+```
+
+### 4. Composition Over Inheritance
+```typescript
+// ❌ NEVER use inheritance (MobX issues)
+class BaseModel {}
+class TreeModel extends BaseModel {}
+
+// ✅ ALWAYS use composition
+class TreeModel {
+  selectionManager: TreeSelectionModel;
+  expansionManager: TreeExpansionModel;
+  
+  constructor() {
+    makeAutoObservable(this, {});
+    this.selectionManager = new TreeSelectionModel(this);
+    this.expansionManager = new TreeExpansionModel(this);
+  }
+}
+```
+
+### 5. Computed Properties for Performance
+```typescript
+class TreeModel {
+  selectedNodes = observable.map<string, TreeNodeData>()
+  
+  constructor() {
+    makeAutoObservable(this, {});
+  }
+  
+  // ✅ Computed properties are automatically optimized
+  get selectedNodesArray() {
+    return Array.from(this.selectedNodes.values());
+  }
+  
+  get hasSelection() {
+    return this.selectedNodes.size > 0;
+  }
+}
+```
+
+### 6. Observer Components for Lists
+```typescript
+// ❌ NEVER render observables directly in map
+const NodeList = observer(() => (
+  <div>
+    {nodes.map(node => <div key={node.id}>{node.name}</div>)} {/* Won't react! */}
+  </div>
+))
+
+// ✅ ALWAYS extract to separate observer components
+const NodeItem = observer(({ node }) => <div>{node.name}</div>)
+
+const NodeList = observer(() => (
+  <div>
+    {nodes.map(node => <NodeItem key={node.id} node={node} />)}
+  </div>
+))
+```
+
+## Architecture Overview
+
+```
+TreeComponent
+    ↓ receives
+TreeProvider (MobX Model)
+    ↓ provides data & callbacks
+TreeModel (MobX State)
+    ↓ manages
+Tree Components (React UI)
+```
+
+## Core Components
+
+### 1. TreeProvider (Model Layer)
+**Location**: `/providers/TreeProvider.ts`
+
+**Purpose**: Defines the contract for data loading, node rendering, and interaction callbacks. Works independently of React.
+
+**Key Features**:
+- Data loading methods (`loadNodes`, `loadChildren`, `refresh`, `search`)
+- Per-node context menus (`getNodeContextMenu`, `getMultiNodeContextMenu`)
+- Node rendering overrides (`getNodeRenderer`, `getDefaultRenderer`)
+- Capability checks (`canExpand`, `canSelect`, `canDrag`, `canDrop`)
+- Event callbacks (`onSelectionChange`, `onDragDrop`, `onContextMenuAction`)
+- Non-React node rendering (`TreeNodeRenderer.renderText`, `renderIcon`)
+
+### 2. TreeModel (State Layer)
+**Location**: `/models/TreeModel.ts`
+
+**Purpose**: MobX observable state container that manages tree data, selection, expansion, and UI state.
+
+**State Management**:
+```typescript
+class TreeModel {
+  // Core Data - using observable.map for reactive collections
+  nodes: TreeNodeData[] = []
+  nodeMap = observable.map<string, TreeNodeData>()
+  
+  // UI State - using observable.map instead of Set/Map
+  selectedNodes = observable.map<string, TreeNodeData>()
+  expandedNodes = observable.map<string, boolean>()
+  focusedNode: string | null = null
+  
+  // Loading State
+  isLoading: boolean = false
+  loadingNodes = observable.map<string, boolean>()
+  errors = observable.map<string, Error>()
+  
+  // Interaction State
+  draggedNodes: TreeNodeData[] = []
+  dropTarget: TreeNodeData | null = null
+  contextMenuNode: TreeNodeData | null = null
+  
+  constructor(public provider: TreeProvider) {
+    makeAutoObservable(this, {
+      // Most defaults are correct, empty overrides object
+    });
+  }
+  
+  // Computed properties for derived state
+  get selectedNodesArray(): TreeNodeData[] {
+    return Array.from(this.selectedNodes.values());
+  }
+  
+  get hasSelection(): boolean {
+    return this.selectedNodes.size > 0;
+  }
+  
+  get isNodeSelected() {
+    return (nodeId: string) => this.selectedNodes.has(nodeId);
+  }
+  
+  // Async actions using flow
+  loadNodes = flow(function* (this: TreeModel, options?: TreeLoadOptions) {
+    this.isLoading = true;
+    this.errors.clear();
+    
+    try {
+      const result = yield this.provider.loadNodes(options);
+      this.nodes = result.nodes;
+      
+      // Update node map for fast lookups
+      this.nodeMap.clear();
+      result.nodes.forEach(node => this.nodeMap.set(node.id, node));
+      
+    } catch (error) {
+      this.errors.set('loadNodes', error);
+    } finally {
+      this.isLoading = false;
+    }
+  });
+}
+```
+
+### 3. Tree Component (UI Layer)
+**Location**: `/components/Tree.tsx`
+
+**Purpose**: Main React component that receives TreeProvider as prop and renders the tree UI.
+
+**Component Interface**:
+```typescript
+interface TreeProps {
+  provider: TreeProvider;
+  className?: string;
+  height?: number;
+  // All behavior controlled by provider - no separate props
+}
+
+export const Tree = observer(({ provider, className, height }: TreeProps) => {
+  const [model] = useState(() => new TreeModel(provider))
+  
+  // All configuration comes from provider:
+  // - provider.isMultiSelectEnabled
+  // - provider.isDragDropEnabled  
+  // - provider.isVirtualizationEnabled
+  // - provider.getVirtualizationConfig()
+  
+  // Component delegates all actions to model,
+  // which calls provider callbacks
+})
+```
+
+## File & Folder Structure
+
+```
+fs-ui/src/TreeComponent/
+├── architecture.md
+├── providers/
+│   └── TreeProvider.ts              # Provider interface
+├── models/
+│   ├── TreeModel.ts                 # Main MobX state model
+│   ├── TreeNode.ts                  # Individual node state
+│   ├── TreeSelection.ts             # Selection state management
+│   ├── TreeExpansion.ts             # Expansion state management
+│   └── TreeLoading.ts               # Loading state management
+├── components/
+│   ├── Tree.tsx                     # Main tree component
+│   ├── TreeNode.tsx                 # Individual node component
+│   ├── TreeNodeList.tsx             # Node list container
+│   ├── TreeContextMenu.tsx          # Context menu component
+│   └── shared/
+│       ├── TreeIcon.tsx             # Icon rendering
+│       ├── TreeLoader.tsx           # Loading indicators
+│       └── TreeVirtualization.tsx   # Virtual scrolling
+├── renderers/
+│   ├── DefaultNodeRenderer.ts       # Default node rendering
+│   ├── TextNodeRenderer.ts          # Text-only rendering
+│   └── CustomNodeRenderer.tsx       # Custom React rendering
+├── types/
+│   ├── TreeTypes.ts                 # Core type definitions
+│   ├── TreeEvents.ts                # Event type definitions
+│   └── TreeOptions.ts               # Configuration types
+├── utils/
+│   ├── TreeUtils.ts                 # Tree manipulation utilities
+│   ├── TreeKeyboard.ts              # Keyboard navigation
+│   └── TreeAccessibility.ts         # ARIA utilities
+└── index.ts                         # Public exports
+```
+
+## Data Flow
+
+### 1. Initialization
+```
+1. Tree component receives TreeProvider
+2. TreeModel created with provider
+3. TreeModel calls provider.initialize()
+4. TreeModel calls provider.loadNodes()
+5. Tree renders with initial data
+```
+
+### 2. User Interactions
+```
+User clicks node
+    ↓
+TreeNode component handles event
+    ↓
+Calls TreeModel.selectNode()
+    ↓
+TreeModel updates @observable selectedNodes
+    ↓
+TreeModel calls provider.onSelectionChange()
+    ↓
+UI re-renders via MobX observer
+```
+
+### 3. Context Menus
+```
+User right-clicks node
+    ↓
+TreeNode calls provider.getNodeContextMenu(node)
+    ↓
+TreeContextMenu renders menu items
+    ↓
+User clicks menu item
+    ↓
+TreeContextMenu calls provider.onContextMenuAction()
+```
+
+### 4. Custom Rendering
+```
+TreeNode needs to render
+    ↓
+Calls provider.getNodeRenderer(node)
+    ↓
+If custom renderer exists:
+  - Use renderer.renderComponent (React)
+  - Or renderer.renderText (non-React)
+    ↓
+Otherwise use default rendering
+```
+
+## State Management Details
+
+### TreeModel State Structure (MobX Best Practices)
+```typescript
+class TreeModel {
+  // Core Data - using observable.map for reactive collections
+  nodes: TreeNodeData[] = []
+  nodeMap = observable.map<string, TreeNodeData>()
+  
+  // UI State - using observable.map instead of Set/Map
+  selectedNodes = observable.map<string, TreeNodeData>()
+  expandedNodes = observable.map<string, boolean>()
+  focusedNode: string | null = null
+  
+  // Loading State
+  isLoading: boolean = false
+  loadingNodes = observable.map<string, boolean>()
+  errors = observable.map<string, Error>()
+  
+  // Interaction State
+  draggedNodes: TreeNodeData[] = []
+  dropTarget: TreeNodeData | null = null
+  contextMenuNode: TreeNodeData | null = null
+  
+  constructor(public provider: TreeProvider) {
+    makeAutoObservable(this, {
+      // Most defaults are correct, empty overrides object
+    });
+  }
+  
+  // Computed properties for derived state
+  get selectedNodesArray(): TreeNodeData[] {
+    return Array.from(this.selectedNodes.values());
+  }
+  
+  get hasSelection(): boolean {
+    return this.selectedNodes.size > 0;
+  }
+  
+  get isNodeSelected() {
+    return (nodeId: string) => this.selectedNodes.has(nodeId);
+  }
+  
+  // Async actions using flow
+  loadNodes = flow(function* (this: TreeModel, options?: TreeLoadOptions) {
+    this.isLoading = true;
+    this.errors.clear();
+    
+    try {
+      const result = yield this.provider.loadNodes(options);
+      this.nodes = result.nodes;
+      
+      // Update node map for fast lookups
+      this.nodeMap.clear();
+      result.nodes.forEach(node => this.nodeMap.set(node.id, node));
+      
+    } catch (error) {
+      this.errors.set('loadNodes', error);
+    } finally {
+      this.isLoading = false;
+    }
+  });
+}
+```
+
+### Provider Callback Integration
+All user interactions flow through the provider:
+
+- **Selection**: `provider.onSelectionChange(selectionInfo)`
+- **Expansion**: `provider.onNodeExpansion(node, expanded)`
+- **Double-click**: `provider.onNodeDoubleClick(node)`
+- **Drag & Drop**: `provider.onDragDrop(dragInfo)`
+- **Context Menu**: `provider.onContextMenuAction(menuId, nodes)`
+- **Focus**: `provider.onNodeFocus(node)`
+
+## Node Rendering System
+
+### Multi-Environment Support
+The TreeProvider supports rendering in multiple environments:
+
+```typescript
+interface TreeNodeRenderer {
+  // Non-React environments (Node.js, CLI tools)
+  renderText?(node: TreeNodeData): string
+  renderIcon?(node: TreeNodeData): string
+  getDisplayProps?(node: TreeNodeData): DisplayProps
+  
+  // React environments
+  renderComponent?: React.ComponentType<{node: TreeNodeData}>
+}
+```
+
+### Per-Node Customization
+Each node can have its own renderer:
+
+```typescript
+// Provider can customize per node
+provider.getNodeRenderer(fileNode) // Returns FileRenderer
+provider.getNodeRenderer(dirNode)  // Returns DirectoryRenderer
+provider.getDefaultRenderer()      // Returns fallback renderer
+```
+
+### Context Menu Customization
+Each node can have different context menus:
+
+```typescript
+// Different menus per node type
+provider.getNodeContextMenu(fileNode) // [Edit, Delete, Rename]
+provider.getNodeContextMenu(dirNode)  // [New File, New Folder, Delete]
+provider.getMultiNodeContextMenu(nodes) // [Delete Selected, Move]
+provider.getEmptySpaceContextMenu() // [New File, New Folder, Paste]
+```
+
+## Usage Examples
+
+### Basic Usage
+```typescript
+// Create provider with configuration
+const fileSystemProvider = new FileSystemTreeProvider(fileSystem, {
+  multiSelectEnabled: true,
+  dragDropEnabled: true,
+  virtualizationEnabled: true
+})
+
+// Use in React - all behavior comes from provider
+<Tree provider={fileSystemProvider} />
+```
+
+### Custom Provider Implementation
+```typescript
+class GitTreeProvider implements TreeProvider {
+  constructor(private gitRepo: GitRepository) {}
+  
+  async loadNodes() {
+    return { nodes: await this.gitRepo.getFiles() }
+  }
+  
+  getNodeContextMenu(node: TreeNodeData) {
+    if (node.type === 'file') {
+      return [
+        { id: 'edit', label: 'Edit File', icon: 'edit' },
+        { id: 'delete', label: 'Delete', icon: 'trash' },
+        { type: 'separator' },
+        { id: 'commit', label: 'Commit Changes', icon: 'git-commit' }
+      ]
+    }
+    return []
+  }
+  
+  onContextMenuAction(menuId: string, nodes: TreeNodeData[]) {
+    switch (menuId) {
+      case 'edit': this.editFile(nodes[0]); break
+      case 'delete': this.deleteFiles(nodes); break
+      case 'commit': this.commitChanges(nodes); break
+    }
+  }
+}
+```
+
+## Performance Considerations
+
+- **MobX Reactivity**: Only affected components re-render on state changes
+- **Virtualization**: Built-in support for large trees
+- **Lazy Loading**: Provider-driven on-demand loading
+- **Memory Management**: Automatic cleanup of unused nodes
+- **Debounced Actions**: Built-in debouncing for frequent operations
+
+## Accessibility Features
+
+- **ARIA Support**: Full screen reader compatibility
+- **Keyboard Navigation**: Arrow keys, space, enter
+- **Focus Management**: Proper focus handling and visibility
+- **High Contrast**: Respects system accessibility preferences
+- **Voice Control**: Semantic markup for voice navigation
+
+## Integration Points
+
+### With FileBrowser
+```typescript
+const fileBrowserProvider = new FileBrowserTreeProvider(fileSystem)
+<Tree provider={fileBrowserProvider} />
+```