@sc4rfurryx/proteusjs 1.0.0 → 1.1.1

package/dist/modules/container.esm.js

@@ -0,0 +1,194 @@
+/*!
+ * ProteusJS v1.1.1
+ * Shape-shifting responsive design that adapts like the sea god himself
+ * (c) 2025 sc4rfurry
+ * Released under the MIT License
+ */
+/**
+ * @sc4rfurryx/proteusjs/container
+ * Container/Style Query helpers with visualization devtools
+ *
+ * @version 1.1.0
+ * @author sc4rfurry
+ * @license MIT
+ */
+/**
+ * Sugar on native container queries with dev visualization
+ */
+function defineContainer(target, name, opts = {}) {
+    const targetEl = typeof target === 'string' ? document.querySelector(target) : target;
+    if (!targetEl) {
+        throw new Error('Target element not found');
+    }
+    const { type = 'size', inlineSize: _inlineSize = true } = opts;
+    const containerName = name || `container-${Math.random().toString(36).substring(2, 11)}`;
+    // Apply container properties
+    const element = targetEl;
+    element.style.containerName = containerName;
+    element.style.containerType = type;
+    // Warn if containment settings are missing
+    const computedStyle = getComputedStyle(element);
+    if (!computedStyle.contain || computedStyle.contain === 'none') {
+        console.warn(`Container "${containerName}" may need explicit containment settings for optimal performance`);
+    }
+    // Dev overlay (only in development)
+    if (process.env['NODE_ENV'] === 'development' || window.__PROTEUS_DEV__) {
+        createDevOverlay(element, containerName);
+    }
+}
+/**
+ * Create development overlay showing container bounds and breakpoints
+ */
+function createDevOverlay(element, name) {
+    const overlay = document.createElement('div');
+    overlay.className = 'proteus-container-overlay';
+    overlay.style.cssText = `
+    position: absolute;
+    top: 0;
+    left: 0;
+    right: 0;
+    bottom: 0;
+    pointer-events: none;
+    border: 2px dashed rgba(255, 0, 255, 0.5);
+    background: rgba(255, 0, 255, 0.05);
+    z-index: 9999;
+    font-family: monospace;
+    font-size: 12px;
+    color: #ff00ff;
+  `;
+    const label = document.createElement('div');
+    label.style.cssText = `
+    position: absolute;
+    top: -20px;
+    left: 0;
+    background: rgba(255, 0, 255, 0.9);
+    color: white;
+    padding: 2px 6px;
+    border-radius: 3px;
+    font-size: 10px;
+    white-space: nowrap;
+  `;
+    label.textContent = `Container: ${name}`;
+    const sizeInfo = document.createElement('div');
+    sizeInfo.style.cssText = `
+    position: absolute;
+    bottom: 2px;
+    right: 2px;
+    background: rgba(0, 0, 0, 0.7);
+    color: white;
+    padding: 2px 4px;
+    border-radius: 2px;
+    font-size: 10px;
+  `;
+    overlay.appendChild(label);
+    overlay.appendChild(sizeInfo);
+    // Position overlay relative to container
+    if (getComputedStyle(element).position === 'static') {
+        element.style.position = 'relative';
+    }
+    element.appendChild(overlay);
+    // Update size info
+    const updateSizeInfo = () => {
+        const rect = element.getBoundingClientRect();
+        sizeInfo.textContent = `${Math.round(rect.width)}×${Math.round(rect.height)}`;
+    };
+    updateSizeInfo();
+    // Update on resize
+    if ('ResizeObserver' in window) {
+        const resizeObserver = new ResizeObserver(updateSizeInfo);
+        resizeObserver.observe(element);
+    }
+    // Store cleanup function
+    element._proteusContainerCleanup = () => {
+        overlay.remove();
+    };
+}
+/**
+ * Helper to create container query CSS rules
+ */
+function createContainerQuery(containerName, condition, styles) {
+    const cssRules = Object.entries(styles)
+        .map(([property, value]) => `  ${property}: ${value};`)
+        .join('\n');
+    return `@container ${containerName} (${condition}) {\n${cssRules}\n}`;
+}
+/**
+ * Apply container query styles dynamically
+ */
+function applyContainerQuery(containerName, condition, styles) {
+    const css = createContainerQuery(containerName, condition, styles);
+    const styleElement = document.createElement('style');
+    styleElement.textContent = css;
+    styleElement.setAttribute('data-proteus-container', containerName);
+    document.head.appendChild(styleElement);
+}
+/**
+ * Remove container query styles
+ */
+function removeContainerQuery(containerName) {
+    const styleElements = document.querySelectorAll(`style[data-proteus-container="${containerName}"]`);
+    styleElements.forEach(element => element.remove());
+}
+/**
+ * Get container size information
+ */
+function getContainerSize(target) {
+    const targetEl = typeof target === 'string' ? document.querySelector(target) : target;
+    if (!targetEl) {
+        throw new Error('Target element not found');
+    }
+    const rect = targetEl.getBoundingClientRect();
+    return {
+        width: rect.width,
+        height: rect.height
+    };
+}
+/**
+ * Check if container queries are supported
+ */
+function isSupported() {
+    return CSS.supports('container-type', 'size');
+}
+/**
+ * Cleanup container overlays and observers
+ */
+function cleanup(target) {
+    const targetEl = typeof target === 'string' ? document.querySelector(target) : target;
+    if (!targetEl)
+        return;
+    // Call stored cleanup function if it exists
+    const elementWithCleanup = targetEl;
+    if (elementWithCleanup._proteusContainerCleanup) {
+        elementWithCleanup._proteusContainerCleanup();
+        delete elementWithCleanup._proteusContainerCleanup;
+    }
+}
+/**
+ * Toggle dev overlay visibility
+ */
+function toggleDevOverlay(visible) {
+    const overlays = document.querySelectorAll('.proteus-container-overlay');
+    overlays.forEach(overlay => {
+        const element = overlay;
+        if (visible !== undefined) {
+            element.style.display = visible ? 'block' : 'none';
+        }
+        else {
+            element.style.display = element.style.display === 'none' ? 'block' : 'none';
+        }
+    });
+}
+// Export default object for convenience
+var index = {
+    defineContainer,
+    createContainerQuery,
+    applyContainerQuery,
+    removeContainerQuery,
+    getContainerSize,
+    isSupported,
+    cleanup,
+    toggleDevOverlay
+};
+
+export { applyContainerQuery, cleanup, createContainerQuery, index as default, defineContainer, getContainerSize, isSupported, removeContainerQuery, toggleDevOverlay };
+//# sourceMappingURL=container.esm.js.map

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

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

package/dist/modules/perf.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @sc4rfurryx/proteusjs/perf
+ * Performance guardrails and CWV-friendly patterns
+ *
+ * @version 1.1.0
+ * @author sc4rfurry
+ * @license MIT
+ */
+interface SpeculationOptions {
+    prerender?: string[];
+    prefetch?: string[];
+    sameOriginOnly?: boolean;
+}
+interface ContentVisibilityOptions {
+    containIntrinsicSize?: string;
+}
+/**
+ * Apply content-visibility for performance optimization
+ */
+declare function contentVisibility(selector: string | Element, mode?: 'auto' | 'hidden', opts?: ContentVisibilityOptions): void;
+/**
+ * Set fetch priority for resources
+ */
+declare function fetchPriority(selector: string | Element, priority: 'high' | 'low' | 'auto'): void;
+/**
+ * Set up speculation rules for prerendering and prefetching
+ */
+declare function speculate(opts: SpeculationOptions): void;
+/**
+ * Yield to browser using scheduler.yield or postTask when available
+ */
+declare function yieldToBrowser(): Promise<void>;
+/**
+ * Optimize images with loading and decoding hints
+ */
+declare function optimizeImages(selector?: string | Element): void;
+/**
+ * Preload critical resources
+ */
+declare function preloadCritical(resources: Array<{
+    href: string;
+    as: string;
+    type?: string;
+}>): void;
+/**
+ * Measure and report Core Web Vitals
+ */
+declare function measureCWV(): Promise<{
+    lcp?: number;
+    fid?: number;
+    cls?: number;
+}>;
+declare const boost: {
+    contentVisibility: typeof contentVisibility;
+    fetchPriority: typeof fetchPriority;
+    speculate: typeof speculate;
+    yieldToBrowser: typeof yieldToBrowser;
+    optimizeImages: typeof optimizeImages;
+    preloadCritical: typeof preloadCritical;
+    measureCWV: typeof measureCWV;
+};
+declare const _default: {
+    contentVisibility: typeof contentVisibility;
+    fetchPriority: typeof fetchPriority;
+    speculate: typeof speculate;
+    yieldToBrowser: typeof yieldToBrowser;
+    optimizeImages: typeof optimizeImages;
+    preloadCritical: typeof preloadCritical;
+    measureCWV: typeof measureCWV;
+    boost: {
+        contentVisibility: typeof contentVisibility;
+        fetchPriority: typeof fetchPriority;
+        speculate: typeof speculate;
+        yieldToBrowser: typeof yieldToBrowser;
+        optimizeImages: typeof optimizeImages;
+        preloadCritical: typeof preloadCritical;
+        measureCWV: typeof measureCWV;
+    };
+};
+
+export { boost, contentVisibility, _default as default, fetchPriority, measureCWV, optimizeImages, preloadCritical, speculate, yieldToBrowser };
+export type { ContentVisibilityOptions, SpeculationOptions };

package/dist/modules/perf.esm.js

@@ -0,0 +1,257 @@
+/*!
+ * ProteusJS v1.1.1
+ * 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 };