microui-wc 0.1.0

package/src/core/breakpoints.js

@@ -0,0 +1,195 @@
+/**
+ * @fileoverview Centralized Breakpoint System for microUI
+ * 
+ * Provides MD3-compliant responsive breakpoints with reactive subscriptions.
+ * All components should use this utility for consistent responsive behavior.
+ * 
+ * MD3 Window Size Classes:
+ * - Compact: < 600px (mobile phones)
+ * - Medium: 600-839px (tablets, foldables)
+ * - Expanded: ≥ 840px (desktop, large tablets)
+ * 
+ * @see https://m3.material.io/foundations/layout/applying-layout
+ */
+
+/**
+ * MD3 Breakpoint values in pixels
+ */
+export const BREAKPOINTS = {
+    /** Maximum width for compact (mobile) layout */
+    compact: 600,
+    /** Maximum width for medium (tablet) layout */
+    medium: 840,
+    /** Minimum width for expanded (desktop) layout */
+    expanded: 840
+};
+
+/**
+ * Breakpoint size class names
+ * @typedef {'compact' | 'medium' | 'expanded'} BreakpointClass
+ */
+
+/**
+ * Callback function type for breakpoint changes
+ * @typedef {(breakpoint: BreakpointClass) => void} BreakpointCallback
+ */
+
+class BreakpointObserver {
+    /** @type {Set<BreakpointCallback>} */
+    #listeners = new Set();
+
+    /** @type {BreakpointClass} */
+    #current = 'expanded';
+
+    /** @type {MediaQueryList|null} */
+    #mqCompact = null;
+
+    /** @type {MediaQueryList|null} */
+    #mqMedium = null;
+
+    constructor() {
+        if (typeof window !== 'undefined') {
+            this.#setupMediaQueries();
+        }
+    }
+
+    /**
+     * Set up media query listeners
+     * @private
+     */
+    #setupMediaQueries() {
+        // Compact: < 600px
+        this.#mqCompact = window.matchMedia(`(max-width: ${BREAKPOINTS.compact - 1}px)`);
+        this.#mqCompact.addEventListener('change', this.#handleChange);
+
+        // Medium: 600-839px
+        this.#mqMedium = window.matchMedia(
+            `(min-width: ${BREAKPOINTS.compact}px) and (max-width: ${BREAKPOINTS.medium - 1}px)`
+        );
+        this.#mqMedium.addEventListener('change', this.#handleChange);
+
+        // Set initial value
+        this.#updateCurrent();
+    }
+
+    /**
+     * Handle media query change events
+     * @private
+     */
+    #handleChange = () => {
+        const oldValue = this.#current;
+        this.#updateCurrent();
+
+        if (oldValue !== this.#current) {
+            this.#notifyListeners();
+        }
+    };
+
+    /**
+     * Update current breakpoint based on media queries
+     * @private
+     */
+    #updateCurrent() {
+        if (this.#mqCompact?.matches) {
+            this.#current = 'compact';
+        } else if (this.#mqMedium?.matches) {
+            this.#current = 'medium';
+        } else {
+            this.#current = 'expanded';
+        }
+    }
+
+    /**
+     * Notify all listeners of breakpoint change
+     * @private
+     */
+    #notifyListeners() {
+        this.#listeners.forEach(callback => {
+            try {
+                callback(this.#current);
+            } catch (e) {
+                console.error('[Breakpoints] Listener error:', e);
+            }
+        });
+    }
+
+    /**
+     * Get current breakpoint class (live query)
+     * @returns {BreakpointClass}
+     */
+    get current() {
+        // Always query live for most accurate state
+        if (this.#mqCompact?.matches) {
+            return 'compact';
+        } else if (this.#mqMedium?.matches) {
+            return 'medium';
+        }
+        return 'expanded';
+    }
+
+    /**
+     * Check if currently in compact (mobile) mode
+     * @returns {boolean}
+     */
+    get isCompact() {
+        return this.#mqCompact?.matches ?? false;
+    }
+
+    /**
+     * Check if currently in medium (tablet) mode
+     * @returns {boolean}
+     */
+    get isMedium() {
+        return this.#mqMedium?.matches ?? false;
+    }
+
+    /**
+     * Check if currently in expanded (desktop) mode
+     * @returns {boolean}
+     */
+    get isExpanded() {
+        return !this.isCompact && !this.isMedium;
+    }
+
+    /**
+     * Check if NOT in compact mode (medium or expanded)
+     * @returns {boolean}
+     */
+    get isNotCompact() {
+        return this.#current !== 'compact';
+    }
+
+    /**
+     * Subscribe to breakpoint changes
+     * @param {BreakpointCallback} callback - Called with new breakpoint class on change
+     * @returns {() => void} Unsubscribe function
+     */
+    subscribe(callback) {
+        this.#listeners.add(callback);
+
+        // Call immediately with current value
+        callback(this.#current);
+
+        // Return unsubscribe function
+        return () => {
+            this.#listeners.delete(callback);
+        };
+    }
+
+    /**
+     * Get window width in pixels (for testing/debugging)
+     * @returns {number}
+     */
+    get windowWidth() {
+        return typeof window !== 'undefined' ? window.innerWidth : 1200;
+    }
+}
+
+/**
+ * Global breakpoint observer singleton
+ * @type {BreakpointObserver}
+ */
+export const breakpoints = new BreakpointObserver();
+
+// Also expose class for testing
+export { BreakpointObserver };

package/src/core/bus.js

@@ -0,0 +1,378 @@
+/**
+ * @fileoverview microUI EventBus - CrossBus 1.0.0 Adapter
+ * 
+ * Wraps CrossBus for microUI components with agentic features.
+ * Following AGENTS.md best practices for maximum performance.
+ * 
+ * Performance: 111M ops/sec with emitSync
+ * Features: 
+ *  - ACK-based delivery, zero memory leaks
+ *  - Capability discovery for AI agents
+ *  - Debug mode toggle
+ *  - Health monitoring
+ *  - Inbound/outbound hooks for observability
+ */
+
+import { CrossBus } from 'crossbus';
+
+/** microUI framework version */
+export const MICROUI_VERSION = '0.1.0';
+
+// Create singleton instance for microUI (Window Singleton Pattern)
+// Ensures shared bus across split bundles/chunks
+const GLOBAL_BUS_KEY = '__MICROUI_CROSSBUS__';
+
+// Defensive check for test environments where window may not be defined
+const globalScope = typeof window !== 'undefined' ? window : globalThis;
+
+// AI Agent Discovery: Capability negotiation (stored locally for getCapabilities())
+const MICROUI_CAPABILITIES = [
+    'ui:toast',
+    'ui:modal',
+    'ui:theme',
+    'ui:tabs',
+    'ui:dropdown',
+    'ui:form',
+    'ui:grid',
+    'ui:stack',
+    'ui:virtual-list'
+];
+
+const MICROUI_META = {
+    type: 'ui-framework',
+    version: MICROUI_VERSION,
+    description: 'AI-Optimized UI Framework - Web Components Edition'
+};
+
+if (!globalScope[GLOBAL_BUS_KEY]) {
+    globalScope[GLOBAL_BUS_KEY] = new CrossBus({
+        peerId: 'microui',
+        isHub: true,
+        requestTimeout: 5000,
+        capabilities: MICROUI_CAPABILITIES,
+        meta: MICROUI_META
+    });
+    // Best practice: Set max listeners for many UI components
+    globalScope[GLOBAL_BUS_KEY].setMaxListeners(100);
+}
+
+const crossBus = globalScope[GLOBAL_BUS_KEY];
+
+// ============================================================================
+// COMPONENT CAPABILITY REGISTRY (Phase 2)
+// Allows components to register their capabilities at runtime
+// AI agents can query this to discover available component features
+// ============================================================================
+const COMPONENT_REGISTRY_KEY = '__MICROUI_COMPONENT_REGISTRY__';
+if (!globalScope[COMPONENT_REGISTRY_KEY]) {
+    globalScope[COMPONENT_REGISTRY_KEY] = new Map();
+}
+const componentRegistry = globalScope[COMPONENT_REGISTRY_KEY];
+
+/**
+ * Simplified bus wrapper for microUI components
+ * Optimized following CrossBus AGENTS.md
+ */
+export const bus = {
+    /**
+     * Subscribe to a signal
+     * @param {string} event - Event name (supports wildcards 'ui:*')
+     * @param {Function} callback - Handler function
+     * @returns {Function} Unsubscribe function
+     */
+    on(event, callback) {
+        const subscription = crossBus.on(event, (eventData) => {
+            callback(eventData.data ?? eventData);
+        });
+        return () => subscription.unsubscribe();
+    },
+
+    /**
+     * Subscribe once
+     */
+    once(event, callback) {
+        const unsub = this.on(event, (data) => {
+            unsub();
+            callback(data);
+        });
+    },
+
+    /**
+     * Unsubscribe
+     */
+    off(event, callback) {
+        crossBus.off(event, callback);
+    },
+
+    /**
+     * Emit a signal - Uses emitSync for 111M ops/sec
+     * Best practice from AGENTS.md: "Always use emitSync for local events"
+     */
+    emit(event, data) {
+        return crossBus.emitSync(event, data);
+    },
+
+    /**
+     * Async emit with full envelope (slower but with confirmation)
+     */
+    async emitAsync(event, data) {
+        return crossBus.emit(event, data);
+    },
+
+    /**
+     * Broadcast signal to all peers
+     */
+    signal(event, data) {
+        crossBus.signal(event, data);
+    },
+
+    /**
+     * Request/Response pattern (RPC)
+     */
+    async request(peerId, handler, payload) {
+        return crossBus.request(peerId, handler, payload);
+    },
+
+    /**
+     * Broadcast request to all peers
+     */
+    async broadcastRequest(handler, payload) {
+        return crossBus.broadcastRequest(handler, payload);
+    },
+
+    /**
+     * Register a request handler
+     */
+    handle(name, handler) {
+        return crossBus.handle(name, handler);
+    },
+
+    /**
+     * Remove handler
+     */
+    unhandle(name) {
+        crossBus.unhandle(name);
+    },
+
+    /**
+     * Clear/destroy - Best practice: "Call destroy() to prevent memory leaks"
+     */
+    destroy() {
+        crossBus.destroy();
+    },
+
+    /**
+     * Set max listeners
+     */
+    setMaxListeners(n) {
+        crossBus.setMaxListeners(n);
+    },
+
+    /**
+     * Peer management
+     */
+    get peerId() { return crossBus.peerId; },
+    get peers() { return crossBus.peers; },
+    get peerCount() { return crossBus.peerCount; },
+
+    /**
+     * Check if listeners exist for a signal (CrossBus native)
+     * @param {string} event - Event name
+     * @returns {boolean}
+     */
+    hasListeners(event) { return crossBus.hasListeners(event); },
+
+    /**
+     * Direct access to CrossBus instance
+     */
+    get raw() { return crossBus; }
+};
+
+// Predefined UI events
+export const UIEvents = {
+    // Toast
+    TOAST_SHOW: 'ui:toast:show',
+    TOAST_DISMISS: 'ui:toast:dismiss',
+
+    // Modal
+    MODAL_OPEN: 'ui:modal:open',
+    MODAL_CLOSE: 'ui:modal:close',
+
+    // Theme
+    THEME_CHANGE: 'ui:theme:change',
+
+    // Navigation
+    TAB_CHANGE: 'ui:tab:change',
+    DROPDOWN_SELECT: 'ui:dropdown:select',
+
+    // Form
+    FORM_SUBMIT: 'ui:form:submit',
+    FORM_VALIDATE: 'ui:form:validate'
+};
+
+/**
+ * Show toast helper
+ */
+export const showToast = (message, options = {}) => {
+    bus.emit(UIEvents.TOAST_SHOW, { message, ...options });
+};
+
+// ============================================================================
+// AI AGENT FEATURES (CrossBus 1.0.0)
+// ============================================================================
+
+/**
+ * Enable debug mode for CrossBus tracing
+ * 
+ * NOTE: CrossBus debug mode is set at creation time.
+ * This function checks if debug is enabled but cannot toggle it dynamically.
+ * For runtime debugging, use addInboundHook/addOutboundHook instead.
+ * 
+ * @returns {boolean} Whether debug mode is currently enabled
+ */
+export const isDebugEnabled = () => crossBus.debug;
+
+/**
+ * Alias for isDebugEnabled for backwards compatibility
+ * @deprecated Use isDebugEnabled() instead
+ */
+export const enableDebug = () => {
+    console.warn('[microUI] enableDebug() is deprecated. Debug mode is set at CrossBus creation. Use addInboundHook/addOutboundHook for runtime tracing.');
+    return crossBus.debug;
+};
+
+/**
+ * Disable debug mode
+ * @deprecated Debug mode cannot be toggled after creation
+ */
+export const disableDebug = () => {
+    console.warn('[microUI] disableDebug() is deprecated. Debug mode is set at CrossBus creation.');
+};
+
+/**
+ * Get health status of the CrossBus instance
+ * Useful for AI agents to verify framework readiness
+ * 
+ * @returns {Object} Health status including uptime, peers, handlers
+ * @example
+ * getHealth(); // { status: 'healthy', peerId: 'microui', uptime: 12345, ... }
+ */
+export const getHealth = () => {
+    return crossBus.healthCheck?.() ?? {
+        status: 'unknown',
+        peerId: crossBus.peerId,
+        note: 'healthCheck not available in this CrossBus version'
+    };
+};
+
+/**
+ * Get framework capabilities
+ * AI agents can use this for feature discovery
+ * 
+ * @returns {Object} Capabilities and metadata
+ */
+export const getCapabilities = () => ({
+    peerId: crossBus.peerId,
+    capabilities: MICROUI_CAPABILITIES,
+    meta: MICROUI_META,
+    version: MICROUI_VERSION
+});
+
+/**
+ * Add inbound hook for message interception
+ * Useful for AI agents to trace/log all incoming messages
+ * 
+ * @param {Function} fn - Hook function (payload, ctx) => payload
+ * @returns {Function} Remove hook function
+ */
+export const addInboundHook = (fn) => {
+    return crossBus.addInboundHook?.(fn) ?? (() => { });
+};
+
+/**
+ * Add outbound hook for message interception
+ * Useful for AI agents to trace/log all outgoing messages
+ * 
+ * @param {Function} fn - Hook function (payload, ctx) => payload
+ * @returns {Function} Remove hook function
+ */
+export const addOutboundHook = (fn) => {
+    return crossBus.addOutboundHook?.(fn) ?? (() => { });
+};
+
+// ============================================================================
+// COMPONENT CAPABILITY REGISTRATION (Phase 2)
+// ============================================================================
+
+/**
+ * Register a component's capabilities
+ * Components call this in connectedCallback to announce their features
+ * 
+ * @param {string} tagName - Custom element tag name (e.g., 'mu-toast')
+ * @param {Object} capabilities - Component capability descriptor
+ * @param {string[]} capabilities.signals - Signals this component listens to
+ * @param {string[]} capabilities.handlers - RPC handlers this component provides
+ * @param {Object} capabilities.options - Component-specific options (e.g., positions, severities)
+ * @example
+ * registerComponent('mu-toast', {
+ *   signals: ['ui:toast:show', 'ui:toast:dismiss'],
+ *   options: { positions: ['top-right', 'bottom-left'], severities: ['info', 'success'] }
+ * });
+ */
+export const registerComponent = (tagName, capabilities) => {
+    componentRegistry.set(tagName, {
+        ...capabilities,
+        registeredAt: Date.now()
+    });
+};
+
+/**
+ * Unregister a component (for cleanup)
+ * 
+ * @param {string} tagName - Custom element tag name
+ */
+export const unregisterComponent = (tagName) => {
+    componentRegistry.delete(tagName);
+};
+
+/**
+ * Get a specific component's capabilities
+ * 
+ * @param {string} tagName - Custom element tag name
+ * @returns {Object|null} Component capabilities or null if not registered
+ */
+export const getComponentCapabilities = (tagName) => {
+    return componentRegistry.get(tagName) ?? null;
+};
+
+/**
+ * Get all registered components and their capabilities
+ * AI agents use this to discover available UI features
+ * 
+ * @returns {Object} Map of all registered components
+ * @example
+ * getRegisteredComponents();
+ * // {
+ * //   'mu-toast': { signals: ['ui:toast:show'], options: {...} },
+ * //   'mu-modal': { signals: ['ui:modal:open'], options: {...} }
+ * // }
+ */
+export const getRegisteredComponents = () => {
+    return Object.fromEntries(componentRegistry);
+};
+
+/**
+ * Check if a specific signal has any registered component handlers
+ * 
+ * @param {string} signal - Signal name to check
+ * @returns {string[]} List of component tag names that handle this signal
+ */
+export const getComponentsForSignal = (signal) => {
+    const handlers = [];
+    for (const [tagName, caps] of componentRegistry) {
+        if (caps.signals?.includes(signal)) {
+            handlers.push(tagName);
+        }
+    }
+    return handlers;
+};