@sc4rfurryx/proteusjs 1.0.0

package/src/observers/IntersectionObserverPolyfill.ts

@@ -0,0 +1,289 @@
+/**
+ * IntersectionObserver Polyfill for ProteusJS
+ * Provides IntersectionObserver functionality for browsers that don't support it
+ */
+
+export interface IntersectionObserverEntry {
+  target: Element;
+  boundingClientRect: DOMRectReadOnly;
+  intersectionRect: DOMRectReadOnly;
+  rootBounds: DOMRectReadOnly | null;
+  intersectionRatio: number;
+  isIntersecting: boolean;
+  time: number;
+}
+
+export type IntersectionObserverCallback = (entries: IntersectionObserverEntry[]) => void;
+
+export class IntersectionObserverPolyfill {
+  public root: Element | null;
+  public rootMargin: string;
+  public thresholds: number[];
+  
+  private callback: IntersectionObserverCallback;
+  private observedElements: Map<Element, { lastRatio: number; wasIntersecting: boolean }> = new Map();
+  private rafId: number | null = null;
+  private isObserving: boolean = false;
+  private parsedRootMargin: { top: number; right: number; bottom: number; left: number };
+
+  constructor(callback: IntersectionObserverCallback, options?: IntersectionObserverInit) {
+    this.callback = callback;
+    this.root = (options?.root instanceof Element ? options.root : null);
+    this.rootMargin = options?.rootMargin || '0px';
+    this.thresholds = this.normalizeThresholds(options?.threshold);
+    this.parsedRootMargin = this.parseRootMargin(this.rootMargin);
+  }
+
+  /**
+   * Start observing an element
+   */
+  public observe(element: Element): void {
+    if (this.observedElements.has(element)) return;
+
+    this.observedElements.set(element, {
+      lastRatio: 0,
+      wasIntersecting: false
+    });
+
+    if (!this.isObserving) {
+      this.startObserving();
+    }
+  }
+
+  /**
+   * Stop observing an element
+   */
+  public unobserve(element: Element): void {
+    this.observedElements.delete(element);
+
+    if (this.observedElements.size === 0) {
+      this.stopObserving();
+    }
+  }
+
+  /**
+   * Disconnect all observations
+   */
+  public disconnect(): void {
+    this.observedElements.clear();
+    this.stopObserving();
+  }
+
+  /**
+   * Start the polling mechanism
+   */
+  private startObserving(): void {
+    if (this.isObserving) return;
+    
+    this.isObserving = true;
+    this.checkForIntersections();
+  }
+
+  /**
+   * Stop the polling mechanism
+   */
+  private stopObserving(): void {
+    if (!this.isObserving) return;
+    
+    this.isObserving = false;
+    if (this.rafId) {
+      cancelAnimationFrame(this.rafId);
+      this.rafId = null;
+    }
+  }
+
+  /**
+   * Check for intersection changes
+   */
+  private checkForIntersections(): void {
+    if (!this.isObserving) return;
+
+    const changedEntries: IntersectionObserverEntry[] = [];
+    const rootBounds = this.getRootBounds();
+
+    this.observedElements.forEach((lastState, element) => {
+      // Check if element is still in DOM
+      if (!document.contains(element)) {
+        this.observedElements.delete(element);
+        return;
+      }
+
+      const targetRect = element.getBoundingClientRect();
+      const intersectionRect = this.calculateIntersection(targetRect, rootBounds);
+      const intersectionRatio = this.calculateIntersectionRatio(targetRect, intersectionRect);
+      const isIntersecting = intersectionRatio > 0;
+
+      // Check if we should trigger callback
+      const shouldTrigger = this.shouldTriggerCallback(
+        intersectionRatio,
+        lastState.lastRatio,
+        isIntersecting,
+        lastState.wasIntersecting
+      );
+
+      if (shouldTrigger) {
+        // Update stored state
+        this.observedElements.set(element, {
+          lastRatio: intersectionRatio,
+          wasIntersecting: isIntersecting
+        });
+
+        // Create entry
+        const entry: IntersectionObserverEntry = {
+          target: element,
+          boundingClientRect: this.createDOMRectReadOnly(targetRect),
+          intersectionRect: this.createDOMRectReadOnly(intersectionRect),
+          rootBounds: rootBounds ? this.createDOMRectReadOnly(rootBounds) : null,
+          intersectionRatio,
+          isIntersecting,
+          time: performance.now()
+        };
+
+        changedEntries.push(entry);
+      }
+    });
+
+    // Call callback if there are changes
+    if (changedEntries.length > 0) {
+      try {
+        this.callback(changedEntries);
+      } catch (error) {
+        console.error('IntersectionObserver callback error:', error);
+      }
+    }
+
+    // Schedule next check
+    if (this.isObserving) {
+      this.rafId = requestAnimationFrame(() => this.checkForIntersections());
+    }
+  }
+
+  /**
+   * Get root bounds with margin applied
+   */
+  private getRootBounds(): DOMRect {
+    const rootElement = this.root || document.documentElement;
+    const rect = rootElement.getBoundingClientRect();
+    
+    return new DOMRect(
+      rect.left - this.parsedRootMargin.left,
+      rect.top - this.parsedRootMargin.top,
+      rect.width + this.parsedRootMargin.left + this.parsedRootMargin.right,
+      rect.height + this.parsedRootMargin.top + this.parsedRootMargin.bottom
+    );
+  }
+
+  /**
+   * Calculate intersection rectangle
+   */
+  private calculateIntersection(targetRect: DOMRect, rootBounds: DOMRect): DOMRect {
+    const left = Math.max(targetRect.left, rootBounds.left);
+    const top = Math.max(targetRect.top, rootBounds.top);
+    const right = Math.min(targetRect.right, rootBounds.right);
+    const bottom = Math.min(targetRect.bottom, rootBounds.bottom);
+
+    const width = Math.max(0, right - left);
+    const height = Math.max(0, bottom - top);
+
+    return new DOMRect(left, top, width, height);
+  }
+
+  /**
+   * Calculate intersection ratio
+   */
+  private calculateIntersectionRatio(targetRect: DOMRect, intersectionRect: DOMRect): number {
+    const targetArea = targetRect.width * targetRect.height;
+    if (targetArea === 0) return 0;
+
+    const intersectionArea = intersectionRect.width * intersectionRect.height;
+    return intersectionArea / targetArea;
+  }
+
+  /**
+   * Check if callback should be triggered based on thresholds
+   */
+  private shouldTriggerCallback(
+    currentRatio: number,
+    lastRatio: number,
+    isIntersecting: boolean,
+    wasIntersecting: boolean
+  ): boolean {
+    // Always trigger on first observation
+    if (lastRatio === 0 && !wasIntersecting) {
+      return true;
+    }
+
+    // Check if intersection state changed
+    if (isIntersecting !== wasIntersecting) {
+      return true;
+    }
+
+    // Check if any threshold was crossed
+    for (const threshold of this.thresholds) {
+      if ((lastRatio < threshold && currentRatio >= threshold) ||
+          (lastRatio > threshold && currentRatio <= threshold)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Normalize threshold values
+   */
+  private normalizeThresholds(threshold?: number | number[]): number[] {
+    if (threshold === undefined) return [0];
+    if (typeof threshold === 'number') return [threshold];
+    return threshold.slice().sort((a, b) => a - b);
+  }
+
+  /**
+   * Parse root margin string
+   */
+  private parseRootMargin(margin: string): { top: number; right: number; bottom: number; left: number } {
+    const values = margin.split(/\s+/).map(value => {
+      const num = parseFloat(value);
+      return value.endsWith('%') ? (num / 100) * window.innerHeight : num;
+    });
+
+    switch (values.length) {
+      case 1: return { top: values[0]!, right: values[0]!, bottom: values[0]!, left: values[0]! };
+      case 2: return { top: values[0]!, right: values[1]!, bottom: values[0]!, left: values[1]! };
+      case 3: return { top: values[0]!, right: values[1]!, bottom: values[2]!, left: values[1]! };
+      case 4: return { top: values[0]!, right: values[1]!, bottom: values[2]!, left: values[3]! };
+      default: return { top: 0, right: 0, bottom: 0, left: 0 };
+    }
+  }
+
+  /**
+   * Create a DOMRectReadOnly-like object
+   */
+  private createDOMRectReadOnly(rect: DOMRect): DOMRectReadOnly {
+    return {
+      x: rect.x,
+      y: rect.y,
+      width: rect.width,
+      height: rect.height,
+      top: rect.top,
+      right: rect.right,
+      bottom: rect.bottom,
+      left: rect.left,
+      toJSON: () => ({
+        x: rect.x,
+        y: rect.y,
+        width: rect.width,
+        height: rect.height,
+        top: rect.top,
+        right: rect.right,
+        bottom: rect.bottom,
+        left: rect.left
+      })
+    };
+  }
+}
+
+// Add static method for feature detection
+(IntersectionObserverPolyfill as any).isSupported = (): boolean => {
+  return typeof IntersectionObserver !== 'undefined';
+};

package/src/observers/ObserverManager.ts

@@ -0,0 +1,299 @@
+/**
+ * Observer Manager for ProteusJS
+ * Manages ResizeObserver and IntersectionObserver instances efficiently
+ */
+
+import type { ResizeCallback, IntersectionCallback } from '../types';
+import { ResizeObserverPolyfill } from './ResizeObserverPolyfill';
+import { IntersectionObserverPolyfill } from './IntersectionObserverPolyfill';
+
+export interface ObserverEntry {
+  element: Element;
+  callback: ResizeCallback | IntersectionCallback;
+  options?: ResizeObserverOptions | IntersectionObserverInit;
+}
+
+export class ObserverManager {
+  private resizeObservers: Map<string, ResizeObserver> = new Map();
+  private intersectionObservers: Map<string, IntersectionObserver> = new Map();
+  private resizeEntries: Map<Element, ObserverEntry> = new Map();
+  private intersectionEntries: Map<Element, ObserverEntry> = new Map();
+  private isPolyfillMode: boolean = false;
+
+  constructor() {
+    this.checkPolyfillNeeds();
+  }
+
+  /**
+   * Observe element for resize changes
+   */
+  public observeResize(
+    element: Element, 
+    callback: ResizeCallback, 
+    options?: ResizeObserverOptions
+  ): () => void {
+    const observerKey = this.getResizeObserverKey(options);
+    let observer = this.resizeObservers.get(observerKey);
+
+    if (!observer) {
+      observer = this.createResizeObserver(options);
+      this.resizeObservers.set(observerKey, observer);
+    }
+
+    // Store entry for cleanup
+    const entry: ObserverEntry = {
+      element,
+      callback: callback as any,
+      ...(options && { options })
+    };
+    this.resizeEntries.set(element, entry);
+
+    // Start observing
+    observer.observe(element, options);
+
+    // Return unobserve function
+    return () => this.unobserveResize(element);
+  }
+
+  /**
+   * Observe element for intersection changes
+   */
+  public observeIntersection(
+    element: Element,
+    callback: IntersectionCallback,
+    options?: IntersectionObserverInit
+  ): () => void {
+    const observerKey = this.getIntersectionObserverKey(options);
+    let observer = this.intersectionObservers.get(observerKey);
+
+    if (!observer) {
+      observer = this.createIntersectionObserver(callback, options);
+      this.intersectionObservers.set(observerKey, observer);
+    }
+
+    // Store entry for cleanup
+    const entry: ObserverEntry = {
+      element,
+      callback: callback as any,
+      ...(options && { options })
+    };
+    this.intersectionEntries.set(element, entry);
+
+    // Start observing
+    observer.observe(element);
+
+    // Return unobserve function
+    return () => this.unobserveIntersection(element);
+  }
+
+  /**
+   * Stop observing element for resize changes
+   */
+  public unobserveResize(element: Element): void {
+    const entry = this.resizeEntries.get(element);
+    if (!entry) return;
+
+    const observerKey = this.getResizeObserverKey(entry.options as ResizeObserverOptions);
+    const observer = this.resizeObservers.get(observerKey);
+    
+    if (observer) {
+      observer.unobserve(element);
+    }
+
+    this.resizeEntries.delete(element);
+    this.cleanupResizeObserver(observerKey);
+  }
+
+  /**
+   * Stop observing element for intersection changes
+   */
+  public unobserveIntersection(element: Element): void {
+    const entry = this.intersectionEntries.get(element);
+    if (!entry) return;
+
+    const observerKey = this.getIntersectionObserverKey(entry.options as IntersectionObserverInit);
+    const observer = this.intersectionObservers.get(observerKey);
+    
+    if (observer) {
+      observer.unobserve(element);
+    }
+
+    this.intersectionEntries.delete(element);
+    this.cleanupIntersectionObserver(observerKey);
+  }
+
+  /**
+   * Get total number of observed elements
+   */
+  public getObservedElementCount(): number {
+    return this.resizeEntries.size + this.intersectionEntries.size;
+  }
+
+  /**
+   * Get number of active observers
+   */
+  public getObserverCount(): number {
+    return this.resizeObservers.size + this.intersectionObservers.size;
+  }
+
+  /**
+   * Check if element is being observed for resize
+   */
+  public isObservingResize(element: Element): boolean {
+    return this.resizeEntries.has(element);
+  }
+
+  /**
+   * Check if element is being observed for intersection
+   */
+  public isObservingIntersection(element: Element): boolean {
+    return this.intersectionEntries.has(element);
+  }
+
+  /**
+   * Disconnect all observers and clean up
+   */
+  public destroy(): void {
+    // Disconnect all resize observers
+    this.resizeObservers.forEach(observer => observer.disconnect());
+    this.resizeObservers.clear();
+    this.resizeEntries.clear();
+
+    // Disconnect all intersection observers
+    this.intersectionObservers.forEach(observer => observer.disconnect());
+    this.intersectionObservers.clear();
+    this.intersectionEntries.clear();
+  }
+
+  /**
+   * Get debug information
+   */
+  public getDebugInfo(): object {
+    return {
+      isPolyfillMode: this.isPolyfillMode,
+      resizeObservers: this.resizeObservers.size,
+      intersectionObservers: this.intersectionObservers.size,
+      resizeEntries: this.resizeEntries.size,
+      intersectionEntries: this.intersectionEntries.size,
+      totalObservedElements: this.getObservedElementCount(),
+      totalObservers: this.getObserverCount()
+    };
+  }
+
+  /**
+   * Check if polyfills are needed and set up accordingly
+   */
+  private checkPolyfillNeeds(): void {
+    if (typeof ResizeObserver === 'undefined') {
+      this.setupResizeObserverPolyfill();
+      this.isPolyfillMode = true;
+    }
+
+    if (typeof IntersectionObserver === 'undefined') {
+      this.setupIntersectionObserverPolyfill();
+      this.isPolyfillMode = true;
+    }
+  }
+
+  /**
+   * Set up ResizeObserver polyfill
+   */
+  private setupResizeObserverPolyfill(): void {
+    (globalThis as any).ResizeObserver = ResizeObserverPolyfill;
+  }
+
+  /**
+   * Set up IntersectionObserver polyfill
+   */
+  private setupIntersectionObserverPolyfill(): void {
+    (globalThis as any).IntersectionObserver = IntersectionObserverPolyfill;
+  }
+
+  /**
+   * Create a new ResizeObserver instance
+   */
+  private createResizeObserver(_options?: ResizeObserverOptions): ResizeObserver {
+    return new ResizeObserver((entries) => {
+      entries.forEach(entry => {
+        const storedEntry = this.resizeEntries.get(entry.target);
+        if (storedEntry) {
+          (storedEntry.callback as ResizeCallback)(entry);
+        }
+      });
+    });
+  }
+
+  /**
+   * Create a new IntersectionObserver instance
+   */
+  private createIntersectionObserver(
+    _callback: IntersectionCallback,
+    options?: IntersectionObserverInit
+  ): IntersectionObserver {
+    return new IntersectionObserver((entries) => {
+      entries.forEach(entry => {
+        const storedEntry = this.intersectionEntries.get(entry.target);
+        if (storedEntry) {
+          (storedEntry.callback as IntersectionCallback)(entry);
+        }
+      });
+    }, options);
+  }
+
+  /**
+   * Generate key for ResizeObserver based on options
+   */
+  private getResizeObserverKey(options?: ResizeObserverOptions): string {
+    if (!options) return 'default';
+    return `box:${options.box || 'content-box'}`;
+  }
+
+  /**
+   * Generate key for IntersectionObserver based on options
+   */
+  private getIntersectionObserverKey(options?: IntersectionObserverInit): string {
+    if (!options) return 'default';
+    
+    const root = options.root ? 'custom' : 'viewport';
+    const rootMargin = options.rootMargin || '0px';
+    const threshold = Array.isArray(options.threshold) 
+      ? options.threshold.join(',') 
+      : (options.threshold || 0).toString();
+    
+    return `${root}:${rootMargin}:${threshold}`;
+  }
+
+  /**
+   * Clean up ResizeObserver if no longer needed
+   */
+  private cleanupResizeObserver(observerKey: string): void {
+    const hasElements = Array.from(this.resizeEntries.values()).some(
+      entry => this.getResizeObserverKey(entry.options as ResizeObserverOptions) === observerKey
+    );
+
+    if (!hasElements) {
+      const observer = this.resizeObservers.get(observerKey);
+      if (observer) {
+        observer.disconnect();
+        this.resizeObservers.delete(observerKey);
+      }
+    }
+  }
+
+  /**
+   * Clean up IntersectionObserver if no longer needed
+   */
+  private cleanupIntersectionObserver(observerKey: string): void {
+    const hasElements = Array.from(this.intersectionEntries.values()).some(
+      entry => this.getIntersectionObserverKey(entry.options as IntersectionObserverInit) === observerKey
+    );
+
+    if (!hasElements) {
+      const observer = this.intersectionObservers.get(observerKey);
+      if (observer) {
+        observer.disconnect();
+        this.intersectionObservers.delete(observerKey);
+      }
+    }
+  }
+}