create-microact-app 1.0.1

package/templates/vanilla/node_modules/@monygroupcorp/microact/src/DOMUpdater.js

@@ -0,0 +1,320 @@
+/**
+ * DOMUpdater - Utility for granular DOM updates
+ * Preserves focus state, scroll position, and form input values during updates
+ */
+export class DOMUpdater {
+    constructor() {
+        this._activeElement = null;
+        this._activeElementPath = null;
+        this._scrollPositions = new Map();
+    }
+
+    /**
+     * Save the currently focused element and scroll positions
+     * @param {HTMLElement} rootElement - Root element to save state from
+     */
+    saveState(rootElement) {
+        // Save active element
+        const activeElement = document.activeElement;
+        if (activeElement && rootElement.contains(activeElement)) {
+            this._activeElement = activeElement;
+            this._activeElementPath = this._getElementPath(activeElement, rootElement);
+        } else {
+            this._activeElement = null;
+            this._activeElementPath = null;
+        }
+
+        // Save scroll positions for all scrollable containers
+        this._scrollPositions.clear();
+        const scrollableElements = rootElement.querySelectorAll('[data-scroll-container], [style*="overflow"]');
+        scrollableElements.forEach(el => {
+            if (el.scrollTop !== undefined || el.scrollLeft !== undefined) {
+                const path = this._getElementPath(el, rootElement);
+                this._scrollPositions.set(path, {
+                    scrollTop: el.scrollTop,
+                    scrollLeft: el.scrollLeft
+                });
+            }
+        });
+    }
+
+    /**
+     * Restore focus and scroll positions after DOM update
+     * @param {HTMLElement} rootElement - Root element to restore state in
+     */
+    restoreState(rootElement) {
+        // Restore focus
+        if (this._activeElementPath) {
+            const element = this._getElementByPath(rootElement, this._activeElementPath);
+            if (element && element.focus) {
+                try {
+                    // Restore cursor position if it's an input/textarea
+                    if (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement) {
+                        const selectionStart = element.selectionStart || 0;
+                        element.focus();
+                        if (element.setSelectionRange) {
+                            element.setSelectionRange(selectionStart, selectionStart);
+                        }
+                    } else {
+                        element.focus();
+                    }
+                } catch (e) {
+                    // Focus may fail if element is not focusable, ignore
+                }
+            }
+        }
+
+        // Restore scroll positions
+        this._scrollPositions.forEach((position, path) => {
+            const element = this._getElementByPath(rootElement, path);
+            if (element) {
+                element.scrollTop = position.scrollTop;
+                element.scrollLeft = position.scrollLeft;
+            }
+        });
+    }
+
+    /**
+     * Get a path string to identify an element within its root
+     * @private
+     */
+    _getElementPath(element, root) {
+        const path = [];
+        let current = element;
+        
+        while (current && current !== root && current.parentNode) {
+            const parent = current.parentNode;
+            const index = Array.from(parent.children).indexOf(current);
+            path.unshift(index);
+            current = parent;
+        }
+        
+        return path.join('/');
+    }
+
+    /**
+     * Get an element by its path within root
+     * @private
+     */
+    _getElementByPath(root, path) {
+        const indices = path.split('/').map(Number);
+        let current = root;
+        
+        for (const index of indices) {
+            if (!current.children || !current.children[index]) {
+                return null;
+            }
+            current = current.children[index];
+        }
+        
+        return current;
+    }
+
+    /**
+     * Compare two HTML strings and determine if they're structurally different
+     * @param {string} oldHTML - Previous HTML
+     * @param {string} newHTML - New HTML
+     * @returns {boolean} - True if structure is significantly different
+     */
+    diffHTML(oldHTML, newHTML) {
+        if (oldHTML === newHTML) return false;
+        
+        // Simple heuristic: if length difference is > 50%, likely structural change
+        const lengthDiff = Math.abs(oldHTML.length - newHTML.length);
+        const avgLength = (oldHTML.length + newHTML.length) / 2;
+        if (lengthDiff / avgLength > 0.5) {
+            return true;
+        }
+        
+        // Check for tag changes (simplified)
+        const oldTags = oldHTML.match(/<[^>]+>/g) || [];
+        const newTags = newHTML.match(/<[^>]+>/g) || [];
+        if (oldTags.length !== newTags.length) {
+            return true;
+        }
+        
+        return false;
+    }
+
+    /**
+     * Update text content of a node
+     * @param {Node} node - Node to update
+     * @param {string} newText - New text content
+     */
+    updateText(node, newText) {
+        if (node.nodeType === Node.TEXT_NODE) {
+            node.textContent = newText;
+        } else if (node.nodeType === Node.ELEMENT_NODE) {
+            // For elements, update only if it's a text-only element
+            if (node.children.length === 0) {
+                node.textContent = newText;
+            }
+        }
+    }
+
+    /**
+     * Update attributes of an element
+     * @param {HTMLElement} element - Element to update
+     * @param {Object} newAttrs - New attributes object
+     */
+    updateAttributes(element, newAttrs) {
+        if (!element || element.nodeType !== Node.ELEMENT_NODE) return;
+        
+        // Get current attributes
+        const currentAttrs = {};
+        Array.from(element.attributes).forEach(attr => {
+            currentAttrs[attr.name] = attr.value;
+        });
+        
+        // Update changed attributes
+        Object.keys(newAttrs).forEach(name => {
+            const newValue = newAttrs[name];
+            if (currentAttrs[name] !== newValue) {
+                if (newValue === null || newValue === undefined) {
+                    element.removeAttribute(name);
+                } else {
+                    element.setAttribute(name, newValue);
+                }
+            }
+        });
+        
+        // Remove attributes that are no longer present
+        Object.keys(currentAttrs).forEach(name => {
+            if (!(name in newAttrs)) {
+                element.removeAttribute(name);
+            }
+        });
+    }
+
+    /**
+     * Update children of a parent element using a simple reconciliation algorithm
+     * @param {HTMLElement} parent - Parent element
+     * @param {NodeList|Array} oldChildren - Current children
+     * @param {DocumentFragment|HTMLElement} newChildrenContainer - Container with new children
+     */
+    updateChildren(parent, oldChildren, newChildrenContainer) {
+        const oldArray = Array.from(oldChildren);
+        const newArray = Array.from(newChildrenContainer.children || []);
+        
+        // If structure is too different, replace entirely
+        if (Math.abs(oldArray.length - newArray.length) > oldArray.length * 0.3) {
+            return false; // Signal to fall back to full replacement
+        }
+        
+        // Simple reconciliation: update in place where possible
+        const maxLength = Math.max(oldArray.length, newArray.length);
+        
+        for (let i = 0; i < maxLength; i++) {
+            const oldChild = oldArray[i];
+            const newChild = newArray[i];
+            
+            if (!oldChild && newChild) {
+                // New child - append
+                parent.appendChild(newChild);
+            } else if (oldChild && !newChild) {
+                // Old child removed
+                oldChild.remove();
+            } else if (oldChild && newChild) {
+                // Both exist - try to update in place
+                if (this._canUpdateInPlace(oldChild, newChild)) {
+                    this._updateNodeInPlace(oldChild, newChild);
+                } else {
+                    // Replace
+                    parent.replaceChild(newChild, oldChild);
+                }
+            }
+        }
+        
+        return true; // Successfully updated
+    }
+
+    /**
+     * Check if two nodes can be updated in place
+     * @private
+     */
+    _canUpdateInPlace(oldNode, newNode) {
+        if (oldNode.nodeType !== newNode.nodeType) return false;
+        if (oldNode.nodeType === Node.TEXT_NODE) return true;
+        if (oldNode.nodeType === Node.ELEMENT_NODE) {
+            return oldNode.tagName === newNode.tagName;
+        }
+        return false;
+    }
+
+    /**
+     * Update a node in place with new content
+     * @private
+     */
+    _updateNodeInPlace(oldNode, newNode) {
+        if (oldNode.nodeType === Node.TEXT_NODE) {
+            oldNode.textContent = newNode.textContent;
+            return;
+        }
+        
+        if (oldNode.nodeType === Node.ELEMENT_NODE) {
+            // Update attributes
+            const newAttrs = {};
+            Array.from(newNode.attributes).forEach(attr => {
+                newAttrs[attr.name] = attr.value;
+            });
+            this.updateAttributes(oldNode, newAttrs);
+            
+            // Update children recursively
+            const oldChildren = oldNode.childNodes;
+            const newChildren = newNode.childNodes;
+            
+            // For simple text-only updates
+            if (oldChildren.length === 1 && newChildren.length === 1 &&
+                oldChildren[0].nodeType === Node.TEXT_NODE &&
+                newChildren[0].nodeType === Node.TEXT_NODE) {
+                oldChildren[0].textContent = newChildren[0].textContent;
+                return;
+            }
+            
+            // For more complex structures, try to reconcile
+            if (!this.updateChildren(oldNode, oldChildren, newNode)) {
+                // Fall back to replacing content
+                oldNode.innerHTML = newNode.innerHTML;
+            }
+        }
+    }
+
+    /**
+     * Perform a granular update of an element's content
+     * @param {HTMLElement} element - Element to update
+     * @param {string} newHTML - New HTML content
+     * @returns {boolean} - True if granular update succeeded, false if fallback needed
+     */
+    updateGranular(element, newHTML) {
+        // Save state before update
+        this.saveState(element);
+        
+        // Create temporary container for new HTML
+        const temp = document.createElement('div');
+        temp.innerHTML = newHTML;
+        
+        // Try to update children granularly
+        const oldHTML = element.innerHTML;
+        const isStructuralChange = this.diffHTML(oldHTML, newHTML);
+        
+        if (isStructuralChange) {
+            // Structural change detected - fall back to full replacement
+            return false;
+        }
+        
+        // Try granular update
+        try {
+            const success = this.updateChildren(element, element.childNodes, temp);
+            if (success) {
+                // Restore state after successful update
+                this.restoreState(element);
+                return true;
+            }
+        } catch (e) {
+            console.warn('[DOMUpdater] Granular update failed, falling back:', e);
+        }
+        
+        return false;
+    }
+}
+

package/templates/vanilla/node_modules/@monygroupcorp/microact/src/EventBus.js

@@ -0,0 +1,123 @@
+class EventBus {
+    constructor() {
+        this.listeners = new Map();
+        this.debugMode = false;
+    }
+
+    /**
+     * Enable or disable debug logging
+     * @param {boolean} enabled 
+     */
+    setDebugMode(enabled) {
+        this.debugMode = enabled;
+    }
+
+    /**
+     * Subscribe to an event
+     * @param {string} eventName 
+     * @param {Function} callback 
+     * @returns {Function} Unsubscribe function
+     */
+    on(eventName, callback) {
+        if (!this.listeners.has(eventName)) {
+            this.listeners.set(eventName, new Set());
+        }
+        
+        this.listeners.get(eventName).add(callback);
+        
+        if (this.debugMode) {
+            console.log(`[EventBus] Listener added for "${eventName}"`);
+        }
+
+        // Return unsubscribe function
+        return () => this.off(eventName, callback);
+    }
+
+    /**
+     * Remove a specific event listener
+     * @param {string} eventName 
+     * @param {Function} callback 
+     */
+    off(eventName, callback) {
+        if (!this.listeners.has(eventName)) return;
+        
+        this.listeners.get(eventName).delete(callback);
+        
+        if (this.debugMode) {
+            console.log(`[EventBus] Listener removed for "${eventName}"`);
+        }
+
+        // Cleanup empty event sets
+        if (this.listeners.get(eventName).size === 0) {
+            this.listeners.delete(eventName);
+        }
+    }
+
+    /**
+     * Remove all listeners for an event
+     * @param {string} eventName 
+     */
+    removeAllListeners(eventName) {
+        if (eventName) {
+            this.listeners.delete(eventName);
+            if (this.debugMode) {
+                console.log(`[EventBus] All listeners removed for "${eventName}"`);
+            }
+        } else {
+            this.listeners.clear();
+            if (this.debugMode) {
+                console.log('[EventBus] All listeners removed');
+            }
+        }
+    }
+
+    /**
+     * Emit an event with data
+     * @param {string} eventName 
+     * @param {any} data 
+     */
+    emit(eventName, data) {
+        if (!this.listeners.has(eventName)) {
+            return;
+        }
+
+        if (this.debugMode) {
+            console.log(`[EventBus] Emitting "${eventName}"`, data);
+        }
+
+        this.listeners.get(eventName).forEach(callback => {
+            try {
+                callback(data);
+            } catch (error) {
+                console.error(`[EventBus] Error in listener for "${eventName}":`, error);
+            }
+        });
+    }
+
+    /**
+     * Subscribe to an event for one-time use
+     * @param {string} eventName 
+     * @param {Function} callback 
+     * @returns {Function} Unsubscribe function
+     */
+    once(eventName, callback) {
+        // Create a wrapper that will call the callback and then unsubscribe
+        const wrappedCallback = (data) => {
+            // Unsubscribe first to prevent issues if the callback triggers the same event
+            this.off(eventName, wrappedCallback);
+            // Call the original callback
+            try {
+                callback(data);
+            } catch (error) {
+                console.error(`[EventBus] Error in once callback for "${eventName}":`, error);
+            }
+        };
+        
+        // Register the wrapped callback
+        const unsubscribe = this.on(eventName, wrappedCallback);
+        return unsubscribe;
+    }
+}
+
+// Create a single instance for the application
+export const eventBus = new EventBus(); 

package/templates/vanilla/node_modules/@monygroupcorp/microact/src/Router.js

@@ -0,0 +1,253 @@
+/**
+ * Simple client-side router for SPA navigation
+ * Supports static routes and browser history
+ */
+class Router {
+    constructor() {
+        this.routes = new Map();
+        this.currentRoute = null;
+        this.currentHandler = null;
+        this.notFoundHandler = null;
+        
+        // Bind methods
+        this.handleRoute = this.handleRoute.bind(this);
+        this.navigate = this.navigate.bind(this);
+        
+        // Listen for browser back/forward
+        window.addEventListener('popstate', async (e) => {
+            await this.handleRoute(window.location.pathname);
+        });
+    }
+    
+    /**
+     * Register a route
+     * @param {string} path - Route path (e.g., '/', '/cultexecs')
+     * @param {Function} handler - Route handler function
+     */
+    on(path, handler) {
+        this.routes.set(path, handler);
+    }
+    
+    /**
+     * Register a 404 handler
+     * @param {Function} handler - Handler for unmatched routes
+     */
+    notFound(handler) {
+        this.notFoundHandler = handler;
+    }
+    
+    /**
+     * Navigate to a route
+     * @param {string} path - Route path
+     * @param {boolean} replace - Whether to replace history entry
+     */
+    async navigate(path, replace = false) {
+        if (path === window.location.pathname) {
+            return; // Already on this route
+        }
+        
+        if (replace) {
+            window.history.replaceState({ path }, '', path);
+        } else {
+            window.history.pushState({ path }, '', path);
+        }
+        
+        await this.handleRoute(path);
+        
+
+    }
+    
+    /**
+     * Match a path against a route pattern
+     * @param {string} pattern - Route pattern (e.g., '/project/:id')
+     * @param {string} path - Actual path to match
+     * @returns {object|null} Matched params or null if no match
+     * @private
+     */
+    _matchRoute(pattern, path) {
+        // Exact match for static routes
+        if (pattern === path) {
+            return {};
+        }
+        
+        // Split into parts, filtering empty strings
+        const patternParts = pattern.split('/').filter(p => p);
+        const pathParts = path.split('/').filter(p => p);
+        
+        // Must have same number of parts
+        if (patternParts.length !== pathParts.length) {
+            return null;
+        }
+        
+        const params = {};
+        for (let i = 0; i < patternParts.length; i++) {
+            const patternPart = patternParts[i];
+            const pathPart = pathParts[i];
+            
+            // Check if this is a parameter (starts with :)
+            if (patternPart.startsWith(':')) {
+                const paramName = patternPart.slice(1);
+                // Decode URL component
+                try {
+                    params[paramName] = decodeURIComponent(pathPart);
+                } catch (e) {
+                    // If decoding fails, use raw value
+                    params[paramName] = pathPart;
+                }
+            } else if (patternPart !== pathPart) {
+                // Static part doesn't match
+                return null;
+            }
+        }
+        
+        return params;
+    }
+    
+    /**
+     * Find matching route handler
+     * @param {string} path - Route path
+     * @returns {object|null} { handler, params } or null
+     * @private
+     */
+    _findRoute(path) {
+        // First check for exact static route match (static routes take precedence)
+        if (this.routes.has(path)) {
+            return {
+                handler: this.routes.get(path),
+                params: {}
+            };
+        }
+        
+        // Collect all dynamic routes and sort by specificity
+        const dynamicRoutes = [];
+        for (const [pattern, handler] of this.routes.entries()) {
+            // Skip if it's an exact match (already checked above)
+            if (pattern === path) {
+                continue;
+            }
+            
+            // Check if pattern contains dynamic parameters
+            if (pattern.includes(':')) {
+                const paramCount = (pattern.match(/:/g) || []).length;
+                // Count literal (non-param) parts for better specificity
+                const literalCount = pattern.split('/').filter(p => p && !p.startsWith(':')).length;
+                dynamicRoutes.push({ pattern, handler, paramCount, literalCount });
+            }
+        }
+        
+        // Sort by literal count first (more literals = more specific), then by param count
+        // This ensures routes with literal parts (like /create) are matched before fully dynamic routes
+        dynamicRoutes.sort((a, b) => {
+            if (b.literalCount !== a.literalCount) {
+                return b.literalCount - a.literalCount;
+            }
+            return b.paramCount - a.paramCount;
+        });
+        
+        // Try each route in order of specificity
+        for (const { pattern, handler } of dynamicRoutes) {
+            const params = this._matchRoute(pattern, path);
+            if (params !== null) {
+                return { handler, params };
+            }
+        }
+        
+        return null;
+    }
+    
+    /**
+     * Handle route change
+     * @param {string} path - Route path
+     */
+    async handleRoute(path) {
+        // Clean up current handler if it exists
+        if (this.currentHandler && typeof this.currentHandler.cleanup === 'function') {
+            this.currentHandler.cleanup();
+        }
+        
+        // Find matching route
+        const match = this._findRoute(path);
+        
+        if (match) {
+            this.currentRoute = path;
+            // Call handler with params and store the result (which may include cleanup function)
+            // Handle both sync and async handlers
+            const result = await Promise.resolve(match.handler(match.params));
+            this.currentHandler = result || null;
+            
+
+        } else if (this.notFoundHandler) {
+            this.currentRoute = null;
+            this.currentHandler = null;
+            this.notFoundHandler(path);
+        } else {
+            console.warn(`No route handler for: ${path}`);
+        }
+    }
+    
+    /**
+     * Start the router
+     */
+    async start() {
+        // Handle initial route
+        await this.handleRoute(window.location.pathname);
+    }
+    
+    /**
+     * Get current route
+     */
+    getCurrentRoute() {
+        return this.currentRoute || window.location.pathname;
+    }
+    
+    /**
+     * Encode a title for use in URL (slug)
+     * @param {string} title - Title to encode
+     * @returns {string} URL-safe slug
+     */
+    _encodeTitle(title) {
+        if (!title) return '';
+        return title
+            .toLowerCase()
+            .trim()
+            .replace(/[^a-z0-9]+/g, '-')  // Replace non-alphanumeric with hyphens
+            .replace(/^-+|-+$/g, '');      // Remove leading/trailing hyphens
+    }
+    
+    /**
+     * Decode a URL slug back to title (approximate)
+     * @param {string} slug - URL slug
+     * @returns {string} Decoded title
+     */
+    _decodeTitle(slug) {
+        if (!slug) return '';
+        return slug
+            .split('-')
+            .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+            .join(' ');
+    }
+    
+    /**
+     * Generate URL from chain ID, factory title, instance name, and optional piece title
+     * @param {string|number} chainId - Chain ID (e.g., 1 for Ethereum mainnet)
+     * @param {string} factoryTitle - Factory title
+     * @param {string} instanceName - Instance name
+     * @param {string} [pieceTitle] - Optional piece title (for ERC1155)
+     * @returns {string} URL path
+     */
+    generateURL(chainId, factoryTitle, instanceName, pieceTitle = null) {
+        const chainIdStr = String(chainId || '1'); // Default to 1 (Ethereum mainnet)
+        const factorySlug = this._encodeTitle(factoryTitle);
+        const instanceSlug = this._encodeTitle(instanceName);
+        
+        if (pieceTitle) {
+            const pieceSlug = this._encodeTitle(pieceTitle);
+            return `/${chainIdStr}/${factorySlug}/${instanceSlug}/${pieceSlug}`;
+        }
+        
+        return `/${chainIdStr}/${factorySlug}/${instanceSlug}`;
+    }
+}
+
+export default Router;
+