@anymux/ui-kit 0.1.0

package/src/list/types/ListTypes.ts

@@ -0,0 +1,178 @@
+/**
+ * Core Type Definitions for ListItemsComponent
+ * 
+ * Defines the fundamental interfaces and types used throughout the component.
+ * These types support the provider pattern and multiple view types.
+ */
+
+// AICODE-NOTE: Basic item data structure that must be flexible for different use cases
+export interface ListItemData {
+  /** Unique identifier for the item */
+  id: string;
+  /** Display name of the item */
+  name: string;
+  /** Optional type classification (file, folder, etc.) */
+  type?: string;
+  /** Optional size in bytes */
+  size?: number;
+  /** Optional modification date */
+  modified?: Date;
+  /** Optional icon identifier or URL */
+  icon?: string;
+  /** Optional thumbnail URL */
+  thumbnail?: string;
+  /** Optional thumbnail URL (alias for image display) */
+  thumbnailUrl?: string;
+  /** Additional custom properties */
+  [key: string]: any;
+  isDirectory?: boolean;
+  children?: ListItemData[];
+  metadata?: Record<string, any>;
+  
+  // AICODE-NOTE: Variable dimensions and image support
+  imageUrl?: string;
+  aspectRatio?: number;
+  getDimensions?(): { width: number; height: number };
+}
+
+// AICODE-NOTE: Options for loading items, supports filtering, sorting, and pagination
+export interface ListLoadOptions {
+  /** Number of items to load (for pagination) */
+  limit?: number;
+  /** Starting offset for pagination */
+  offset?: number;
+  /** Search query to filter items */
+  searchQuery?: string;
+  /** Sort field */
+  sortBy?: string;
+  /** Sort direction */
+  sortDirection?: 'asc' | 'desc';
+  /** Additional filter criteria */
+  filters?: Record<string, any>;
+}
+
+// AICODE-NOTE: Result from loading items, includes total count for virtualization
+export interface ListLoadResult {
+  /** Array of loaded items */
+  items: ListItemData[];
+  /** Total number of items available (for virtualization) */
+  totalCount?: number;
+  /** Whether there are more items to load */
+  hasMore?: boolean;
+  /** Loading cursor for pagination */
+  nextCursor?: string;
+}
+
+// AICODE-NOTE: Selection information passed to provider callbacks
+export interface ListSelectionInfo {
+  /** Currently selected items */
+  selectedItems: ListItemData[];
+  /** Previously selected items */
+  previousSelection: ListItemData[];
+  /** Type of selection operation */
+  selectionType: 'single' | 'multi' | 'range';
+  /** What triggered the selection change */
+  trigger: 'click' | 'keyboard' | 'api';
+}
+
+// AICODE-NOTE: Information about drag and drop operations
+export interface ListDragDropInfo {
+  /** Items being dragged */
+  draggedItems: ListItemData[];
+  /** Target item being dropped on */
+  targetItem: ListItemData | null;
+  /** Drop position relative to target */
+  position: 'before' | 'after' | 'inside';
+  /** Original drag event */
+  event: DragEvent;
+}
+
+// AICODE-NOTE: Configuration for virtualization to handle huge datasets
+export 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;
+}
+
+// AICODE-NOTE: Extended view type definition supporting custom renderers
+export interface ListViewType {
+  /** Unique identifier for the view type */
+  readonly id: string;
+  /** Human-readable name */
+  readonly name: string;
+  /** Optional icon for the view type */
+  readonly icon?: string;
+  /** Number of items per row (1 for list, 'auto' for responsive grid) */
+  readonly itemsPerRow?: number | 'auto' | 'custom';
+  /** Whether to show detailed information */
+  readonly showDetails?: boolean;
+  /** Whether to show thumbnails */
+  readonly showThumbnails?: boolean;
+  /** Available thumbnail sizes */
+  readonly thumbnailSizes?: ThumbnailSize[];
+  /** Column definitions for details view */
+  readonly columns?: string[];
+  /** Custom renderer for this view type */
+  readonly customRenderer?: any;
+}
+
+// AICODE-NOTE: Thumbnail size options for grid and thumbnail views
+export type ThumbnailSize = 'small' | 'medium' | 'large' | 'extra-large';
+
+// AICODE-NOTE: Context menu item definition
+export interface ListContextMenuItem {
+  /** Menu item identifier */
+  id: string;
+  /** Display label */
+  label: string;
+  /** Optional icon (string or React component) */
+  icon?: string | React.ComponentType<any>;
+  /** Whether item is disabled */
+  disabled?: boolean;
+  /** Whether this is a separator */
+  type?: 'item' | 'separator';
+  /** Whether this is a destructive action */
+  destructive?: boolean;
+  /** Tooltip text */
+  tooltip?: string;
+  /** Keyboard shortcut display */
+  shortcut?: string;
+  /** Submenu items */
+  submenu?: ListContextMenuItem[];
+}
+
+// AICODE-NOTE: Item renderer interface for custom rendering
+export interface ListItemRenderer {
+  /** Render item as text (for non-React environments) */
+  renderText?(item: ListItemData): string;
+  /** Render item icon */
+  renderIcon?(item: ListItemData): string;
+  /** Render item thumbnail */
+  renderThumbnail?(item: ListItemData): string;
+  /** Get display properties */
+  getDisplayProps?(item: ListItemData): {
+    className?: string;
+    style?: React.CSSProperties;
+    title?: string;
+    ariaLabel?: string;
+  };
+  /** Custom React component for item rendering */
+  renderComponent?: React.ComponentType<{ item: ListItemData; [key: string]: any }>;
+}
+
+// AICODE-NOTE: Error information for graceful error handling
+export interface ListError {
+  /** Error message */
+  message: string;
+  /** Error code */
+  code?: string;
+  /** Whether error is recoverable */
+  recoverable?: boolean;
+  /** Retry function */
+  retry?: () => void;
+} 

package/src/list/utils/BenchmarkLogger.ts

@@ -0,0 +1,243 @@
+// AICODE-NOTE: Benchmark logging utility for performance monitoring and optimization
+
+export interface BenchmarkResult {
+  operation: string;
+  duration: number;
+  timestamp: number;
+  metadata?: Record<string, any>;
+}
+
+export interface BenchmarkReport {
+  totalOperations: number;
+  totalDuration: number;
+  averageDuration: number;
+  slowestOperation: BenchmarkResult | null;
+  fastestOperation: BenchmarkResult | null;
+  operations: BenchmarkResult[];
+}
+
+export class BenchmarkLogger {
+  private results: BenchmarkResult[] = [];
+  private activeTimers = new Map<string, number>();
+  private enabled: boolean = true;
+
+  constructor(enabled: boolean = true) {
+    this.enabled = enabled;
+  }
+
+  /**
+   * Start timing an operation
+   */
+  start(operation: string, metadata?: Record<string, any>): void {
+    if (!this.enabled) return;
+    
+    const startTime = performance.now();
+    this.activeTimers.set(operation, startTime);
+    
+    if (metadata) {
+      console.log(`🚀 [BENCHMARK] Starting: ${operation}`, metadata);
+    } else {
+      console.log(`🚀 [BENCHMARK] Starting: ${operation}`);
+    }
+  }
+
+  /**
+   * End timing an operation and log the result
+   */
+  end(operation: string, metadata?: Record<string, any>): number {
+    if (!this.enabled) return 0;
+    
+    const startTime = this.activeTimers.get(operation);
+    if (!startTime) {
+      console.warn(`⚠️ [BENCHMARK] No start time found for operation: ${operation}`);
+      return 0;
+    }
+
+    const endTime = performance.now();
+    const duration = endTime - startTime;
+    
+    const result: BenchmarkResult = {
+      operation,
+      duration,
+      timestamp: Date.now(),
+      metadata
+    };
+    
+    this.results.push(result);
+    this.activeTimers.delete(operation);
+    
+    // Color-coded logging based on duration
+    const color = this.getDurationColor(duration);
+    const formattedDuration = this.formatDuration(duration);
+    
+    if (metadata) {
+      console.log(`${color} [BENCHMARK] Completed: ${operation} in ${formattedDuration}`, metadata);
+    } else {
+      console.log(`${color} [BENCHMARK] Completed: ${operation} in ${formattedDuration}`);
+    }
+    
+    return duration;
+  }
+
+  /**
+   * Time a synchronous operation
+   */
+  time<T>(operation: string, fn: () => T, metadata?: Record<string, any>): T {
+    this.start(operation, metadata);
+    try {
+      const result = fn();
+      this.end(operation, metadata);
+      return result;
+    } catch (error) {
+      this.end(operation, { ...metadata, error: error instanceof Error ? error.message : String(error) });
+      throw error;
+    }
+  }
+
+  /**
+   * Time an asynchronous operation
+   */
+  async timeAsync<T>(operation: string, fn: () => Promise<T>, metadata?: Record<string, any>): Promise<T> {
+    this.start(operation, metadata);
+    try {
+      const result = await fn();
+      this.end(operation, metadata);
+      return result;
+    } catch (error) {
+      this.end(operation, { ...metadata, error: error instanceof Error ? error.message : String(error) });
+      throw error;
+    }
+  }
+
+  /**
+   * Get a performance report
+   */
+  getReport(): BenchmarkReport {
+    if (this.results.length === 0) {
+      return {
+        totalOperations: 0,
+        totalDuration: 0,
+        averageDuration: 0,
+        slowestOperation: null,
+        fastestOperation: null,
+        operations: []
+      };
+    }
+
+    const totalDuration = this.results.reduce((sum, result) => sum + result.duration, 0);
+    const averageDuration = totalDuration / this.results.length;
+    
+    const sortedByDuration = [...this.results].sort((a, b) => a.duration - b.duration);
+    const fastestOperation = sortedByDuration[0] || null;
+    const slowestOperation = sortedByDuration[sortedByDuration.length - 1] || null;
+
+    return {
+      totalOperations: this.results.length,
+      totalDuration,
+      averageDuration,
+      slowestOperation,
+      fastestOperation,
+      operations: [...this.results]
+    };
+  }
+
+  /**
+   * Log a performance report
+   */
+  logReport(): void {
+    if (!this.enabled) return;
+    
+    const report = this.getReport();
+    
+    console.group('📊 [BENCHMARK] Performance Report');
+    console.log(`Total Operations: ${report.totalOperations}`);
+    console.log(`Total Duration: ${this.formatDuration(report.totalDuration)}`);
+    console.log(`Average Duration: ${this.formatDuration(report.averageDuration)}`);
+    
+    if (report.slowestOperation) {
+      console.log(`Slowest: ${report.slowestOperation.operation} (${this.formatDuration(report.slowestOperation.duration)})`);
+    }
+    
+    if (report.fastestOperation) {
+      console.log(`Fastest: ${report.fastestOperation.operation} (${this.formatDuration(report.fastestOperation.duration)})`);
+    }
+    
+    // Group operations by name
+    const operationGroups = this.groupOperationsByName(report.operations);
+    console.log('\n📈 Operations Summary:');
+    
+    Object.entries(operationGroups).forEach(([name, operations]) => {
+      const avgDuration = operations.reduce((sum, op) => sum + op.duration, 0) / operations.length;
+      console.log(`  ${name}: ${operations.length}x, avg ${this.formatDuration(avgDuration)}`);
+    });
+    
+    console.groupEnd();
+  }
+
+  /**
+   * Clear all benchmark results
+   */
+  clear(): void {
+    this.results = [];
+    this.activeTimers.clear();
+  }
+
+  /**
+   * Enable or disable benchmarking
+   */
+  setEnabled(enabled: boolean): void {
+    this.enabled = enabled;
+  }
+
+  /**
+   * Check if benchmarking is enabled
+   */
+  isEnabled(): boolean {
+    return this.enabled;
+  }
+
+  private getDurationColor(duration: number): string {
+    if (duration < 1) return '🟢'; // Green - very fast
+    if (duration < 10) return '🟡'; // Yellow - fast
+    if (duration < 50) return '🟠'; // Orange - moderate
+    return '🔴'; // Red - slow
+  }
+
+  private formatDuration(duration: number): string {
+    if (duration < 1) {
+      return `${duration.toFixed(3)}ms`;
+    } else if (duration < 1000) {
+      return `${duration.toFixed(1)}ms`;
+    } else {
+      return `${(duration / 1000).toFixed(2)}s`;
+    }
+  }
+
+  private groupOperationsByName(operations: BenchmarkResult[]): Record<string, BenchmarkResult[]> {
+    return operations.reduce((groups, operation) => {
+      const name = operation.operation;
+      if (!groups[name]) {
+        groups[name] = [];
+      }
+      groups[name].push(operation);
+      return groups;
+    }, {} as Record<string, BenchmarkResult[]>);
+  }
+}
+
+// AICODE-NOTE: Global benchmark logger instance
+export const benchmarkLogger = new BenchmarkLogger(
+  typeof window !== 'undefined' && 
+  (window.location.hostname === 'localhost' || window.location.hostname === '127.0.0.1')
+);
+
+// AICODE-NOTE: Convenience functions for common benchmarking patterns
+export const benchmark = {
+  start: (operation: string, metadata?: Record<string, any>) => benchmarkLogger.start(operation, metadata),
+  end: (operation: string, metadata?: Record<string, any>) => benchmarkLogger.end(operation, metadata),
+  time: <T>(operation: string, fn: () => T, metadata?: Record<string, any>) => benchmarkLogger.time(operation, fn, metadata),
+  timeAsync: <T>(operation: string, fn: () => Promise<T>, metadata?: Record<string, any>) => benchmarkLogger.timeAsync(operation, fn, metadata),
+  report: () => benchmarkLogger.logReport(),
+  clear: () => benchmarkLogger.clear(),
+  setEnabled: (enabled: boolean) => benchmarkLogger.setEnabled(enabled)
+};