@uistate/core 4.1.1 → 4.1.2

package/README.md

@@ -2,7 +2,7 @@
 
 A revolutionary approach to UI state management using CSS custom properties and DOM attributes, featuring Attribute-Driven State Inheritance (ADSI).
 
-**Current Version**: 4.1.1
+**Current Version**: 4.1.2
 
 **Author**: Ajdin Imsirovic <ajdika@live.com> (GitHub)  
 **Maintainer**: uistate <ajdika.i@gmail.com> (npm)
@@ -15,7 +15,7 @@ npm install @uistate/core
 
 ## Quick Start
 
-UIstate v4.1.1 provides four core modules that can be imported individually:
+UIstate v4.1.2 provides four core modules that can be imported individually:
 
 ```javascript
 import { createCssState, createEventState, stateSerializer, createTemplateManager } from '@uistate/core';

package/cssState.js

@@ -1,9 +1,3 @@
-/**
- * UIstate - CSS-based state management module with integrated serialization
- * Part of the UIstate declarative state management system
- * Uses CSS custom properties and data attributes for state representation
- * Features modular extension capabilities for DOM binding and events
- */
 import StateSerializer from './stateSerializer.js';
 
 const createCssState = (initialState = {}, serializer = StateSerializer) => {
@@ -12,7 +6,7 @@ const createCssState = (initialState = {}, serializer = StateSerializer) => {
         _observers: new Map(),
         _serializer: serializer,
         _specialHandlers: {},
-        _eventHandlers: new Map(), // Store custom event binding handlers
+        _eventHandlers: new Map(),
 
         init(serializerConfig) {
             if (!this._sheet) {
@@ -22,12 +16,10 @@ const createCssState = (initialState = {}, serializer = StateSerializer) => {
                 this._addRule(':root {}');
             }
 
-            // Configure serializer if options provided
             if (serializerConfig && typeof serializerConfig === 'object') {
                 this._serializer.configure(serializerConfig);
             }
 
-            // Initialize with any provided state
             if (initialState && typeof initialState === 'object') {
                 Object.entries(initialState).forEach(([key, value]) => {
                     this.setState(key, value);
@@ -38,14 +30,11 @@ const createCssState = (initialState = {}, serializer = StateSerializer) => {
         },
 
         setState(key, value) {
-            // Use serializer for CSS variables
             const cssValue = this._serializer.serialize(key, value);
             document.documentElement.style.setProperty(`--${key}`, cssValue);
 
-            // Use serializer to handle all attribute application consistently
             this._serializer.applyToAttributes(key, value);
 
-            // Notify any registered observers of the state change
             this._notifyObservers(key, value);
             return value;
         },
@@ -61,7 +50,6 @@ const createCssState = (initialState = {}, serializer = StateSerializer) => {
             const value = getComputedStyle(document.documentElement).getPropertyValue(`--${key}`).trim();
             if (!value) return '';
 
-            // Use serializer for deserialization
             return this._serializer.deserialize(key, value);
         },
 
@@ -90,7 +78,6 @@ const createCssState = (initialState = {}, serializer = StateSerializer) => {
             return this;
         },
 
-        // New method for registering event bindings
         registerEventBinding(eventType, handler) {
             this._eventHandlers.set(eventType, handler);
             return this;
@@ -101,27 +88,21 @@ const createCssState = (initialState = {}, serializer = StateSerializer) => {
                 const stateKey = el.dataset.observe;
 
                 this.observe(stateKey, (value) => {
-                    // Special handlers should run first to set data-state
                     if (this._specialHandlers[stateKey]?.observe) {
                         this._specialHandlers[stateKey].observe(value, el);
                     } else if (stateKey.endsWith('-state') && el.hasAttribute('data-state')) {
-                        // Only update data-state for elements that already have this attribute
                         el.dataset.state = value;
                     } else {
-                        // For normal state observers like theme, counter, etc.
                         el.textContent = value;
                     }
                 });
 
-                // Trigger initial state
                 const initialValue = this.getState(stateKey);
                 if (this._specialHandlers[stateKey]?.observe) {
                     this._specialHandlers[stateKey].observe(initialValue, el);
                 } else if (stateKey.endsWith('-state') && el.hasAttribute('data-state')) {
-                    // Only set data-state for elements that should have this attribute
                     el.dataset.state = initialValue;
                 } else {
-                    // For normal elements
                     el.textContent = initialValue;
                 }
 
@@ -131,7 +112,6 @@ const createCssState = (initialState = {}, serializer = StateSerializer) => {
             return this;
         },
 
-        // Default event handlers available for implementations to use
         defaultClickHandler(e) {
             const target = e.target.closest('[data-state-action]');
             if (!target) return;
@@ -139,13 +119,11 @@ const createCssState = (initialState = {}, serializer = StateSerializer) => {
             const stateAction = target.dataset.stateAction;
             if (!stateAction) return;
 
-            // Special handlers get first priority
             if (this._specialHandlers[stateAction]?.action) {
                 this._specialHandlers[stateAction].action(target);
                 return;
             }
 
-            // Handle direct value setting via data-state-value
             if (target.dataset.stateValue !== undefined) {
                 const valueToSet = target.dataset.stateValue;
                 this.setState(stateAction, valueToSet);
@@ -158,20 +136,16 @@ const createCssState = (initialState = {}, serializer = StateSerializer) => {
 
             if (!stateAction) return;
 
-            // Special handlers should access any needed data directly from the target
             if (this._specialHandlers[stateAction]?.action) {
                 this._specialHandlers[stateAction].action(target);
             }
         },
 
-        // Updated setupStateActions to use registered event handlers
         setupStateActions(container = document) {
-            // Only bind the registered event types
             this._eventHandlers.forEach((handler, eventType) => {
                 container.addEventListener(eventType, handler);
             });
 
-            // If no event handlers registered, register the default ones
             if (this._eventHandlers.size === 0) {
                 container.addEventListener('click', (e) => this.defaultClickHandler(e));
                 container.addEventListener('input', (e) => this.defaultInputHandler(e));
@@ -186,7 +160,6 @@ const createCssState = (initialState = {}, serializer = StateSerializer) => {
             }
         },
 
-        // Add serializer configuration method
         configureSerializer(config) {
             if (this._serializer.configure) {
                 this._serializer.configure(config);
@@ -194,18 +167,14 @@ const createCssState = (initialState = {}, serializer = StateSerializer) => {
             return this;
         },
 
-        // Clean up resources
         destroy() {
             this._observers.clear();
-            // The style element will remain in the DOM
-            // as removing it would affect the UI state
         }
     };
 
     return state.init();
 };
 
-// Create a singleton instance for easy usage
 const UIstate = createCssState();
 
 export { createCssState };

package/eventState.js

@@ -1,23 +1,12 @@
-/**
- * UIstate - Event-based hierarchical state management module
- * Part of the UIstate declarative state management system
- * Uses DOM events for pub/sub with hierarchical path support
- */
-
 const createEventState = (initial = {}) => {
-    // Clone the initial state to avoid direct mutations to the passed object
     const store = JSON.parse(JSON.stringify(initial));
 
-    // Create a dedicated DOM element to use as an event bus
     const bus = document.createElement("x-store");
 
-    // Optional: Keep the bus element off the actual DOM for better encapsulation
-    // but this isn't strictly necessary for functionality
     bus.style.display = "none";
     document.documentElement.appendChild(bus);
 
     return {
-        // get a value from the store by path
         get: (path) => {
             if (!path) return store;
             return path
@@ -29,16 +18,13 @@ const createEventState = (initial = {}) => {
                 );
         },
 
-        // set a value in the store by path
         set: (path, value) => {
             if(!path) return;
 
-            // Update the store
             let target = store;
             const parts = path.split(".");
             const last = parts.pop();
 
-            // Create the path if it doesn't exist
             parts.forEach((part) => {
                 if (!target[part] || typeof target[part] !== "object") {
                     target[part] = {};
@@ -46,13 +32,10 @@ const createEventState = (initial = {}) => {
                 target = target[part];
             });
 
-            // Set the value
             target[last] = value;
 
-            // Notify subscribers with a DOM event
             bus.dispatchEvent(new CustomEvent(path, { detail: value }));
 
-            // Also dispatch events for parent paths to support wildcards
             if (parts.length > 0) {
                 let parentPath = "";
                 for (const part of parts) {
@@ -64,7 +47,6 @@ const createEventState = (initial = {}) => {
                     );
                 }
 
-                // Dispatch root wildcard for any state change
                 bus.dispatchEvent(
                     new CustomEvent("*", {
                         detail: { path, value},
@@ -75,7 +57,6 @@ const createEventState = (initial = {}) => {
             return value;
         },
 
-        // Subscribe to changes on a path
         subscribe: (path, callback) => {
             if (!path || typeof callback !== "function") return () => {};
 
@@ -85,7 +66,6 @@ const createEventState = (initial = {}) => {
             return () => bus.removeEventListener(path, handler);
         },
 
-        // Optional method to clean up resources
         destroy: () => {
             if (bus.parentNode) {
                 bus.parentNode.removeChild(bus);

package/index.js

@@ -1,18 +1,6 @@
-/**
- * UIstate - Simple barrel file for core modules
- * 
- * Exports the four core UIstate modules:
- * - cssState: CSS custom properties state management
- * - eventState: Event-based state management
- * - stateSerializer: State serialization utilities  
- * - templateManager: Declarative template management
- */
-
-// Export the four core modules
 export { createCssState } from './cssState.js';
 export { createEventState } from './eventState.js';
 export { default as stateSerializer } from './stateSerializer.js';
 export { createTemplateManager } from './templateManager.js';
 
-// For convenience, also export cssState as default
 export { createCssState as default } from './cssState.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uistate/core",
-  "version": "4.1.1",
+  "version": "4.1.2",
   "description": "Revolutionary DOM-based state management using CSS custom properties - zero dependencies, potential O(1) updates",
   "type": "module",
   "main": "index.js",

package/stateSerializer.js

@@ -1,17 +1,3 @@
-/**
- * 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) {
@@ -22,7 +8,6 @@ function escapeCssValue(value) {
 
 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) {
@@ -30,32 +15,19 @@ function unescapeCssValue(value) {
     });
 }
 
-/**
- * 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
+        mode: 'hybrid',
+        debug: false,
+        complexThreshold: 3,
+        preserveTypes: true,
     };
 
-    // 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) {
@@ -63,14 +35,7 @@ function createSerializer(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 '';
             }
@@ -80,37 +45,24 @@ function createSerializer(config = {}) {
                              (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(']')))) {
@@ -120,64 +72,42 @@ function createSerializer(config = {}) {
                     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()}`;
@@ -196,37 +126,21 @@ function createSerializer(config = {}) {
                     });
                 }
             } 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'
@@ -237,18 +151,10 @@ function createSerializer(config = {}) {
             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();
@@ -260,7 +166,6 @@ function createSerializer(config = {}) {
     return serializer;
 }
 
-// Create a default instance with hybrid mode
 const StateSerializer = createSerializer();
 
 export default StateSerializer;

package/templateManager.js

@@ -1,8 +1,3 @@
-/**
- * TemplateManager - Component mounting and event delegation
- * Handles HTML templating, component mounting, and event delegation
- */
-
 const createTemplateManager = (stateManager) => {
     const manager = {
         handlers: {},
@@ -12,25 +7,11 @@ const createTemplateManager = (stateManager) => {
             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') {
@@ -40,7 +21,6 @@ const createTemplateManager = (stateManager) => {
                     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 || 
@@ -70,40 +50,30 @@ const createTemplateManager = (stateManager) => {
                 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
+                .replace(/^['"]|['"]$/g, '');
             
             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;
         },
         
@@ -131,13 +101,11 @@ const createTemplateManager = (stateManager) => {
             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');
@@ -145,10 +113,8 @@ const createTemplateManager = (stateManager) => {
                 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, () => {
@@ -162,17 +128,6 @@ const createTemplateManager = (stateManager) => {
             };
         },
         
-        /**
-         * 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;
             
@@ -191,25 +146,22 @@ const createTemplateManager = (stateManager) => {
                 .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 element;
         }
     };
     
     return manager;
 };
 
-// Create a standalone instance that doesn't depend on any state manager
 const TemplateManager = createTemplateManager();
 
 export default createTemplateManager;