@anymux/ui-kit 0.1.0

package/src/list/utils/MasonryLayoutEngine.ts

@@ -0,0 +1,401 @@
+// AICODE-NOTE: DOM-free masonry layout engine based on Masonry.js algorithm
+// Supports both horizontal and vertical masonry with aspect ratio preservation
+
+export interface MasonryItem {
+  id: string;
+  width: number;
+  height: number;
+  aspectRatio?: number; // width/height ratio
+}
+
+export interface MasonryItemPosition {
+  id: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface MasonryLayoutResult {
+  items: MasonryItemPosition[];
+  totalHeight: number;
+  totalWidth: number;
+  columns: number;
+}
+
+export interface MasonryConfig {
+  containerWidth: number;
+  columnWidth?: number; // If not provided, calculated from first item or container
+  gutter: number;
+  horizontalOrder: boolean; // true for horizontal masonry, false for vertical
+  fitWidth?: boolean; // Fit container to used columns
+}
+
+export class MasonryLayoutEngine {
+  private config: MasonryConfig;
+  private cache = new Map<string, MasonryLayoutResult>();
+  private cacheKey = '';
+
+  // Layout state
+  private cols: number = 0;
+  private colYs: number[] = [];
+  private maxY: number = 0;
+  private horizontalColIndex: number = 0;
+  private calculatedColumnWidth: number = 0;
+
+  // Horizontal masonry state
+  private rows: Array<{ y: number; height: number; items: Array<{ x: number; width: number }> }> = [];
+
+  // Public getter for calculated column width
+  get columnWidth(): number {
+    return this.calculatedColumnWidth;
+  }
+
+  constructor(config: MasonryConfig) {
+    this.config = { ...config };
+    this.resetLayout();
+  }
+
+  updateConfig(newConfig: Partial<MasonryConfig>): void {
+    this.config = { ...this.config, ...newConfig };
+    this.cache.clear(); // Clear cache when config changes
+    this.resetLayout();
+  }
+
+  calculateLayout(items: MasonryItem[]): MasonryLayoutResult {
+    // Early return for empty items
+    if (items.length === 0) {
+      return {
+        items: [],
+        totalHeight: 0,
+        totalWidth: this.config.containerWidth,
+        columns: 0
+      };
+    }
+
+    // Generate cache key (optimized for large datasets)
+    const configKey = `${this.config.containerWidth}:${this.config.columnWidth}:${this.config.gutter}:${this.config.horizontalOrder}`;
+    const itemsHash = this.hashItems(items);
+    const cacheKey = `${configKey}:${itemsHash}`;
+
+    // Return cached result if available
+    if (this.cache.has(cacheKey)) {
+      return this.cache.get(cacheKey)!;
+    }
+
+    // Calculate fresh layout
+    this.resetLayout();
+    this.measureColumns(items);
+
+    const positions: MasonryItemPosition[] = [];
+
+    for (const item of items) {
+      const position = this.getItemLayoutPosition(item);
+      positions.push({
+        id: item.id,
+        x: position.x,
+        y: position.y,
+        width: item.width,
+        height: item.height
+      });
+    }
+
+    const result: MasonryLayoutResult = {
+      items: positions,
+      totalHeight: this.getContainerSize().height,
+      totalWidth: this.getContainerSize().width,
+      columns: this.cols
+    };
+
+    // Cache the result
+    this.cache.set(cacheKey, result);
+    
+    // Limit cache size to prevent memory leaks
+    if (this.cache.size > 50) { // Reduced cache size for better memory usage
+      const firstKey = this.cache.keys().next().value;
+      if (firstKey) {
+        this.cache.delete(firstKey);
+      }
+    }
+
+    return result;
+  }
+
+  // AICODE-NOTE: Optimized hash function for large item arrays
+  private hashItems(items: MasonryItem[]): string {
+    if (items.length <= 100) {
+      // For small arrays, use detailed hash
+      return items.map(item => `${item.id}:${item.width}:${item.height}`).join('|');
+    } else {
+      // For large arrays, use summary hash to avoid performance issues
+      const summary = {
+        count: items.length,
+        firstId: items[0]?.id,
+        lastId: items[items.length - 1]?.id,
+        avgWidth: items.reduce((sum, item) => sum + item.width, 0) / items.length,
+        avgHeight: items.reduce((sum, item) => sum + item.height, 0) / items.length
+      };
+      return JSON.stringify(summary);
+    }
+  }
+
+  private resetLayout(): void {
+    this.colYs = [];
+    this.maxY = 0;
+    this.horizontalColIndex = 0;
+    this.rows = [];
+  }
+
+  private measureColumns(items: MasonryItem[]): void {
+    // Calculate column width if not provided
+    if (!this.config.columnWidth) {
+      const firstItem = items[0];
+      this.calculatedColumnWidth = firstItem?.width || this.config.containerWidth;
+    } else {
+      this.calculatedColumnWidth = this.config.columnWidth;
+    }
+
+    const columnWidth = this.calculatedColumnWidth + this.config.gutter;
+    const containerWidth = this.config.containerWidth;
+    let cols = (containerWidth + this.config.gutter) / columnWidth;
+
+    // Fix rounding errors, typically with gutters
+    const excess = columnWidth - (containerWidth % columnWidth);
+    const mathMethod = excess && excess < 1 ? 'round' : 'floor';
+    cols = Math[mathMethod](cols);
+    this.cols = Math.max(cols, 1);
+
+    // Initialize column Y positions with initial gutter offset
+    this.colYs = [];
+    for (let i = 0; i < this.cols; i++) {
+      this.colYs.push(0);
+    }
+  }
+
+  private getItemLayoutPosition(item: MasonryItem): { x: number; y: number } {
+    if (this.config.horizontalOrder) {
+      return this.getHorizontalLayoutPosition(item);
+    } else {
+      return this.getVerticalLayoutPosition(item);
+    }
+  }
+
+  private getVerticalLayoutPosition(item: MasonryItem): { x: number; y: number } {
+    // Calculate how many columns this item spans
+    const remainder = item.width % this.calculatedColumnWidth;
+    const mathMethod = remainder && remainder < 1 ? 'round' : 'ceil';
+    let colSpan = Math[mathMethod](item.width / this.calculatedColumnWidth);
+    colSpan = Math.min(colSpan, this.cols);
+
+    const colPosition = this.getTopColPosition(colSpan);
+
+    // Calculate position: gutter on left edge, then (columnWidth + gutter) per column
+    const position = {
+      x: this.config.gutter + colPosition.col * (this.calculatedColumnWidth + this.config.gutter),
+      y: colPosition.y + this.config.gutter
+    };
+
+    // Update column heights with gutter spacing
+    const setHeight = colPosition.y + item.height + this.config.gutter;
+    const setMax = colSpan + colPosition.col;
+    for (let i = colPosition.col; i < setMax; i++) {
+      this.colYs[i] = setHeight;
+    }
+
+    this.maxY = Math.max(this.maxY, setHeight);
+
+    return position;
+  }
+
+  private getHorizontalLayoutPosition(item: MasonryItem): { x: number; y: number } {
+    const itemWidth = item.width;
+    const itemHeight = item.height;
+    const gutter = this.config.gutter;
+    const containerWidth = this.config.containerWidth;
+
+    // Find the row with the shortest current width or create new row
+    let targetRowIndex = -1;
+    let targetX = gutter; // Start with left margin
+
+    // Check existing rows to see if item fits
+    for (let i = 0; i < this.rows.length; i++) {
+      const row = this.rows[i];
+      if (!row) continue;
+      
+      const currentRowWidth = row.items.reduce((sum, item) => sum + item.width + gutter, gutter);
+      
+      // Check if item fits in this row
+      if (currentRowWidth + itemWidth + gutter <= containerWidth) {
+        targetRowIndex = i;
+        targetX = currentRowWidth;
+        break;
+      }
+    }
+
+    // If no existing row can fit the item, create a new row
+    if (targetRowIndex === -1) {
+      const lastRow = this.rows[this.rows.length - 1];
+      const newRowY = this.rows.length === 0 ? gutter : 
+        (lastRow ? lastRow.y + lastRow.height + gutter : gutter);
+      
+      this.rows.push({
+        y: newRowY,
+        height: itemHeight,
+        items: []
+      });
+      targetRowIndex = this.rows.length - 1;
+      targetX = gutter;
+    }
+
+    const targetRow = this.rows[targetRowIndex];
+    if (!targetRow) {
+      // Fallback: create a new row if somehow targetRow is undefined
+      this.rows.push({
+        y: gutter,
+        height: itemHeight,
+        items: []
+      });
+      targetRowIndex = this.rows.length - 1;
+      targetX = gutter;
+    }
+
+    const finalTargetRow = this.rows[targetRowIndex];
+    if (finalTargetRow) {
+      // Add item to the row
+      finalTargetRow.items.push({
+        x: targetX,
+        width: itemWidth
+      });
+
+      // Update row height to accommodate the tallest item
+      finalTargetRow.height = Math.max(finalTargetRow.height, itemHeight);
+
+      // Calculate total height
+      this.maxY = Math.max(this.maxY, finalTargetRow.y + finalTargetRow.height);
+    }
+
+    const finalRow = this.rows[targetRowIndex];
+    return {
+      x: targetX,
+      y: finalRow ? finalRow.y : gutter
+    };
+  }
+
+  private getTopColPosition(colSpan: number): { col: number; y: number } {
+    const colGroup = this.getTopColGroup(colSpan);
+    const minimumY = Math.min(...colGroup);
+    const colIndex = colGroup.indexOf(minimumY);
+
+    return {
+      col: colIndex >= 0 ? colIndex : 0,
+      y: minimumY
+    };
+  }
+
+  private getTopColGroup(colSpan: number): number[] {
+    if (colSpan < 2) {
+      return this.colYs;
+    }
+
+    const colGroup: number[] = [];
+    const groupCount = this.cols + 1 - colSpan;
+    
+    for (let i = 0; i < groupCount; i++) {
+      colGroup[i] = this.getColGroupY(i, colSpan);
+    }
+    
+    return colGroup;
+  }
+
+  private getColGroupY(col: number, colSpan: number): number {
+    if (colSpan < 2) {
+      return this.colYs[col] ?? 0;
+    }
+    
+    const groupColYs = this.colYs.slice(col, col + colSpan);
+    return groupColYs.length > 0 ? Math.max(...groupColYs) : 0;
+  }
+
+  private getHorizontalColPosition(colSpan: number, item: MasonryItem): { col: number; y: number } {
+    let col = this.horizontalColIndex % this.cols;
+    const isOver = colSpan > 1 && col + colSpan > this.cols;
+    
+    // Shift to next row if item can't fit on current row
+    col = isOver ? 0 : col;
+    
+    // Don't let zero-size items take up space
+    const hasSize = item.width && item.height;
+    this.horizontalColIndex = hasSize ? col + colSpan : this.horizontalColIndex;
+
+    return {
+      col: col,
+      y: this.getColGroupY(col, colSpan)
+    };
+  }
+
+  private getContainerSize(): { height: number; width: number } {
+    // For vertical masonry, maxY comes from colYs (column heights).
+    // For horizontal masonry, maxY is accumulated in getHorizontalLayoutPosition
+    // from this.rows — do NOT overwrite it from colYs (which are never updated).
+    if (!this.config.horizontalOrder) {
+      this.maxY = this.colYs.length > 0 ? Math.max(...this.colYs) : 0;
+    }
+
+    const size = {
+      height: this.maxY + this.config.gutter, // Add final bottom gutter
+      width: this.config.containerWidth
+    };
+
+    if (this.config.fitWidth) {
+      size.width = this.getContainerFitWidth();
+    }
+
+    return size;
+  }
+
+  private getContainerFitWidth(): number {
+    let unusedCols = 0;
+    let i = this.cols;
+    
+    while (--i) {
+      if (this.colYs[i] !== 0) {
+        break;
+      }
+      unusedCols++;
+    }
+    
+    return (this.cols - unusedCols) * this.calculatedColumnWidth - this.config.gutter;
+  }
+
+  // Utility method to clear cache manually
+  clearCache(): void {
+    this.cache.clear();
+  }
+
+  // Get cache statistics for debugging
+  getCacheStats(): { size: number; keys: string[] } {
+    return {
+      size: this.cache.size,
+      keys: Array.from(this.cache.keys())
+    };
+  }
+}
+
+// Factory functions for common configurations
+export function createVerticalMasonry(containerWidth: number, columnWidth?: number, gutter: number = 4): MasonryLayoutEngine {
+  return new MasonryLayoutEngine({
+    containerWidth,
+    columnWidth,
+    gutter,
+    horizontalOrder: false
+  });
+}
+
+export function createHorizontalMasonry(containerWidth: number, columnWidth?: number, gutter: number = 4): MasonryLayoutEngine {
+  return new MasonryLayoutEngine({
+    containerWidth,
+    columnWidth,
+    gutter,
+    horizontalOrder: true
+  });
+} 

package/src/list/utils/__tests__/MasonryLayoutEngine.test.ts

@@ -0,0 +1,157 @@
+import { MasonryLayoutEngine, createVerticalMasonry, createHorizontalMasonry, MasonryItem } from '../MasonryLayoutEngine';
+
+describe('MasonryLayoutEngine', () => {
+  const containerWidth = 800;
+  const columnWidth = 200;
+  const gutter = 16;
+
+  const createTestItems = (): MasonryItem[] => [
+    { id: '1', width: 200, height: 300, aspectRatio: 2/3 }, // Portrait
+    { id: '2', width: 200, height: 150, aspectRatio: 4/3 }, // Landscape
+    { id: '3', width: 200, height: 200, aspectRatio: 1 },   // Square
+    { id: '4', width: 200, height: 400, aspectRatio: 1/2 }, // Tall portrait
+    { id: '5', width: 200, height: 100, aspectRatio: 2 },   // Wide landscape
+  ];
+
+  describe('Vertical Masonry', () => {
+    it('should create vertical masonry layout', () => {
+      const engine = createVerticalMasonry(containerWidth, columnWidth, gutter);
+      expect(engine).toBeInstanceOf(MasonryLayoutEngine);
+    });
+
+    it('should calculate layout for vertical masonry', () => {
+      const engine = createVerticalMasonry(containerWidth, columnWidth, gutter);
+      const items = createTestItems();
+      
+      const result = engine.calculateLayout(items);
+      
+      expect(result.items).toHaveLength(items.length);
+      expect(result.totalHeight).toBeGreaterThan(0);
+      expect(result.totalWidth).toBe(containerWidth);
+      expect(result.columns).toBeGreaterThan(0);
+      
+      // Check that all items have valid positions
+      result.items.forEach(item => {
+        expect(item.x).toBeGreaterThanOrEqual(0);
+        expect(item.y).toBeGreaterThanOrEqual(0);
+        expect(item.width).toBeGreaterThan(0);
+        expect(item.height).toBeGreaterThan(0);
+        expect(item.id).toBeTruthy();
+      });
+    });
+
+    it('should pack items efficiently in vertical masonry', () => {
+      const engine = createVerticalMasonry(containerWidth, columnWidth, gutter);
+      const items = createTestItems();
+      
+      const result = engine.calculateLayout(items);
+      
+      // Items should be distributed across columns
+      const xPositions = [...new Set(result.items.map(item => item.x))];
+      expect(xPositions.length).toBeGreaterThan(1); // Multiple columns used
+      
+      // Items should start from gutter offset in at least one column
+      const minY = Math.min(...result.items.map(item => item.y));
+      expect(minY).toBe(gutter);
+    });
+  });
+
+  describe('Horizontal Masonry', () => {
+    it('should create horizontal masonry layout', () => {
+      const engine = createHorizontalMasonry(containerWidth, columnWidth, gutter);
+      expect(engine).toBeInstanceOf(MasonryLayoutEngine);
+    });
+
+    it('should calculate layout for horizontal masonry', () => {
+      const engine = createHorizontalMasonry(containerWidth, columnWidth, gutter);
+      const items = createTestItems();
+      
+      const result = engine.calculateLayout(items);
+      
+      expect(result.items).toHaveLength(items.length);
+      expect(result.totalHeight).toBeGreaterThan(0);
+      expect(result.totalWidth).toBe(containerWidth);
+      expect(result.columns).toBeGreaterThan(0);
+    });
+
+    it('should arrange items differently than vertical masonry', () => {
+      const verticalEngine = createVerticalMasonry(containerWidth, columnWidth, gutter);
+      const horizontalEngine = createHorizontalMasonry(containerWidth, columnWidth, gutter);
+      const items = createTestItems();
+      
+      const verticalResult = verticalEngine.calculateLayout(items);
+      const horizontalResult = horizontalEngine.calculateLayout(items);
+      
+      // Results should be different (different positioning algorithm)
+      const verticalPositions = verticalResult.items.map(item => `${item.x},${item.y}`).join('|');
+      const horizontalPositions = horizontalResult.items.map(item => `${item.x},${item.y}`).join('|');
+      
+      expect(verticalPositions).not.toBe(horizontalPositions);
+    });
+  });
+
+  describe('Caching', () => {
+    it('should cache layout results', () => {
+      const engine = createVerticalMasonry(containerWidth, columnWidth, gutter);
+      const items = createTestItems();
+      
+      // First calculation
+      const result1 = engine.calculateLayout(items);
+      const stats1 = engine.getCacheStats();
+      
+      // Second calculation with same items
+      const result2 = engine.calculateLayout(items);
+      const stats2 = engine.getCacheStats();
+      
+      // Results should be identical (cached)
+      expect(result1).toBe(result2);
+      expect(stats1.size).toBe(1);
+      expect(stats2.size).toBe(1);
+    });
+
+    it('should clear cache when config changes', () => {
+      const engine = createVerticalMasonry(containerWidth, columnWidth, gutter);
+      const items = createTestItems();
+      
+      // First calculation
+      engine.calculateLayout(items);
+      expect(engine.getCacheStats().size).toBe(1);
+      
+      // Update config
+      engine.updateConfig({ containerWidth: containerWidth + 100 });
+      expect(engine.getCacheStats().size).toBe(0);
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('should handle empty items array', () => {
+      const engine = createVerticalMasonry(containerWidth, columnWidth, gutter);
+      const result = engine.calculateLayout([]);
+      
+      expect(result.items).toHaveLength(0);
+      expect(result.totalHeight).toBe(0);
+    });
+
+    it('should handle single item', () => {
+      const engine = createVerticalMasonry(containerWidth, columnWidth, gutter);
+      const items = [{ id: '1', width: 200, height: 300, aspectRatio: 2/3 }];
+      
+      const result = engine.calculateLayout(items);
+      
+      expect(result.items).toHaveLength(1);
+      expect(result.items[0]?.x).toBe(gutter); // First item has gutter offset
+      expect(result.items[0]?.y).toBe(gutter);
+    });
+
+    it('should handle very wide items', () => {
+      const engine = createVerticalMasonry(containerWidth, columnWidth, gutter);
+      const items = [{ id: '1', width: containerWidth, height: 200, aspectRatio: 4 }];
+      
+      const result = engine.calculateLayout(items);
+      
+      expect(result.items).toHaveLength(1);
+      expect(result.items[0]?.x).toBe(gutter); // First item has gutter offset
+      expect(result.items[0]?.y).toBe(gutter);
+    });
+  });
+});