@anymux/ui-kit 0.1.0

package/src/list/models/ListItemsModel.ts

@@ -0,0 +1,1301 @@
+import { makeAutoObservable, observable, flow } from "mobx";
+import {
+  LIST_VIEW_TYPE,
+} from "../providers/ListItemsProvider";
+import type {
+  ListItemsProvider,
+  ListItemsProviderListener,
+  ListViewType,
+} from "../providers/ListItemsProvider";
+import type {
+  ListItemData,
+  ListLoadOptions,
+  ListLoadResult,
+  ListSelectionInfo,
+  ListDragDropInfo
+} from "../types/ListTypes";
+import { benchmark } from "../utils/BenchmarkLogger";
+import { GridLayoutCalculator, createGridCalculator, type GridItemLayout } from "../utils/GridLayoutCalculator";
+import { MasonryLayoutEngine, createVerticalMasonry, createHorizontalMasonry, type MasonryItem, type MasonryItemPosition } from "../utils/MasonryLayoutEngine";
+
+// AICODE-NOTE: List could be in different states: thumbnail, grid, list, details and shuld be possible to define custom states..
+// AICODE-NOTE: It could be used in file explorer like windows explorer or finder but also in other places
+// AICODE-NOTE: Should use virtualized list like react-window
+// AICODE-NOTE: for provider/model design see ../TreeComponent/models/TreeModel.ts
+
+// AICODE-NOTE: Skeleton UI or shimmer for items while loading; graceful error display.
+// AICODE-NOTE: Expose imperative methods (scroll to item, focus item, programmatically select, refresh, etc.).
+// AICODE-NOTE: Support single, multiple, and range selection with shift/control modifiers; expose selected item(s) via API.
+// AICODE-NOTE: Think about Item interface, it should be flexible and support different types of items.
+
+export class ListItemsModel implements ListItemsProviderListener {
+  currentViewType: ListViewType = LIST_VIEW_TYPE;
+  
+  // AICODE-NOTE: Core data using observable collections for reactive updates
+  _allItems: ListItemData[] = [];
+  itemMap = observable.map<string, ListItemData>();
+  totalItemCount: number = 0;
+
+  // Search/filter state
+  searchQuery: string = '';
+  
+  // AICODE-NOTE: Selection state using observable.map for O(1) lookups
+  selectedItems = observable.map<string, ListItemData>();
+  previousSelection: ListItemData[] = [];
+  focusedItem: string | null = null;
+
+  // Range selection anchor - tracks the starting point for shift+click range selection
+  selectionAnchor: string | null = null;
+
+  // AICODE-NOTE: Loading state for different ranges and operations
+  isLoading: boolean = false;
+  loadingRanges = observable.map<string, boolean>();
+  errors = observable.map<string, Error>();
+  
+  // AICODE-NOTE: Virtualization state for handling huge datasets
+  viewportRange: { start: number; end: number } = { start: 0, end: 0 };
+  scrollPosition: number = 0;
+  containerSize: { width: number; height: number } = { width: 0, height: 0 };
+  
+  // AICODE-NOTE: Drag and drop state
+  isDragging: boolean = false;
+  draggedItems: ListItemData[] = [];
+  dragOverItem: string | null = null;
+  dragOverPosition: 'before' | 'after' | 'inside' | null = null;
+  
+  // AICODE-NOTE: View size management state
+  itemSize: 'small' | 'medium' | 'large' | 'extra-large' = 'medium';
+  customItemWidth: number = 200;
+  customItemHeight: number = 220;
+  itemsPerRow: number | 'auto' = 'auto';
+  
+  // AICODE-NOTE: Layout calculators for precise positioning
+  private gridCalculator: GridLayoutCalculator | null = null;
+  private verticalMasonryEngine: MasonryLayoutEngine | null = null;
+  private horizontalMasonryEngine: MasonryLayoutEngine | null = null;
+  
+  // AICODE-NOTE: Debug visualization toggle
+  debugVisualization: boolean = false;
+
+  // Compact mode: details view shows only Icon + Name
+  compactMode: boolean = false;
+
+  // Column visibility for details view (only relevant when compactMode is false)
+  columnVisibility: { type: boolean; modified: boolean; size: boolean } = {
+    type: true,
+    modified: true,
+    size: true
+  };
+
+  // Checkbox mode for multi-select
+  showCheckboxes: boolean = false;
+
+  // Scroll-to-item: views watch this and scroll their container when set
+  scrollToItemId: string | null = null;
+
+  // Pagination state
+  pageSize: number = 50;
+  currentPage: number = 0;
+
+  constructor(public provider: ListItemsProvider) {
+    makeAutoObservable(this, {});
+  }
+
+  // =====================
+  // Computed filtered items
+  // =====================
+
+  get items(): ListItemData[] {
+    if (!this.searchQuery) return this._allItems;
+    const q = this.searchQuery.toLowerCase();
+    return this._allItems.filter(item => item.name.toLowerCase().includes(q));
+  }
+
+  get hasSearchQuery(): boolean {
+    return this.searchQuery.length > 0;
+  }
+
+  get allItemsCount(): number {
+    return this._allItems.length;
+  }
+
+  setSearchQuery(query: string): void {
+    this.searchQuery = query;
+  }
+
+  clearSearch(): void {
+    this.searchQuery = '';
+  }
+
+  clearItems(): void {
+    this._allItems = [];
+  }
+
+  // =====================
+  // ListItemsProviderListener Implementation
+  // =====================
+  
+  onItemsCountChanged(count: number): void {
+    this.totalItemCount = count;
+    // AICODE-NOTE: Notify UI components that the total count has changed
+    // This is useful for virtualization and pagination
+  }
+  
+  onItemChanged(itemIndex: number): void {
+    // AICODE-NOTE: Handle individual item changes for reactive updates
+    // This allows providers to notify of granular changes without full reload
+    if (itemIndex >= 0 && itemIndex < this._allItems.length) {
+      // Trigger re-render for specific item by updating the map
+      const item = this._allItems[itemIndex];
+      if (item) {
+        this.itemMap.set(item.id, { ...item });
+      }
+    }
+  }
+
+  // =====================
+  // Computed Properties
+  // =====================
+  
+  get selectedItemsArray(): ListItemData[] {
+    return Array.from(this.selectedItems.values());
+  }
+  
+  get hasSelection(): boolean {
+    return this.selectedItems.size > 0;
+  }
+  
+  get isItemSelected() {
+    return (itemId: string) => this.selectedItems.has(itemId);
+  }
+  
+  get itemHeight(): number {
+    return this.provider.getItemHeight(this.currentViewType);
+  }
+
+  get isLoaded(): boolean {
+    return !this.isLoading && this._allItems.length > 0;
+  }
+
+  get hasErrors(): boolean {
+    return this.errors.size > 0;
+  }
+
+  // AICODE-NOTE: Performance optimized computed properties
+  get selectedItemIds(): Set<string> {
+    return new Set(this.selectedItems.keys());
+  }
+
+  get visibleItemsCount(): number {
+    const { start, end } = this.viewportRange;
+    return Math.max(0, end - start + 1);
+  }
+
+  get loadedItemsCount(): number {
+    return this._allItems.filter(item => item !== null && item !== undefined).length;
+  }
+
+  get loadingProgress(): number {
+    if (this.totalItemCount === 0) return 0;
+    return Math.min(100, (this.loadedItemsCount / this.totalItemCount) * 100);
+  }
+
+  get isFullyLoaded(): boolean {
+    return this.loadedItemsCount >= this.totalItemCount;
+  }
+
+  get totalPages(): number {
+    if (this.pageSize <= 0 || this.totalItemCount <= 0) return 0;
+    return Math.ceil(this.totalItemCount / this.pageSize);
+  }
+
+  get hasNextPage(): boolean {
+    return this.currentPage < this.totalPages - 1;
+  }
+
+  get hasPreviousPage(): boolean {
+    return this.currentPage > 0;
+  }
+
+  // =====================
+  // Pagination Actions
+  // =====================
+
+  goToPage = flow(function* (this: ListItemsModel, page: number) {
+    if (page < 0 || page >= this.totalPages) return;
+    this.currentPage = page;
+    yield this.loadItems({ limit: this.pageSize, offset: page * this.pageSize });
+  });
+
+  nextPage = flow(function* (this: ListItemsModel) {
+    if (this.hasNextPage) {
+      yield this.goToPage(this.currentPage + 1);
+    }
+  });
+
+  prevPage = flow(function* (this: ListItemsModel) {
+    if (this.hasPreviousPage) {
+      yield this.goToPage(this.currentPage - 1);
+    }
+  });
+
+  setPageSize(size: number): void {
+    if (size > 0) {
+      this.pageSize = size;
+      this.currentPage = 0;
+    }
+  }
+
+  // =====================
+  // Async Actions (using flow for MobX best practices)
+  // =====================
+  
+  /**
+   * Load items from the provider
+   * Uses MobX flow for proper async action handling
+   */
+  loadItems = flow(function* (this: ListItemsModel, options?: ListLoadOptions) {
+    benchmark.start('loadItems', { 
+      itemCount: this.items.length, 
+      viewType: this.currentViewType.id,
+      options 
+    });
+    
+    this.isLoading = true;
+    this.errors.clear();
+    
+    try {
+      benchmark.start('provider.loadItems');
+      const result: ListLoadResult = yield this.provider.loadItems(options);
+      benchmark.end('provider.loadItems', { itemCount: result.items.length });
+      
+      benchmark.start('updateItemsAndMap');
+      // Update items and item map
+      this._allItems = result.items;
+      this.totalItemCount = result.totalCount ?? result.items.length;
+
+      // Update item map for fast lookups
+      this.itemMap.clear();
+      result.items.forEach((item: ListItemData) => this.itemMap.set(item.id, item));
+      benchmark.end('updateItemsAndMap', { itemCount: result.items.length });
+      
+    } catch (error) {
+      const errorKey = 'loadItems';
+      this.errors.set(errorKey, error instanceof Error ? error : new Error(String(error)));
+    } finally {
+      this.isLoading = false;
+      benchmark.end('loadItems', { 
+        finalItemCount: this.items.length,
+        hasErrors: this.errors.size > 0
+      });
+    }
+  });
+
+  /**
+   * Load a specific range of items for virtualization
+   */
+  loadItemRange = flow(function* (this: ListItemsModel, start: number, end: number) {
+    const rangeKey = `${start}-${end}`;
+    this.loadingRanges.set(rangeKey, true);
+    
+    try {
+      const result: ListLoadResult = yield this.provider.loadItemRange?.(start, end) ?? { items: [] };
+      
+      // Merge items into existing array at correct positions
+      result.items.forEach((item, index) => {
+        const absoluteIndex = start + index;
+        this._allItems[absoluteIndex] = item;
+        this.itemMap.set(item.id, item);
+      });
+      
+    } catch (error) {
+      this.errors.set(rangeKey, error instanceof Error ? error : new Error(String(error)));
+    } finally {
+      this.loadingRanges.delete(rangeKey);
+    }
+  });
+
+  /**
+   * Refresh items from provider
+   */
+  refresh = flow(function* (this: ListItemsModel) {
+    if (this.provider.refresh) {
+      this.isLoading = true;
+      this.errors.clear();
+      
+      try {
+        const result: ListLoadResult = yield this.provider.refresh();
+        this._allItems = result.items;
+        this.totalItemCount = result.totalCount ?? result.items.length;
+
+        // Update item map
+        this.itemMap.clear();
+        result.items.forEach((item: ListItemData) => this.itemMap.set(item.id, item));
+        
+      } catch (error) {
+        this.errors.set('refresh', error instanceof Error ? error : new Error(String(error)));
+      } finally {
+        this.isLoading = false;
+      }
+    }
+  });
+
+  // =====================
+  // Selection Actions
+  // =====================
+  
+  /**
+   * Select a single item with proper single/multi-selection logic
+   */
+  selectItem(item: ListItemData, modifiers?: { ctrl?: boolean; shift?: boolean }): void {
+    // Store previous selection for callback
+    this.previousSelection = [...this.selectedItemsArray];
+
+    const wasSelected = this.selectedItems.has(item.id);
+    const isMultiSelectMode = this.provider.isMultiSelectEnabled && modifiers?.ctrl;
+    const isRangeSelectMode = this.provider.isMultiSelectEnabled && modifiers?.shift;
+
+    if (isRangeSelectMode && this.selectionAnchor) {
+      // Shift+click: select range from anchor to clicked item
+      this.selectRange(this.selectionAnchor, item.id);
+    } else if (isMultiSelectMode) {
+      // Ctrl+click: toggle individual item
+      if (wasSelected) {
+        this.selectedItems.delete(item.id);
+      } else {
+        this.selectedItems.set(item.id, item);
+      }
+      // Update anchor to current item for future range selections
+      this.selectionAnchor = item.id;
+    } else {
+      // Plain click: single selection
+      this.selectedItems.clear();
+      this.selectedItems.set(item.id, item);
+      // Set anchor for future shift+click range selections
+      this.selectionAnchor = item.id;
+    }
+
+    // Always update focused item when clicking
+    this.focusedItem = item.id;
+
+    // Notify provider of selection change
+    if (this.provider.onSelectionChange) {
+      this.provider.onSelectionChange({
+        selectedItems: this.selectedItemsArray,
+        previousSelection: this.previousSelection,
+        selectionType: isRangeSelectMode ? 'range' : (isMultiSelectMode ? 'multi' : 'single'),
+        trigger: 'click'
+      });
+    }
+  }
+
+  /**
+   * Select a contiguous range of items between two item IDs
+   */
+  selectRange(fromId: string, toId: string): void {
+    const fromIndex = this.items.findIndex(item => item.id === fromId);
+    const toIndex = this.items.findIndex(item => item.id === toId);
+
+    if (fromIndex === -1 || toIndex === -1) return;
+
+    const start = Math.min(fromIndex, toIndex);
+    const end = Math.max(fromIndex, toIndex);
+
+    this.selectedItems.clear();
+    for (let i = start; i <= end; i++) {
+      const item = this.items[i];
+      if (item) {
+        this.selectedItems.set(item.id, item);
+      }
+    }
+  }
+
+  /**
+   * Clear all selection
+   */
+  clearSelection(): void {
+    const hadSelection = this.selectedItems.size > 0;
+    if (!hadSelection) return;
+    
+    // Store previous selection for callback
+    this.previousSelection = [...this.selectedItemsArray];
+    this.selectedItems.clear();
+    
+    if (this.provider.onSelectionChange) {
+      this.provider.onSelectionChange({
+        selectedItems: [],
+        previousSelection: this.previousSelection,
+        selectionType: this.provider.isMultiSelectEnabled ? 'multi' : 'single',
+        trigger: 'api'
+      });
+    }
+  }
+
+  /**
+   * Select all items (if multi-select enabled)
+   */
+  selectAll(): void {
+    if (!this.provider.isMultiSelectEnabled) return;
+    
+    this.selectedItems.clear();
+    this.items.forEach(item => {
+      this.selectedItems.set(item.id, item);
+    });
+    
+    if (this.provider.onSelectionChange) {
+      this.provider.onSelectionChange({
+        selectedItems: this.selectedItemsArray,
+        previousSelection: [],
+        selectionType: 'multi',
+        trigger: 'api'
+      });
+    }
+  }
+
+  // =====================
+  // View Type Management
+  // =====================
+  
+  /**
+   * Set the current view type
+   */
+  setViewType(viewType: ListViewType): void {
+    console.log('ListItemsModel.setViewType called:', {
+      from: this.currentViewType.id,
+      to: viewType.id,
+      same: this.currentViewType.id === viewType.id
+    });
+    
+    if (this.currentViewType.id !== viewType.id) {
+      this.currentViewType = viewType;
+      console.log('View type changed to:', this.currentViewType.id);
+      
+      // Notify provider
+      if (this.provider.onViewTypeChange) {
+        this.provider.onViewTypeChange(viewType);
+      }
+    } else {
+      console.log('View type not changed - same as current');
+    }
+  }
+
+  // =====================
+  // Size Management
+  // =====================
+  
+  /**
+   * Set item size for grid and masonry views
+   */
+  setItemSize(size: 'small' | 'medium' | 'large' | 'extra-large'): void {
+    this.itemSize = size;
+    
+    // Update custom dimensions based on size
+    const sizeMap = {
+      'small': { width: 160, height: 120 },
+      'medium': { width: 240, height: 180 },
+      'large': { width: 320, height: 240 },
+      'extra-large': { width: 400, height: 300 }
+    };
+    
+    const dimensions = sizeMap[size];
+    this.customItemWidth = dimensions.width;
+    this.customItemHeight = dimensions.height;
+    
+    // Update calculators with new dimensions
+    this.updateLayoutCalculators();
+  }
+  
+  /**
+   * Set custom item width and update calculators
+   */
+  setCustomItemWidth(width: number): void {
+    this.customItemWidth = Math.max(120, Math.min(600, width));
+    this.updateLayoutCalculators();
+  }
+  
+  /**
+   * Set custom item height and update calculators
+   */
+  setCustomItemHeight(height: number): void {
+    this.customItemHeight = Math.max(80, Math.min(500, height));
+    this.updateLayoutCalculators();
+  }
+  
+  /**
+   * Get current item dimensions
+   */
+  get itemDimensions(): { width: number; height: number } {
+    return {
+      width: this.customItemWidth,
+      height: this.customItemHeight
+    };
+  }
+  
+  /**
+   * Set items per row for grid and masonry views
+   */
+  setItemsPerRow(itemsPerRow: number | 'auto'): void {
+    this.itemsPerRow = itemsPerRow;
+    this.updateLayoutCalculators();
+  }
+  
+  /**
+   * Set debug visualization mode
+   */
+  setDebugVisualization(enabled: boolean): void {
+    this.debugVisualization = enabled;
+  }
+
+  setCompactMode(compact: boolean): void {
+    this.compactMode = compact;
+  }
+
+  toggleCheckboxes(): void {
+    this.showCheckboxes = !this.showCheckboxes;
+  }
+
+  setShowCheckboxes(show: boolean): void {
+    this.showCheckboxes = show;
+  }
+
+  setColumnVisibility(column: 'type' | 'modified' | 'size', visible: boolean): void {
+    this.columnVisibility = { ...this.columnVisibility, [column]: visible };
+  }
+
+  get detailsGridTemplateColumns(): string {
+    const cols: string[] = [];
+    if (this.showCheckboxes) cols.push('20px');
+    cols.push('24px', 'minmax(0, 1fr)');
+    if (!this.compactMode) {
+      if (this.columnVisibility.type) cols.push('100px');
+      if (this.columnVisibility.modified) cols.push('140px');
+      if (this.columnVisibility.size) cols.push('90px');
+    }
+    return cols.join(' ');
+  }
+
+  /**
+   * Generate random aspect ratio for Pinterest-like variety
+   */
+  /**
+   * Deterministic aspect ratio based on item id (stable across re-renders).
+   * Uses a simple hash to pick from predefined ratios.
+   */
+  private generateDeterministicAspectRatio(id: string): number {
+    const ratios = [0.6, 0.7, 0.8, 1.0, 1.2, 1.4, 1.6];
+    let hash = 0;
+    for (let i = 0; i < id.length; i++) {
+      hash = ((hash << 5) - hash + id.charCodeAt(i)) | 0;
+    }
+    const index = Math.abs(hash) % ratios.length;
+    return ratios[index] ?? 1.0;
+  }
+  
+  /**
+   * Get effective items per row based on view and container width
+   */
+  getEffectiveItemsPerRow(containerWidth?: number): number {
+    if (typeof this.itemsPerRow === 'number') {
+      return this.itemsPerRow;
+    }
+    
+    // Auto calculation based on container width and item width
+    if (containerWidth) {
+      const itemWidth = this.customItemWidth;
+      const gap = 12; // Default gap
+      const availableWidth = containerWidth - (gap * 2);
+      const itemsWithGaps = Math.floor((availableWidth + gap) / (itemWidth + gap));
+      return Math.max(1, Math.min(8, itemsWithGaps));
+    }
+    
+    return 4; // Default fallback
+  }
+
+  // =====================
+  // Focus Management
+  // =====================
+
+  /**
+   * Set focused item
+   */
+  setFocusedItem(itemId: string | null): void {
+    this.focusedItem = itemId;
+  }
+
+  /**
+   * Focus next item
+   */
+  focusNext(): boolean {
+    if (this.items.length === 0) return false;
+
+    const currentIndex = this.focusedItem
+      ? this.items.findIndex(item => item.id === this.focusedItem)
+      : -1;
+
+    const nextIndex = currentIndex < this.items.length - 1 ? currentIndex + 1 : 0;
+    const nextItem = this.items[nextIndex];
+    if (nextItem) {
+      this.focusedItem = nextItem.id;
+    }
+    return true;
+  }
+
+  /**
+   * Focus previous item
+   */
+  focusPrevious(): boolean {
+    if (this.items.length === 0) return false;
+
+    const currentIndex = this.focusedItem
+      ? this.items.findIndex(item => item.id === this.focusedItem)
+      : 0;
+
+    const prevIndex = currentIndex > 0 ? currentIndex - 1 : this.items.length - 1;
+    const prevItem = this.items[prevIndex];
+    if (prevItem) {
+      this.focusedItem = prevItem.id;
+    }
+    return true;
+  }
+
+  /**
+   * Focus the first item in the list
+   */
+  focusFirst(): boolean {
+    if (this.items.length === 0) return false;
+    const firstItem = this.items[0];
+    if (firstItem) {
+      this.focusedItem = firstItem.id;
+      this.ensureItemVisible(firstItem.id);
+    }
+    return true;
+  }
+
+  /**
+   * Focus the last item in the list
+   */
+  focusLast(): boolean {
+    if (this.items.length === 0) return false;
+    const lastItem = this.items[this.items.length - 1];
+    if (lastItem) {
+      this.focusedItem = lastItem.id;
+      this.ensureItemVisible(lastItem.id);
+    }
+    return true;
+  }
+
+  // =====================
+  // Keyboard Navigation
+  // =====================
+
+  /**
+   * Handle keyboard events for list navigation.
+   * Can be used directly via onKeyDown on a container element,
+   * or the useListKeyboard hook can be used for automatic attachment.
+   *
+   * - ArrowUp/ArrowDown: navigate between items
+   * - Home/End: jump to first/last item
+   * - Enter: open focused item (navigate into folder or open file)
+   * - Space: toggle selection of focused item
+   * - Escape: clear selection, or navigate up one directory level if nothing selected
+   * - Ctrl+A: select all items
+   */
+  handleKeyDown(event: KeyboardEvent): void {
+    // Skip when an input/textarea is focused (e.g. inline rename)
+    const tag = (event.target as HTMLElement)?.tagName;
+    if (tag === 'INPUT' || tag === 'TEXTAREA') return;
+
+    if (this.items.length === 0) return;
+
+    const { key, ctrlKey, metaKey, shiftKey } = event;
+    const isModifier = ctrlKey || metaKey;
+
+    switch (key) {
+      case 'ArrowUp': {
+        event.preventDefault();
+        const idx = this.getFocusedIndex();
+        if (idx > 0) {
+          this.navigateToIndex(idx - 1, shiftKey);
+        }
+        break;
+      }
+      case 'ArrowDown': {
+        event.preventDefault();
+        const idx = this.getFocusedIndex();
+        if (idx < this.items.length - 1) {
+          this.navigateToIndex(idx + 1, shiftKey);
+        }
+        break;
+      }
+      case 'Home': {
+        event.preventDefault();
+        this.navigateToIndex(0, shiftKey);
+        break;
+      }
+      case 'End': {
+        event.preventDefault();
+        this.navigateToIndex(this.items.length - 1, shiftKey);
+        break;
+      }
+      case 'Enter': {
+        event.preventDefault();
+        const item = this.focusedItem ? this.getItem(this.focusedItem) : this.items[0];
+        if (item && this.provider.onItemDoubleClick) {
+          this.provider.onItemDoubleClick(item);
+        }
+        break;
+      }
+      case ' ': {
+        event.preventDefault();
+        const item = this.focusedItem ? this.getItem(this.focusedItem) : this.items[0];
+        if (item) {
+          this.selectItem(item, { ctrl: true, shift: shiftKey });
+        }
+        break;
+      }
+      case 'Escape': {
+        event.preventDefault();
+        if (this.hasSelection) {
+          this.clearSelection();
+        } else if (this.provider.onNavigateUp) {
+          this.provider.onNavigateUp();
+        }
+        break;
+      }
+      case 'a':
+      case 'A': {
+        if (isModifier) {
+          event.preventDefault();
+          this.selectAll();
+        }
+        break;
+      }
+    }
+  }
+
+  /**
+   * Get the index of the currently focused item, defaulting to 0
+   */
+  private getFocusedIndex(): number {
+    if (!this.focusedItem) return 0;
+    const idx = this.items.findIndex(item => item.id === this.focusedItem);
+    return idx === -1 ? 0 : idx;
+  }
+
+  /**
+   * Navigate to a specific item index, updating focus, selection, and scroll
+   */
+  private navigateToIndex(index: number, extendSelection: boolean = false): void {
+    const item = this.items[index];
+    if (!item) return;
+
+    this.focusedItem = item.id;
+
+    if (extendSelection && this.provider.isMultiSelectEnabled) {
+      if (!this.selectionAnchor) {
+        this.selectionAnchor = this.focusedItem || item.id;
+      }
+      this.selectRange(this.selectionAnchor, item.id);
+    } else {
+      this.selectItem(item);
+    }
+
+    this.ensureItemVisible(item.id);
+  }
+
+  // =====================
+  // Drag and Drop Management
+  // =====================
+  
+  /**
+   * Check if an item can be dragged
+   */
+  canDragItem(item: ListItemData): boolean {
+    if (!this.provider.isDragDropEnabled) return false;
+    return this.provider.canDragItem?.(item) ?? true;
+  }
+  
+  /**
+   * Check if items can be dropped on a target
+   */
+  canDropItems(draggedItems: ListItemData[], targetItem: ListItemData | null, position: 'before' | 'after' | 'inside'): boolean {
+    if (!this.provider.isDragDropEnabled) return false;
+    return this.provider.canDropItems?.(draggedItems, targetItem, position) ?? true;
+  }
+  
+  /**
+   * Start drag operation
+   */
+  startDrag(items: ListItemData[], event: DragEvent): void {
+    if (!this.provider.isDragDropEnabled) return;
+    
+    this.isDragging = true;
+    this.draggedItems = items;
+    
+    // AICODE-NOTE: Set drag data for HTML5 drag and drop
+    const itemIds = items.map(item => item.id);
+    event.dataTransfer?.setData('application/json', JSON.stringify({
+      type: 'list-items',
+      itemIds
+    }));
+    
+    // AICODE-NOTE: Set drag effect
+    if (event.dataTransfer) {
+      event.dataTransfer.effectAllowed = 'move';
+    }
+    
+    // Notify provider
+    if (this.provider.onDragStart) {
+      this.provider.onDragStart(items, event);
+    }
+  }
+  
+  /**
+   * Handle drag over item
+   */
+  setDragOver(itemId: string | null, position: 'before' | 'after' | 'inside' | null): void {
+    this.dragOverItem = itemId;
+    this.dragOverPosition = position;
+  }
+  
+  /**
+   * Handle drop operation
+   */
+  handleDrop(targetItem: ListItemData | null, position: 'before' | 'after' | 'inside', event: DragEvent): boolean {
+    if (!this.isDragging || this.draggedItems.length === 0) return false;
+    
+    // AICODE-NOTE: Check if drop is allowed
+    if (!this.canDropItems(this.draggedItems, targetItem, position)) {
+      this.endDrag(false);
+      return false;
+    }
+    
+    // AICODE-NOTE: Create drag drop info
+    const dragDropInfo: ListDragDropInfo = {
+      draggedItems: this.draggedItems,
+      targetItem,
+      position,
+      event
+    };
+    
+    // Notify provider
+    if (this.provider.onDrop) {
+      this.provider.onDrop(dragDropInfo);
+    }
+    
+    this.endDrag(true);
+    return true;
+  }
+  
+  /**
+   * End drag operation
+   */
+  endDrag(success: boolean): void {
+    const draggedItems = [...this.draggedItems];
+    
+    this.isDragging = false;
+    this.draggedItems = [];
+    this.dragOverItem = null;
+    this.dragOverPosition = null;
+    
+    // Notify provider
+    if (this.provider.onDragEnd) {
+      this.provider.onDragEnd(draggedItems, success);
+    }
+  }
+
+  // =====================
+  // Virtualization Support
+  // =====================
+  
+  /**
+   * Update viewport range for virtualization and trigger dynamic loading
+   */
+  updateViewportRange(start: number, end: number): void {
+    this.viewportRange = { start, end };
+    
+    // AICODE-NOTE: Trigger dynamic loading for visible range
+    this.loadVisibleItems(start, end);
+  }
+
+  /**
+   * Load items that are visible in the current viewport
+   */
+  private loadVisibleItems = flow(function* (this: ListItemsModel, start: number, end: number) {
+    // AICODE-NOTE: Check if provider supports range loading
+    if (!this.provider.loadItemRange) {
+      return;
+    }
+
+    // AICODE-NOTE: Expand range to include overscan for smoother scrolling
+    const overscan = 10;
+    const expandedStart = Math.max(0, start - overscan);
+    const expandedEnd = Math.min(this.totalItemCount, end + overscan);
+
+    // AICODE-NOTE: Check which items in the range are missing
+    const missingRanges: Array<{ start: number; end: number }> = [];
+    let rangeStart = -1;
+
+    for (let i = expandedStart; i <= expandedEnd; i++) {
+      const hasItem = i < this._allItems.length && this._allItems[i] !== undefined;
+      
+      if (!hasItem) {
+        if (rangeStart === -1) {
+          rangeStart = i;
+        }
+      } else {
+        if (rangeStart !== -1) {
+          missingRanges.push({ start: rangeStart, end: i - 1 });
+          rangeStart = -1;
+        }
+      }
+    }
+
+    // AICODE-NOTE: Add final range if it extends to the end
+    if (rangeStart !== -1) {
+      missingRanges.push({ start: rangeStart, end: expandedEnd });
+    }
+
+    // AICODE-NOTE: Load missing ranges
+    for (const range of missingRanges) {
+      // AICODE-NOTE: Skip if already loading this range
+      const rangeKey = `${range.start}-${range.end}`;
+      if (this.loadingRanges.has(rangeKey)) {
+        continue;
+      }
+
+      try {
+        yield this.loadItemRange(range.start, range.end + 1);
+      } catch (error) {
+        console.warn('Failed to load item range:', range, error);
+      }
+    }
+  });
+
+  /**
+   * Update scroll position
+   */
+  updateScrollPosition(position: number): void {
+    this.scrollPosition = position;
+  }
+
+  /**
+   * Update container size
+   */
+  updateContainerSize(width: number, height: number): void {
+    this.containerSize = { width, height };
+    
+    // Update calculators with new container size
+    this.updateLayoutCalculators();
+  }
+
+  // AICODE-NOTE: Layout calculator management
+  
+  /**
+   * Update layout calculators with current settings
+   */
+  private updateLayoutCalculators(): void {
+    const { width, height } = this.containerSize;
+    
+
+    
+    if (width > 0 && height > 0) {
+      // Update grid calculator with very flexible constraints for better auto-calculation
+      // AICODE-NOTE: Prioritize fitting multiple items over exact size matching
+      const minWidth = 120; // Absolute minimum for readability
+      const maxWidth = width * 0.95; // Allow up to 95% of container width
+      
+      // console.log('📐 [MODEL] Grid constraints:', {
+      //   container: `${width}x${height}`,
+      //   minWidth,
+      //   maxWidth,
+      //   customItemWidth: this.customItemWidth,
+      //   itemsPerRow: this.itemsPerRow
+      // });
+      
+      if (this.gridCalculator) {
+        this.gridCalculator.updateConfig({
+          containerWidth: width,
+          containerHeight: height,
+          itemsPerRow: this.itemsPerRow,
+          minItemWidth: minWidth,
+          maxItemWidth: maxWidth,
+          aspectRatio: this.customItemWidth / this.customItemHeight
+        });
+      } else {
+        this.gridCalculator = createGridCalculator(width, height, {
+          itemsPerRow: this.itemsPerRow,
+          minItemWidth: minWidth,
+          maxItemWidth: maxWidth,
+          aspectRatio: this.customItemWidth / this.customItemHeight
+        });
+      }
+      
+      // Update masonry engines with tight spacing for compact layout
+      const gutter = 4; // Tight spacing for dense masonry layout
+
+      // Calculate optimal column width for masonry layout
+      const targetColumns = this.itemsPerRow === 'auto' ?
+        Math.floor(width / 250) || 3 : // Default to ~250px columns
+        (typeof this.itemsPerRow === 'number' ? this.itemsPerRow : 3);
+      
+      const availableWidth = width - (gutter * (targetColumns + 1));
+      const columnWidth = Math.floor(availableWidth / targetColumns);
+      
+      if (this.verticalMasonryEngine) {
+        this.verticalMasonryEngine.updateConfig({
+          containerWidth: width,
+          columnWidth,
+          gutter,
+          horizontalOrder: false
+        });
+      } else {
+        this.verticalMasonryEngine = createVerticalMasonry(width, columnWidth, gutter);
+      }
+      
+      if (this.horizontalMasonryEngine) {
+        this.horizontalMasonryEngine.updateConfig({
+          containerWidth: width,
+          columnWidth,
+          gutter,
+          horizontalOrder: true
+        });
+      } else {
+        this.horizontalMasonryEngine = createHorizontalMasonry(width, columnWidth, gutter);
+      }
+    }
+  }
+
+  /**
+   * Get grid layout for current items
+   */
+  getGridLayout(): { layout: GridItemLayout[]; totalHeight: number } | null {
+    // Don't call updateLayoutCalculators() here — it modifies observables and
+    // would violate MobX strict mode when called during render.
+    
+    if (this.gridCalculator) {
+      const result = this.gridCalculator.calculateLayout(this.items.length);
+      return {
+        layout: result.items,
+        totalHeight: result.totalHeight
+      };
+    }
+    
+    return null;
+  }
+
+  /**
+   * Check whether an item is an actual image that should get variable height
+   * in masonry layout. Non-image items (folders, docs, code files) get uniform height.
+   */
+  private isImageItem(item: ListItemData): boolean {
+    // Has an explicit aspect ratio set on the item data
+    if (item.aspectRatio) return true;
+    // Has a thumbnail URL (provider-supplied image)
+    if (item.thumbnailUrl) return true;
+    // Has an image URL
+    if (item.imageUrl) return true;
+    // Provider reports a measured aspect ratio for this path
+    if (this.provider.getAspectRatio?.(item.path) !== undefined) return true;
+    return false;
+  }
+
+  /**
+   * Get vertical masonry layout for current items
+   */
+  getVerticalMasonryLayout(): { layout: MasonryItemPosition[]; totalHeight: number } | null {
+    // Don't call updateLayoutCalculators() here — it modifies observables and
+    // would violate MobX strict mode when called during render. The engine is
+    // created by updateContainerSize() which runs in useEffect.
+
+    if (this.verticalMasonryEngine) {
+      // Convert items to masonry data.
+      // Only images get variable height based on aspect ratio.
+      // Non-image items (folders, documents, etc.) get a uniform fixed height.
+      const columnWidth = this.verticalMasonryEngine?.columnWidth || 250;
+      const fixedNonImageHeight = Math.round(columnWidth * 0.75); // 4:3 aspect for uniform tiles
+
+      const masonryItems: MasonryItem[] = this.items.map(item => {
+        const width = columnWidth;
+
+        if (this.isImageItem(item)) {
+          const aspectRatio = item.aspectRatio
+            || this.provider.getAspectRatio?.(item.path)
+            || this.generateDeterministicAspectRatio(item.id);
+          const height = Math.round(width / aspectRatio);
+          return { id: item.id, width, height, aspectRatio };
+        }
+
+        // Non-image: fixed uniform height
+        return { id: item.id, width, height: fixedNonImageHeight };
+      });
+
+      const result = this.verticalMasonryEngine.calculateLayout(masonryItems);
+      return {
+        layout: result.items,
+        totalHeight: result.totalHeight
+      };
+    }
+
+    return null;
+  }
+
+  /**
+   * Get horizontal masonry layout for current items
+   */
+  getHorizontalMasonryLayout(): { layout: MasonryItemPosition[]; totalHeight: number } | null {
+    // Don't call updateLayoutCalculators() here — same reason as vertical.
+
+    if (this.horizontalMasonryEngine) {
+      // Convert items to masonry data.
+      // Only images get variable height; non-image items get uniform height.
+      const columnWidth = this.horizontalMasonryEngine?.columnWidth || 250;
+      const fixedNonImageHeight = Math.round(columnWidth * 0.75); // 4:3 aspect for uniform tiles
+
+      const masonryItems: MasonryItem[] = this.items.map(item => {
+        const width = columnWidth;
+
+        if (this.isImageItem(item)) {
+          const aspectRatio = item.aspectRatio
+            || this.provider.getAspectRatio?.(item.path)
+            || this.generateDeterministicAspectRatio(item.id);
+          const height = Math.round(width / aspectRatio);
+          return { id: item.id, width, height, aspectRatio };
+        }
+
+        // Non-image: fixed uniform height
+        return { id: item.id, width, height: fixedNonImageHeight };
+      });
+
+      const result = this.horizontalMasonryEngine.calculateLayout(masonryItems);
+      return {
+        layout: result.items,
+        totalHeight: result.totalHeight
+      };
+    }
+
+    return null;
+  }
+
+  /**
+   * Get visible items for virtualization
+   */
+  getVisibleGridItems(scrollTop: number, viewportHeight: number): GridItemLayout[] {
+    if (!this.gridCalculator) return [];
+    
+    const result = this.gridCalculator.calculateVisibleItems(
+      this.items.length,
+      scrollTop,
+      viewportHeight
+    );
+    
+    return result.visibleItems;
+  }
+
+  /**
+   * Get visible vertical masonry items for virtualization
+   */
+  getVisibleVerticalMasonryItems(scrollTop: number, viewportHeight: number): MasonryItemPosition[] {
+    const layout = this.getVerticalMasonryLayout();
+    if (!layout) return [];
+    
+    // Filter items that are visible in the viewport
+    return layout.layout.filter(item => {
+      const itemTop = item.y;
+      const itemBottom = item.y + item.height;
+      const viewportTop = scrollTop;
+      const viewportBottom = scrollTop + viewportHeight;
+      
+      return itemBottom >= viewportTop && itemTop <= viewportBottom;
+    });
+  }
+
+  /**
+   * Get visible horizontal masonry items for virtualization
+   */
+  getVisibleHorizontalMasonryItems(scrollTop: number, viewportHeight: number): MasonryItemPosition[] {
+    const layout = this.getHorizontalMasonryLayout();
+    if (!layout) return [];
+    
+    // Filter items that are visible in the viewport
+    return layout.layout.filter(item => {
+      const itemTop = item.y;
+      const itemBottom = item.y + item.height;
+      const viewportTop = scrollTop;
+      const viewportBottom = scrollTop + viewportHeight;
+      
+      return itemBottom >= viewportTop && itemTop <= viewportBottom;
+    });
+  }
+
+  /**
+   * Get visible masonry items for virtualization (unified method)
+   */
+  getVisibleMasonryItems(scrollTop: number, viewportHeight: number, isHorizontal: boolean = false, overscan: number = 100): MasonryItemPosition[] {
+    const layout = isHorizontal ? this.getHorizontalMasonryLayout() : this.getVerticalMasonryLayout();
+    if (!layout) return [];
+    
+    // Add overscan to viewport for smoother scrolling
+    const viewportTop = scrollTop - overscan;
+    const viewportBottom = scrollTop + viewportHeight + overscan;
+    
+    // Filter items that intersect with the extended viewport
+    return layout.layout.filter(item => {
+      const itemTop = item.y;
+      const itemBottom = item.y + item.height;
+      
+      return itemBottom >= viewportTop && itemTop <= viewportBottom;
+    });
+  }
+
+  // =====================
+  // Imperative Methods
+  // =====================
+  
+  /**
+   * Ensure item is visible (scroll to item)
+   */
+  ensureItemVisible(itemId: string): boolean {
+    const index = this.items.findIndex(item => item.id === itemId);
+    if (index === -1) return false;
+
+    this.scrollToItemId = itemId;
+    return true;
+  }
+
+  clearScrollToItem(): void {
+    this.scrollToItemId = null;
+  }
+
+  /**
+   * Get item by ID
+   */
+  getItem(itemId: string): ListItemData | undefined {
+    return this.itemMap.get(itemId);
+  }
+
+  /**
+   * Get item index
+   */
+  getItemIndex(itemId: string): number {
+    return this.items.findIndex(item => item.id === itemId);
+  }
+
+  /**
+   * Resolve thumbnail URL for an item via provider cache.
+   * Returns blob URL when ready, undefined while loading.
+   * MobX observer components re-render when the URL becomes available.
+   */
+  resolveThumbnailUrl(item: ListItemData): string | undefined {
+    return this.provider.resolveThumbnailUrl?.(item);
+  }
+
+  // AICODE-NOTE: Should have functionality like ensure visible etc.
+  // AICODE-NOTE: Should have support for selection, focus, etc.
+  // AICODE-NOTE: Use similar approach as in TreeComponent for context menu, icons, multi-select, etc.
+  // AICODE-NOTE: Should support custom item drawing
+  // AICODE-NOTE: Should have ellipsis for long text
+
+  // AICODE-NOTE: Should have different sizes for thumbnail(grid) view
+  // AICODE-NOTE: thumbnail should be from N per line until 1 per line
+}