@anymux/ui-kit 0.1.0

package/src/list/models/TreemapModel.ts

@@ -0,0 +1,204 @@
+import { makeAutoObservable } from 'mobx';
+import type { ListItemData } from '../types/ListTypes';
+
+/**
+ * Extension category color map.
+ * Maps file extensions to RGBA colors for the cushion treemap renderer.
+ */
+export const EXTENSION_CATEGORIES: Record<string, [number, number, number, number]> = {
+  // JavaScript/TypeScript — blue
+  js: [49, 120, 198, 255],
+  jsx: [49, 120, 198, 255],
+  ts: [49, 120, 198, 255],
+  tsx: [49, 120, 198, 255],
+  mjs: [49, 120, 198, 255],
+  cjs: [49, 120, 198, 255],
+  // Styles — teal
+  css: [21, 114, 182, 255],
+  scss: [21, 114, 182, 255],
+  less: [21, 114, 182, 255],
+  sass: [21, 114, 182, 255],
+  // Markup — orange
+  html: [227, 79, 38, 255],
+  xml: [227, 79, 38, 255],
+  svg: [227, 79, 38, 255],
+  vue: [227, 79, 38, 255],
+  // Data — gray
+  json: [107, 114, 128, 255],
+  yaml: [107, 114, 128, 255],
+  yml: [107, 114, 128, 255],
+  toml: [107, 114, 128, 255],
+  env: [107, 114, 128, 255],
+  // Images — green
+  png: [16, 185, 129, 255],
+  jpg: [16, 185, 129, 255],
+  jpeg: [16, 185, 129, 255],
+  gif: [16, 185, 129, 255],
+  webp: [16, 185, 129, 255],
+  avif: [16, 185, 129, 255],
+  ico: [16, 185, 129, 255],
+  // Documents — purple
+  md: [139, 92, 246, 255],
+  txt: [139, 92, 246, 255],
+  pdf: [139, 92, 246, 255],
+  doc: [139, 92, 246, 255],
+  docx: [139, 92, 246, 255],
+  // Archives — amber
+  zip: [245, 158, 11, 255],
+  tar: [245, 158, 11, 255],
+  gz: [245, 158, 11, 255],
+  br: [245, 158, 11, 255],
+  rar: [245, 158, 11, 255],
+  '7z': [245, 158, 11, 255],
+};
+
+/** Default color for directories — lighter blue */
+const DIRECTORY_COLOR: [number, number, number, number] = [96, 165, 250, 255];
+
+/** Default color for unknown file types — neutral gray */
+const OTHER_COLOR: [number, number, number, number] = [156, 163, 175, 255];
+
+/** Color scheme category labels and CSS hex colors for the legend */
+export const EXTENSION_LEGEND: Array<{ label: string; color: string }> = [
+  { label: 'JS/TS', color: '#3178C6' },
+  { label: 'Styles', color: '#1572B6' },
+  { label: 'Markup', color: '#E34F26' },
+  { label: 'Data', color: '#6B7280' },
+  { label: 'Images', color: '#10B981' },
+  { label: 'Docs', color: '#8B5CF6' },
+  { label: 'Archives', color: '#F59E0B' },
+  { label: 'Folders', color: '#60A5FA' },
+  { label: 'Other', color: '#9CA3AF' },
+];
+
+export type ColorScheme = 'extension' | 'size' | 'type';
+
+/**
+ * Get the RGBA color for a file extension (used by the cushion treemap renderer).
+ */
+export function getColorForExtension(name: string, isDirectory: boolean): [number, number, number, number] {
+  if (isDirectory) return DIRECTORY_COLOR;
+  const ext = name.split('.').pop()?.toLowerCase() ?? '';
+  return EXTENSION_CATEGORIES[ext] ?? OTHER_COLOR;
+}
+
+/**
+ * Get the CSS hex color string for an extension (used by overlays/tooltips).
+ */
+export function getHexColorForExtension(name: string, isDirectory: boolean): string {
+  const [r, g, b] = getColorForExtension(name, isDirectory);
+  return `#${r.toString(16).padStart(2, '0')}${g.toString(16).padStart(2, '0')}${b.toString(16).padStart(2, '0')}`;
+}
+
+/**
+ * Format bytes to a human-readable string.
+ */
+export function formatBytes(bytes: number): string {
+  if (bytes === 0) return '0 B';
+  const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+  const k = 1024;
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  const value = bytes / Math.pow(k, i);
+  return `${value < 10 ? value.toFixed(1) : Math.round(value)} ${units[i]}`;
+}
+
+/**
+ * Phase 1 TreemapModel — works with items already loaded in ListItemsModel.
+ *
+ * No worker scanning, no async. Computes layout from the flat items list,
+ * using file `size` for proportional rectangles (directories get size=1).
+ */
+export class TreemapModel {
+  // === Observable state ===
+
+  /** Current zoom path within the treemap */
+  zoomPath: string = '';
+
+  /** Path of the hovered tile (for tooltip) */
+  hoveredPath: string | null = null;
+
+  /** Active color scheme */
+  colorScheme: ColorScheme = 'extension';
+
+  /** Whether to show file name labels on tiles */
+  showLabels: boolean = true;
+
+  /** Whether to show size labels on tiles */
+  showSizes: boolean = true;
+
+  /** Highlighted extension category label (e.g. 'JS/TS') for legend filtering */
+  highlightedExtension: string | null = null;
+
+  constructor() {
+    makeAutoObservable(this);
+  }
+
+  // === Actions ===
+
+  zoomIn(path: string): void {
+    this.zoomPath = path;
+  }
+
+  zoomOut(): void {
+    if (!this.zoomPath) return;
+    const parts = this.zoomPath.split('/');
+    parts.pop();
+    this.zoomPath = parts.join('/');
+  }
+
+  resetZoom(): void {
+    this.zoomPath = '';
+  }
+
+  setHoveredPath(path: string | null): void {
+    this.hoveredPath = path;
+  }
+
+  setColorScheme(scheme: ColorScheme): void {
+    this.colorScheme = scheme;
+  }
+
+  toggleLabels(): void {
+    this.showLabels = !this.showLabels;
+  }
+
+  toggleSizes(): void {
+    this.showSizes = !this.showSizes;
+  }
+
+  setHighlightedExtension(ext: string | null): void {
+    this.highlightedExtension = this.highlightedExtension === ext ? null : ext;
+  }
+
+  // === Computed helpers ===
+
+  get breadcrumbs(): Array<{ name: string; path: string }> {
+    if (!this.zoomPath) return [];
+    const parts = this.zoomPath.split('/').filter(Boolean);
+    const result: Array<{ name: string; path: string }> = [];
+    for (let i = 0; i < parts.length; i++) {
+      result.push({
+        name: parts[i]!,
+        path: parts.slice(0, i + 1).join('/')
+      });
+    }
+    return result;
+  }
+
+  /**
+   * Get the RGBA color for a node based on the current color scheme.
+   */
+  getNodeColor(item: ListItemData): [number, number, number, number] {
+    switch (this.colorScheme) {
+      case 'extension':
+        return getColorForExtension(item.name, !!item.isDirectory);
+      case 'type':
+        return item.isDirectory ? DIRECTORY_COLOR : [16, 185, 129, 255];
+      case 'size':
+        // Placeholder — would need maxSize context. Just use extension for now.
+        return getColorForExtension(item.name, !!item.isDirectory);
+      default:
+        return OTHER_COLOR;
+    }
+  }
+}

package/src/list/providers/ListItemsProvider.ts

@@ -0,0 +1,313 @@
+import type { 
+  ListItemData, 
+  ListLoadOptions, 
+  ListLoadResult, 
+  ListSelectionInfo,
+  ListViewType as BaseListViewType,
+  ListDragDropInfo,
+  ListContextMenuItem,
+  VirtualizationConfig
+} from '../types/ListTypes';
+
+export interface ListItemsProviderListener {
+    onItemsCountChanged(count: number): void;
+    onItemChanged(itemIndex: number): void;
+}
+
+// AICODE-NOTE: Extended view type with additional properties for different view modes
+export interface ListViewType extends BaseListViewType {
+    // Inherits all properties from base type
+}
+
+// AICODE-NOTE: Built-in view types with extended properties
+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',
+    showThumbnails: true,
+    thumbnailSizes: ['small', 'medium', 'large', 'extra-large']
+};
+
+export const DETAILS_VIEW_TYPE: ListViewType = {
+    id: "details",
+    name: "Details",
+    icon: "table",
+    itemsPerRow: 1,
+    showDetails: true,
+    columns: ['name', 'size', 'modified', 'type']
+};
+
+export const MASONRY_HORIZONTAL_VIEW_TYPE: ListViewType = {
+    id: "masonry-horizontal",
+    name: "Masonry Horizontal",
+    icon: "layout-grid",
+    itemsPerRow: 'auto',
+    showThumbnails: true,
+    thumbnailSizes: ['small', 'medium', 'large', 'extra-large']
+};
+
+export const MASONRY_VERTICAL_VIEW_TYPE: ListViewType = {
+    id: "masonry-vertical",
+    name: "Masonry Vertical",
+    icon: "columns",
+    itemsPerRow: 'auto',
+    showThumbnails: true,
+    thumbnailSizes: ['small', 'medium', 'large', 'extra-large']
+};
+
+export const TREEMAP_VIEW_TYPE: ListViewType = {
+    id: "treemap",
+    name: "Treemap",
+    icon: "square-stack",
+    itemsPerRow: 'auto',
+    showDetails: false
+};
+
+/** Recursive tree node for treemap view */
+export interface TreemapNodeData {
+  name: string;
+  path: string;
+  size?: number;
+  isDirectory: boolean;
+  children?: TreemapNodeData[];
+}
+
+/** Progress info reported during recursive directory scan */
+export interface TreemapScanProgress {
+  directoriesScanned: number;
+  filesFound: number;
+  totalSize: number;
+}
+
+// AICODE-NOTE: Core provider interface with essential methods for MVP
+export interface ListItemsProvider {
+    // =====================
+    // Basic Configuration
+    // =====================
+    
+    /** Provider identifier */
+    readonly id: string;
+    
+    /** Human-readable name */
+    readonly name: string;
+    
+    /** Supported view types for this provider */
+    readonly supportedViewTypes: ListViewType[];
+    
+    /** Whether multi-selection is enabled */
+    readonly isMultiSelectEnabled: boolean;
+    
+    /** Whether virtualization is enabled */
+    readonly isVirtualizationEnabled: boolean;
+    
+    // =====================
+    // Data Loading Methods
+    // =====================
+    
+    /**
+     * Load items from the data source
+     * @param options Loading options for filtering, sorting, pagination
+     * @returns Promise resolving to loaded items
+     */
+    loadItems(options?: ListLoadOptions): Promise<ListLoadResult>;
+    
+    /**
+     * Get total count of items (for virtualization)
+     * @returns Promise resolving to total item count
+     */
+    getItemCount(): Promise<number>;
+    
+    /**
+     * Load a specific range of items (for virtualization)
+     * @param start Starting index
+     * @param end Ending index
+     * @returns Promise resolving to items in range
+     */
+    loadItemRange?(start: number, end: number): Promise<ListLoadResult>;
+    
+    /**
+     * Refresh/reload items
+     * @returns Promise resolving to refreshed items
+     */
+    refresh?(): Promise<ListLoadResult>;
+    
+    // =====================
+    // View Configuration
+    // =====================
+    
+    /**
+     * Get item height for a specific view type (for virtualization)
+     * @param viewType The view type to get height for
+     * @returns Fixed height in pixels
+     */
+    getItemHeight(viewType: ListViewType): number;
+    
+    /**
+     * Get item width for grid-based view types
+     * @param viewType The view type to get width for
+     * @returns Fixed width in pixels
+     */
+    getItemWidth?(viewType: ListViewType): number;
+    
+    /**
+     * Get virtualization configuration
+     * @returns Virtualization config object
+     */
+    getVirtualizationConfig?(): VirtualizationConfig;
+    
+    // =====================
+    // Event Callbacks
+    // =====================
+    
+    /**
+     * Called when selection changes
+     * @param selectionInfo Information about the selection change
+     */
+    onSelectionChange?(selectionInfo: ListSelectionInfo): void;
+    
+    /**
+     * Called when view type changes
+     * @param viewType New view type
+     */
+    onViewTypeChange?(viewType: ListViewType): void;
+    
+    /**
+     * Called when an item is double-clicked
+     * @param item The item that was double-clicked
+     */
+    onItemDoubleClick?(item: ListItemData): void;
+
+    /**
+     * Called when keyboard navigation requests going up one level (Escape key).
+     * Providers that support hierarchical navigation should implement this.
+     */
+    onNavigateUp?(): void;
+    
+    // =====================
+    // Legacy Listener Support
+    // =====================
+    
+    addListener(listener: ListItemsProviderListener): void;
+    removeListener(listener: ListItemsProviderListener): void;
+    
+    // =====================
+    // Item Rendering
+    // =====================
+    
+    /**
+     * Get custom icon for an item
+     * @param item Target item
+     * @returns Icon identifier or React component
+     */
+    getItemIcon?(item: ListItemData): string | React.ComponentType<any>;
+
+    /**
+     * Resolve a thumbnail URL for an item. Providers with async thumbnail
+     * loading return blob URLs from an observable cache — MobX observer
+     * components re-render when the URL becomes available.
+     */
+    resolveThumbnailUrl?(item: ListItemData): string | undefined;
+
+    /**
+     * Get measured aspect ratio (width/height) for an item by path.
+     * Used by masonry layout to size items correctly instead of using
+     * deterministic random fallback ratios.
+     */
+    getAspectRatio?(path: string): number | undefined;
+    
+    // =====================
+    // Treemap Data (recursive directory scan)
+    // =====================
+
+    /**
+     * Load recursive directory data for treemap view.
+     * Returns a nested tree of items including subfolder contents.
+     * @param onProgress Optional callback reporting scan progress
+     */
+    loadTreemapData?(onProgress?: (progress: TreemapScanProgress) => void): Promise<TreemapNodeData[]>;
+
+    // =====================
+    // Context Menu Support (for future phases)
+    // =====================
+    
+    /**
+     * Get context menu items for a specific item
+     * @param item Target item
+     * @returns Array of context menu items
+     */
+    getItemContextMenu?(item: ListItemData): ListContextMenuItem[];
+    
+    /**
+     * Get context menu items for multiple selected items
+     * @param items Selected items
+     * @returns Array of context menu items
+     */
+    getMultiItemContextMenu?(items: ListItemData[]): ListContextMenuItem[];
+
+    /**
+     * Get context menu items for empty space (no item right-clicked)
+     * @returns Array of context menu items
+     */
+    getEmptySpaceContextMenu?(): ListContextMenuItem[];
+
+    /**
+     * Called when a context menu action is selected
+     * @param menuItemId Menu item identifier
+     * @param items Items the action applies to (empty array for empty-space actions)
+     */
+    onContextMenuAction?(menuItemId: string, items: ListItemData[]): void;
+    
+    // =====================
+    // Drag and Drop Support
+    // =====================
+    
+    /**
+     * Whether drag and drop is enabled
+     */
+    readonly isDragDropEnabled?: boolean;
+    
+    /**
+     * Check if an item can be dragged
+     * @param item Item to check
+     * @returns Whether the item can be dragged
+     */
+    canDragItem?(item: ListItemData): boolean;
+    
+    /**
+     * Check if items can be dropped on a target
+     * @param draggedItems Items being dragged
+     * @param targetItem Target item (null for empty space)
+     * @param position Drop position relative to target
+     * @returns Whether the drop is allowed
+     */
+    canDropItems?(draggedItems: ListItemData[], targetItem: ListItemData | null, position: 'before' | 'after' | 'inside'): boolean;
+    
+    /**
+     * Called when drag operation starts
+     * @param draggedItems Items being dragged
+     * @param event Original drag event
+     */
+    onDragStart?(draggedItems: ListItemData[], event: DragEvent): void;
+    
+    /**
+     * Called when items are dropped
+     * @param dragDropInfo Information about the drag and drop operation
+     */
+    onDrop?(dragDropInfo: ListDragDropInfo): void;
+    
+    /**
+     * Called when drag operation ends (whether successful or not)
+     * @param draggedItems Items that were being dragged
+     * @param success Whether the drop was successful
+     */
+    onDragEnd?(draggedItems: ListItemData[], success: boolean): void;
+}