@sc4rfurryx/proteusjs 1.0.0

package/src/integration.test.ts

@@ -0,0 +1,227 @@
+/**
+ * Integration tests for ProteusJS
+ * Tests the complete system working together
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { ProteusJS } from './core/ProteusJS';
+
+describe('ProteusJS Integration', () => {
+  let proteus: ProteusJS;
+  let testContainer: HTMLElement;
+
+  beforeEach(() => {
+    // Reset singleton
+    (ProteusJS as any).instance = null;
+    
+    // Create test container
+    testContainer = document.createElement('div');
+    testContainer.className = 'test-container';
+    testContainer.style.width = '500px';
+    testContainer.style.height = '300px';
+    document.body.appendChild(testContainer);
+
+    // Initialize ProteusJS
+    proteus = new ProteusJS({
+      debug: true,
+      autoInit: false,
+      containers: {
+        autoDetect: false,
+        breakpoints: {
+          sm: '300px',
+          md: '500px',
+          lg: '800px'
+        }
+      }
+    });
+  });
+
+  afterEach(() => {
+    if (proteus) {
+      proteus.destroy();
+    }
+    if (testContainer && testContainer.parentNode) {
+      testContainer.parentNode.removeChild(testContainer);
+    }
+  });
+
+  describe('System Integration', () => {
+    it('should initialize all systems', () => {
+      proteus.init();
+      
+      expect(proteus.isInitialized()).toBe(true);
+      expect(proteus.getEventSystem()).toBeDefined();
+      expect(proteus.getPluginSystem()).toBeDefined();
+      expect(proteus.getPerformanceMonitor()).toBeDefined();
+      expect(proteus.getMemoryManager()).toBeDefined();
+      expect(proteus.getObserverManager()).toBeDefined();
+      expect(proteus.getContainerManager()).toBeDefined();
+    });
+
+    it('should create containers', () => {
+      proteus.init();
+      
+      const container = proteus.container(testContainer);
+      expect(container).toBeDefined();
+      
+      const containerManager = proteus.getContainerManager();
+      expect(containerManager.getContainer(testContainer)).toBeDefined();
+    });
+
+    it('should apply fluid typography', () => {
+      proteus.init();
+      
+      const textElement = document.createElement('p');
+      textElement.textContent = 'Test text';
+      testContainer.appendChild(textElement);
+
+      proteus.fluidType(textElement, {
+        minSize: 16,
+        maxSize: 24,
+        minContainer: 300,
+        maxContainer: 800,
+        unit: 'px',
+        containerUnit: 'cw',
+        curve: 'linear'
+      });
+
+      expect(textElement.style.fontSize).toBeTruthy();
+    });
+
+    it('should generate typographic scales', () => {
+      proteus.init();
+      
+      const scale = proteus.createTypeScale({
+        ratio: 1.2,
+        baseSize: 16,
+        baseUnit: 'px',
+        levels: 5,
+        direction: 'both'
+      });
+
+      expect(scale).toBeDefined();
+      expect(scale.levels).toHaveLength(11); // 5 up + 5 down + 1 base
+      expect(scale.cssCustomProperties).toBeDefined();
+    });
+  });
+
+  describe('Performance Monitoring', () => {
+    it('should track performance metrics', () => {
+      proteus.init();
+      
+      const performanceMonitor = proteus.getPerformanceMonitor();
+      performanceMonitor.start();
+      
+      const metrics = performanceMonitor.getMetrics();
+      expect(metrics).toBeDefined();
+      expect(typeof metrics.frameRate).toBe('number');
+      expect(typeof metrics.memoryUsage).toBe('number');
+    });
+  });
+
+  describe('Memory Management', () => {
+    it('should track and cleanup resources', () => {
+      proteus.init();
+      
+      const memoryManager = proteus.getMemoryManager();
+      
+      // Register a test resource
+      const resourceId = memoryManager.register({
+        id: 'test-resource',
+        type: 'observer',
+        cleanup: vi.fn(),
+        element: testContainer
+      });
+
+      expect(resourceId).toBe('test-resource');
+      
+      const info = memoryManager.getMemoryInfo();
+      expect(info).toHaveProperty('managedResources', 1);
+      
+      // Cleanup
+      const cleaned = memoryManager.unregister(resourceId);
+      expect(cleaned).toBe(true);
+    });
+  });
+
+  describe('Container Queries', () => {
+    it('should respond to container size changes', async () => {
+      proteus.init();
+      
+      const container = proteus.container(testContainer, {
+        breakpoints: {
+          small: '200px',
+          medium: '400px',
+          large: '600px'
+        }
+      });
+
+      // Simulate size change
+      testContainer.style.width = '450px';
+      
+      // Wait for observer to trigger
+      await new Promise(resolve => setTimeout(resolve, 50));
+      
+      const state = (container as any).getState();
+      expect(state.width).toBe(450);
+      expect(state.activeBreakpoints).toContain('small');
+      expect(state.activeBreakpoints).toContain('medium');
+    });
+  });
+
+  describe('Event System', () => {
+    it('should emit and handle events', () => {
+      proteus.init();
+      
+      const eventSystem = proteus.getEventSystem();
+      const mockCallback = vi.fn();
+      
+      eventSystem.on('test-event', mockCallback);
+      eventSystem.emit('test-event', { data: 'test' });
+      
+      expect(mockCallback).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: 'test-event',
+          detail: { data: 'test' }
+        })
+      );
+    });
+  });
+
+  describe('Plugin System', () => {
+    it('should register and install plugins', () => {
+      proteus.init();
+      
+      const pluginSystem = proteus.getPluginSystem();
+      const mockPlugin = {
+        name: 'test-plugin',
+        version: '1.0.0',
+        install: vi.fn(),
+        uninstall: vi.fn()
+      };
+      
+      pluginSystem.register(mockPlugin);
+      pluginSystem.install('test-plugin');
+      
+      expect(mockPlugin.install).toHaveBeenCalledWith(proteus);
+      expect(pluginSystem.isInstalled('test-plugin')).toBe(true);
+    });
+  });
+
+  describe('Error Handling', () => {
+    it('should handle initialization errors gracefully', () => {
+      const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+      
+      // Mock unsupported browser
+      vi.spyOn(ProteusJS, 'isSupported').mockReturnValue(false);
+      
+      proteus.init();
+      
+      expect(consoleSpy).toHaveBeenCalledWith(
+        'ProteusJS: Browser not supported. Missing required APIs.'
+      );
+      
+      consoleSpy.mockRestore();
+    });
+  });
+});

package/src/layout/AdaptiveGrid.ts

@@ -0,0 +1,429 @@
+/**
+ * Adaptive Grid System for ProteusJS
+ * Container-aware CSS Grid with auto-column calculation and masonry support
+ */
+
+export interface GridConfig {
+  minColumnWidth: number;
+  maxColumns: number;
+  gap: number | 'fluid';
+  aspectRatio?: number;
+  masonry: boolean;
+  autoFlow: 'row' | 'column' | 'row dense' | 'column dense';
+  alignment: {
+    justify: 'start' | 'end' | 'center' | 'stretch' | 'space-around' | 'space-between' | 'space-evenly';
+    align: 'start' | 'end' | 'center' | 'stretch';
+  };
+  responsive: boolean;
+  breakpoints?: Record<string, Partial<GridConfig>>;
+}
+
+export interface GridState {
+  columns: number;
+  rows: number;
+  gap: number;
+  itemWidth: number;
+  itemHeight: number;
+  containerWidth: number;
+  containerHeight: number;
+}
+
+export class AdaptiveGrid {
+  private element: Element;
+  private config: Required<GridConfig>;
+  private state: GridState;
+  private resizeObserver: ResizeObserver | null = null;
+  private mutationObserver: MutationObserver | null = null;
+
+  constructor(element: Element, config: Partial<GridConfig> = {}) {
+    this.element = element;
+    this.config = {
+      minColumnWidth: 250,
+      maxColumns: 12,
+      gap: 16,
+      aspectRatio: 1,
+      masonry: false,
+      autoFlow: 'row',
+      alignment: {
+        justify: 'stretch',
+        align: 'stretch'
+      },
+      responsive: true,
+      breakpoints: {},
+      ...config
+    };
+
+    this.state = this.createInitialState();
+    this.setupGrid();
+  }
+
+  /**
+   * Initialize and activate the grid
+   */
+  public activate(): void {
+    this.updateGrid();
+    this.setupObservers();
+  }
+
+  /**
+   * Deactivate and clean up the grid
+   */
+  public deactivate(): void {
+    this.cleanupObservers();
+    this.removeGridStyles();
+  }
+
+  /**
+   * Update grid configuration
+   */
+  public updateConfig(newConfig: Partial<GridConfig>): void {
+    this.config = { ...this.config, ...newConfig };
+    this.updateGrid();
+  }
+
+  /**
+   * Get current grid state
+   */
+  public getState(): GridState {
+    return { ...this.state };
+  }
+
+  /**
+   * Force grid recalculation
+   */
+  public recalculate(): void {
+    this.updateGrid();
+  }
+
+  /**
+   * Add items to the grid
+   */
+  public addItems(items: Element[]): void {
+    const fragment = document.createDocumentFragment();
+    items.forEach(item => {
+      this.prepareGridItem(item);
+      fragment.appendChild(item);
+    });
+    this.element.appendChild(fragment);
+    this.updateGrid();
+  }
+
+  /**
+   * Remove items from the grid
+   */
+  public removeItems(items: Element[]): void {
+    items.forEach(item => {
+      if (item.parentNode === this.element) {
+        this.element.removeChild(item);
+      }
+    });
+    this.updateGrid();
+  }
+
+  /**
+   * Get optimal column count for container width
+   */
+  public calculateOptimalColumns(containerWidth: number): number {
+    const availableWidth = containerWidth - this.getGapValue();
+    const minWidth = this.config.minColumnWidth;
+    
+    // Calculate maximum possible columns based on min width
+    const maxPossibleColumns = Math.floor((availableWidth + this.getGapValue()) / (minWidth + this.getGapValue()));
+    
+    // Respect max columns limit
+    return Math.min(maxPossibleColumns, this.config.maxColumns);
+  }
+
+  /**
+   * Setup initial grid styles
+   */
+  private setupGrid(): void {
+    const htmlElement = this.element as HTMLElement;
+    htmlElement.style.display = 'grid';
+    
+    if (this.config.masonry) {
+      this.setupMasonryGrid();
+    } else {
+      this.setupRegularGrid();
+    }
+  }
+
+  /**
+   * Setup regular CSS Grid
+   */
+  private setupRegularGrid(): void {
+    const htmlElement = this.element as HTMLElement;
+    
+    htmlElement.style.gridAutoFlow = this.config.autoFlow;
+    htmlElement.style.justifyContent = this.config.alignment.justify;
+    htmlElement.style.alignContent = this.config.alignment.align;
+    htmlElement.style.justifyItems = this.config.alignment.justify;
+    htmlElement.style.alignItems = this.config.alignment.align;
+  }
+
+  /**
+   * Setup masonry grid using CSS Grid Level 3 or fallback
+   */
+  private setupMasonryGrid(): void {
+    const htmlElement = this.element as HTMLElement;
+    
+    // Check for native masonry support
+    if (this.supportsMasonry()) {
+      htmlElement.style.gridTemplateRows = 'masonry';
+    } else {
+      // Fallback to JavaScript masonry
+      this.implementJavaScriptMasonry();
+    }
+  }
+
+  /**
+   * Update grid layout
+   */
+  private updateGrid(): void {
+    const containerRect = this.element.getBoundingClientRect();
+    const containerWidth = containerRect.width;
+    const containerHeight = containerRect.height;
+
+    // Apply responsive config if needed
+    const activeConfig = this.getActiveConfig(containerWidth);
+    
+    // Calculate optimal columns
+    const columns = this.calculateOptimalColumns(containerWidth);
+    const gap = this.getGapValue();
+    
+    // Calculate item dimensions
+    const itemWidth = (containerWidth - gap * (columns - 1)) / columns;
+    const itemHeight = activeConfig.aspectRatio 
+      ? itemWidth / activeConfig.aspectRatio 
+      : 0; // Auto height
+
+    // Update state
+    this.state = {
+      columns,
+      rows: Math.ceil(this.getItemCount() / columns),
+      gap,
+      itemWidth,
+      itemHeight,
+      containerWidth,
+      containerHeight
+    };
+
+    // Apply grid styles
+    this.applyGridStyles();
+
+    // Handle masonry layout
+    if (activeConfig.masonry && !this.supportsMasonry()) {
+      this.updateMasonryLayout();
+    }
+  }
+
+  /**
+   * Apply calculated grid styles
+   */
+  private applyGridStyles(): void {
+    const htmlElement = this.element as HTMLElement;
+    const { columns, gap, itemHeight } = this.state;
+
+    // Set grid template columns
+    htmlElement.style.gridTemplateColumns = `repeat(${columns}, 1fr)`;
+    
+    // Set gap
+    htmlElement.style.gap = `${gap}px`;
+    
+    // Set row height if aspect ratio is specified
+    if (itemHeight > 0) {
+      htmlElement.style.gridAutoRows = `${itemHeight}px`;
+    } else {
+      htmlElement.style.gridAutoRows = 'auto';
+    }
+
+    // Prepare all grid items
+    Array.from(this.element.children).forEach(child => {
+      this.prepareGridItem(child);
+    });
+  }
+
+  /**
+   * Prepare individual grid item
+   */
+  private prepareGridItem(item: Element): void {
+    const htmlItem = item as HTMLElement;
+    
+    // Ensure proper box-sizing
+    htmlItem.style.boxSizing = 'border-box';
+    
+    // Handle aspect ratio for items if specified
+    if (this.config.aspectRatio && !this.config.masonry) {
+      htmlItem.style.aspectRatio = this.config.aspectRatio.toString();
+    }
+    
+    // Add grid item class for styling
+    htmlItem.classList.add('proteus-grid-item');
+  }
+
+  /**
+   * Implement JavaScript masonry layout
+   */
+  private implementJavaScriptMasonry(): void {
+    const items = Array.from(this.element.children) as HTMLElement[];
+    const { columns, gap } = this.state;
+    
+    // Create column height trackers
+    const columnHeights = new Array(columns).fill(0);
+    
+    items.forEach((item, index) => {
+      // Find shortest column
+      const shortestColumnIndex = columnHeights.indexOf(Math.min(...columnHeights));
+      
+      // Position item
+      const column = shortestColumnIndex;
+      const row = Math.floor(columnHeights[shortestColumnIndex] / (this.state.itemHeight + gap));
+      
+      item.style.gridColumnStart = (column + 1).toString();
+      item.style.gridRowStart = (row + 1).toString();
+      
+      // Update column height
+      const itemHeight = item.getBoundingClientRect().height || this.state.itemHeight;
+      columnHeights[shortestColumnIndex] += itemHeight + gap;
+    });
+  }
+
+  /**
+   * Update masonry layout
+   */
+  private updateMasonryLayout(): void {
+    // Wait for layout to settle, then update masonry
+    requestAnimationFrame(() => {
+      this.implementJavaScriptMasonry();
+    });
+  }
+
+  /**
+   * Setup observers for responsive behavior
+   */
+  private setupObservers(): void {
+    if (!this.config.responsive) return;
+
+    // Resize observer for container size changes
+    this.resizeObserver = new ResizeObserver(() => {
+      this.updateGrid();
+    });
+    this.resizeObserver.observe(this.element);
+
+    // Mutation observer for content changes
+    this.mutationObserver = new MutationObserver(() => {
+      this.updateGrid();
+    });
+    this.mutationObserver.observe(this.element, {
+      childList: true,
+      subtree: false
+    });
+  }
+
+  /**
+   * Clean up observers
+   */
+  private cleanupObservers(): void {
+    if (this.resizeObserver) {
+      this.resizeObserver.disconnect();
+      this.resizeObserver = null;
+    }
+
+    if (this.mutationObserver) {
+      this.mutationObserver.disconnect();
+      this.mutationObserver = null;
+    }
+  }
+
+  /**
+   * Remove grid styles
+   */
+  private removeGridStyles(): void {
+    const htmlElement = this.element as HTMLElement;
+    
+    // Remove grid styles
+    htmlElement.style.removeProperty('display');
+    htmlElement.style.removeProperty('grid-template-columns');
+    htmlElement.style.removeProperty('grid-template-rows');
+    htmlElement.style.removeProperty('gap');
+    htmlElement.style.removeProperty('grid-auto-flow');
+    htmlElement.style.removeProperty('justify-content');
+    htmlElement.style.removeProperty('align-content');
+    htmlElement.style.removeProperty('justify-items');
+    htmlElement.style.removeProperty('align-items');
+    htmlElement.style.removeProperty('grid-auto-rows');
+
+    // Remove item styles
+    Array.from(this.element.children).forEach(child => {
+      const htmlChild = child as HTMLElement;
+      htmlChild.style.removeProperty('grid-column-start');
+      htmlChild.style.removeProperty('grid-row-start');
+      htmlChild.style.removeProperty('aspect-ratio');
+      htmlChild.classList.remove('proteus-grid-item');
+    });
+  }
+
+  /**
+   * Get active configuration based on container width
+   */
+  private getActiveConfig(containerWidth: number): Required<GridConfig> {
+    let activeConfig = { ...this.config };
+
+    // Apply breakpoint-specific configs
+    if (this.config.breakpoints) {
+      const sortedBreakpoints = Object.entries(this.config.breakpoints)
+        .map(([name, config]) => ({ name, width: parseInt(name), config }))
+        .sort((a, b) => a.width - b.width);
+
+      for (const breakpoint of sortedBreakpoints) {
+        if (containerWidth >= breakpoint.width) {
+          activeConfig = { ...activeConfig, ...breakpoint.config };
+        }
+      }
+    }
+
+    return activeConfig;
+  }
+
+  /**
+   * Get gap value in pixels
+   */
+  private getGapValue(): number {
+    if (this.config.gap === 'fluid') {
+      // Fluid gap based on container width
+      const containerWidth = this.element.getBoundingClientRect().width;
+      return Math.max(8, Math.min(32, containerWidth * 0.02));
+    }
+    return this.config.gap as number;
+  }
+
+  /**
+   * Get number of grid items
+   */
+  private getItemCount(): number {
+    return this.element.children.length;
+  }
+
+  /**
+   * Check if native masonry is supported
+   */
+  private supportsMasonry(): boolean {
+    if (typeof CSS === 'undefined' || !CSS.supports) return false;
+    return CSS.supports('grid-template-rows', 'masonry');
+  }
+
+  /**
+   * Create initial state
+   */
+  private createInitialState(): GridState {
+    return {
+      columns: 1,
+      rows: 1,
+      gap: 16,
+      itemWidth: 0,
+      itemHeight: 0,
+      containerWidth: 0,
+      containerHeight: 0
+    };
+  }
+}