@sc4rfurryx/proteusjs 1.0.0 → 1.1.0

package/dist/modules/anchor.esm.js

@@ -0,0 +1,218 @@
+/*!
+ * 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/anchor
+ * CSS Anchor Positioning utilities with robust JS fallback
+ *
+ * @version 1.1.0
+ * @author sc4rfurry
+ * @license MIT
+ */
+/**
+ * Declarative tethers (tooltips, callouts) via CSS Anchor Positioning when available;
+ * robust JS fallback with flip/collision detection
+ */
+function tether(floating, opts) {
+    const floatingEl = typeof floating === 'string' ? document.querySelector(floating) : floating;
+    const anchorEl = typeof opts.anchor === 'string' ? document.querySelector(opts.anchor) : opts.anchor;
+    if (!floatingEl || !anchorEl) {
+        throw new Error('Both floating and anchor elements must exist');
+    }
+    const { placement = 'bottom', align = 'center', offset = 8, strategy = 'absolute' } = opts;
+    // Check for CSS Anchor Positioning support
+    const hasAnchorPositioning = CSS.supports('anchor-name', 'test');
+    let isDestroyed = false;
+    let resizeObserver = null;
+    const setupCSSAnchorPositioning = () => {
+        if (!hasAnchorPositioning)
+            return false;
+        // Generate unique anchor name
+        const anchorName = `anchor-${Math.random().toString(36).substring(2, 11)}`;
+        // Set anchor name on anchor element
+        anchorEl.style.setProperty('anchor-name', anchorName);
+        // Position floating element using CSS anchor positioning
+        const floatingStyle = floatingEl;
+        floatingStyle.style.position = strategy;
+        floatingStyle.style.setProperty('position-anchor', anchorName);
+        // Set position based on placement
+        switch (placement) {
+            case 'top':
+                floatingStyle.style.bottom = `anchor(bottom, ${offset}px)`;
+                break;
+            case 'bottom':
+                floatingStyle.style.top = `anchor(bottom, ${offset}px)`;
+                break;
+            case 'left':
+                floatingStyle.style.right = `anchor(left, ${offset}px)`;
+                break;
+            case 'right':
+                floatingStyle.style.left = `anchor(right, ${offset}px)`;
+                break;
+        }
+        // Set alignment
+        if (placement === 'top' || placement === 'bottom') {
+            switch (align) {
+                case 'start':
+                    floatingStyle.style.left = 'anchor(left)';
+                    break;
+                case 'center':
+                    floatingStyle.style.left = 'anchor(center)';
+                    floatingStyle.style.transform = 'translateX(-50%)';
+                    break;
+                case 'end':
+                    floatingStyle.style.right = 'anchor(right)';
+                    break;
+            }
+        }
+        else {
+            switch (align) {
+                case 'start':
+                    floatingStyle.style.top = 'anchor(top)';
+                    break;
+                case 'center':
+                    floatingStyle.style.top = 'anchor(center)';
+                    floatingStyle.style.transform = 'translateY(-50%)';
+                    break;
+                case 'end':
+                    floatingStyle.style.bottom = 'anchor(bottom)';
+                    break;
+            }
+        }
+        return true;
+    };
+    const calculatePosition = () => {
+        const anchorRect = anchorEl.getBoundingClientRect();
+        const floatingRect = floatingEl.getBoundingClientRect();
+        const viewport = {
+            width: window.innerWidth,
+            height: window.innerHeight
+        };
+        let finalPlacement = placement;
+        let x = 0;
+        let y = 0;
+        // Calculate base position
+        switch (finalPlacement) {
+            case 'top':
+                x = anchorRect.left;
+                y = anchorRect.top - floatingRect.height - offset;
+                break;
+            case 'bottom':
+                x = anchorRect.left;
+                y = anchorRect.bottom + offset;
+                break;
+            case 'left':
+                x = anchorRect.left - floatingRect.width - offset;
+                y = anchorRect.top;
+                break;
+            case 'right':
+                x = anchorRect.right + offset;
+                y = anchorRect.top;
+                break;
+            case 'auto': {
+                // Choose best placement based on available space
+                const spaces = {
+                    top: anchorRect.top,
+                    bottom: viewport.height - anchorRect.bottom,
+                    left: anchorRect.left,
+                    right: viewport.width - anchorRect.right
+                };
+                const bestPlacement = Object.entries(spaces).reduce((a, b) => spaces[a[0]] > spaces[b[0]] ? a : b)[0];
+                finalPlacement = bestPlacement;
+                return calculatePosition(); // Recursive call with determined placement
+            }
+        }
+        // Apply alignment
+        if (finalPlacement === 'top' || finalPlacement === 'bottom') {
+            switch (align) {
+                case 'start':
+                    // x already set correctly
+                    break;
+                case 'center':
+                    x = anchorRect.left + (anchorRect.width - floatingRect.width) / 2;
+                    break;
+                case 'end':
+                    x = anchorRect.right - floatingRect.width;
+                    break;
+            }
+        }
+        else {
+            switch (align) {
+                case 'start':
+                    // y already set correctly
+                    break;
+                case 'center':
+                    y = anchorRect.top + (anchorRect.height - floatingRect.height) / 2;
+                    break;
+                case 'end':
+                    y = anchorRect.bottom - floatingRect.height;
+                    break;
+            }
+        }
+        // Collision detection and adjustment
+        if (x < 0)
+            x = 8;
+        if (y < 0)
+            y = 8;
+        if (x + floatingRect.width > viewport.width) {
+            x = viewport.width - floatingRect.width - 8;
+        }
+        if (y + floatingRect.height > viewport.height) {
+            y = viewport.height - floatingRect.height - 8;
+        }
+        return { x, y };
+    };
+    const updatePosition = () => {
+        if (isDestroyed)
+            return;
+        if (!hasAnchorPositioning) {
+            const { x, y } = calculatePosition();
+            const floatingStyle = floatingEl;
+            floatingStyle.style.position = strategy;
+            floatingStyle.style.left = `${x}px`;
+            floatingStyle.style.top = `${y}px`;
+        }
+    };
+    const setupJSFallback = () => {
+        updatePosition();
+        // Set up observers for position updates
+        resizeObserver = new ResizeObserver(updatePosition);
+        resizeObserver.observe(anchorEl);
+        resizeObserver.observe(floatingEl);
+        window.addEventListener('scroll', updatePosition, { passive: true });
+        window.addEventListener('resize', updatePosition, { passive: true });
+    };
+    const destroy = () => {
+        isDestroyed = true;
+        if (resizeObserver) {
+            resizeObserver.disconnect();
+            resizeObserver = null;
+        }
+        window.removeEventListener('scroll', updatePosition);
+        window.removeEventListener('resize', updatePosition);
+        // Clean up CSS anchor positioning
+        if (hasAnchorPositioning) {
+            anchorEl.style.removeProperty('anchor-name');
+            const floatingStyle = floatingEl;
+            floatingStyle.style.removeProperty('position-anchor');
+            floatingStyle.style.position = '';
+        }
+    };
+    // Initialize
+    if (!setupCSSAnchorPositioning()) {
+        setupJSFallback();
+    }
+    return {
+        destroy
+    };
+}
+// Export default object for convenience
+var index = {
+    tether
+};
+
+export { index as default, tether };
+//# sourceMappingURL=anchor.esm.js.map

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

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

package/dist/modules/container.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @sc4rfurryx/proteusjs/container
+ * Container/Style Query helpers with visualization devtools
+ *
+ * @version 1.1.0
+ * @author sc4rfurry
+ * @license MIT
+ */
+interface ContainerOptions {
+    type?: 'size' | 'style';
+    inlineSize?: boolean;
+}
+/**
+ * Sugar on native container queries with dev visualization
+ */
+declare function defineContainer(target: Element | string, name?: string, opts?: ContainerOptions): void;
+/**
+ * Helper to create container query CSS rules
+ */
+declare function createContainerQuery(containerName: string, condition: string, styles: Record<string, string>): string;
+/**
+ * Apply container query styles dynamically
+ */
+declare function applyContainerQuery(containerName: string, condition: string, styles: Record<string, string>): void;
+/**
+ * Remove container query styles
+ */
+declare function removeContainerQuery(containerName: string): void;
+/**
+ * Get container size information
+ */
+declare function getContainerSize(target: Element | string): {
+    width: number;
+    height: number;
+};
+/**
+ * Check if container queries are supported
+ */
+declare function isSupported(): boolean;
+/**
+ * Cleanup container overlays and observers
+ */
+declare function cleanup(target: Element | string): void;
+/**
+ * Toggle dev overlay visibility
+ */
+declare function toggleDevOverlay(visible?: boolean): void;
+declare const _default: {
+    defineContainer: typeof defineContainer;
+    createContainerQuery: typeof createContainerQuery;
+    applyContainerQuery: typeof applyContainerQuery;
+    removeContainerQuery: typeof removeContainerQuery;
+    getContainerSize: typeof getContainerSize;
+    isSupported: typeof isSupported;
+    cleanup: typeof cleanup;
+    toggleDevOverlay: typeof toggleDevOverlay;
+};
+
+export { applyContainerQuery, cleanup, createContainerQuery, _default as default, defineContainer, getContainerSize, isSupported, removeContainerQuery, toggleDevOverlay };
+export type { ContainerOptions };

package/dist/modules/container.esm.js

@@ -0,0 +1,194 @@
+/*!
+ * 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/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 };