@anymux/ui-kit 0.1.0

package/src/list/architecture.md

@@ -0,0 +1,807 @@
+# ListItemsComponent Architecture
+
+## Overview
+
+The ListItemsComponent is a high-performance, virtualized list component built with React, MobX, and TypeScript. It provides a flexible, accessible, and extensible list interface that can work with any data source through the Provider pattern. The component supports multiple view types (list, grid, details, thumbnails) and can handle massive datasets through virtualization. The provider can work with or without React, supporting both web and non-web environments.
+
+**🎯 Primary Use Cases**: File explorers (Windows Explorer, macOS Finder), media galleries, data tables, search results, any large dataset display requiring multiple view modes.
+
+## Design Principles
+
+- **Provider-Driven Architecture**: ListItemsProvider model drives ALL behavior (selection, rendering, virtualization, view types)
+- **Direct Provider Injection**: No registry pattern - provider passed directly to ListItems 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, view types configured in provider
+- **Callback-Based**: ListItems component calls provider callbacks for all interactions
+- **Item-Level Customization**: Per-item 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**: Mandatory virtualization support for huge datasets (react-window/react-virtualized)
+- **Type Safety**: Comprehensive TypeScript coverage
+- **Responsive Design**: Grid layouts adapt to container width, thumbnail sizes configurable
+
+## MobX Best Practices (CRITICAL)
+
+**⚠️ STRICT REQUIREMENTS - These patterns must be followed exactly:**
+
+### 1. No Decorators - Use makeAutoObservable
+```typescript
+// ❌ NEVER use decorators
+class ListItemsModel {
+  @observable items = []
+  @action selectItem() {}
+}
+
+// ✅ ALWAYS use makeAutoObservable
+class ListItemsModel {
+  items = []
+  
+  constructor() {
+    makeAutoObservable(this, {}); // Empty overrides object
+  }
+  
+  selectItem() {} // Automatically becomes action
+}
+```
+
+### 2. Observable Collections - Use observable.map()
+```typescript
+// ❌ NEVER use plain Map/Set
+selectedItems = new Map<string, ListItemData>()
+itemStates = new Set<string>()
+
+// ✅ ALWAYS use observable.map()
+selectedItems = observable.map<string, ListItemData>()
+itemStates = observable.map<string, ItemState>()
+```
+
+### 3. Async Actions - Use flow
+```typescript
+// ❌ NEVER use async/await directly in actions
+async loadItems() {
+  this.isLoading = true;
+  const result = await api.loadItems();
+  this.items = result; // ⚠️ Not in action!
+}
+
+// ✅ ALWAYS use flow for async operations
+loadItems = flow(function* (this: ListItemsModel) {
+  this.isLoading = true;
+  const result = yield api.loadItems();
+  this.items = result; // ✅ Automatically in action
+});
+```
+
+### 4. Composition Over Inheritance
+```typescript
+// ❌ NEVER use inheritance (MobX issues)
+class BaseModel {}
+class ListItemsModel extends BaseModel {}
+
+// ✅ ALWAYS use composition
+class ListItemsModel {
+  selectionManager: ListSelectionModel;
+  viewManager: ViewTypeManager;
+  virtualizationManager: VirtualizationModel;
+  
+  constructor() {
+    makeAutoObservable(this, {});
+    this.selectionManager = new ListSelectionModel(this);
+    this.viewManager = new ViewTypeManager(this);
+    this.virtualizationManager = new VirtualizationModel(this);
+  }
+}
+```
+
+### 5. Observer Components for Lists
+```typescript
+// ❌ NEVER render observables directly in map
+const ItemList = observer(() => (
+  <div>
+    {items.map(item => <div key={item.id}>{item.name}</div>)} {/* Won't react! */}
+  </div>
+))
+
+// ✅ ALWAYS extract to separate observer components
+const ListItem = observer(({ item }) => <div>{item.name}</div>)
+
+const ItemList = observer(() => (
+  <div>
+    {items.map(item => <ListItem key={item.id} item={item} />)}
+  </div>
+))
+```
+
+### 6. Icon Handling Pattern (CRITICAL)
+```typescript
+// AICODE-NOTE: Icon handling pattern to avoid React component rendering bugs
+
+// ❌ NEVER try to render React components directly from string props
+{menuItem.icon && <menuItem.icon className="w-4 h-4" />} // JSX element type error!
+
+// ✅ ALWAYS check type and handle appropriately
+{menuItem.icon && (
+  <span className="w-4 h-4 flex-shrink-0 flex items-center justify-center">
+    {typeof menuItem.icon === 'string' ? (
+      <span className="text-sm">{getIconEmoji(menuItem.icon)}</span>
+    ) : (
+      React.createElement(menuItem.icon, { className: 'w-4 h-4' })
+    )}
+  </span>
+)}
+
+// ✅ Provider pattern: Return string identifiers, map to emojis/components in UI
+const getIconEmoji = (iconName: string): string => {
+  const iconMap: Record<string, string> = {
+    'eye': '👁️', 'edit': '✏️', 'trash': '🗑️', 'folder-open': '📂',
+    'copy': '📋', 'scissors': '✂️', 'archive': '📦'
+  };
+  return iconMap[iconName] || iconName;
+};
+
+// ✅ For complex icons, use React.createElement instead of JSX
+React.createElement(IconComponent, { className: 'w-4 h-4' })
+```
+
+## Architecture Overview
+
+```
+ListItemsComponent
+    ↓ receives
+ListItemsProvider (MobX Model)
+    ↓ provides data & callbacks
+ListItemsModel (MobX State)
+    ↓ manages
+ListItems Components (React UI + Virtualization)
+```
+
+## Core Components
+
+### 1. ListItemsProvider (Model Layer)
+**Location**: `/providers/ListItemsProvider.ts`
+
+**Purpose**: Defines the contract for data loading, item rendering, view types, and interaction callbacks. Works independently of React.
+
+**Key Features**:
+- Data loading methods (`loadItems`, `loadRange`, `refresh`, `search`)
+- View type management (`getSupportedViewTypes`, `getViewTypeConfig`)
+- Per-item context menus (`getItemContextMenu`, `getMultiItemContextMenu`)
+- Item rendering overrides (`getItemRenderer`, `getDefaultRenderer`)
+- Capability checks (`canSelect`, `canDrag`, `canDrop`, `canEdit`)
+- Event callbacks (`onSelectionChange`, `onDragDrop`, `onContextMenuAction`, `onViewTypeChange`)
+- Non-React item rendering (`ListItemRenderer.renderText`, `renderIcon`, `renderThumbnail`)
+- Virtualization configuration (`getVirtualizationConfig`, `getItemHeight`)
+
+### 2. ListItemsModel (State Layer)
+**Location**: `/models/ListItemsModel.ts`
+
+**Purpose**: MobX observable state container that manages list data, selection, view types, and UI state.
+
+**State Management**:
+```typescript
+class ListItemsModel {
+  // Core Data - using observable collections
+  items: ListItemData[] = []
+  itemMap = observable.map<string, ListItemData>()
+  totalItemCount: number = 0
+  
+  // View State
+  currentViewType: ListViewType = LIST_VIEW_TYPE
+  availableViewTypes: ListViewType[] = []
+  gridColumnsCount: number = 4
+  thumbnailSize: ThumbnailSize = 'medium'
+  
+  // UI State - using observable.map instead of Set/Map
+  selectedItems = observable.map<string, ListItemData>()
+  focusedItem: string | null = null
+  hoveredItem: string | null = null
+  
+  // Loading State
+  isLoading: boolean = false
+  loadingRanges = observable.map<string, boolean>()
+  errors = observable.map<string, Error>()
+  
+  // Virtualization State
+  viewportRange: { start: number; end: number } = { start: 0, end: 0 }
+  scrollPosition: number = 0
+  containerSize: { width: number; height: number } = { width: 0, height: 0 }
+  
+  // Interaction State
+  draggedItems: ListItemData[] = []
+  dropTarget: ListItemData | null = null
+  contextMenuItem: ListItemData | null = null
+  isEditing: string | null = null
+  
+  constructor(public provider: ListItemsProvider) {
+    makeAutoObservable(this, {});
+  }
+  
+  // Computed properties for derived state
+  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 gridItemsPerRow(): number {
+    if (this.currentViewType.id !== 'grid') return 1;
+    const itemWidth = this.provider.getItemWidth?.(this.currentViewType) ?? 200;
+    return Math.floor(this.containerSize.width / itemWidth);
+  }
+  
+  // Async actions using flow
+  loadItems = flow(function* (this: ListItemsModel, options?: ListLoadOptions) {
+    this.isLoading = true;
+    this.errors.clear();
+    
+    try {
+      const result = yield this.provider.loadItems(options);
+      this.items = result.items;
+      this.totalItemCount = result.totalCount ?? result.items.length;
+      
+      // Update item map for fast lookups
+      this.itemMap.clear();
+      result.items.forEach(item => this.itemMap.set(item.id, item));
+      
+    } catch (error) {
+      this.errors.set('loadItems', error);
+    } finally {
+      this.isLoading = false;
+    }
+  });
+  
+  loadItemRange = flow(function* (this: ListItemsModel, start: number, end: number) {
+    const rangeKey = `${start}-${end}`;
+    this.loadingRanges.set(rangeKey, true);
+    
+    try {
+      const result = 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.items[absoluteIndex] = item;
+        this.itemMap.set(item.id, item);
+      });
+      
+    } catch (error) {
+      this.errors.set(rangeKey, error);
+    } finally {
+      this.loadingRanges.delete(rangeKey);
+    }
+  });
+}
+```
+
+### 3. ListItems Component (UI Layer)
+**Location**: `/components/ListItems.tsx`
+
+**Purpose**: Main React component that receives ListItemsProvider as prop and renders the virtualized list UI.
+
+**Component Interface**:
+```typescript
+interface ListItemsProps {
+  provider: ListItemsProvider;
+  className?: string;
+  height?: number;
+  width?: number;
+  // All behavior controlled by provider - no separate props
+}
+
+export const ListItems = observer(({ provider, className, height, width }: ListItemsProps) => {
+  const [model] = useState(() => new ListItemsModel(provider))
+  
+  // All configuration comes from provider:
+  // - provider.supportedViewTypes
+  // - provider.isMultiSelectEnabled
+  // - provider.isDragDropEnabled  
+  // - provider.isVirtualizationEnabled
+  // - provider.getVirtualizationConfig()
+  
+  // Component delegates all actions to model,
+  // which calls provider callbacks
+})
+```
+
+## View Types System
+
+### Built-in View Types
+```typescript
+export const LIST_VIEW_TYPE: ListViewType = {
+  id: "list",
+  name: "List",
+  icon: "list",
+  itemsPerRow: 1,
+  showDetails: false
+};
+
+export const GRID_VIEW_TYPE: ListViewType = {
+  id: "grid", 
+  name: "Grid",
+  icon: "grid",
+  itemsPerRow: 'auto', // Calculated based on container width
+  showDetails: false
+};
+
+export const DETAILS_VIEW_TYPE: ListViewType = {
+  id: "details",
+  name: "Details", 
+  icon: "table",
+  itemsPerRow: 1,
+  showDetails: true,
+  columns: ['name', 'size', 'modified', 'type']
+};
+
+export const THUMBNAILS_VIEW_TYPE: ListViewType = {
+  id: "thumbnails",
+  name: "Thumbnails",
+  icon: "images",
+  itemsPerRow: 'auto',
+  showThumbnails: true,
+  thumbnailSizes: ['small', 'medium', 'large', 'extra-large']
+};
+
+export const MASONRY_HORIZONTAL_VIEW_TYPE: ListViewType = {
+  id: "masonry-horizontal",
+  name: "Masonry Horizontal",
+  icon: "masonry-horizontal",
+  itemsPerRow: 'auto',
+  showDetails: false,
+  masonry: true
+};
+
+export const MASONRY_VERTICAL_VIEW_TYPE: ListViewType = {
+  id: "masonry-vertical",
+  name: "Masonry Vertical",
+  icon: "masonry-vertical",
+  itemsPerRow: 'auto',
+  showDetails: false,
+  masonry: true
+};
+```
+
+### Custom View Types
+```typescript
+export const CUSTOM_VIEW_TYPE: ListViewType = {
+  id: "custom-cushion-tree-map",
+  name: "Cushion Tree Map",
+  icon: "custom",
+  itemsPerRow: 'custom',
+  customRenderer: CushionTreeMapRenderer
+};
+```
+
+## File & Folder Structure
+
+```
+fs-ui/src/ListItemsComponent/
+├── architecture.md
+├── providers/
+│   └── ListItemsProvider.ts         # Provider interface
+├── models/
+│   ├── ListItemsModel.ts            # Main MobX state model
+│   ├── ListSelection.ts             # Selection state management
+│   ├── ViewTypeManager.ts           # View type state management
+│   ├── VirtualizationModel.ts       # Virtualization state management
+│   └── ListLoading.ts               # Loading state management
+├── components/
+│   ├── ListItems.tsx                # Main list component
+│   ├── ListItem.tsx                 # Individual item component
+│   ├── VirtualizedList.tsx          # Virtualization wrapper
+│   ├── ViewTypeSelector.tsx         # View type switcher
+│   ├── ListContextMenu.tsx          # Context menu component
+│   ├── GridView.tsx                 # Grid layout component
+│   ├── DetailsView.tsx              # Details/table view component
+│   ├── ThumbnailsView.tsx           # Thumbnails view component
+│   └── shared/
+│       ├── ListIcon.tsx             # Icon rendering
+│       ├── ListLoader.tsx           # Loading indicators
+│       ├── ListThumbnail.tsx        # Thumbnail rendering
+│       └── ListVirtualization.tsx   # Virtual scrolling utilities
+├── renderers/
+│   ├── DefaultItemRenderer.ts       # Default item rendering
+│   ├── TextItemRenderer.ts          # Text-only rendering
+│   ├── ThumbnailItemRenderer.ts     # Thumbnail rendering
+│   └── CustomItemRenderer.tsx       # Custom React rendering
+├── types/
+│   ├── ListTypes.ts                 # Core type definitions
+│   ├── ListEvents.ts                # Event type definitions
+│   ├── ListViewTypes.ts             # View type definitions
+│   └── ListOptions.ts               # Configuration types
+├── utils/
+│   ├── ListUtils.ts                 # List manipulation utilities
+│   ├── ListKeyboard.ts              # Keyboard navigation
+│   ├── ListAccessibility.ts         # ARIA utilities
+│   ├── ListVirtualization.ts        # Virtualization calculations
+│   └── ListTextEllipsis.ts          # Text truncation utilities
+└── index.ts                         # Public exports
+```
+
+## Data Flow
+
+### 1. Initialization
+```
+1. ListItems component receives ListItemsProvider
+2. ListItemsModel created with provider
+3. ListItemsModel calls provider.initialize()
+4. ListItemsModel calls provider.loadItems()
+5. ListItems renders with initial data and view type
+```
+
+### 2. View Type Changes
+```
+User clicks view type button
+    ↓
+ViewTypeSelector component handles event
+    ↓
+Calls ListItemsModel.setViewType()
+    ↓
+ListItemsModel updates @observable currentViewType
+    ↓
+ListItemsModel calls provider.onViewTypeChange()
+    ↓
+UI re-renders with new layout via MobX observer
+```
+
+### 3. Virtualization Flow
+```
+User scrolls list
+    ↓
+VirtualizedList component updates viewport
+    ↓
+Calls ListItemsModel.updateViewport()
+    ↓
+ListItemsModel calculates visible range
+    ↓
+If new items needed: calls loadItemRange()
+    ↓
+UI renders only visible items
+```
+
+### 4. Selection Interactions
+```
+User clicks item (with modifiers)
+    ↓
+ListItem component handles event
+    ↓
+Calls ListItemsModel.selectItem(modifiers)
+    ↓
+ListItemsModel updates @observable selectedItems
+    ↓
+ListItemsModel calls provider.onSelectionChange()
+    ↓
+UI re-renders selection state via MobX observer
+```
+
+## Virtualization Strategy
+
+### Requirements
+- **Mandatory**: Must handle 100k+ items without performance degradation
+- **Library**: Use `react-window` or `react-virtualized-auto-sizer`
+- **Height**: Fixed item heights per view type for optimal performance
+- **Windowing**: Only render visible items + small overscan buffer
+- **Dynamic Loading**: Load item ranges on-demand as user scrolls
+
+### Implementation
+```typescript
+interface VirtualizationConfig {
+  /** Fixed item height for current view type */
+  itemHeight: number;
+  /** Items to render outside visible area */
+  overscan: number;
+  /** Minimum items before enabling virtualization */
+  threshold: number;
+  /** Dynamic loading range size */
+  rangeSize: number;
+}
+
+class VirtualizationModel {
+  viewportHeight: number = 0;
+  scrollTop: number = 0;
+  itemHeight: number = 40;
+  
+  constructor(private owner: ListItemsModel) {
+    makeAutoObservable(this, {});
+  }
+  
+  get visibleRange(): { start: number; end: number } {
+    const start = Math.floor(this.scrollTop / this.itemHeight);
+    const end = Math.min(
+      start + Math.ceil(this.viewportHeight / this.itemHeight),
+      this.owner.totalItemCount
+    );
+    return { start, end };
+  }
+  
+  get visibleItems(): ListItemData[] {
+    const { start, end } = this.visibleRange;
+    return this.owner.items.slice(start, end + 1);
+  }
+}
+```
+
+## Performance Optimizations
+
+### MobX Optimizations
+- **Computed Properties**: Use for derived state calculations
+- **Observable Maps**: For O(1) lookups instead of array.find()
+- **Granular Observables**: Separate selection, loading, and UI state
+- **Reaction Cleanup**: Dispose of unused reactions
+
+### Virtualization Optimizations
+- **Fixed Heights**: Avoid dynamic height calculations
+- **Overscan Buffer**: Prevent white space during fast scrolling
+- **Range Loading**: Load items in batches, cache aggressively
+- **Memory Management**: Unload items outside viewport bounds
+
+### Rendering Optimizations
+- **Observer Components**: Extract list items to separate observer components
+- **Memoization**: Use React.memo for expensive item renderers
+- **CSS Containment**: Use CSS `contain` property for layout isolation
+- **Image Lazy Loading**: Load thumbnails only when visible
+
+## Accessibility Features
+
+### Keyboard Navigation
+- **Arrow Keys**: Navigate between items in all view types
+- **Home/End**: Jump to first/last item
+- **Page Up/Down**: Scroll by viewport height
+- **Space**: Toggle selection (multi-select mode)
+- **Enter**: Activate/open item
+- **F2**: Start inline editing (if supported)
+
+### Screen Reader Support
+- **Role Definitions**: `listbox`, `option`, `grid`, `gridcell`
+- **ARIA Labels**: Descriptive labels for all interactive elements
+- **Selection Announcements**: Announce selection changes
+- **Position Information**: "Item 5 of 1000" for context
+- **View Type Announcements**: Announce view changes
+
+### Focus Management
+- **Visual Focus**: Clear focus indicators
+- **Focus Trap**: Keep focus within component
+- **Restore Focus**: Remember focus position on re-entry
+
+## Usage Examples
+
+### Basic File Explorer
+```typescript
+const fileSystemProvider = new FileSystemListProvider(fileSystem, {
+  supportedViewTypes: [LIST_VIEW_TYPE, GRID_VIEW_TYPE, DETAILS_VIEW_TYPE],
+  multiSelectEnabled: true,
+  dragDropEnabled: true,
+  virtualizationEnabled: true,
+  defaultViewType: DETAILS_VIEW_TYPE
+});
+
+<ListItems provider={fileSystemProvider} height={600} />
+```
+
+### Media Gallery
+```typescript
+const mediaProvider = new MediaGalleryProvider(mediaService, {
+  supportedViewTypes: [THUMBNAILS_VIEW_TYPE, GRID_VIEW_TYPE],
+  multiSelectEnabled: true,
+  virtualizationEnabled: true,
+  defaultThumbnailSize: 'large'
+});
+
+<ListItems provider={mediaProvider} />
+```
+
+### Custom Data Grid
+```typescript
+class DataGridProvider implements ListItemsProvider {
+  constructor(private dataSource: DataSource) {}
+  
+  async loadItems(options?: ListLoadOptions) {
+    return { 
+      items: await this.dataSource.query(options),
+      totalCount: await this.dataSource.count()
+    };
+  }
+  
+  getSupportedViewTypes() {
+    return [DETAILS_VIEW_TYPE, LIST_VIEW_TYPE];
+  }
+  
+  getItemRenderer(item: ListItemData) {
+    return new CustomDataItemRenderer(item.type);
+  }
+  
+  onSelectionChange(selectionInfo: ListSelectionInfo) {
+    // Handle selection for parent application
+    this.notifySelectionChanged(selectionInfo.selectedItems);
+  }
+}
+```
+
+## Integration Points
+
+### With File System
+```typescript
+const fileListProvider = new FileSystemListProvider(fileSystem, {
+  supportedViewTypes: [LIST_VIEW_TYPE, DETAILS_VIEW_TYPE, THUMBNAILS_VIEW_TYPE],
+  showHiddenFiles: false,
+  sortBy: 'name'
+});
+
+<ListItems provider={fileListProvider} />
+```
+
+### With Search Results
+```typescript
+const searchProvider = new SearchResultsProvider(searchService, {
+  supportedViewTypes: [LIST_VIEW_TYPE, DETAILS_VIEW_TYPE],
+  highlightSearchTerms: true,
+  maxResults: 1000
+});
+
+<ListItems provider={searchProvider} />
+```
+
+### With Database Query
+```typescript
+const dbProvider = new DatabaseListProvider(dbConnection, {
+  table: 'products',
+  supportedViewTypes: [DETAILS_VIEW_TYPE],
+  virtualizationEnabled: true,
+  pageSize: 100
+});
+
+<ListItems provider={dbProvider} />
+```
+
+## Error Handling & Loading States
+
+### Loading States
+- **Initial Load**: Full component loading spinner
+- **Range Loading**: Skeleton items in viewport
+- **Background Refresh**: Subtle loading indicator
+- **Search Loading**: Search spinner with debouncing
+
+### Error States
+- **Load Errors**: Retry button with error message
+- **Network Errors**: Offline indicator with retry
+- **Permission Errors**: Clear access denied message
+- **Partial Errors**: Show available items, note errors
+
+### Empty States
+- **No Items**: Helpful empty state illustration
+- **No Search Results**: Search suggestions and filters
+- **Filter No Results**: Clear active filters button
+
+## Testing Strategy
+
+### Unit Tests
+- **Models**: MobX state transitions and computed properties
+- **Providers**: Data loading and callback functionality
+- **Utils**: Virtualization calculations and utilities
+
+### Integration Tests
+- **Provider + Model**: Data flow and state management
+- **Component + Model**: UI interactions and updates
+- **Virtualization**: Scroll behavior and range loading
+
+### E2E Tests
+- **View Switching**: All view types render correctly
+- **Large Datasets**: Performance with 10k+ items
+- **Selection**: Multi-select with keyboard and mouse
+- **Accessibility**: Screen reader and keyboard navigation
+
+## Migration Notes
+
+### From Legacy Components
+1. **Wrap existing data sources** in ListItemsProvider interface
+2. **Migrate selection logic** to provider callbacks
+3. **Update view switching** to use view type system
+4. **Add virtualization** for performance with large datasets
+5. **Enhance accessibility** with proper ARIA attributes
+
+### Breaking Changes
+- **Selection API**: New selection event structure
+- **View Types**: Standardized view type definitions
+- **Rendering**: New renderer interface for customization
+- **Performance**: Mandatory virtualization for large lists
+
+This architecture provides a solid foundation for building high-performance, accessible list components that can handle massive datasets while maintaining a clean, extensible codebase following MobX best practices.
+
+## Size Controls
+
+The `ViewSizeControls` component provides user interface for adjusting item sizes in grid and masonry views:
+
+### Features
+
+- **Size Presets**: Quick buttons for small, medium, large, and extra-large sizes
+- **Custom Sliders**: Fine-grained width and height adjustment sliders
+- **Live Preview**: Real-time dimension display
+- **View-Aware**: Only shows for views that support sizing (grid, masonry)
+
+### Usage
+
+```typescript
+<ViewSizeControls
+  model={listModel}
+  showSizePresets={true}
+  showCustomSliders={false}
+  className="size-controls"
+/>
+```
+
+### Size Management in Model
+
+The `ListItemsModel` provides size management through:
+
+- `itemSize`: Current preset size ('small' | 'medium' | 'large' | 'extra-large')
+- `customItemWidth`: Custom width in pixels (80-500px)
+- `customItemHeight`: Custom height in pixels (60-400px)
+- `itemsPerRow`: Number of items per row (1-8, or 'auto')
+- `itemDimensions`: Computed property returning current dimensions
+- `setItemSize()`: Set preset size with automatic dimension updates
+- `setCustomItemWidth()` / `setCustomItemHeight()`: Fine-grained control
+- `setItemsPerRow()`: Control column count in grid and masonry views
+
+## Variable Item Dimensions
+
+Items can have custom dimensions for realistic masonry layouts:
+
+### Item Dimension Interface
+
+```typescript
+interface ListItemData {
+  // ... other properties
+  getDimensions?(): { width: number; height: number };
+  imageUrl?: string;
+  aspectRatio?: number;
+}
+```
+
+### Features
+
+- **Dynamic Sizing**: Items can return custom dimensions via `getDimensions()`
+- **Aspect Ratio Preservation**: Images maintain their aspect ratios in layouts
+- **Fake Image Integration**: Uses picsum.photos for varied placeholder images
+- **Performance Optimized**: Efficient rendering with large datasets (10,000+ items)
+
+### Image Service Integration
+
+The component integrates with picsum.photos for realistic image placeholders:
+
+```typescript
+// Generate varied image URLs
+const imageUrl = `https://picsum.photos/${width}/${height}?random=${seed}`;
+```
+
+## Large Dataset Support
+
+The component is optimized for large datasets:
+
+### Performance Features
+
+- **Virtualization Ready**: Supports react-window for 10,000+ items
+- **Efficient Rendering**: Memoized components and computed properties
+- **Memory Management**: Proper cleanup and garbage collection
+- **Smooth Scrolling**: Optimized for large lists without performance degradation
+
+### Test Dataset
+
+The `TestListProvider` can generate large datasets with:
+- 10,000 varied items
+- Random dimensions and aspect ratios
+- Fake images with different sizes
+- Realistic file metadata