@sc4rfurryx/proteusjs 1.0.0 → 1.1.0

package/src/modules/perf/index.ts

@@ -0,0 +1,291 @@
+/**
+ * @sc4rfurryx/proteusjs/perf
+ * Performance guardrails and CWV-friendly patterns
+ * 
+ * @version 1.1.0
+ * @author sc4rfurry
+ * @license MIT
+ */
+
+export interface SpeculationOptions {
+  prerender?: string[];
+  prefetch?: string[];
+  sameOriginOnly?: boolean;
+}
+
+export interface ContentVisibilityOptions {
+  containIntrinsicSize?: string;
+}
+
+/**
+ * Apply content-visibility for performance optimization
+ */
+export function contentVisibility(
+  selector: string | Element,
+  mode: 'auto' | 'hidden' = 'auto',
+  opts: ContentVisibilityOptions = {}
+): void {
+  const elements = typeof selector === 'string' 
+    ? document.querySelectorAll(selector)
+    : [selector];
+
+  const { containIntrinsicSize = '1000px 400px' } = opts;
+
+  elements.forEach(element => {
+    const el = element as HTMLElement;
+    el.style.contentVisibility = mode;
+    
+    if (mode === 'auto') {
+      el.style.containIntrinsicSize = containIntrinsicSize;
+    }
+  });
+}
+
+/**
+ * Set fetch priority for resources
+ */
+export function fetchPriority(
+  selector: string | Element,
+  priority: 'high' | 'low' | 'auto'
+): void {
+  const elements = typeof selector === 'string'
+    ? document.querySelectorAll(selector)
+    : [selector];
+
+  elements.forEach(element => {
+    if (element instanceof HTMLImageElement || 
+        element instanceof HTMLLinkElement ||
+        element instanceof HTMLScriptElement) {
+      (element as HTMLImageElement | HTMLLinkElement | HTMLScriptElement & { fetchPriority?: string }).fetchPriority = priority;
+    }
+  });
+}
+
+/**
+ * Set up speculation rules for prerendering and prefetching
+ */
+export function speculate(opts: SpeculationOptions): void {
+  const { prerender = [], prefetch = [], sameOriginOnly = true } = opts;
+
+  // Check for Speculation Rules API support
+  if (!('supports' in HTMLScriptElement && HTMLScriptElement.supports('speculationrules'))) {
+    console.warn('Speculation Rules API not supported');
+    return;
+  }
+
+  const rules: any = {};
+
+  if (prerender.length > 0) {
+    rules.prerender = prerender.map(url => {
+      const rule: any = { where: { href_matches: url } };
+      if (sameOriginOnly) {
+        rule.where.href_matches = new URL(url, window.location.origin).href;
+      }
+      return rule;
+    });
+  }
+
+  if (prefetch.length > 0) {
+    rules.prefetch = prefetch.map(url => {
+      const rule: any = { where: { href_matches: url } };
+      if (sameOriginOnly) {
+        rule.where.href_matches = new URL(url, window.location.origin).href;
+      }
+      return rule;
+    });
+  }
+
+  if (Object.keys(rules).length === 0) return;
+
+  // Create and inject speculation rules script
+  const script = document.createElement('script');
+  script.type = 'speculationrules';
+  script.textContent = JSON.stringify(rules);
+  document.head.appendChild(script);
+}
+
+/**
+ * Yield to browser using scheduler.yield or postTask when available
+ */
+export async function yieldToBrowser(): Promise<void> {
+  // Use scheduler.yield if available (Chrome 115+)
+  if ('scheduler' in window && 'yield' in (window as any).scheduler) {
+    return (window as any).scheduler.yield();
+  }
+
+  // Use scheduler.postTask if available
+  if ('scheduler' in window && 'postTask' in (window as any).scheduler) {
+    return new Promise(resolve => {
+      (window as any).scheduler.postTask(resolve, { priority: 'user-blocking' });
+    });
+  }
+
+  // Fallback to setTimeout
+  return new Promise(resolve => {
+    setTimeout(resolve, 0);
+  });
+}
+
+/**
+ * Optimize images with loading and decoding hints
+ */
+export function optimizeImages(selector: string | Element = 'img'): void {
+  const images = typeof selector === 'string'
+    ? document.querySelectorAll(selector)
+    : [selector];
+
+  images.forEach(img => {
+    if (!(img instanceof HTMLImageElement)) return;
+
+    // Set loading attribute if not already set
+    if (!img.hasAttribute('loading')) {
+      const rect = img.getBoundingClientRect();
+      const isAboveFold = rect.top < window.innerHeight;
+      img.loading = isAboveFold ? 'eager' : 'lazy';
+    }
+
+    // Set decoding hint
+    if (!img.hasAttribute('decoding')) {
+      img.decoding = 'async';
+    }
+
+    // Set fetch priority for above-fold images
+    if (!img.hasAttribute('fetchpriority')) {
+      const rect = img.getBoundingClientRect();
+      const isAboveFold = rect.top < window.innerHeight;
+      if (isAboveFold) {
+        (img as any).fetchPriority = 'high';
+      }
+    }
+  });
+}
+
+/**
+ * Preload critical resources
+ */
+export function preloadCritical(resources: Array<{ href: string; as: string; type?: string }>): void {
+  resources.forEach(({ href, as, type }) => {
+    // Check if already preloaded
+    const existing = document.querySelector(`link[rel="preload"][href="${href}"]`);
+    if (existing) return;
+
+    const link = document.createElement('link');
+    link.rel = 'preload';
+    link.href = href;
+    link.as = as;
+    if (type) {
+      link.type = type;
+    }
+    document.head.appendChild(link);
+  });
+}
+
+/**
+ * Measure and report Core Web Vitals
+ */
+export function measureCWV(): Promise<{ lcp?: number; fid?: number; cls?: number }> {
+  return new Promise(resolve => {
+    const metrics: { lcp?: number; fid?: number; cls?: number } = {};
+    let metricsCount = 0;
+    const totalMetrics = 3;
+
+    const checkComplete = () => {
+      metricsCount++;
+      if (metricsCount >= totalMetrics) {
+        resolve(metrics);
+      }
+    };
+
+    // LCP (Largest Contentful Paint)
+    if ('PerformanceObserver' in window) {
+      try {
+        const lcpObserver = new PerformanceObserver(list => {
+          const entries = list.getEntries();
+          const lastEntry = entries[entries.length - 1] as any;
+          metrics.lcp = lastEntry.startTime;
+        });
+        lcpObserver.observe({ entryTypes: ['largest-contentful-paint'] });
+        
+        // Stop observing after 10 seconds
+        setTimeout(() => {
+          lcpObserver.disconnect();
+          checkComplete();
+        }, 10000);
+      } catch {
+        checkComplete();
+      }
+
+      // FID (First Input Delay)
+      try {
+        const fidObserver = new PerformanceObserver(list => {
+          const entries = list.getEntries();
+          entries.forEach((entry: any) => {
+            metrics.fid = entry.processingStart - entry.startTime;
+          });
+          fidObserver.disconnect();
+          checkComplete();
+        });
+        fidObserver.observe({ entryTypes: ['first-input'] });
+        
+        // If no input after 10 seconds, consider FID as 0
+        setTimeout(() => {
+          if (metrics.fid === undefined) {
+            metrics.fid = 0;
+            fidObserver.disconnect();
+            checkComplete();
+          }
+        }, 10000);
+      } catch {
+        checkComplete();
+      }
+
+      // CLS (Cumulative Layout Shift)
+      try {
+        let clsValue = 0;
+        const clsObserver = new PerformanceObserver(list => {
+          list.getEntries().forEach((entry: any) => {
+            if (!entry.hadRecentInput) {
+              clsValue += entry.value;
+            }
+          });
+          metrics.cls = clsValue;
+        });
+        clsObserver.observe({ entryTypes: ['layout-shift'] });
+        
+        // Stop observing after 10 seconds
+        setTimeout(() => {
+          clsObserver.disconnect();
+          checkComplete();
+        }, 10000);
+      } catch {
+        checkComplete();
+      }
+    } else {
+      // Fallback if PerformanceObserver is not supported
+      setTimeout(() => resolve(metrics), 100);
+    }
+  });
+}
+
+// Export boost object to match usage examples in upgrade spec
+export const boost = {
+  contentVisibility,
+  fetchPriority,
+  speculate,
+  yieldToBrowser,
+  optimizeImages,
+  preloadCritical,
+  measureCWV
+};
+
+// Export all functions as named exports and default object
+export default {
+  contentVisibility,
+  fetchPriority,
+  speculate,
+  yieldToBrowser,
+  optimizeImages,
+  preloadCritical,
+  measureCWV,
+  boost
+};

package/src/modules/popover/index.ts

@@ -0,0 +1,238 @@
+/**
+ * @sc4rfurryx/proteusjs/popover
+ * HTML Popover API wrapper with robust focus/inert handling
+ * 
+ * @version 1.1.0
+ * @author sc4rfurry
+ * @license MIT
+ */
+
+export interface PopoverOptions {
+  type?: 'menu' | 'dialog' | 'tooltip';
+  trapFocus?: boolean;
+  restoreFocus?: boolean;
+  closeOnEscape?: boolean;
+  onOpen?: () => void;
+  onClose?: () => void;
+}
+
+export interface PopoverController {
+  open(): void;
+  close(): void;
+  toggle(): void;
+  destroy(): void;
+}
+
+/**
+ * Unified API for menus, tooltips, and dialogs using the native Popover API
+ * with robust focus/inert handling
+ */
+export function attach(
+  trigger: Element | string,
+  panel: Element | string,
+  opts: PopoverOptions = {}
+): PopoverController {
+  const triggerEl = typeof trigger === 'string' ? document.querySelector(trigger) : trigger;
+  const panelEl = typeof panel === 'string' ? document.querySelector(panel) : panel;
+
+  if (!triggerEl || !panelEl) {
+    throw new Error('Both trigger and panel elements must exist');
+  }
+
+  const {
+    type = 'menu',
+    trapFocus = type === 'dialog',
+    restoreFocus = true,
+    closeOnEscape = true,
+    onOpen,
+    onClose
+  } = opts;
+
+  let isOpen = false;
+  let previousFocus: Element | null = null;
+  let focusTrap: FocusTrap | null = null;
+
+  // Check for native Popover API support
+  const hasPopoverAPI = 'popover' in HTMLElement.prototype;
+
+  // Set up ARIA attributes
+  const setupAria = () => {
+    const panelId = panelEl.id || `popover-${Math.random().toString(36).substr(2, 9)}`;
+    panelEl.id = panelId;
+
+    triggerEl.setAttribute('aria-expanded', 'false');
+    triggerEl.setAttribute('aria-controls', panelId);
+
+    if (type === 'menu') {
+      triggerEl.setAttribute('aria-haspopup', 'menu');
+      panelEl.setAttribute('role', 'menu');
+    } else if (type === 'dialog') {
+      triggerEl.setAttribute('aria-haspopup', 'dialog');
+      panelEl.setAttribute('role', 'dialog');
+      panelEl.setAttribute('aria-modal', 'true');
+    } else if (type === 'tooltip') {
+      triggerEl.setAttribute('aria-describedby', panelId);
+      panelEl.setAttribute('role', 'tooltip');
+    }
+  };
+
+  // Set up native popover if supported
+  const setupNativePopover = () => {
+    if (hasPopoverAPI) {
+      (panelEl as any).popover = type === 'dialog' ? 'manual' : 'auto';
+      triggerEl.setAttribute('popovertarget', panelEl.id);
+    }
+  };
+
+  // Focus trap implementation
+  class FocusTrap {
+    private focusableElements: Element[] = [];
+
+    constructor(private container: Element) {
+      this.updateFocusableElements();
+    }
+
+    private updateFocusableElements() {
+      const selector = 'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])';
+      this.focusableElements = Array.from(this.container.querySelectorAll(selector));
+    }
+
+    activate() {
+      this.updateFocusableElements();
+      if (this.focusableElements.length > 0) {
+        (this.focusableElements[0] as HTMLElement).focus();
+      }
+      document.addEventListener('keydown', this.handleKeyDown);
+    }
+
+    deactivate() {
+      document.removeEventListener('keydown', this.handleKeyDown);
+    }
+
+    private handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key !== 'Tab') return;
+
+      const firstElement = this.focusableElements[0] as HTMLElement;
+      const lastElement = this.focusableElements[this.focusableElements.length - 1] as HTMLElement;
+
+      if (e.shiftKey) {
+        if (document.activeElement === firstElement) {
+          e.preventDefault();
+          lastElement.focus();
+        }
+      } else {
+        if (document.activeElement === lastElement) {
+          e.preventDefault();
+          firstElement.focus();
+        }
+      }
+    };
+  }
+
+  const open = () => {
+    if (isOpen) return;
+
+    if (restoreFocus) {
+      previousFocus = document.activeElement;
+    }
+
+    if (hasPopoverAPI) {
+      (panelEl as any).showPopover();
+    } else {
+      (panelEl as HTMLElement).style.display = 'block';
+      panelEl.setAttribute('data-popover-open', 'true');
+    }
+
+    triggerEl.setAttribute('aria-expanded', 'true');
+    isOpen = true;
+
+    if (trapFocus) {
+      focusTrap = new FocusTrap(panelEl);
+      focusTrap.activate();
+    }
+
+    if (onOpen) {
+      onOpen();
+    }
+  };
+
+  const close = () => {
+    if (!isOpen) return;
+
+    if (hasPopoverAPI) {
+      (panelEl as any).hidePopover();
+    } else {
+      (panelEl as HTMLElement).style.display = 'none';
+      panelEl.removeAttribute('data-popover-open');
+    }
+
+    triggerEl.setAttribute('aria-expanded', 'false');
+    isOpen = false;
+
+    if (focusTrap) {
+      focusTrap.deactivate();
+      focusTrap = null;
+    }
+
+    if (restoreFocus && previousFocus) {
+      (previousFocus as HTMLElement).focus();
+      previousFocus = null;
+    }
+
+    if (onClose) {
+      onClose();
+    }
+  };
+
+  const toggle = () => {
+    if (isOpen) {
+      close();
+    } else {
+      open();
+    }
+  };
+
+  const handleKeyDown = (e: KeyboardEvent) => {
+    if (closeOnEscape && e.key === 'Escape' && isOpen) {
+      e.preventDefault();
+      close();
+    }
+  };
+
+  const handleClick = (e: Event) => {
+    e.preventDefault();
+    toggle();
+  };
+
+  const destroy = () => {
+    triggerEl.removeEventListener('click', handleClick);
+    document.removeEventListener('keydown', handleKeyDown);
+    
+    if (focusTrap) {
+      focusTrap.deactivate();
+    }
+    
+    if (isOpen) {
+      close();
+    }
+  };
+
+  // Initialize
+  setupAria();
+  setupNativePopover();
+  
+  triggerEl.addEventListener('click', handleClick);
+  document.addEventListener('keydown', handleKeyDown);
+
+  return {
+    open,
+    close,
+    toggle,
+    destroy
+  };
+}
+
+// Export default object for convenience
+export default {
+  attach
+};