@sc4rfurryx/proteusjs 1.0.0

package/src/containers/ContainerManager.ts

@@ -0,0 +1,370 @@
+/**
+ * Container Manager for ProteusJS
+ * Manages multiple SmartContainer instances and provides the main API
+ */
+
+import type { ContainerConfig, BreakpointConfig } from '../types';
+import { SmartContainer, ContainerOptions, ContainerState } from './SmartContainer';
+import { ObserverManager } from '../observers/ObserverManager';
+import { MemoryManager } from '../core/MemoryManager';
+import { EventSystem } from '../core/EventSystem';
+import { performanceTracker } from '../utils/performance';
+
+export class ContainerManager {
+  private containers: Map<Element, SmartContainer> = new Map();
+  private observerManager: ObserverManager;
+  private memoryManager: MemoryManager;
+  private eventSystem: EventSystem;
+  private config: Required<ContainerConfig>;
+  private autoDetectionEnabled: boolean = false;
+
+  constructor(
+    config: ContainerConfig,
+    observerManager: ObserverManager,
+    memoryManager: MemoryManager,
+    eventSystem: EventSystem
+  ) {
+    this.observerManager = observerManager;
+    this.memoryManager = memoryManager;
+    this.eventSystem = eventSystem;
+    
+    this.config = {
+      autoDetect: true,
+      breakpoints: {
+        sm: '300px',
+        md: '500px',
+        lg: '800px',
+        xl: '1200px'
+      },
+      units: true,
+      isolation: true,
+      polyfill: true,
+      ...config
+    };
+
+    if (this.config.autoDetect) {
+      this.enableAutoDetection();
+    }
+  }
+
+  /**
+   * Create and manage a container
+   */
+  public container(
+    selector: string | Element | Element[],
+    options: ContainerOptions = {}
+  ): SmartContainer | SmartContainer[] {
+    performanceTracker.mark('container-create');
+
+    const elements = this.normalizeSelector(selector);
+    const containers: SmartContainer[] = [];
+
+    elements.forEach(element => {
+      let container = this.containers.get(element);
+      
+      if (container) {
+        // Update existing container
+        if (options.breakpoints) {
+          container.updateBreakpoints(options.breakpoints);
+        }
+      } else {
+        // Create new container
+        const mergedOptions: ContainerOptions = {
+          breakpoints: this.config.breakpoints,
+          ...options
+        };
+
+        container = new SmartContainer(
+          element,
+          mergedOptions,
+          this.observerManager,
+          this.memoryManager
+        );
+
+        this.containers.set(element, container);
+        container.activate();
+
+        // Emit container created event
+        this.eventSystem.emit('containerCreated', {
+          element,
+          container,
+          options: mergedOptions
+        });
+      }
+
+      containers.push(container);
+    });
+
+    performanceTracker.measure('container-create');
+
+    return elements.length === 1 ? containers[0]! : containers;
+  }
+
+  /**
+   * Remove container management from element(s)
+   */
+  public removeContainer(selector: string | Element | Element[]): boolean {
+    const elements = this.normalizeSelector(selector);
+    let removed = false;
+
+    elements.forEach(element => {
+      const container = this.containers.get(element);
+      if (container) {
+        container.deactivate();
+        this.containers.delete(element);
+        removed = true;
+
+        // Emit container removed event
+        this.eventSystem.emit('containerRemoved', {
+          element,
+          container
+        });
+      }
+    });
+
+    return removed;
+  }
+
+  /**
+   * Get container instance for element
+   */
+  public getContainer(element: Element): SmartContainer | undefined {
+    return this.containers.get(element);
+  }
+
+  /**
+   * Get all managed containers
+   */
+  public getAllContainers(): SmartContainer[] {
+    return Array.from(this.containers.values());
+  }
+
+  /**
+   * Get containers by breakpoint
+   */
+  public getContainersByBreakpoint(breakpoint: string): SmartContainer[] {
+    return this.getAllContainers().filter(container =>
+      container.isBreakpointActive(breakpoint)
+    );
+  }
+
+  /**
+   * Update global breakpoints
+   */
+  public updateGlobalBreakpoints(breakpoints: BreakpointConfig): void {
+    const stringBreakpoints = Object.fromEntries(
+      Object.entries(breakpoints).map(([key, value]) => [key, String(value)])
+    );
+    this.config.breakpoints = { ...this.config.breakpoints, ...stringBreakpoints };
+    
+    // Update all existing containers
+    this.containers.forEach(container => {
+      container.updateBreakpoints(this.config.breakpoints);
+    });
+
+    // Emit breakpoints updated event
+    this.eventSystem.emit('breakpointsUpdated', {
+      breakpoints: this.config.breakpoints
+    });
+  }
+
+  /**
+   * Enable automatic container detection
+   */
+  public enableAutoDetection(): void {
+    if (this.autoDetectionEnabled) return;
+
+    this.autoDetectionEnabled = true;
+    this.scanForContainers();
+
+    // Set up mutation observer for new elements
+    this.setupMutationObserver();
+  }
+
+  /**
+   * Disable automatic container detection
+   */
+  public disableAutoDetection(): void {
+    this.autoDetectionEnabled = false;
+    // Note: We don't remove existing containers, just stop auto-detection
+  }
+
+  /**
+   * Manually scan for containers
+   */
+  public scanForContainers(): void {
+    if (!this.autoDetectionEnabled) return;
+
+    performanceTracker.mark('container-scan');
+
+    // Look for elements with container-related attributes or classes
+    const candidates = this.findContainerCandidates();
+    
+    candidates.forEach(element => {
+      if (!this.containers.has(element)) {
+        const options = this.extractOptionsFromElement(element);
+        this.container(element, options);
+      }
+    });
+
+    performanceTracker.measure('container-scan');
+  }
+
+  /**
+   * Get container statistics
+   */
+  public getStats(): object {
+    const containers = this.getAllContainers();
+    const stats = {
+      totalContainers: containers.length,
+      activeContainers: containers.filter(c => c.getState().lastUpdate > 0).length,
+      autoDetectionEnabled: this.autoDetectionEnabled,
+      breakpoints: Object.keys(this.config.breakpoints),
+      containersByBreakpoint: {} as Record<string, number>
+    };
+
+    // Count containers by active breakpoints
+    Object.keys(this.config.breakpoints).forEach(bp => {
+      stats.containersByBreakpoint[bp] = this.getContainersByBreakpoint(bp).length;
+    });
+
+    return stats;
+  }
+
+  /**
+   * Destroy all containers and clean up
+   */
+  public destroy(): void {
+    // Deactivate all containers
+    this.containers.forEach(container => {
+      container.deactivate();
+    });
+
+    this.containers.clear();
+    this.autoDetectionEnabled = false;
+  }
+
+  /**
+   * Normalize selector to array of elements
+   */
+  private normalizeSelector(selector: string | Element | Element[]): Element[] {
+    if (typeof selector === 'string') {
+      return Array.from(document.querySelectorAll(selector));
+    } else if (selector instanceof Element) {
+      return [selector];
+    } else if (Array.isArray(selector)) {
+      return selector;
+    }
+    return [];
+  }
+
+  /**
+   * Find potential container elements
+   */
+  private findContainerCandidates(): Element[] {
+    const candidates: Element[] = [];
+
+    // Elements with data-container attribute
+    candidates.push(...Array.from(document.querySelectorAll('[data-container]')));
+
+    // Elements with container-related classes
+    candidates.push(...Array.from(document.querySelectorAll('.container, .card, .widget, .component')));
+
+    // Elements with CSS container-type
+    if (typeof CSS !== 'undefined' && CSS.supports && CSS.supports('container-type', 'inline-size')) {
+      const allElements = document.querySelectorAll('*');
+      allElements.forEach(element => {
+        const style = getComputedStyle(element);
+        if (style.containerType && style.containerType !== 'normal') {
+          candidates.push(element);
+        }
+      });
+    }
+
+    // Remove duplicates
+    return Array.from(new Set(candidates));
+  }
+
+  /**
+   * Extract container options from element attributes
+   */
+  private extractOptionsFromElement(element: Element): ContainerOptions {
+    const options: ContainerOptions = {};
+
+    // Extract from data attributes
+    const containerData = element.getAttribute('data-container');
+    if (containerData) {
+      try {
+        const parsed = JSON.parse(containerData);
+        Object.assign(options, parsed);
+      } catch (error) {
+        // Ignore invalid JSON
+      }
+    }
+
+    // Extract breakpoints from data-breakpoints
+    const breakpointsData = element.getAttribute('data-breakpoints');
+    if (breakpointsData) {
+      try {
+        options.breakpoints = JSON.parse(breakpointsData);
+      } catch (error) {
+        // Ignore invalid JSON
+      }
+    }
+
+    // Extract container type from CSS or data attribute
+    const containerType = element.getAttribute('data-container-type');
+    if (containerType) {
+      options.containerType = containerType as any;
+    }
+
+    return options;
+  }
+
+  /**
+   * Set up mutation observer for auto-detection
+   */
+  private setupMutationObserver(): void {
+    if (typeof MutationObserver === 'undefined') return;
+
+    const observer = new MutationObserver((mutations) => {
+      let shouldScan = false;
+
+      mutations.forEach(mutation => {
+        if (mutation.type === 'childList') {
+          mutation.addedNodes.forEach(node => {
+            if (node.nodeType === Node.ELEMENT_NODE) {
+              shouldScan = true;
+            }
+          });
+        } else if (mutation.type === 'attributes') {
+          if (
+            mutation.attributeName?.startsWith('data-container') ||
+            mutation.attributeName === 'class'
+          ) {
+            shouldScan = true;
+          }
+        }
+      });
+
+      if (shouldScan) {
+        // Debounce scanning to avoid excessive calls
+        setTimeout(() => this.scanForContainers(), 100);
+      }
+    });
+
+    observer.observe(document.body, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: ['data-container', 'data-breakpoints', 'data-container-type', 'class']
+    });
+
+    // Register cleanup
+    this.memoryManager.register({
+      id: 'container-mutation-observer',
+      type: 'observer',
+      cleanup: () => observer.disconnect()
+    });
+  }
+}

package/src/containers/ContainerUnits.ts

@@ -0,0 +1,336 @@
+/**
+ * Container Units System for ProteusJS
+ * Implements CSS-like container units (cw, ch, cmin, cmax, cqi, cqb)
+ */
+
+import type { ContainerUnit } from '../types';
+
+export interface ContainerDimensions {
+  width: number;
+  height: number;
+  inlineSize: number;
+  blockSize: number;
+}
+
+export interface UnitCalculation {
+  value: number;
+  unit: ContainerUnit;
+  pixelValue: number;
+  containerDimensions: ContainerDimensions;
+}
+
+export class ContainerUnits {
+  private containerDimensions: Map<Element, ContainerDimensions> = new Map();
+  private unitProperties: Map<Element, Set<string>> = new Map();
+
+  /**
+   * Update container dimensions for an element
+   */
+  public updateDimensions(element: Element, dimensions: ContainerDimensions): void {
+    this.containerDimensions.set(element, dimensions);
+    this.updateUnitProperties(element);
+  }
+
+  /**
+   * Calculate container unit value in pixels
+   */
+  public calculateUnit(
+    element: Element,
+    value: number,
+    unit: ContainerUnit
+  ): number {
+    const dimensions = this.containerDimensions.get(element);
+    if (!dimensions) {
+      console.warn('ProteusJS: No container dimensions found for element');
+      return 0;
+    }
+
+    switch (unit) {
+      case 'cw':
+        return (value / 100) * dimensions.width;
+      case 'ch':
+        return (value / 100) * dimensions.height;
+      case 'cmin':
+        return (value / 100) * Math.min(dimensions.width, dimensions.height);
+      case 'cmax':
+        return (value / 100) * Math.max(dimensions.width, dimensions.height);
+      case 'cqi':
+        return (value / 100) * dimensions.inlineSize;
+      case 'cqb':
+        return (value / 100) * dimensions.blockSize;
+      default:
+        return 0;
+    }
+  }
+
+  /**
+   * Parse container unit string (e.g., "50cw", "25ch")
+   */
+  public parseUnit(unitString: string): { value: number; unit: ContainerUnit } | null {
+    const match = unitString.match(/^(\d*\.?\d+)(cw|ch|cmin|cmax|cqi|cqb)$/);
+    if (!match) return null;
+
+    return {
+      value: parseFloat(match[1]!),
+      unit: match[2]! as ContainerUnit
+    };
+  }
+
+  /**
+   * Convert container unit to pixels for specific element
+   */
+  public toPixels(element: Element, unitString: string): number {
+    const parsed = this.parseUnit(unitString);
+    if (!parsed) return 0;
+
+    return this.calculateUnit(element, parsed.value, parsed.unit);
+  }
+
+  /**
+   * Apply container units to element styles
+   */
+  public applyUnits(element: Element, styles: Record<string, string>): void {
+    const htmlElement = element as HTMLElement;
+    const appliedProperties = new Set<string>();
+
+    Object.entries(styles).forEach(([property, value]) => {
+      const convertedValue = this.convertUnitsInValue(element, value);
+      if (convertedValue !== value) {
+        htmlElement.style.setProperty(property, convertedValue);
+        appliedProperties.add(property);
+      }
+    });
+
+    // Track applied properties for cleanup
+    if (appliedProperties.size > 0) {
+      if (!this.unitProperties.has(element)) {
+        this.unitProperties.set(element, new Set());
+      }
+      appliedProperties.forEach(prop => {
+        this.unitProperties.get(element)!.add(prop);
+      });
+    }
+  }
+
+  /**
+   * Remove container unit styles from element
+   */
+  public removeUnits(element: Element): void {
+    const htmlElement = element as HTMLElement;
+    const properties = this.unitProperties.get(element);
+    
+    if (properties) {
+      properties.forEach(property => {
+        htmlElement.style.removeProperty(property);
+      });
+      this.unitProperties.delete(element);
+    }
+  }
+
+  /**
+   * Generate CSS custom properties for container units
+   */
+  public generateCustomProperties(element: Element): Record<string, string> {
+    const dimensions = this.containerDimensions.get(element);
+    if (!dimensions) return {};
+
+    return {
+      '--cw': `${dimensions.width / 100}px`,
+      '--ch': `${dimensions.height / 100}px`,
+      '--cmin': `${Math.min(dimensions.width, dimensions.height) / 100}px`,
+      '--cmax': `${Math.max(dimensions.width, dimensions.height) / 100}px`,
+      '--cqi': `${dimensions.inlineSize / 100}px`,
+      '--cqb': `${dimensions.blockSize / 100}px`
+    };
+  }
+
+  /**
+   * Apply custom properties to element
+   */
+  public applyCustomProperties(element: Element): void {
+    const htmlElement = element as HTMLElement;
+    const properties = this.generateCustomProperties(element);
+    
+    Object.entries(properties).forEach(([property, value]) => {
+      htmlElement.style.setProperty(property, value);
+    });
+  }
+
+  /**
+   * Create responsive value using container units
+   */
+  public createResponsiveValue(
+    baseValue: number,
+    unit: ContainerUnit,
+    options: {
+      min?: number;
+      max?: number;
+      scale?: number;
+    } = {}
+  ): string {
+    const { min, max, scale = 1 } = options;
+    const scaledValue = baseValue * scale;
+    
+    if (min !== undefined && max !== undefined) {
+      return `clamp(${min}px, ${scaledValue}${unit}, ${max}px)`;
+    } else if (min !== undefined) {
+      return `max(${min}px, ${scaledValue}${unit})`;
+    } else if (max !== undefined) {
+      return `min(${scaledValue}${unit}, ${max}px)`;
+    }
+    
+    return `${scaledValue}${unit}`;
+  }
+
+  /**
+   * Get container unit statistics
+   */
+  public getStats(): object {
+    return {
+      trackedContainers: this.containerDimensions.size,
+      elementsWithUnits: this.unitProperties.size,
+      totalUnitProperties: Array.from(this.unitProperties.values())
+        .reduce((sum, props) => sum + props.size, 0)
+    };
+  }
+
+  /**
+   * Clean up container data
+   */
+  public cleanup(element: Element): void {
+    this.removeUnits(element);
+    this.containerDimensions.delete(element);
+  }
+
+  /**
+   * Clear all data
+   */
+  public clear(): void {
+    // Remove all unit styles
+    this.unitProperties.forEach((_properties, element) => {
+      this.removeUnits(element);
+    });
+    
+    this.containerDimensions.clear();
+    this.unitProperties.clear();
+  }
+
+  /**
+   * Convert container units in a CSS value string
+   */
+  private convertUnitsInValue(element: Element, value: string): string {
+    // Match container unit patterns in the value
+    const unitRegex = /(\d*\.?\d+)(cw|ch|cmin|cmax|cqi|cqb)/g;
+    
+    return value.replace(unitRegex, (_match, numStr, unit) => {
+      const num = parseFloat(numStr);
+      const pixels = this.calculateUnit(element, num, unit as ContainerUnit);
+      return `${pixels}px`;
+    });
+  }
+
+  /**
+   * Update unit properties when dimensions change
+   */
+  private updateUnitProperties(element: Element): void {
+    const properties = this.unitProperties.get(element);
+    if (!properties) return;
+
+    const htmlElement = element as HTMLElement;
+    // const computedStyle = getComputedStyle(htmlElement); // Currently unused
+    
+    // Re-apply container unit styles with new dimensions
+    properties.forEach(property => {
+      const currentValue = htmlElement.style.getPropertyValue(property);
+      if (currentValue && this.hasContainerUnits(currentValue)) {
+        const convertedValue = this.convertUnitsInValue(element, currentValue);
+        htmlElement.style.setProperty(property, convertedValue);
+      }
+    });
+
+    // Update custom properties
+    this.applyCustomProperties(element);
+  }
+
+  /**
+   * Check if value contains container units
+   */
+  private hasContainerUnits(value: string): boolean {
+    return /\d+(cw|ch|cmin|cmax|cqi|cqb)/.test(value);
+  }
+}
+
+/**
+ * Utility functions for container units
+ */
+export const containerUnitUtils = {
+  /**
+   * Create fluid typography using container units
+   */
+  createFluidType(
+    minSize: number,
+    maxSize: number,
+    minContainer: number,
+    maxContainer: number,
+    unit: ContainerUnit = 'cw'
+  ): string {
+    const slope = (maxSize - minSize) / (maxContainer - minContainer);
+    const yIntercept = minSize - slope * minContainer;
+    
+    return `clamp(${minSize}px, ${yIntercept}px + ${slope * 100}${unit}, ${maxSize}px)`;
+  },
+
+  /**
+   * Create responsive spacing using container units
+   */
+  createFluidSpacing(
+    baseSpacing: number,
+    scale: number = 1,
+    unit: ContainerUnit = 'cw'
+  ): string {
+    const scaledValue = baseSpacing * scale;
+    return `${scaledValue}${unit}`;
+  },
+
+  /**
+   * Convert viewport units to container units
+   */
+  convertViewportToContainer(
+    value: string,
+    containerWidth: number,
+    containerHeight: number,
+    viewportWidth: number = window.innerWidth,
+    viewportHeight: number = window.innerHeight
+  ): string {
+    return value.replace(/(\d*\.?\d+)(vw|vh|vmin|vmax)/g, (match, numStr, unit) => {
+      const num = parseFloat(numStr);
+      let containerValue: number;
+      let containerUnit: ContainerUnit;
+
+      switch (unit) {
+        case 'vw':
+          containerValue = (num * viewportWidth) / containerWidth * 100;
+          containerUnit = 'cw';
+          break;
+        case 'vh':
+          containerValue = (num * viewportHeight) / containerHeight * 100;
+          containerUnit = 'ch';
+          break;
+        case 'vmin':
+          const vminPixels = (num / 100) * Math.min(viewportWidth, viewportHeight);
+          containerValue = (vminPixels / Math.min(containerWidth, containerHeight)) * 100;
+          containerUnit = 'cmin';
+          break;
+        case 'vmax':
+          const vmaxPixels = (num / 100) * Math.max(viewportWidth, viewportHeight);
+          containerValue = (vmaxPixels / Math.max(containerWidth, containerHeight)) * 100;
+          containerUnit = 'cmax';
+          break;
+        default:
+          return match;
+      }
+
+      return `${containerValue.toFixed(2)}${containerUnit}`;
+    });
+  }
+};