@sc4rfurryx/proteusjs 1.0.0 → 1.1.0

package/dist/modules/perf.esm.js

@@ -0,0 +1,257 @@
+/*!
+ * ProteusJS v1.1.0
+ * Shape-shifting responsive design that adapts like the sea god himself
+ * (c) 2025 sc4rfurry
+ * Released under the MIT License
+ */
+/**
+ * @sc4rfurryx/proteusjs/perf
+ * Performance guardrails and CWV-friendly patterns
+ *
+ * @version 1.1.0
+ * @author sc4rfurry
+ * @license MIT
+ */
+/**
+ * Apply content-visibility for performance optimization
+ */
+function contentVisibility(selector, mode = 'auto', opts = {}) {
+    const elements = typeof selector === 'string'
+        ? document.querySelectorAll(selector)
+        : [selector];
+    const { containIntrinsicSize = '1000px 400px' } = opts;
+    elements.forEach(element => {
+        const el = element;
+        el.style.contentVisibility = mode;
+        if (mode === 'auto') {
+            el.style.containIntrinsicSize = containIntrinsicSize;
+        }
+    });
+}
+/**
+ * Set fetch priority for resources
+ */
+function fetchPriority(selector, priority) {
+    const elements = typeof selector === 'string'
+        ? document.querySelectorAll(selector)
+        : [selector];
+    elements.forEach(element => {
+        if (element instanceof HTMLImageElement ||
+            element instanceof HTMLLinkElement ||
+            element instanceof HTMLScriptElement) {
+            element.fetchPriority = priority;
+        }
+    });
+}
+/**
+ * Set up speculation rules for prerendering and prefetching
+ */
+function speculate(opts) {
+    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 = {};
+    if (prerender.length > 0) {
+        rules.prerender = prerender.map(url => {
+            const rule = { 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 = { 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
+ */
+async function yieldToBrowser() {
+    // Use scheduler.yield if available (Chrome 115+)
+    if ('scheduler' in window && 'yield' in window.scheduler) {
+        return window.scheduler.yield();
+    }
+    // Use scheduler.postTask if available
+    if ('scheduler' in window && 'postTask' in window.scheduler) {
+        return new Promise(resolve => {
+            window.scheduler.postTask(resolve, { priority: 'user-blocking' });
+        });
+    }
+    // Fallback to setTimeout
+    return new Promise(resolve => {
+        setTimeout(resolve, 0);
+    });
+}
+/**
+ * Optimize images with loading and decoding hints
+ */
+function optimizeImages(selector = 'img') {
+    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.fetchPriority = 'high';
+            }
+        }
+    });
+}
+/**
+ * Preload critical resources
+ */
+function preloadCritical(resources) {
+    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
+ */
+function measureCWV() {
+    return new Promise(resolve => {
+        const metrics = {};
+        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];
+                    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) => {
+                        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) => {
+                        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
+const boost = {
+    contentVisibility,
+    fetchPriority,
+    speculate,
+    yieldToBrowser,
+    optimizeImages,
+    preloadCritical,
+    measureCWV
+};
+// Export all functions as named exports and default object
+var index = {
+    contentVisibility,
+    fetchPriority,
+    speculate,
+    yieldToBrowser,
+    optimizeImages,
+    preloadCritical,
+    measureCWV,
+    boost
+};
+
+export { boost, contentVisibility, index as default, fetchPriority, measureCWV, optimizeImages, preloadCritical, speculate, yieldToBrowser };
+//# sourceMappingURL=perf.esm.js.map

package/dist/modules/perf.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"perf.esm.js","sources":["../../src/modules/perf/index.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/modules/popover.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @sc4rfurryx/proteusjs/popover
+ * HTML Popover API wrapper with robust focus/inert handling
+ *
+ * @version 1.1.0
+ * @author sc4rfurry
+ * @license MIT
+ */
+interface PopoverOptions {
+    type?: 'menu' | 'dialog' | 'tooltip';
+    trapFocus?: boolean;
+    restoreFocus?: boolean;
+    closeOnEscape?: boolean;
+    onOpen?: () => void;
+    onClose?: () => void;
+}
+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
+ */
+declare function attach(trigger: Element | string, panel: Element | string, opts?: PopoverOptions): PopoverController;
+declare const _default: {
+    attach: typeof attach;
+};
+
+export { attach, _default as default };
+export type { PopoverController, PopoverOptions };

package/dist/modules/popover.esm.js

@@ -0,0 +1,191 @@
+/*!
+ * ProteusJS v1.1.0
+ * Shape-shifting responsive design that adapts like the sea god himself
+ * (c) 2025 sc4rfurry
+ * Released under the MIT License
+ */
+/**
+ * @sc4rfurryx/proteusjs/popover
+ * HTML Popover API wrapper with robust focus/inert handling
+ *
+ * @version 1.1.0
+ * @author sc4rfurry
+ * @license MIT
+ */
+/**
+ * Unified API for menus, tooltips, and dialogs using the native Popover API
+ * with robust focus/inert handling
+ */
+function attach(trigger, panel, opts = {}) {
+    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 = null;
+    let focusTrap = 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.popover = type === 'dialog' ? 'manual' : 'auto';
+            triggerEl.setAttribute('popovertarget', panelEl.id);
+        }
+    };
+    // Focus trap implementation
+    class FocusTrap {
+        constructor(container) {
+            this.container = container;
+            this.focusableElements = [];
+            this.handleKeyDown = (e) => {
+                if (e.key !== 'Tab')
+                    return;
+                const firstElement = this.focusableElements[0];
+                const lastElement = this.focusableElements[this.focusableElements.length - 1];
+                if (e.shiftKey) {
+                    if (document.activeElement === firstElement) {
+                        e.preventDefault();
+                        lastElement.focus();
+                    }
+                }
+                else {
+                    if (document.activeElement === lastElement) {
+                        e.preventDefault();
+                        firstElement.focus();
+                    }
+                }
+            };
+            this.updateFocusableElements();
+        }
+        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].focus();
+            }
+            document.addEventListener('keydown', this.handleKeyDown);
+        }
+        deactivate() {
+            document.removeEventListener('keydown', this.handleKeyDown);
+        }
+    }
+    const open = () => {
+        if (isOpen)
+            return;
+        if (restoreFocus) {
+            previousFocus = document.activeElement;
+        }
+        if (hasPopoverAPI) {
+            panelEl.showPopover();
+        }
+        else {
+            panelEl.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.hidePopover();
+        }
+        else {
+            panelEl.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.focus();
+            previousFocus = null;
+        }
+        if (onClose) {
+            onClose();
+        }
+    };
+    const toggle = () => {
+        if (isOpen) {
+            close();
+        }
+        else {
+            open();
+        }
+    };
+    const handleKeyDown = (e) => {
+        if (closeOnEscape && e.key === 'Escape' && isOpen) {
+            e.preventDefault();
+            close();
+        }
+    };
+    const handleClick = (e) => {
+        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
+var index = {
+    attach
+};
+
+export { attach, index as default };
+//# sourceMappingURL=popover.esm.js.map

package/dist/modules/popover.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"popover.esm.js","sources":["../../src/modules/popover/index.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/modules/scroll.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @sc4rfurryx/proteusjs/scroll
+ * Scroll-driven animations with CSS Scroll-Linked Animations
+ *
+ * @version 1.1.0
+ * @author sc4rfurry
+ * @license MIT
+ */
+interface ScrollAnimateOptions {
+    keyframes: Keyframe[];
+    range?: [string, string];
+    timeline?: {
+        axis?: 'block' | 'inline';
+        start?: string;
+        end?: string;
+    };
+    fallback?: 'io' | false;
+}
+/**
+ * Zero-boilerplate setup for CSS Scroll-Linked Animations with fallbacks
+ */
+declare function scrollAnimate(target: Element | string, opts: ScrollAnimateOptions): void;
+/**
+ * Create a scroll-triggered animation that plays once when element enters viewport
+ */
+declare function scrollTrigger(target: Element | string, keyframes: Keyframe[], options?: KeyframeAnimationOptions): void;
+/**
+ * Parallax effect using scroll-driven animations
+ */
+declare function parallax(target: Element | string, speed?: number): void;
+/**
+ * Cleanup function to remove scroll animations
+ */
+declare function cleanup(target: Element | string): void;
+declare const _default: {
+    scrollAnimate: typeof scrollAnimate;
+    scrollTrigger: typeof scrollTrigger;
+    parallax: typeof parallax;
+    cleanup: typeof cleanup;
+};
+
+export { cleanup, _default as default, parallax, scrollAnimate, scrollTrigger };
+export type { ScrollAnimateOptions };