@anymux/ui-kit 0.1.0

package/src/list/utils/ListKeyboard.ts

@@ -0,0 +1,414 @@
+import React from 'react';
+import { ListItemsModel } from '../models/ListItemsModel';
+
+// AICODE-NOTE: Keyboard navigation utility for list components
+
+export interface KeyboardNavigationOptions {
+  enableArrowKeys?: boolean;
+  enableHomeEnd?: boolean;
+  enableSpaceEnter?: boolean;
+  enableSelectAll?: boolean;
+  enableEscape?: boolean;
+  enablePageUpDown?: boolean;
+}
+
+export class ListKeyboardHandler {
+  private model: ListItemsModel;
+  private options: Required<KeyboardNavigationOptions>;
+  private isAttached: boolean = false;
+
+  constructor(model: ListItemsModel, options: KeyboardNavigationOptions = {}) {
+    this.model = model;
+    this.options = {
+      enableArrowKeys: true,
+      enableHomeEnd: true,
+      enableSpaceEnter: true,
+      enableSelectAll: true,
+      enableEscape: true,
+      enablePageUpDown: true,
+      ...options
+    };
+  }
+
+  /**
+   * Attach keyboard event listeners
+   */
+  attach(element?: HTMLElement): void {
+    if (this.isAttached) return;
+    
+    const target = element || document;
+    target.addEventListener('keydown', this.handleKeyDown as EventListener);
+    this.isAttached = true;
+  }
+
+  /**
+   * Detach keyboard event listeners
+   */
+  detach(element?: HTMLElement): void {
+    if (!this.isAttached) return;
+    
+    const target = element || document;
+    target.removeEventListener('keydown', this.handleKeyDown as EventListener);
+    this.isAttached = false;
+  }
+
+  /**
+   * Main keyboard event handler
+   */
+  private handleKeyDown = (event: Event): void => {
+    const keyboardEvent = event as KeyboardEvent;
+
+    // Skip when an input/textarea is focused (e.g. inline rename)
+    const tag = (keyboardEvent.target as HTMLElement)?.tagName;
+    if (tag === 'INPUT' || tag === 'TEXTAREA') return;
+
+    // AICODE-NOTE: Only handle keyboard events when list has focus or items
+    if (this.model.items.length === 0) return;
+
+    const { key, ctrlKey, metaKey, shiftKey } = keyboardEvent;
+    const isModifierPressed = ctrlKey || metaKey;
+
+    // AICODE-NOTE: Handle different keyboard shortcuts
+    switch (key) {
+      case 'ArrowUp':
+        if (this.options.enableArrowKeys) {
+          keyboardEvent.preventDefault();
+          this.handleArrowUp(shiftKey);
+        }
+        break;
+
+      case 'ArrowDown':
+        if (this.options.enableArrowKeys) {
+          keyboardEvent.preventDefault();
+          this.handleArrowDown(shiftKey);
+        }
+        break;
+
+      case 'ArrowLeft':
+        if (this.options.enableArrowKeys && this.model.currentViewType.id === 'grid') {
+          keyboardEvent.preventDefault();
+          this.handleArrowLeft(shiftKey);
+        }
+        break;
+
+      case 'ArrowRight':
+        if (this.options.enableArrowKeys && this.model.currentViewType.id === 'grid') {
+          keyboardEvent.preventDefault();
+          this.handleArrowRight(shiftKey);
+        }
+        break;
+
+      case 'Home':
+        if (this.options.enableHomeEnd) {
+          keyboardEvent.preventDefault();
+          this.handleHome(shiftKey);
+        }
+        break;
+
+      case 'End':
+        if (this.options.enableHomeEnd) {
+          keyboardEvent.preventDefault();
+          this.handleEnd(shiftKey);
+        }
+        break;
+
+      case 'PageUp':
+        if (this.options.enablePageUpDown) {
+          keyboardEvent.preventDefault();
+          this.handlePageUp(shiftKey);
+        }
+        break;
+
+      case 'PageDown':
+        if (this.options.enablePageUpDown) {
+          keyboardEvent.preventDefault();
+          this.handlePageDown(shiftKey);
+        }
+        break;
+
+      case ' ': // Space
+        if (this.options.enableSpaceEnter) {
+          keyboardEvent.preventDefault();
+          this.handleSpace(shiftKey);
+        }
+        break;
+
+      case 'Enter':
+        if (this.options.enableSpaceEnter) {
+          keyboardEvent.preventDefault();
+          this.handleEnter();
+        }
+        break;
+
+      case 'a':
+      case 'A':
+        if (this.options.enableSelectAll && isModifierPressed) {
+          keyboardEvent.preventDefault();
+          this.handleSelectAll();
+        }
+        break;
+
+      case 'Escape':
+        if (this.options.enableEscape) {
+          keyboardEvent.preventDefault();
+          this.handleEscape();
+        }
+        break;
+    }
+  };
+
+  /**
+   * Handle arrow up navigation
+   */
+  private handleArrowUp(shiftKey: boolean): void {
+    if (this.model.currentViewType.id === 'grid') {
+      this.handleGridArrowUp(shiftKey);
+    } else {
+      this.handleListArrowUp(shiftKey);
+    }
+  }
+
+  /**
+   * Handle arrow down navigation
+   */
+  private handleArrowDown(shiftKey: boolean): void {
+    if (this.model.currentViewType.id === 'grid') {
+      this.handleGridArrowDown(shiftKey);
+    } else {
+      this.handleListArrowDown(shiftKey);
+    }
+  }
+
+  /**
+   * Handle arrow left navigation (grid view)
+   */
+  private handleArrowLeft(shiftKey: boolean): void {
+    const currentIndex = this.getCurrentFocusedIndex();
+    if (currentIndex > 0) {
+      this.navigateToIndex(currentIndex - 1, shiftKey);
+    }
+  }
+
+  /**
+   * Handle arrow right navigation (grid view)
+   */
+  private handleArrowRight(shiftKey: boolean): void {
+    const currentIndex = this.getCurrentFocusedIndex();
+    if (currentIndex < this.model.items.length - 1) {
+      this.navigateToIndex(currentIndex + 1, shiftKey);
+    }
+  }
+
+  /**
+   * Handle list view arrow up
+   */
+  private handleListArrowUp(shiftKey: boolean): void {
+    const currentIndex = this.getCurrentFocusedIndex();
+    if (currentIndex > 0) {
+      this.navigateToIndex(currentIndex - 1, shiftKey);
+    }
+  }
+
+  /**
+   * Handle list view arrow down
+   */
+  private handleListArrowDown(shiftKey: boolean): void {
+    const currentIndex = this.getCurrentFocusedIndex();
+    if (currentIndex < this.model.items.length - 1) {
+      this.navigateToIndex(currentIndex + 1, shiftKey);
+    }
+  }
+
+  /**
+   * Handle grid view arrow up (move up by grid columns)
+   */
+  private handleGridArrowUp(shiftKey: boolean): void {
+    const currentIndex = this.getCurrentFocusedIndex();
+    const columnsPerRow = this.getGridColumnsPerRow();
+    const newIndex = Math.max(0, currentIndex - columnsPerRow);
+    this.navigateToIndex(newIndex, shiftKey);
+  }
+
+  /**
+   * Handle grid view arrow down (move down by grid columns)
+   */
+  private handleGridArrowDown(shiftKey: boolean): void {
+    const currentIndex = this.getCurrentFocusedIndex();
+    const columnsPerRow = this.getGridColumnsPerRow();
+    const newIndex = Math.min(this.model.items.length - 1, currentIndex + columnsPerRow);
+    this.navigateToIndex(newIndex, shiftKey);
+  }
+
+  /**
+   * Handle Home key - go to first item
+   */
+  private handleHome(shiftKey: boolean): void {
+    this.navigateToIndex(0, shiftKey);
+  }
+
+  /**
+   * Handle End key - go to last item
+   */
+  private handleEnd(shiftKey: boolean): void {
+    this.navigateToIndex(this.model.items.length - 1, shiftKey);
+  }
+
+  /**
+   * Handle Page Up - move up by visible page size
+   */
+  private handlePageUp(shiftKey: boolean): void {
+    const currentIndex = this.getCurrentFocusedIndex();
+    const pageSize = this.getPageSize();
+    const newIndex = Math.max(0, currentIndex - pageSize);
+    this.navigateToIndex(newIndex, shiftKey);
+  }
+
+  /**
+   * Handle Page Down - move down by visible page size
+   */
+  private handlePageDown(shiftKey: boolean): void {
+    const currentIndex = this.getCurrentFocusedIndex();
+    const pageSize = this.getPageSize();
+    const newIndex = Math.min(this.model.items.length - 1, currentIndex + pageSize);
+    this.navigateToIndex(newIndex, shiftKey);
+  }
+
+  /**
+   * Handle Space key - toggle selection of focused item
+   */
+  private handleSpace(shiftKey: boolean): void {
+    const focusedItem = this.getFocusedItem();
+    if (focusedItem) {
+      this.model.selectItem(focusedItem, { ctrl: true, shift: shiftKey });
+    }
+  }
+
+  /**
+   * Handle Enter key - activate focused item
+   */
+  private handleEnter(): void {
+    const focusedItem = this.getFocusedItem();
+    if (focusedItem && this.model.provider.onItemDoubleClick) {
+      this.model.provider.onItemDoubleClick(focusedItem);
+    }
+  }
+
+  /**
+   * Handle Ctrl+A - select all items
+   */
+  private handleSelectAll(): void {
+    this.model.selectAll();
+  }
+
+  /**
+   * Handle Escape - clear selection first, then navigate up one directory
+   */
+  private handleEscape(): void {
+    if (this.model.hasSelection) {
+      this.model.clearSelection();
+    } else if (this.model.provider.onNavigateUp) {
+      this.model.provider.onNavigateUp();
+    }
+  }
+
+  /**
+   * Navigate to specific index with optional range selection
+   */
+  private navigateToIndex(index: number, extendSelection: boolean = false): void {
+    const item = this.model.items[index];
+    if (!item) return;
+
+    // Update focused item
+    this.model.setFocusedItem(item.id);
+
+    // Handle selection based on shift key
+    if (extendSelection && this.model.provider.isMultiSelectEnabled) {
+      // Shift+arrow: extend range selection from anchor
+      if (!this.model.selectionAnchor) {
+        // Set anchor if not already set
+        this.model.selectionAnchor = this.model.focusedItem || item.id;
+      }
+      this.model.selectRange(this.model.selectionAnchor, item.id);
+    } else {
+      // Plain arrow: single selection, reset anchor
+      this.model.selectItem(item);
+    }
+
+    // Ensure item is visible
+    this.model.ensureItemVisible(item.id);
+  }
+
+  /**
+   * Get current focused item index
+   */
+  private getCurrentFocusedIndex(): number {
+    if (!this.model.focusedItem) {
+      return 0;
+    }
+    return this.model.getItemIndex(this.model.focusedItem);
+  }
+
+  /**
+   * Get currently focused item
+   */
+  private getFocusedItem() {
+    if (!this.model.focusedItem) {
+      // AICODE-NOTE: If no item is focused, focus the first item
+      if (this.model.items.length > 0) {
+        const firstItem = this.model.items[0];
+        if (firstItem) {
+          this.model.setFocusedItem(firstItem.id);
+          return firstItem;
+        }
+      }
+      return null;
+    }
+    const item = this.model.getItem(this.model.focusedItem);
+    return item || null;
+  }
+
+  /**
+   * Get number of columns per row in grid view
+   */
+  private getGridColumnsPerRow(): number {
+    // AICODE-NOTE: Default to 4 columns, could be made configurable
+    return 4;
+  }
+
+  /**
+   * Get page size for page up/down navigation
+   */
+  private getPageSize(): number {
+    // AICODE-NOTE: Default to 10 items per page, could be calculated from viewport
+    return 10;
+  }
+}
+
+/**
+ * Hook for using keyboard navigation in React components
+ */
+export const useListKeyboard = (
+  model: ListItemsModel,
+  options?: KeyboardNavigationOptions,
+  containerRef?: React.RefObject<HTMLElement | HTMLDivElement | null>
+) => {
+  const keyboardHandler = React.useMemo(
+    () => new ListKeyboardHandler(model, options),
+    [model, options]
+  );
+
+  React.useEffect(() => {
+    const element = containerRef?.current;
+    if (element) {
+      keyboardHandler.attach(element);
+    }
+
+    return () => {
+      if (element) {
+        keyboardHandler.detach(element);
+      }
+    };
+  }, [keyboardHandler, containerRef]);
+
+  return keyboardHandler;
+}; 

package/src/list/utils/MasonryLayoutCalculator.ts

@@ -0,0 +1,302 @@
+import { makeAutoObservable } from "mobx";
+
+// AICODE-NOTE: Masonry layout calculator for variable height items
+export interface MasonryLayoutConfig {
+  containerWidth: number;
+  containerHeight: number;
+  columnCount: number | 'auto';
+  gap: number;
+  padding: number;
+  minColumnWidth: number;
+  maxColumnWidth: number;
+}
+
+export interface MasonryItemLayout {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  column: number;
+  thumbnailWidth: number;
+  thumbnailHeight: number;
+  textHeight: number;
+}
+
+export interface MasonryLayoutResult {
+  columnCount: number;
+  columnWidth: number;
+  totalHeight: number;
+  items: MasonryItemLayout[];
+  columnHeights: number[];
+}
+
+// AICODE-NOTE: Item data interface for masonry calculations
+export interface MasonryItemData {
+  id: string;
+  aspectRatio?: number;
+  customHeight?: number;
+  textLength?: number;
+}
+
+// AICODE-NOTE: MobX-enabled calculation class for masonry layouts with reactive updates
+export class MasonryLayoutCalculator {
+  private config: MasonryLayoutConfig;
+
+  constructor(config: MasonryLayoutConfig) {
+    this.config = config;
+    makeAutoObservable(this, {});
+  }
+
+  // AICODE-NOTE: Update configuration and trigger reactive updates
+  updateConfig(updates: Partial<MasonryLayoutConfig>): void {
+    this.config = { ...this.config, ...updates };
+  }
+
+  // AICODE-NOTE: Computed getter for current configuration
+  get currentConfig(): MasonryLayoutConfig {
+    return this.config;
+  }
+
+  // AICODE-NOTE: Calculate optimal column count
+  calculateColumnCount(): number {
+    if (typeof this.config.columnCount === 'number') {
+      return Math.max(1, this.config.columnCount);
+    }
+
+    const { containerWidth, gap, padding, minColumnWidth, maxColumnWidth } = this.config;
+    const availableWidth = containerWidth - (padding * 2);
+    
+    // Find optimal column count
+    let bestColumnCount = 1;
+    
+    for (let columnCount = 1; columnCount <= 8; columnCount++) {
+      const totalGaps = (columnCount - 1) * gap;
+      const columnWidth = (availableWidth - totalGaps) / columnCount;
+      
+      if (columnWidth >= minColumnWidth && columnWidth <= maxColumnWidth) {
+        bestColumnCount = columnCount;
+      } else if (columnWidth < minColumnWidth) {
+        break;
+      }
+    }
+    
+    return bestColumnCount;
+  }
+
+  // AICODE-NOTE: Calculate column width
+  calculateColumnWidth(columnCount: number): number {
+    const { containerWidth, gap, padding } = this.config;
+    const availableWidth = containerWidth - (padding * 2);
+    const totalGaps = (columnCount - 1) * gap;
+    return Math.floor((availableWidth - totalGaps) / columnCount);
+  }
+
+  // AICODE-NOTE: Calculate item height based on content
+  calculateItemHeight(
+    item: MasonryItemData,
+    columnWidth: number,
+    baseHeight: number = 200
+  ): number {
+    // Use custom height if provided
+    if (item.customHeight) {
+      return item.customHeight;
+    }
+
+    // Calculate height based on aspect ratio
+    if (item.aspectRatio) {
+      const thumbnailHeight = columnWidth / item.aspectRatio;
+      const textHeight = this.calculateTextHeight(item.textLength || 0);
+      const padding = 16;
+      return Math.floor(thumbnailHeight + textHeight + padding);
+    }
+
+    // Default height with text consideration
+    const textHeight = this.calculateTextHeight(item.textLength || 0);
+    return baseHeight + textHeight;
+  }
+
+  // AICODE-NOTE: Calculate text height based on content length
+  private calculateTextHeight(textLength: number): number {
+    const baseTextHeight = 40;
+    const extraLines = Math.floor(textLength / 30); // Rough estimate
+    return baseTextHeight + (extraLines * 20);
+  }
+
+  // AICODE-NOTE: Calculate thumbnail dimensions within item
+  calculateThumbnailDimensions(
+    item: MasonryItemData,
+    columnWidth: number,
+    itemHeight: number
+  ): { width: number; height: number } {
+    const padding = 16;
+    const textHeight = this.calculateTextHeight(item.textLength || 0);
+    const availableWidth = columnWidth - padding;
+    const availableHeight = itemHeight - textHeight - padding;
+
+    if (item.aspectRatio) {
+      const thumbnailWidth = Math.min(availableWidth, availableHeight * item.aspectRatio);
+      const thumbnailHeight = thumbnailWidth / item.aspectRatio;
+      return {
+        width: Math.floor(thumbnailWidth),
+        height: Math.floor(thumbnailHeight)
+      };
+    }
+
+    // Square thumbnail by default
+    const size = Math.min(availableWidth, availableHeight);
+    return {
+      width: Math.floor(size),
+      height: Math.floor(size)
+    };
+  }
+
+  // AICODE-NOTE: Calculate layout for all items
+  calculateLayout(items: MasonryItemData[]): MasonryLayoutResult {
+    const columnCount = this.calculateColumnCount();
+    const columnWidth = this.calculateColumnWidth(columnCount);
+    const columnHeights = new Array(columnCount).fill(this.config.padding);
+    const layoutItems: MasonryItemLayout[] = [];
+
+    for (let i = 0; i < items.length; i++) {
+      const item = items[i];
+      if (!item) continue;
+      
+      // Find shortest column
+      const shortestColumnIndex = columnHeights.indexOf(Math.min(...columnHeights));
+      const currentHeight = columnHeights[shortestColumnIndex];
+      
+      // Calculate item dimensions
+      const itemHeight = this.calculateItemHeight(item, columnWidth);
+      const { width: thumbnailWidth, height: thumbnailHeight } = 
+        this.calculateThumbnailDimensions(item, columnWidth, itemHeight);
+      const textHeight = this.calculateTextHeight(item.textLength || 0);
+      
+      // Calculate position
+      const x = this.config.padding + (shortestColumnIndex * (columnWidth + this.config.gap));
+      const y = currentHeight;
+      
+      layoutItems.push({
+        x,
+        y,
+        width: columnWidth,
+        height: itemHeight,
+        column: shortestColumnIndex,
+        thumbnailWidth,
+        thumbnailHeight,
+        textHeight
+      });
+      
+      // Update column height
+      columnHeights[shortestColumnIndex] = currentHeight + itemHeight + this.config.gap;
+    }
+
+    const totalHeight = Math.max(...columnHeights) + this.config.padding;
+
+    return {
+      columnCount,
+      columnWidth,
+      totalHeight,
+      items: layoutItems,
+      columnHeights
+    };
+  }
+
+  // AICODE-NOTE: Calculate visible items for virtualization
+  calculateVisibleItems(
+    items: MasonryItemData[],
+    scrollTop: number,
+    viewportHeight: number,
+    overscan: number = 200
+  ): { startIndex: number; endIndex: number; visibleItems: MasonryItemLayout[] } {
+    const layout = this.calculateLayout(items);
+    const viewportTop = scrollTop - overscan;
+    const viewportBottom = scrollTop + viewportHeight + overscan;
+    
+    const visibleIndices: number[] = [];
+    const visibleItems: MasonryItemLayout[] = [];
+    
+    for (let i = 0; i < layout.items.length; i++) {
+      const item = layout.items[i];
+      if (item && item.y < viewportBottom && (item.y + item.height) > viewportTop) {
+        visibleIndices.push(i);
+        visibleItems.push(item);
+      }
+    }
+    
+    const startIndex = visibleIndices.length > 0 ? Math.min(...visibleIndices) : 0;
+    const endIndex = visibleIndices.length > 0 ? Math.max(...visibleIndices) : 0;
+    
+    return {
+      startIndex,
+      endIndex,
+      visibleItems
+    };
+  }
+
+  // AICODE-NOTE: Get item position by index
+  getItemPosition(itemIndex: number, items: MasonryItemData[]): MasonryItemLayout | null {
+    const layout = this.calculateLayout(items);
+    return layout.items[itemIndex] || null;
+  }
+
+  // AICODE-NOTE: Find item at position
+  getItemAtPosition(x: number, y: number, items: MasonryItemData[]): number | null {
+    const layout = this.calculateLayout(items);
+    
+    for (let i = 0; i < layout.items.length; i++) {
+      const item = layout.items[i];
+      if (item &&
+        x >= item.x &&
+        x <= item.x + item.width &&
+        y >= item.y &&
+        y <= item.y + item.height
+      ) {
+        return i;
+      }
+    }
+    
+    return null;
+  }
+}
+
+// AICODE-NOTE: Factory function for masonry calculator
+export function createMasonryCalculator(
+  containerWidth: number,
+  containerHeight: number,
+  options: Partial<MasonryLayoutConfig> = {}
+): MasonryLayoutCalculator {
+  const defaultConfig: MasonryLayoutConfig = {
+    containerWidth,
+    containerHeight,
+    columnCount: 'auto',
+    gap: 4,
+    padding: 4,
+    minColumnWidth: 200,
+    maxColumnWidth: 400,
+    ...options
+  };
+  
+  return new MasonryLayoutCalculator(defaultConfig);
+}
+
+// AICODE-NOTE: Preset configurations for masonry layouts
+export const MASONRY_PRESETS = {
+  compact: {
+    gap: 4,
+    padding: 4,
+    minColumnWidth: 160,
+    maxColumnWidth: 250
+  },
+  comfortable: {
+    gap: 8,
+    padding: 8,
+    minColumnWidth: 200,
+    maxColumnWidth: 300
+  },
+  spacious: {
+    gap: 16,
+    padding: 16,
+    minColumnWidth: 250,
+    maxColumnWidth: 400
+  }
+} as const;