@anymux/ui-kit 0.1.0

package/src/file-browser/adapters/README.md

@@ -0,0 +1,504 @@
+# FileBrowser Adapter System
+
+This directory contains example adapters demonstrating how to integrate external systems with the FileBrowser's dual-panel coordination system.
+
+## Overview
+
+The FileBrowser adapter system provides a standardized way to:
+- Extend FileBrowser functionality with domain-specific features
+- Maintain selection and navigation coordination between external systems and FileBrowser panels
+- Implement reactive patterns using MobX for seamless state synchronization
+- Handle complex multi-panel interactions and state management
+
+## Architecture
+
+### Coordination Pattern
+
+The core coordination pattern follows these principles:
+
+```typescript
+// 1. Listen to FileBrowser state changes via MobX reactions
+const selectionDisposer = reaction(
+  () => ({
+    selectedItems: Array.from(fileBrowserModel.selectionManager.selectedItems.keys()),
+    focusedItem: fileBrowserModel.selectionManager.focusedItem
+  }),
+  ({ focusedItem }) => {
+    // React to selection changes
+    this.handleSelectionChange(focusedItem);
+  }
+);
+
+// 2. Update external system state based on FileBrowser changes
+private async handleSelectionChange(item: FileBrowserItem | null) {
+  if (!item) return;
+  
+  // Update external system
+  await this.updateExternalSystem(item);
+}
+
+// 3. Coordinate back to FileBrowser when external system changes
+public selectFromExternalSystem(externalItem: any) {
+  // Convert external item to FileBrowser item
+  const fileBrowserItem = this.convertToFileBrowserItem(externalItem);
+  
+  // Use coordination methods
+  this.fileBrowserModel.selectionManager.selectItem(fileBrowserItem.id);
+}
+```
+
+### Key Coordination Points
+
+1. **Selection Coordination**: Synchronize selection between FileBrowser and external systems
+2. **Navigation Coordination**: Coordinate navigation events across panels
+3. **State Management**: Maintain consistent state between systems
+4. **Error Handling**: Provide graceful error handling with proper user feedback
+
+## Example Adapters
+
+### DocumentViewerAdapter
+
+Demonstrates integration with a document viewing system:
+
+```typescript
+import { DocumentViewerAdapter } from './DocumentViewerAdapter';
+
+// Initialize adapter
+const documentViewer = new DocumentViewerAdapter(fileBrowserModel, {
+  supportedFileTypes: ['.pdf', '.doc', '.docx', '.txt', '.md'],
+  previewEnabled: true,
+  maxFileSize: 50 * 1024 * 1024, // 50MB
+  enableCoordination: true
+});
+
+// Document will automatically load when files are selected in FileBrowser
+// Navigation will automatically clear stale document state
+```
+
+**Key Features:**
+- Automatic document loading on file selection
+- Preview generation and caching
+- File type validation and size constraints
+- Navigation-aware state management
+- Bidirectional coordination with FileBrowser
+
+### GitBrowserAdapter
+
+Demonstrates integration with Git repository functionality:
+
+```typescript
+import { GitBrowserAdapter } from './GitBrowserAdapter';
+
+// Initialize adapter
+const gitBrowser = new GitBrowserAdapter(fileBrowserModel, {
+  repositoryPath: '/path/to/repo',
+  autoFetch: false,
+  statusRefreshInterval: 5000,
+  enableCoordination: true
+});
+
+// Load repository
+await gitBrowser.loadRepository('/path/to/repo');
+
+// Git status will automatically update based on FileBrowser navigation
+// Branch switching will coordinate with FileBrowser content updates
+```
+
+**Key Features:**
+- Git repository integration
+- Branch and commit coordination
+- File status overlay
+- Left panel mode integration
+- Automatic status refresh
+
+## Creating Custom Adapters
+
+### Step 1: Define Your Adapter Interface
+
+```typescript
+export interface MyAdapterOptions {
+  // Configuration options
+  enableCoordination?: boolean;
+  // ... other options
+}
+
+export class MyAdapter {
+  private fileBrowserModel: FileBrowserModel;
+  private options: Required<MyAdapterOptions>;
+  private disposers: Array<() => void> = [];
+
+  constructor(fileBrowserModel: FileBrowserModel, options: MyAdapterOptions = {}) {
+    this.fileBrowserModel = fileBrowserModel;
+    this.options = {
+      enableCoordination: true,
+      ...options
+    };
+
+    makeAutoObservable(this);
+
+    if (this.options.enableCoordination) {
+      this.setupCoordination();
+    }
+  }
+}
+```
+
+### Step 2: Setup Coordination Reactions
+
+```typescript
+private setupCoordination() {
+  // Listen for selection changes
+  const selectionDisposer = reaction(
+    () => ({
+      focusedItem: this.fileBrowserModel.selectionManager.focusedItem
+    }),
+    ({ focusedItem }) => {
+      this.handleSelectionChange(focusedItem);
+    },
+    { fireImmediately: true }
+  );
+
+  // Listen for navigation changes
+  const navigationDisposer = reaction(
+    () => this.fileBrowserModel.navigationManager.currentPath,
+    (currentPath) => {
+      this.handleNavigationChange(currentPath || '/');
+    }
+  );
+
+  this.disposers.push(selectionDisposer, navigationDisposer);
+}
+```
+
+### Step 3: Implement Coordination Handlers
+
+```typescript
+private async handleSelectionChange(item: FileBrowserItem | null) {
+  if (!item) {
+    this.clearExternalState();
+    return;
+  }
+
+  // Update external system based on selection
+  try {
+    await this.updateExternalSystem(item);
+    this.logInfo(`Updated external system for: ${item.name}`);
+  } catch (error) {
+    this.logError('Failed to update external system', error);
+  }
+}
+
+private async handleNavigationChange(currentPath: string) {
+  // React to navigation changes
+  await this.refreshExternalSystemForPath(currentPath);
+}
+```
+
+### Step 4: Provide Public APIs
+
+```typescript
+// Public methods for external control
+public async loadItem(item: FileBrowserItem): Promise<void> {
+  // Use coordination to load item
+  this.fileBrowserModel.selectionManager.selectItem(item.id);
+}
+
+public navigateToItem(item: FileBrowserItem): void {
+  // Use navigation coordination
+  const directoryPath = this.getDirectoryPath(item.path);
+  this.fileBrowserModel.navigationManager.navigateToWithCoordination(
+    directoryPath,
+    'breadcrumb'
+  );
+}
+```
+
+### Step 5: Implement Cleanup
+
+```typescript
+dispose(): void {
+  // Clean up all reactions
+  this.disposers.forEach(dispose => dispose());
+  this.disposers = [];
+  
+  // Clean up external resources
+  this.cleanupExternalSystem();
+  
+  this.logInfo('Adapter disposed');
+}
+```
+
+## Best Practices
+
+### 1. Reactive State Management
+
+- Use MobX `reaction` for listening to FileBrowser state changes
+- Use `makeAutoObservable` for adapter state
+- Avoid direct state mutations, use actions instead
+
+### 2. Error Handling
+
+```typescript
+private async handleCoordinatedOperation(operation: () => Promise<void>) {
+  try {
+    await operation();
+  } catch (error) {
+    this.setError(`Operation failed: ${error}`);
+    // Optionally notify user through FileBrowser error system
+  }
+}
+```
+
+### 3. Performance Optimization
+
+```typescript
+// Use caching for expensive operations
+private cache = new Map<string, any>();
+
+private async getExpensiveData(key: string): Promise<any> {
+  if (this.cache.has(key)) {
+    return this.cache.get(key);
+  }
+  
+  const data = await this.computeExpensiveData(key);
+  this.cache.set(key, data);
+  return data;
+}
+```
+
+### 4. Logging and Debugging
+
+```typescript
+private logInfo(message: string, data?: any): void {
+  this.fileBrowserModel.logger?.info(`[MyAdapter] ${message}`, data);
+}
+
+private logError(message: string, error: any): void {
+  this.fileBrowserModel.logger?.error(`[MyAdapter] ${message}`, error);
+}
+```
+
+### 5. Configuration Management
+
+```typescript
+// Provide sensible defaults
+private readonly defaultOptions: Required<MyAdapterOptions> = {
+  enableCoordination: true,
+  cacheSize: 100,
+  refreshInterval: 5000
+};
+
+constructor(fileBrowserModel: FileBrowserModel, options: MyAdapterOptions = {}) {
+  this.options = { ...this.defaultOptions, ...options };
+}
+```
+
+## Migration Guide
+
+### From Single-Panel to Dual-Panel
+
+If you have existing FileBrowser integrations that need to be migrated to the dual-panel coordination system:
+
+#### 1. Update Event Handling
+
+**Before (single-panel):**
+```typescript
+// Direct event handling
+onItemClick(item: FileBrowserItem) {
+  this.externalSystem.loadItem(item);
+}
+```
+
+**After (dual-panel coordination):**
+```typescript
+// Coordination-based handling
+private setupCoordination() {
+  reaction(
+    () => this.fileBrowserModel.selectionManager.focusedItem,
+    (item) => {
+      if (item) {
+        this.externalSystem.loadItem(item);
+      }
+    }
+  );
+}
+```
+
+#### 2. Update Navigation Handling
+
+**Before:**
+```typescript
+// Direct navigation
+onNavigate(path: string) {
+  this.externalSystem.updatePath(path);
+}
+```
+
+**After:**
+```typescript
+// Coordination-based navigation
+private setupCoordination() {
+  reaction(
+    () => this.fileBrowserModel.navigationManager.currentPath,
+    (path) => {
+      if (path) {
+        this.externalSystem.updatePath(path);
+      }
+    }
+  );
+}
+```
+
+#### 3. Update State Management
+
+**Before:**
+```typescript
+// Manual state tracking
+private selectedItem: FileBrowserItem | null = null;
+
+setSelectedItem(item: FileBrowserItem) {
+  this.selectedItem = item;
+  this.updateUI();
+}
+```
+
+**After:**
+```typescript
+// MobX reactive state
+@observable
+selectedItem: FileBrowserItem | null = null;
+
+// Automatic updates via reactions
+private setupCoordination() {
+  reaction(
+    () => this.fileBrowserModel.selectionManager.focusedItem,
+    (item) => {
+      this.selectedItem = item;
+      // UI updates automatically via MobX
+    }
+  );
+}
+```
+
+## Performance Considerations
+
+### Large Datasets
+
+When working with large datasets:
+
+1. **Implement Virtualization**: Only load/render visible items
+2. **Use Pagination**: Break large datasets into manageable chunks
+3. **Cache Strategically**: Cache frequently accessed data with appropriate TTL
+4. **Debounce Updates**: Avoid excessive updates during rapid changes
+
+```typescript
+// Example: Debounced status updates
+private debouncedStatusUpdate = debounce(async () => {
+  await this.refreshStatus();
+}, 500);
+
+private handleNavigationChange(path: string) {
+  this.debouncedStatusUpdate();
+}
+```
+
+### Memory Management
+
+```typescript
+// Clean up resources properly
+dispose(): void {
+  // Dispose reactions
+  this.disposers.forEach(dispose => dispose());
+  
+  // Clear caches
+  this.cache.clear();
+  
+  // Cancel pending operations
+  this.cancelPendingOperations();
+  
+  // Clear timers
+  if (this.refreshTimer) {
+    clearInterval(this.refreshTimer);
+  }
+}
+```
+
+## Testing
+
+### Unit Testing Adapters
+
+```typescript
+import { DocumentViewerAdapter } from './DocumentViewerAdapter';
+
+describe('DocumentViewerAdapter', () => {
+  let adapter: DocumentViewerAdapter;
+  let mockFileBrowserModel: jest.Mocked<FileBrowserModel>;
+
+  beforeEach(() => {
+    mockFileBrowserModel = createMockFileBrowserModel();
+    adapter = new DocumentViewerAdapter(mockFileBrowserModel);
+  });
+
+  afterEach(() => {
+    adapter.dispose();
+  });
+
+  it('should load document when file is selected', async () => {
+    const testFile = createTestFile('test.pdf');
+    
+    // Simulate selection change
+    mockFileBrowserModel.selectionManager.focusedItem = testFile;
+    
+    // Wait for coordination
+    await waitForReaction();
+    
+    expect(adapter.currentDocument).toBeTruthy();
+    expect(adapter.currentDocument?.fileName).toBe('test.pdf');
+  });
+});
+```
+
+### Integration Testing
+
+```typescript
+describe('Adapter Coordination', () => {
+  it('should maintain coordination between adapters', async () => {
+    const documentAdapter = new DocumentViewerAdapter(fileBrowserModel);
+    const gitAdapter = new GitBrowserAdapter(fileBrowserModel);
+
+    // Select a file
+    fileBrowserModel.selectionManager.selectItem('file1');
+    
+    // Both adapters should react
+    await waitForReactions();
+    
+    expect(documentAdapter.currentDocument).toBeTruthy();
+    expect(gitAdapter.getFileStatus('file1')).toBeTruthy();
+  });
+});
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Infinite Loops**: Use coordination flags to prevent circular updates
+2. **Memory Leaks**: Always dispose reactions and clear caches
+3. **Performance Issues**: Implement debouncing and caching
+4. **Type Errors**: Ensure proper TypeScript interfaces for coordination
+
+### Debugging Tips
+
+```typescript
+// Enable detailed logging
+private logInfo(message: string, data?: any): void {
+  if (process.env.NODE_ENV === 'development') {
+    console.log(`[${this.constructor.name}] ${message}`, data);
+  }
+  this.fileBrowserModel.logger?.info(`[${this.constructor.name}] ${message}`, data);
+}
+```
+
+## Examples
+
+See the `/examples` directory for complete working examples of various adapter patterns and integration scenarios. 

package/src/file-browser/adapters/index.ts

@@ -0,0 +1,27 @@
+// Adapter implementations
+export { DocumentViewerAdapter } from './DocumentViewerAdapter';
+export type { 
+  DocumentViewerOptions, 
+  DocumentInfo 
+} from './DocumentViewerAdapter';
+
+export { GitBrowserAdapter } from './GitBrowserAdapter';
+export type { 
+  GitBrowserOptions,
+  GitFileStatus,
+  GitCommit,
+  GitBranch,
+  GitRepositoryInfo
+} from './GitBrowserAdapter';
+
+// Base adapter patterns and utilities
+export type { AdapterBase, AdapterOptions, AdapterStats, AdapterDisposer } from './types';
+export { BaseAdapter } from './types';
+
+/**
+ * Re-export core FileBrowser types for adapter development
+ */
+export type { FileBrowserItem } from '../types/FileBrowserTypes';
+export type { FileBrowserModel } from '../models/FileBrowserModel';
+export type { SelectionManagerModel } from '../models/SelectionManagerModel';
+export type { NavigationManagerModel } from '../models/NavigationManagerModel'; 

package/src/file-browser/adapters/types.ts

@@ -0,0 +1,70 @@
+import { FileBrowserModel } from '../models/FileBrowserModel';
+import { FileBrowserItem } from '../types/FileBrowserTypes';
+
+/**
+ * Base adapter options that all adapters should support
+ */
+export interface AdapterOptions {
+  enableCoordination?: boolean;
+  enableLogging?: boolean;
+}
+
+/**
+ * Base adapter interface that all adapters should implement
+ */
+export interface AdapterBase {
+  // Core adapter lifecycle
+  dispose(): void;
+  
+  // Coordination methods
+  handleSelectionChange(item: FileBrowserItem | null): void | Promise<void>;
+  handleNavigationChange(path: string): void | Promise<void>;
+  
+  // Status methods
+  readonly isLoading: boolean;
+  readonly error: string | null;
+}
+
+/**
+ * Common coordination patterns for adapters
+ */
+export abstract class BaseAdapter implements AdapterBase {
+  protected fileBrowserModel: FileBrowserModel;
+  protected disposers: Array<() => void> = [];
+  
+  abstract isLoading: boolean;
+  abstract error: string | null;
+
+  constructor(fileBrowserModel: FileBrowserModel) {
+    this.fileBrowserModel = fileBrowserModel;
+  }
+
+  abstract handleSelectionChange(item: FileBrowserItem | null): void | Promise<void>;
+  abstract handleNavigationChange(path: string): void | Promise<void>;
+
+  protected logInfo(message: string, data?: any): void {
+    this.fileBrowserModel.logger?.info(`[${this.constructor.name}] ${message}`, data);
+  }
+
+  protected logError(message: string, error: any): void {
+    this.fileBrowserModel.logger?.error(`[${this.constructor.name}] ${message}`, error);
+  }
+
+  dispose(): void {
+    this.disposers.forEach(dispose => dispose());
+    this.disposers = [];
+    this.logInfo('Adapter disposed');
+  }
+}
+
+/**
+ * Utility types for adapter development
+ */
+export type AdapterDisposer = () => void;
+
+export interface AdapterStats {
+  isLoaded: boolean;
+  hasError: boolean;
+  cacheSize?: number;
+  [key: string]: any;
+}