microui-wc 0.1.0

package/src/core/signals.js

@@ -0,0 +1,164 @@
+/**
+ * @fileoverview Signals - Fine-Grained Reactivity via EventBus (2026 SOTA)
+ * 
+ * Built on top of microUI's EventBus for consistent event architecture.
+ * Enables reactive updates without VDOM diffing.
+ * 
+ * Usage:
+ * const count = signal(0, 'count');
+ * effect((bus) => bus.on('signal:count', (v) => console.log(v)));
+ * count.set(5); // Emits 'signal:count' on bus
+ */
+
+import { bus } from './bus.js';
+
+let signalId = 0;
+
+/**
+ * Create a reactive signal backed by EventBus
+ * @param {T} initialValue 
+ * @param {string} name - Optional name for debugging
+ * @returns {Signal<T>}
+ */
+export function signal(initialValue, name) {
+    let value = initialValue;
+    const id = name || `signal_${++signalId}`;
+    const eventName = `signal:${id}`;
+    const subscribers = new Set();
+
+    // Read function
+    const read = () => {
+        // Track in current computation
+        if (currentComputation) {
+            const unsub = bus.on(eventName, currentComputation);
+            subscribers.add(unsub);
+        }
+        return value;
+    };
+
+    // Set value and emit on bus
+    read.set = (newValue) => {
+        if (value !== newValue) {
+            const oldValue = value;
+            value = newValue;
+
+            // Emit change event on bus
+            bus.emit(eventName, { value: newValue, oldValue, signal: id });
+        }
+    };
+
+    // Update with function
+    read.update = (fn) => {
+        read.set(fn(value));
+    };
+
+    // Get value without tracking
+    read.peek = () => value;
+
+    // Get signal name (using signalName since Function.name is readonly)
+    read.signalName = id;
+
+    // Subscribe to this signal via bus
+    read.subscribe = (callback) => {
+        return bus.on(eventName, (data) => callback(data.value, data.oldValue));
+    };
+
+    // Cleanup
+    read.dispose = () => {
+        for (const unsub of subscribers) {
+            unsub();
+        }
+        subscribers.clear();
+    };
+
+    return read;
+}
+
+// Current computation being tracked
+let currentComputation = null;
+
+/**
+ * Create a computed signal (derived)
+ * Re-computes when dependencies change via bus events
+ */
+export function computed(fn, name) {
+    const id = name || `computed_${++signalId}`;
+    const eventName = `signal:${id}`;
+    let cachedValue;
+    let dirty = true;
+
+    const recompute = () => {
+        dirty = true;
+        const newValue = fn();
+        if (cachedValue !== newValue) {
+            cachedValue = newValue;
+            bus.emit(eventName, { value: newValue, signal: id });
+        }
+    };
+
+    const read = () => {
+        if (dirty) {
+            const prevComputation = currentComputation;
+            currentComputation = recompute;
+            try {
+                cachedValue = fn();
+            } finally {
+                currentComputation = prevComputation;
+            }
+            dirty = false;
+        }
+
+        // Track in parent computation
+        if (currentComputation) {
+            bus.on(eventName, currentComputation);
+        }
+
+        return cachedValue;
+    };
+
+    read.signalName = id;
+    read.subscribe = (callback) => bus.on(eventName, (d) => callback(d.value));
+
+    return read;
+}
+
+/**
+ * Create a reactive effect (side effect)
+ * Runs when any tracked signal changes via bus
+ */
+export function effect(fn) {
+    let disposed = false;
+    const unsubs = [];
+
+    const run = () => {
+        if (disposed) return;
+
+        // Clear old subscriptions
+        for (const unsub of unsubs) unsub();
+        unsubs.length = 0;
+
+        const prevComputation = currentComputation;
+        currentComputation = run;
+        try {
+            fn();
+        } finally {
+            currentComputation = prevComputation;
+        }
+    };
+
+    // Run immediately
+    run();
+
+    // Return dispose function
+    return () => {
+        disposed = true;
+        for (const unsub of unsubs) unsub();
+    };
+}
+
+/**
+ * Batch multiple signal updates (uses bus batching)
+ */
+export function batch(fn) {
+    fn();
+}

package/src/core/store.js

@@ -0,0 +1,268 @@
+/**
+ * @fileoverview Simple Reactive Store for microUI
+ * 
+ * Lightweight state management without complexity.
+ * 
+ * Usage:
+ * const store = createStore({ count: 0 });
+ * store.subscribe((state) => console.log(state.count));
+ * store.set({ count: 1 });
+ * store.update(s => ({ count: s.count + 1 }));
+ */
+
+/**
+ * Create a reactive store
+ * @param {T} initialState - Initial state object
+ * @returns {Store<T>}
+ */
+export function createStore(initialState = {}) {
+    let state = { ...initialState };
+    const listeners = new Set();
+
+    return {
+        /**
+         * Get current state
+         */
+        get() {
+            return state;
+        },
+
+        /**
+         * Set new state (merges with existing)
+         * @param {Partial<T>} newState
+         */
+        set(newState) {
+            state = { ...state, ...newState };
+            this.notify();
+        },
+
+        /**
+         * Update state with function
+         * @param {(s: T) => Partial<T>} fn
+         */
+        update(fn) {
+            const updates = fn(state);
+            this.set(updates);
+        },
+
+        /**
+         * Subscribe to state changes
+         * @param {(state: T) => void} listener
+         * @returns {() => void} Unsubscribe function
+         */
+        subscribe(listener) {
+            listeners.add(listener);
+            // Call immediately with current state
+            listener(state);
+            return () => listeners.delete(listener);
+        },
+
+        /**
+         * Notify all listeners
+         */
+        notify() {
+            for (const listener of listeners) {
+                listener(state);
+            }
+        },
+
+        /**
+         * Reset to initial state
+         */
+        reset() {
+            state = { ...initialState };
+            this.notify();
+        }
+    };
+}
+
+/**
+ * Global app store (singleton pattern)
+ */
+export const appStore = createStore({});
+
+// ============================================
+// NAMESPACED STORES (Enterprise-Scale Feature)
+// ============================================
+
+/**
+ * Registry of all namespaced stores for large-scale apps
+ * @type {Map<string, Store>}
+ */
+const storeRegistry = new Map();
+
+/**
+ * State change history for observability
+ * @type {Map<string, Array<{timestamp: number, state: Object}>>}
+ */
+const stateHistory = new Map();
+
+/** Whether observability is enabled */
+let observabilityEnabled = false;
+
+/**
+ * Create a namespaced store for isolated state management.
+ * Each feature/module can have its own isolated store.
+ * 
+ * @param {string} namespace - Unique namespace for this store (e.g., 'user', 'cart')
+ * @param {Object} initialState - Initial state for this namespace
+ * @returns {Store} Store instance
+ * 
+ * @example
+ * const userStore = createNamespacedStore('user', { profile: null });
+ * const cartStore = createNamespacedStore('cart', { items: [] });
+ */
+export function createNamespacedStore(namespace, initialState = {}) {
+    if (storeRegistry.has(namespace)) {
+        console.warn(`[microUI] Store namespace "${namespace}" already exists. Returning existing store.`);
+        return storeRegistry.get(namespace);
+    }
+
+    const store = createStore(initialState);
+
+    // Wrap set to track history if observability enabled
+    const originalSet = store.set.bind(store);
+    store.set = function (newState) {
+        if (observabilityEnabled) {
+            if (!stateHistory.has(namespace)) {
+                stateHistory.set(namespace, []);
+            }
+            stateHistory.get(namespace).push({
+                timestamp: Date.now(),
+                state: { ...store.get() }
+            });
+            // Keep last 100 entries
+            const history = stateHistory.get(namespace);
+            if (history.length > 100) history.shift();
+        }
+        originalSet(newState);
+    };
+
+    // Add namespace property
+    store.namespace = namespace;
+
+    storeRegistry.set(namespace, store);
+    return store;
+}
+
+/**
+ * Get a store by namespace
+ * @param {string} namespace 
+ * @returns {Store|undefined}
+ */
+export function getStore(namespace) {
+    return storeRegistry.get(namespace);
+}
+
+/**
+ * Get all registered stores as a plain object
+ * @returns {Object<string, Store>}
+ */
+export function getAllStores() {
+    const stores = {};
+    for (const [namespace, store] of storeRegistry) {
+        stores[namespace] = store;
+    }
+    return stores;
+}
+
+/**
+ * Capture the entire application state (all namespaced stores)
+ * Useful for debugging, serialization, or time-travel debugging.
+ * 
+ * @returns {Object} Snapshot of all store states
+ * 
+ * @example
+ * const snapshot = captureAppState();
+ * localStorage.setItem('app-state', JSON.stringify(snapshot));
+ */
+export function captureAppState() {
+    const snapshot = {
+        timestamp: Date.now(),
+        stores: {}
+    };
+
+    for (const [namespace, store] of storeRegistry) {
+        snapshot.stores[namespace] = { ...store.get() };
+    }
+
+    // Include global appStore
+    snapshot.stores['__global__'] = { ...appStore.get() };
+
+    return snapshot;
+}
+
+/**
+ * Restore application state from a snapshot
+ * 
+ * @param {Object} snapshot - Previously captured state snapshot
+ * @param {Object} [options] - Options
+ * @param {boolean} [options.createMissing=false] - Create stores for namespaces not yet registered
+ * 
+ * @example
+ * const snapshot = JSON.parse(localStorage.getItem('app-state'));
+ * restoreAppState(snapshot);
+ */
+export function restoreAppState(snapshot, options = {}) {
+    const { createMissing = false } = options;
+
+    if (!snapshot?.stores) {
+        console.warn('[microUI] Invalid snapshot provided to restoreAppState');
+        return;
+    }
+
+    for (const [namespace, state] of Object.entries(snapshot.stores)) {
+        if (namespace === '__global__') {
+            appStore.set(state);
+            continue;
+        }
+
+        let store = storeRegistry.get(namespace);
+
+        if (!store && createMissing) {
+            store = createNamespacedStore(namespace, {});
+        }
+
+        if (store) {
+            store.set(state);
+        }
+    }
+}
+
+/**
+ * Get state change history for a namespace (requires observability enabled)
+ * @param {string} namespace 
+ * @returns {Array<{timestamp: number, state: Object}>}
+ */
+export function getStateHistory(namespace) {
+    return stateHistory.get(namespace) || [];
+}
+
+/**
+ * Enable state observability (tracks state changes for debugging)
+ */
+export function enableObservability() {
+    observabilityEnabled = true;
+}
+
+/**
+ * Disable state observability
+ */
+export function disableObservability() {
+    observabilityEnabled = false;
+}
+
+/**
+ * Clear all state history
+ */
+export function clearStateHistory() {
+    stateHistory.clear();
+}
+
+/**
+ * Clear store registry (useful for testing)
+ */
+export function clearStoreRegistry() {
+    storeRegistry.clear();
+    stateHistory.clear();
+}

package/src/core/theme.js

@@ -0,0 +1,68 @@
+/**
+ * @fileoverview Theme System for microUI
+ * 
+ * Provides light/dark mode toggling and theme management.
+ * Uses CSS custom properties and data-theme attribute.
+ */
+
+import { bus, UIEvents } from './bus.js';
+
+/**
+ * Theme manager singleton
+ */
+export const Theme = {
+    /**
+     * Set the current theme
+     * @param {'light'|'dark'|'auto'} theme
+     */
+    set(theme) {
+        if (theme === 'auto') {
+            const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+            document.documentElement.setAttribute('data-theme', prefersDark ? 'dark' : 'light');
+        } else {
+            document.documentElement.setAttribute('data-theme', theme);
+        }
+        localStorage.setItem('mu-theme', theme);
+        bus.emit(UIEvents.THEME_CHANGE, { theme });
+    },
+
+    /**
+     * Get current theme
+     * @returns {'light'|'dark'}
+     */
+    get() {
+        return document.documentElement.getAttribute('data-theme') || 'light';
+    },
+
+    /**
+     * Toggle between light and dark
+     */
+    toggle() {
+        const current = this.get();
+        this.set(current === 'dark' ? 'light' : 'dark');
+    },
+
+    /**
+     * Initialize theme from localStorage or system preference
+     */
+    init() {
+        const saved = localStorage.getItem('mu-theme');
+        if (saved) {
+            this.set(saved);
+        } else {
+            this.set('auto');
+        }
+
+        // Listen for system preference changes
+        window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', (e) => {
+            if (localStorage.getItem('mu-theme') === 'auto') {
+                document.documentElement.setAttribute('data-theme', e.matches ? 'dark' : 'light');
+            }
+        });
+    }
+};
+
+// Auto-init on load
+if (typeof window !== 'undefined') {
+    Theme.init();
+}

package/src/core/transitions.js

@@ -0,0 +1,72 @@
+/**
+ * @fileoverview View Transitions API Wrapper (2026 SOTA)
+ * 
+ * Provides smooth, GPU-accelerated page transitions.
+ * Falls back gracefully if not supported.
+ * 
+ * Usage:
+ * await transition(() => {
+ *     document.getElementById('app').innerHTML = newContent;
+ * });
+ */
+
+/**
+ * Check if View Transitions API is supported
+ */
+export const supportsViewTransitions = 'startViewTransition' in document;
+
+/**
+ * Perform a view transition with fallback
+ * @param {() => void | Promise<void>} updateCallback - DOM update function
+ * @returns {Promise<void>}
+ */
+export async function transition(updateCallback) {
+    if (supportsViewTransitions) {
+        const viewTransition = document.startViewTransition(async () => {
+            await updateCallback();
+        });
+
+        await viewTransition.finished;
+    } else {
+        // Fallback: just run the update
+        await updateCallback();
+    }
+}
+
+/**
+ * Transition with custom animation classes
+ * @param {() => void | Promise<void>} updateCallback 
+ * @param {Object} options
+ * @param {string} options.name - View transition name
+ */
+export async function transitionNamed(updateCallback, { name = 'page' } = {}) {
+    if (supportsViewTransitions) {
+        // Add transition name dynamically
+        const style = document.createElement('style');
+        style.textContent = `
+            ::view-transition-old(${name}),
+            ::view-transition-new(${name}) {
+                animation-duration: 0.3s;
+            }
+        `;
+        document.head.appendChild(style);
+
+        await transition(updateCallback);
+
+        style.remove();
+    } else {
+        await updateCallback();
+    }
+}
+
+/**
+ * Navigate with view transition
+ * @param {string} path - Route path
+ * @param {Function} render - Render function
+ */
+export async function navigateWithTransition(path, render) {
+    await transition(() => {
+        window.history.pushState({}, '', path);
+        render();
+    });
+}

package/src/core/utils.js

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview Centralized Utility Functions for microUI
+ * 
+ * Common utility functions used across components.
+ * Import and use these instead of defining inline.
+ */
+
+/**
+ * Escape HTML entities to prevent XSS attacks.
+ * Use this when inserting user-provided content into templates.
+ * 
+ * @param {string|null|undefined} str - String to escape
+ * @returns {string} Escaped string safe for HTML insertion
+ * 
+ * @example
+ * import { escapeHTML } from '../core/utils.js';
+ * 
+ * const userInput = '<script>alert("xss")</script>';
+ * element.innerHTML = `<div>${escapeHTML(userInput)}</div>`;
+ * // Result: <div>&lt;script&gt;alert("xss")&lt;/script&gt;</div>
+ */
+export function escapeHTML(str) {
+    if (str == null) return '';
+    return String(str)
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#039;');
+}