@uistate/core 5.2.0 → 5.4.0

package/stateSerializer.js

@@ -1,267 +0,0 @@
-/**
- * StateSerializer - Configurable serialization module for UIstate
- * Handles transformation between JavaScript values and CSS-compatible string values
- *
- * Supports multiple serialization strategies:
- * - 'escape': Uses custom escaping for all values (original UIstate approach)
- * - 'json': Uses JSON.stringify for complex objects, direct values for primitives
- * - 'hybrid': Automatically selects the best strategy based on value type
- *
- * Also handles serialization of values for data attributes and CSS variables
- * with consistent rules and unified serialization behavior
- */
-
-// Utility functions for CSS value escaping/unescaping
-function escapeCssValue(value) {
-    if (typeof value !== 'string') return value;
-    return value.replace(/[^\x20-\x7E]|[!;{}:()[\]/@,'"]/g, function(char) {
-        const hex = char.charCodeAt(0).toString(16);
-        return '\\' + hex + ' ';
-    });
-}
-
-function unescapeCssValue(value) {
-    if (typeof value !== 'string') return value;
-    // Only perform unescaping if there are escape sequences
-    if (!value.includes('\\')) return value;
-
-    return value.replace(/\\([0-9a-f]{1,6})\s?/gi, function(match, hex) {
-        return String.fromCharCode(parseInt(hex, 16));
-    });
-}
-
-/**
- * Create a configured serializer instance
- * @param {Object} config - Configuration options
- * @returns {Object} - Serializer instance
- */
-function createSerializer(config = {}) {
-    // Default configuration
-    const defaultConfig = {
-        mode: 'hybrid',        // 'escape', 'json', or 'hybrid'
-        debug: false,          // Enable debug logging
-        complexThreshold: 3,   // Object properties threshold for hybrid mode
-        preserveTypes: true    // Preserve type information in serialization
-    };
-
-    // Merge provided config with defaults
-    const options = { ...defaultConfig, ...config };
-
-    // Serializer instance
-    const serializer = {
-        // Current configuration
-        config: options,
-
-        /**
-         * Update configuration
-         * @param {Object} newConfig - New configuration options
-         */
-        configure(newConfig) {
-            Object.assign(this.config, newConfig);
-            if (this.config.debug) {
-                console.log('StateSerializer config updated:', this.config);
-            }
-        },
-
-        /**
-         * Serialize a value for storage in CSS variables
-         * @param {string} key - The state key (for context-aware serialization)
-         * @param {any} value - The value to serialize
-         * @returns {string} - Serialized value
-         */
-        serialize(key, value) {
-            // Handle null/undefined
-            if (value === null || value === undefined) {
-                return '';
-            }
-
-            const valueType = typeof value;
-            const isComplex = valueType === 'object' &&
-                             (Array.isArray(value) ||
-                              (Object.keys(value).length >= this.config.complexThreshold));
-
-            // Select serialization strategy based on configuration and value type
-            if (this.config.mode === 'escape' ||
-                (this.config.mode === 'hybrid' && !isComplex)) {
-                // Use escape strategy for primitives or when escape mode is forced
-                if (valueType === 'string') {
-                    return escapeCssValue(value);
-                } else if (valueType === 'object') {
-                    // For simple objects in escape mode, still use JSON but with escaping
-                    const jsonStr = JSON.stringify(value);
-                    return escapeCssValue(jsonStr);
-                } else {
-                    // For other primitives, convert to string
-                    return String(value);
-                }
-            } else {
-                // Use JSON strategy for complex objects or when JSON mode is forced
-                return JSON.stringify(value);
-            }
-        },
-
-        /**
-         * Deserialize a value from CSS variable storage
-         * @param {string} key - The state key (for context-aware deserialization)
-         * @param {string} value - The serialized value
-         * @returns {any} - Deserialized value
-         */
-        deserialize(key, value) {
-            // Handle empty values
-            if (!value) return '';
-
-            // Try JSON parse first for values that look like JSON
-            if (this.config.mode !== 'escape' &&
-                ((value.startsWith('{') && value.endsWith('}')) ||
-                 (value.startsWith('[') && value.endsWith(']')))) {
-                try {
-                    return JSON.parse(value);
-                } catch (e) {
-                    if (this.config.debug) {
-                        console.warn(`Failed to parse JSON for key "${key}":`, value);
-                    }
-                    // Fall through to unescaping if JSON parse fails
-                }
-            }
-
-            // For non-JSON or escape mode, try unescaping
-            const unescaped = unescapeCssValue(value);
-
-            // If unescaped looks like JSON (might have been double-escaped), try parsing it
-            if (this.config.mode !== 'escape' &&
-                ((unescaped.startsWith('{') && unescaped.endsWith('}')) ||
-                 (unescaped.startsWith('[') && unescaped.endsWith(']')))) {
-                try {
-                    return JSON.parse(unescaped);
-                } catch (e) {
-                    // Not valid JSON, return unescaped string
-                }
-            }
-
-            return unescaped;
-        },
-
-        /**
-         * Serialize a value for data-* attribute
-         * @param {string} key - The state key
-         * @param {any} value - The value to serialize for attribute
-         * @returns {string} - Serialized attribute value
-         */
-        serializeForAttribute(key, value) {
-            if (value === null || value === undefined) return null;
-
-            // For objects, use the standard serializer
-            if (typeof value === 'object') {
-                return this.serialize(key, value);
-            }
-
-            // For primitive values, use direct string conversion
-            return String(value);
-        },
-
-        /**
-         * Apply serialized state to HTML element attributes and properties
-         * @param {string} key - State key
-         * @param {any} value - Value to apply
-         * @param {HTMLElement} element - Target element (defaults to documentElement)
-         */
-        applyToAttributes(key, value, element = document.documentElement) {
-            // Skip null/undefined values
-            if (value === null || value === undefined) {
-                element.removeAttribute(`data-${key}`);
-                return;
-            }
-
-            // Handle objects specially
-            if (typeof value === 'object') {
-                // Set the main attribute with serialized value
-                element.setAttribute(`data-${key}`, this.serialize(key, value));
-
-                // For non-array objects, set individual property attributes
-                if (!Array.isArray(value)) {
-                    Object.entries(value).forEach(([propKey, propValue]) => {
-                        const attributeKey = `data-${key}-${propKey.toLowerCase()}`;
-                        if (propValue !== null && propValue !== undefined) {
-                            if (typeof propValue === 'object') {
-                                element.setAttribute(
-                                    attributeKey,
-                                    this.serialize(`${key}.${propKey}`, propValue)
-                                );
-                            } else {
-                                element.setAttribute(attributeKey, propValue);
-                            }
-                        } else {
-                            element.removeAttribute(attributeKey);
-                        }
-                    });
-                }
-            } else {
-                // For primitives, set directly
-                element.setAttribute(`data-${key}`, value);
-            }
-        },
-
-        /**
-         * Utility method to determine if a value needs complex serialization
-         * @param {any} value - Value to check
-         * @returns {boolean} - True if complex serialization is needed
-         */
-        needsComplexSerialization(value) {
-            return typeof value === 'object' && value !== null;
-        },
-
-        /**
-         * Set state with proper serialization for CSS variables
-         * @param {Object} uistate - UIstate instance
-         * @param {string} path - State path
-         * @param {any} value - Value to set
-         * @returns {any} - The set value
-         */
-        setStateWithCss(uistate, path, value) {
-            // Update UIstate
-            uistate.setState(path, value);
-
-            // Update CSS variable with properly serialized value
-            const cssPath = path.replace(/\./g, '-');
-            const serialized = this.serialize(path, value);
-            document.documentElement.style.setProperty(`--${cssPath}`, serialized);
-
-            // Update data attribute for root level state
-            const segments = path.split('.');
-            if (segments.length === 1) {
-                document.documentElement.dataset[path] = typeof value === 'object'
-                    ? JSON.stringify(value)
-                    : value;
-            }
-
-            return value;
-        },
-
-        /**
-         * Get state with fallback to CSS variables
-         * @param {Object} uistate - UIstate instance
-         * @param {string} path - State path
-         * @returns {any} - Retrieved value
-         */
-        getStateFromCss(uistate, path) {
-            // First try UIstate
-            const value = uistate.getState(path);
-            if (value !== undefined) return value;
-
-            // If not found, try CSS variable
-            const cssPath = path.replace(/\./g, '-');
-            const cssValue = getComputedStyle(document.documentElement)
-                .getPropertyValue(`--${cssPath}`).trim();
-
-            return cssValue ? this.deserialize(path, cssValue) : undefined;
-        }
-    };
-
-    return serializer;
-}
-
-// Create a default instance with hybrid mode
-const StateSerializer = createSerializer();
-
-export default StateSerializer;
-export { createSerializer, escapeCssValue, unescapeCssValue };

package/templateManager.js

@@ -1,216 +0,0 @@
-/**
- * TemplateManager - Component mounting and event delegation
- * Handles HTML templating, component mounting, and event delegation
- */
-
-const createTemplateManager = (stateManager) => {
-    const manager = {
-        handlers: {},
-        
-        onAction(action, handler) {
-            this.handlers[action] = handler;
-            return this;
-        },
-        
-        /**
-         * Register multiple actions with their handlers in a declarative way
-         * @param {Object} actionsMap - Map of action names to handlers or handler configs
-         * @returns {Object} - The manager instance for chaining
-         * 
-         * Example usage:
-         * templateManager.registerActions({
-         *   'add-item': addItem,
-         *   'delete-item': { fn: deleteItem, extractId: true },
-         *   'toggle-state': toggleState
-         * });
-         */
-        registerActions(actionsMap) {
-            Object.entries(actionsMap).forEach(([action, handler]) => {
-                if (typeof handler === 'function') {
-                    // Simple function handler
-                    this.onAction(action, handler);
-                } else if (typeof handler === 'object' && handler !== null) {
-                    // Handler with configuration
-                    const { fn, extractId = true, idAttribute = 'id' } = handler;
-                    
-                    if (typeof fn !== 'function') {
-                        throw new Error(`Handler for action '${action}' must be a function`);
-                    }
-                    
-                    this.onAction(action, (e) => {
-                        if (extractId) {
-                            const target = e.target.closest('[data-action]');
-                            // Look for common ID attributes in order of preference
-                            const id = target.dataset[idAttribute] || 
-                                      target.dataset.actionId || 
-                                      target.dataset.cardId || 
-                                      target.dataset.itemId;
-                                      
-                            fn(id, e, target);
-                        } else {
-                            fn(e);
-                        }
-                    });
-                } else {
-                    throw new Error(`Invalid handler for action '${action}'`);
-                }
-            });
-            return this;
-        },
-        
-        attachDelegation(root = document.body) {
-            root.addEventListener('click', e => {
-                const target = e.target.closest('[data-action]');
-                if (!target) return;
-                
-                const action = target.dataset.action;
-                if (!action) return;
-                
-                const handler = this.handlers[action];
-                if (typeof handler === 'function') {
-                    handler(e);
-                } else if (target.dataset.value !== undefined && stateManager) {
-                    // If we have a state manager, use it to update state
-                    stateManager.setState(action, target.dataset.value);
-                }
-            });
-            return this;
-        },
-        
-        /**
-         * Render a template from a CSS variable
-         * @param {string} templateName - Name of the template (will be prefixed with --template-)
-         * @param {Object} data - Data to inject into the template
-         * @returns {HTMLElement} - The rendered element
-         */
-        renderTemplateFromCss(templateName, data = {}) {
-            const cssTemplate = getComputedStyle(document.documentElement)
-                .getPropertyValue(`--template-${templateName}`)
-                .trim()
-                .replace(/^['"]|['"]$/g, ''); // Remove surrounding quotes
-            
-            if (!cssTemplate) throw new Error(`Template not found in CSS: --template-${templateName}`);
-            
-            let html = cssTemplate;
-            
-            // Replace all placeholders with actual data
-            Object.entries(data).forEach(([key, value]) => {
-                const regex = new RegExp(`{{${key}}}`, 'g');
-                html = html.replace(regex, value);
-            });
-            
-            // Create a temporary container
-            const temp = document.createElement('div');
-            temp.innerHTML = html;
-            
-            // Return the first child (the rendered template)
-            return temp.firstElementChild;
-        },
-        
-        mount(componentName, container) {
-            const tpl = document.getElementById(`${componentName}-template`);
-            if (!tpl) throw new Error(`Template not found: ${componentName}-template`);
-            const clone = tpl.content.cloneNode(true);
-            
-            function resolvePlaceholders(fragment) {
-                Array.from(fragment.querySelectorAll('*')).forEach(el => {
-                    const tag = el.tagName.toLowerCase();
-                    if (tag.endsWith('-placeholder')) {
-                        const name = tag.replace('-placeholder','');
-                        const childTpl = document.getElementById(`${name}-template`);
-                        if (!childTpl) throw new Error(`Template not found: ${name}-template`);
-                        const childClone = childTpl.content.cloneNode(true);
-                        resolvePlaceholders(childClone);
-                        el.replaceWith(childClone);
-                    }
-                });
-            }
-            
-            resolvePlaceholders(clone);
-            container.appendChild(clone);
-            return clone.firstElementChild;
-        },
-        
-        // Helper to create a reactive component with automatic updates
-        createComponent(name, renderFn, stateKeys = []) {
-            if (!stateManager) {
-                throw new Error('State manager is required for reactive components');
-            }
-            
-            // Create template element if it doesn't exist
-            let tpl = document.getElementById(`${name}-template`);
-            if (!tpl) {
-                tpl = document.createElement('template');
-                tpl.id = `${name}-template`;
-                document.body.appendChild(tpl);
-            }
-            
-            // Initial render
-            tpl.innerHTML = renderFn(stateManager);
-            
-            // Set up observers for reactive updates
-            if (stateKeys.length > 0) {
-                stateKeys.forEach(key => {
-                    stateManager.observe(key, () => {
-                        tpl.innerHTML = renderFn(stateManager);
-                    });
-                });
-            }
-            
-            return {
-                mount: (container) => this.mount(name, container)
-            };
-        },
-        
-        /**
-         * Apply CSS classes to an element based on a state key stored in CSS variables
-         * @param {HTMLElement} element - Element to apply classes to
-         * @param {string} stateKey - State key to look up in CSS variables
-         * @param {Object} options - Options for class application
-         * @returns {HTMLElement} - The element for chaining
-         * 
-         * Example usage:
-         * // CSS: :root { --card-primary-classes: "bg-primary text-white"; }
-         * templateManager.applyClassesFromState(cardElement, 'card-primary');
-         */
-        applyClassesFromState(element, stateKey, options = {}) {
-            if (!element) return element;
-            
-            const { 
-                prefix = '',
-                clearExisting = false,
-                namespace = '' 
-            } = typeof options === 'string' ? { prefix: options } : options;
-            
-            const prefixPath = prefix ? `${prefix}-` : '';
-            const namespacePath = namespace ? `${namespace}-` : '';
-            
-            const classString = getComputedStyle(document.documentElement)
-                .getPropertyValue(`--${namespacePath}${stateKey}-classes`)
-                .trim()
-                .replace(/^['"]|['"]$/g, '');
-                
-            if (classString) {
-                // Clear existing classes if specified
-                if (clearExisting) {
-                    element.className = '';
-                }
-                
-                // Add new classes
-                classString.split(' ').forEach(cls => {
-                    if (cls) element.classList.add(cls);
-                });
-            }
-            
-            return element; // For chaining
-        }
-    };
-    
-    return manager;
-};
-
-// Create a standalone instance that doesn't depend on any state manager
-const TemplateManager = createTemplateManager();
-
-export default createTemplateManager;
-export { createTemplateManager, TemplateManager };