microui-wc 0.1.0

package/src/core/render.js

@@ -0,0 +1,201 @@
+/**
+ * @fileoverview Render Utilities for Large-Scale Applications
+ * 
+ * Optimizes rendering for complex apps with thousands of components.
+ * 
+ * Features:
+ * - requestAnimationFrame batching
+ * - Lazy component rendering
+ * - Intersection Observer for viewport-based rendering
+ * - Memoization for expensive computations
+ */
+
+/**
+ * Batch multiple DOM updates into single animation frame
+ * Prevents layout thrashing in complex updates
+ */
+class RenderScheduler {
+    #queue = [];
+    #scheduled = false;
+
+    /**
+     * Schedule a render callback for next animation frame
+     * Multiple calls are batched together
+     */
+    schedule(callback) {
+        this.#queue.push(callback);
+
+        if (!this.#scheduled) {
+            this.#scheduled = true;
+            requestAnimationFrame(() => this.#flush());
+        }
+    }
+
+    #flush() {
+        const callbacks = this.#queue.slice();
+        this.#queue = [];
+        this.#scheduled = false;
+
+        // Execute all callbacks in single frame
+        for (const cb of callbacks) {
+            try {
+                cb();
+            } catch (e) {
+                console.error('[RenderScheduler] Error:', e);
+            }
+        }
+    }
+}
+
+export const scheduler = new RenderScheduler();
+
+/**
+ * Memoize expensive function calls
+ * @param {Function} fn - Function to memoize
+ * @param {Function} keyFn - Optional key function for cache
+ */
+export function memo(fn, keyFn = JSON.stringify) {
+    const cache = new Map();
+
+    return (...args) => {
+        const key = keyFn(args);
+
+        if (cache.has(key)) {
+            return cache.get(key);
+        }
+
+        const result = fn(...args);
+        cache.set(key, result);
+        return result;
+    };
+}
+
+/**
+ * Debounce function calls
+ * @param {Function} fn 
+ * @param {number} delay - Delay in ms
+ */
+export function debounce(fn, delay = 100) {
+    let timer = null;
+
+    return (...args) => {
+        if (timer) clearTimeout(timer);
+        timer = setTimeout(() => fn(...args), delay);
+    };
+}
+
+/**
+ * Throttle function calls
+ * @param {Function} fn 
+ * @param {number} limit - Minimum time between calls in ms
+ */
+export function throttle(fn, limit = 100) {
+    let inThrottle = false;
+
+    return (...args) => {
+        if (!inThrottle) {
+            fn(...args);
+            inThrottle = true;
+            setTimeout(() => inThrottle = false, limit);
+        }
+    };
+}
+
+/**
+ * Create an intersection observer for lazy rendering
+ * @param {Function} onVisible - Called when element becomes visible
+ * @param {Object} options - IntersectionObserver options
+ */
+export function createVisibilityObserver(onVisible, options = {}) {
+    const observer = new IntersectionObserver((entries) => {
+        for (const entry of entries) {
+            if (entry.isIntersecting) {
+                onVisible(entry.target);
+                observer.unobserve(entry.target);
+            }
+        }
+    }, {
+        rootMargin: '100px',
+        threshold: 0,
+        ...options
+    });
+
+    return {
+        observe: (el) => observer.observe(el),
+        disconnect: () => observer.disconnect()
+    };
+}
+
+/**
+ * Batch DOM reads and writes to prevent layout thrashing
+ * Based on fastdom pattern
+ */
+class DomBatch {
+    #reads = [];
+    #writes = [];
+    #scheduled = false;
+
+    /**
+     * Schedule a DOM read (measure)
+     */
+    read(fn) {
+        this.#reads.push(fn);
+        this.#schedule();
+    }
+
+    /**
+     * Schedule a DOM write (mutate)
+     */
+    write(fn) {
+        this.#writes.push(fn);
+        this.#schedule();
+    }
+
+    #schedule() {
+        if (!this.#scheduled) {
+            this.#scheduled = true;
+            requestAnimationFrame(() => this.#flush());
+        }
+    }
+
+    #flush() {
+        // Reads first (measure phase)
+        let fn;
+        while (fn = this.#reads.shift()) {
+            try { fn(); } catch (e) { console.error(e); }
+        }
+
+        // Writes second (mutate phase)
+        while (fn = this.#writes.shift()) {
+            try { fn(); } catch (e) { console.error(e); }
+        }
+
+        this.#scheduled = false;
+
+        // If more work was added during flush, schedule again
+        if (this.#reads.length || this.#writes.length) {
+            this.#schedule();
+        }
+    }
+}
+
+export const domBatch = new DomBatch();
+
+/**
+ * Chunk large array operations to avoid blocking main thread
+ * @param {Array} items - Array to process
+ * @param {Function} processFn - Function to call for each item
+ * @param {number} chunkSize - Items per chunk
+ */
+export async function processInChunks(items, processFn, chunkSize = 100) {
+    for (let i = 0; i < items.length; i += chunkSize) {
+        const chunk = items.slice(i, i + chunkSize);
+
+        for (const item of chunk) {
+            processFn(item, i);
+        }
+
+        // Yield to main thread between chunks
+        await new Promise(r => setTimeout(r, 0));
+    }
+}

package/src/core/ripple.js

@@ -0,0 +1,158 @@
+/**
+ * @fileoverview MD3 Ripple Effect Utility
+ * 
+ * Creates Material Design 3 compliant ripple effects on interactive elements.
+ * The ripple originates from the exact click/touch point and expands outward.
+ * 
+ * Usage:
+ *   import { attachRipple } from './core/ripple.js';
+ *   attachRipple(element);
+ * 
+ * Or for controlled ripple:
+ *   import { createRipple } from './core/ripple.js';
+ *   element.addEventListener('click', (e) => createRipple(element, e));
+ */
+
+/**
+ * Create a ripple effect at the event position within the element.
+ * MD3 behavior: ripple expands immediately, persists while pressed, fades on release.
+ * @param {HTMLElement} element - Container element for the ripple
+ * @param {MouseEvent|TouchEvent} event - The triggering event
+ * @param {Object} options - Ripple options
+ * @param {string} options.color - Ripple color (default: currentColor)
+ * @param {boolean} options.centered - Force ripple to start from center
+ */
+export function createRipple(element, event, options = {}) {
+    const { color = 'currentColor', centered = false } = options;
+
+    // Get element bounds
+    const rect = element.getBoundingClientRect();
+
+    // Calculate ripple position (from click point or center)
+    let x, y;
+    if (centered || !event) {
+        x = rect.width / 2;
+        y = rect.height / 2;
+    } else {
+        // Get click/touch position
+        const clientX = event.touches ? event.touches[0].clientX : event.clientX;
+        const clientY = event.touches ? event.touches[0].clientY : event.clientY;
+        x = clientX - rect.left;
+        y = clientY - rect.top;
+    }
+
+    // Calculate ripple size (must cover entire element from click point)
+    const size = Math.max(
+        Math.hypot(x, y),
+        Math.hypot(rect.width - x, y),
+        Math.hypot(x, rect.height - y),
+        Math.hypot(rect.width - x, rect.height - y)
+    ) * 2;
+
+    // Create ripple element
+    const ripple = document.createElement('span');
+    ripple.className = 'mu-ripple-wave';
+    ripple.style.cssText = `
+        position: absolute;
+        width: ${size}px;
+        height: ${size}px;
+        left: ${x - size / 2}px;
+        top: ${y - size / 2}px;
+        background: ${color};
+        border-radius: 50%;
+        transform: scale(0);
+        opacity: 0.10;
+        pointer-events: none;
+    `;
+
+    // Ensure container has proper positioning
+    const computedStyle = getComputedStyle(element);
+    if (computedStyle.position === 'static') {
+        element.style.position = 'relative';
+    }
+    if (computedStyle.overflow !== 'hidden') {
+        element.style.overflow = 'hidden';
+    }
+
+    // Add ripple to element
+    element.appendChild(ripple);
+
+    // Phase 1: Expand animation (GPU - transform only)
+    ripple.animate([
+        { transform: 'scale(0)' },
+        { transform: 'scale(1)' }
+    ], {
+        duration: 300,
+        easing: 'cubic-bezier(0.4, 0, 0.2, 1)',
+        fill: 'forwards'
+    });
+
+    // Phase 2: Fade out on release (pointer up or leave)
+    const fadeOut = () => {
+        ripple.animate([
+            { opacity: '0.10' },
+            { opacity: '0' }
+        ], {
+            duration: 150,
+            easing: 'ease-out',
+            fill: 'forwards'
+        }).onfinish = () => ripple.remove();
+
+        // Cleanup listeners
+        element.removeEventListener('pointerup', fadeOut);
+        element.removeEventListener('pointerleave', fadeOut);
+        element.removeEventListener('pointercancel', fadeOut);
+    };
+
+    element.addEventListener('pointerup', fadeOut, { once: true });
+    element.addEventListener('pointerleave', fadeOut, { once: true });
+    element.addEventListener('pointercancel', fadeOut, { once: true });
+
+    return ripple;
+}
+
+/**
+ * Attach ripple effect to an element.
+ * @param {HTMLElement} element - Element to attach ripple to
+ * @param {Object} options - Ripple options
+ * @returns {Function} Cleanup function to remove ripple listener
+ */
+export function attachRipple(element, options = {}) {
+    const handler = (e) => {
+        // Don't create ripple if element is disabled
+        if (element.hasAttribute('disabled')) return;
+        createRipple(element, e, options);
+    };
+
+    element.addEventListener('pointerdown', handler);
+
+    // Return cleanup function
+    return () => {
+        element.removeEventListener('pointerdown', handler);
+    };
+}
+
+/**
+ * Mixin for components that need ripple.
+ * Call this.initRipple(targetElement) in connectedCallback.
+ */
+export const RippleMixin = (superclass) => class extends superclass {
+    #rippleCleanup = null;
+
+    /**
+     * Initialize ripple on target element (or self).
+     * @param {HTMLElement} target - Element to add ripple to (defaults to this)
+     * @param {Object} options - Ripple options
+     */
+    initRipple(target = this, options = {}) {
+        this.#rippleCleanup = attachRipple(target, options);
+    }
+
+    disconnectedCallback() {
+        if (this.#rippleCleanup) {
+            this.#rippleCleanup();
+            this.#rippleCleanup = null;
+        }
+        super.disconnectedCallback?.();
+    }
+};

package/src/core/router.js

@@ -0,0 +1,100 @@
+/**
+ * @fileoverview Simple SPA Router for microUI
+ * 
+ * Hash-based routing for single page applications.
+ * 
+ * Usage:
+ * Router.on('/', () => renderHome());
+ * Router.on('/about', () => renderAbout());
+ * Router.on('/user/:id', ({ id }) => renderUser(id));
+ * Router.start();
+ */
+
+class RouterClass {
+    #routes = [];
+    #notFound = null;
+    #currentPath = '';
+
+    /**
+     * Register a route
+     * @param {string} path - Route path (supports :param)
+     * @param {(params: Object) => void} handler
+     */
+    on(path, handler) {
+        // Convert path params to regex
+        const pattern = path
+            .replace(/:[a-zA-Z]+/g, '([^/]+)')
+            .replace(/\//g, '\\/');
+
+        const paramNames = (path.match(/:[a-zA-Z]+/g) || [])
+            .map(p => p.slice(1));
+
+        this.#routes.push({
+            path,
+            pattern: new RegExp(`^${pattern}$`),
+            paramNames,
+            handler
+        });
+
+        return this;
+    }
+
+    /**
+     * Set 404 handler
+     */
+    notFound(handler) {
+        this.#notFound = handler;
+        return this;
+    }
+
+    /**
+     * Navigate to a path
+     * @param {string} path
+     */
+    navigate(path) {
+        window.location.hash = path;
+    }
+
+    /**
+     * Get current path
+     */
+    get current() {
+        return this.#currentPath;
+    }
+
+    /**
+     * Start the router
+     */
+    start() {
+        const handleRoute = () => {
+            const hash = window.location.hash.slice(1) || '/';
+            this.#currentPath = hash;
+
+            for (const route of this.#routes) {
+                const match = hash.match(route.pattern);
+                if (match) {
+                    // Extract params
+                    const params = {};
+                    route.paramNames.forEach((name, i) => {
+                        params[name] = match[i + 1];
+                    });
+
+                    route.handler(params);
+                    return;
+                }
+            }
+
+            // No match - 404
+            if (this.#notFound) {
+                this.#notFound(hash);
+            }
+        };
+
+        window.addEventListener('hashchange', handleRoute);
+        handleRoute(); // Handle initial route
+
+        return this;
+    }
+}
+
+export const Router = new RouterClass();

package/src/core/scheduler.js

@@ -0,0 +1,109 @@
+/**
+ * @fileoverview Task Scheduler API (2026 SOTA)
+ * 
+ * Uses scheduler.postTask() for priority-based scheduling.
+ * Falls back to setTimeout if not supported.
+ * 
+ * Priority levels:
+ * - 'user-blocking': Highest priority (input handlers)
+ * - 'user-visible': Medium priority (rendering)
+ * - 'background': Lowest priority (analytics, prefetch)
+ * 
+ * Usage:
+ * await scheduleTask(() => heavyComputation(), 'background');
+ * await yieldToMain();
+ */
+
+/**
+ * Check if Scheduler API is supported
+ */
+export const supportsScheduler = 'scheduler' in globalThis;
+
+/**
+ * Schedule a task with priority
+ * @param {() => T} callback 
+ * @param {'user-blocking' | 'user-visible' | 'background'} priority 
+ * @returns {Promise<T>}
+ */
+export async function scheduleTask(callback, priority = 'user-visible') {
+    if (supportsScheduler) {
+        return globalThis.scheduler.postTask(callback, { priority });
+    }
+
+    // Fallback with setTimeout based on priority
+    const delay = priority === 'user-blocking' ? 0 :
+        priority === 'user-visible' ? 0 : 1;
+
+    return new Promise(resolve => {
+        setTimeout(() => resolve(callback()), delay);
+    });
+}
+
+/**
+ * Yield to main thread (allow input/rendering)
+ * @returns {Promise<void>}
+ */
+export async function yieldToMain() {
+    if (supportsScheduler && 'yield' in globalThis.scheduler) {
+        return globalThis.scheduler.yield();
+    }
+
+    // Fallback: yield with setTimeout
+    return new Promise(resolve => setTimeout(resolve, 0));
+}
+
+/**
+ * Process items in chunks, yielding between chunks
+ * Better than processInChunks because it uses scheduler.yield()
+ * 
+ * @param {T[]} items 
+ * @param {(item: T, index: number) => void} process 
+ * @param {number} chunkSize
+ */
+export async function processWithYield(items, process, chunkSize = 50) {
+    for (let i = 0; i < items.length; i++) {
+        process(items[i], i);
+
+        // Yield every chunk
+        if ((i + 1) % chunkSize === 0) {
+            await yieldToMain();
+        }
+    }
+}
+
+/**
+ * Run background task (lowest priority, won't block UI)
+ * @param {() => T} callback 
+ * @returns {Promise<T>}
+ */
+export function runBackground(callback) {
+    return scheduleTask(callback, 'background');
+}
+
+/**
+ * Run user-blocking task (highest priority)
+ * @param {() => T} callback 
+ * @returns {Promise<T>}
+ */
+export function runImmediate(callback) {
+    return scheduleTask(callback, 'user-blocking');
+}
+
+/**
+ * Wait for next browser paint (double-rAF pattern)
+ * Use for CSS animation triggers after DOM changes.
+ * This ensures the browser has completed layout/paint before applying
+ * additional classes that would trigger transitions.
+ * 
+ * @returns {Promise<void>}
+ * @example
+ * // Trigger CSS animation after DOM change
+ * element.classList.add('is-open');
+ * await afterPaint();
+ * element.classList.add('is-visible'); // Now transition will animate
+ */
+export function afterPaint() {
+    return new Promise(resolve => {
+        requestAnimationFrame(() => requestAnimationFrame(resolve));
+    });
+}