@uistate/core 4.1.2 → 5.0.0

package/examples/032-todo-app-with-eventTest/tests/todos.test.js

@@ -0,0 +1,192 @@
+/**
+ * todos.test.js - Event-sequence tests for todo functionality
+ * 
+ * These tests define the behavior AND types of the todo domain
+ */
+
+import { createEventTest, test, runTests } from './eventTest.js';
+
+// Helper to set up todo bridges on a test store
+function setupTodoBridges(store) {
+  let nextId = 1;
+  
+  // Add todo
+  store.subscribe('intent.todo.add', (detail) => {
+    const { text } = detail;
+    const items = store.get('domain.todos.items') || [];
+    const todo = { id: nextId++, text: String(text || '').trim(), done: false };
+    if (!todo.text) return;
+    store.set('domain.todos.items', [...items, todo]);
+  });
+  
+  // Toggle todo
+  store.subscribe('intent.todo.toggle', (detail) => {
+    const { id } = detail;
+    const items = store.get('domain.todos.items') || [];
+    const out = items.map(t => (String(t?.id) === String(id)) ? { ...t, done: !t.done } : t);
+    store.set('domain.todos.items', out);
+  });
+  
+  // Clear completed
+  store.subscribe('intent.todo.clearCompleted', () => {
+    const items = store.get('domain.todos.items') || [];
+    store.set('domain.todos.items', items.filter(t => !t.done));
+  });
+  
+  // UI filter
+  store.subscribe('intent.ui.filter', (detail) => {
+    const { filter } = detail;
+    const f = (filter === 'active' || filter === 'completed') ? filter : 'all';
+    store.set('ui.todos.filter', f);
+  });
+}
+
+// Test suite
+const tests = {
+  'add todo creates correct structure': () => {
+    const t = createEventTest({
+      domain: { todos: { items: [] } }
+    });
+    
+    // Set up bridges for this test
+    setupTodoBridges(t.store);
+    
+    // Trigger intent
+    t.trigger('intent.todo.add', { text: 'Buy milk' });
+    
+    // Assert array structure and element types
+    t.assertArrayOf('domain.todos.items', {
+      id: 'number',
+      text: 'string',
+      done: 'boolean'
+    });
+    
+    // Assert array length
+    t.assertArrayLength('domain.todos.items', 1);
+    
+    // Assert specific values
+    const items = t.store.get('domain.todos.items');
+    if (items[0].text !== 'Buy milk') {
+      throw new Error('Expected first todo text to be "Buy milk"');
+    }
+    if (items[0].done !== false) {
+      throw new Error('Expected first todo to not be done');
+    }
+  },
+
+  'toggle todo changes done state': () => {
+    const t = createEventTest({
+      domain: { todos: { items: [{ id: 1, text: 'Buy milk', done: false }] } }
+    });
+    
+    // Set up bridges for this test
+    setupTodoBridges(t.store);
+    
+    // Trigger toggle
+    t.trigger('intent.todo.toggle', { id: 1 });
+    
+    // Assert structure
+    t.assertArrayOf('domain.todos.items', {
+      id: 'number',
+      text: 'string',
+      done: 'boolean'
+    });
+    
+    // Assert done is now true
+    const items = t.store.get('domain.todos.items');
+    if (items[0].done !== true) {
+      throw new Error('Expected todo to be done');
+    }
+  },
+
+  'clear completed removes done todos': () => {
+    const t = createEventTest({
+      domain: {
+        todos: {
+          items: [
+            { id: 1, text: 'Buy milk', done: true },
+            { id: 2, text: 'Walk dog', done: false }
+          ]
+        }
+      }
+    });
+    
+    // Set up bridges for this test
+    setupTodoBridges(t.store);
+    
+    // Trigger clear
+    t.trigger('intent.todo.clearCompleted');
+    
+    // Assert only active todo remains
+    t.assertArrayLength('domain.todos.items', 1);
+    
+    const items = t.store.get('domain.todos.items');
+    if (items[0].text !== 'Walk dog') {
+      throw new Error('Expected only "Walk dog" to remain');
+    }
+  },
+
+  'filter intent updates filter state': () => {
+    const t = createEventTest({
+      ui: { todos: { filter: 'all' } }
+    });
+    
+    // Set up bridges for this test
+    setupTodoBridges(t.store);
+    
+    // Trigger filter change
+    t.trigger('intent.ui.filter', { filter: 'active' });
+    
+    // Assert type
+    t.assertType('ui.todos.filter', 'string');
+    
+    // Assert value
+    t.assertPath('ui.todos.filter', 'active');
+  },
+
+  'intent.todo.add has correct shape': () => {
+    const t = createEventTest({});
+    
+    // Trigger intent
+    t.trigger('intent.todo.add', { text: 'Buy milk' });
+    
+    // Assert intent shape (for type generation)
+    t.assertShape('intent.todo.add', {
+      text: 'string'
+    });
+  },
+
+  'intent.todo.toggle has correct shape': () => {
+    const t = createEventTest({});
+    
+    // Trigger intent
+    t.trigger('intent.todo.toggle', { id: 1 });
+    
+    // Assert intent shape
+    t.assertShape('intent.todo.toggle', {
+      id: 'number'
+    });
+  },
+
+  'empty todos array is valid': () => {
+    const t = createEventTest({
+      domain: { todos: { items: [] } }
+    });
+    
+    // Assert empty array is still typed correctly
+    t.assertArrayOf('domain.todos.items', {
+      id: 'number',
+      text: 'string',
+      done: 'boolean'
+    });
+    
+    t.assertArrayLength('domain.todos.items', 0);
+  }
+};
+
+// Run tests if executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  runTests(tests);
+}
+
+export default tests;

package/index.js

@@ -1,6 +1,17 @@
-export { createCssState } from './cssState.js';
+/**
+ * UIstate v5 - Core barrel exports
+ * 
+ * EventState is now the primary export for application state management.
+ * cssState remains available for CSS variable/theme management use cases.
+ */
+
+// Primary: EventState (recommended for application state)
 export { createEventState } from './eventState.js';
+export { createEventState as default } from './eventState.js';
+
+// Specialized: CSS State (for CSS variables and theme management)
+export { createCssState } from './cssState.js';
+
+// Utilities
 export { default as stateSerializer } from './stateSerializer.js';
 export { createTemplateManager } from './templateManager.js';
-
-export { createCssState as default } from './cssState.js';

package/package.json

@@ -1,29 +1,38 @@
 {
   "name": "@uistate/core",
-  "version": "4.1.2",
-  "description": "Revolutionary DOM-based state management using CSS custom properties - zero dependencies, potential O(1) updates",
+  "version": "5.0.0",
+  "description": "Lightweight event-driven state management with slot orchestration and experimental event-sequence testing (eventTest.js available under dual license)",
   "type": "module",
   "main": "index.js",
   "exports": {
     ".": "./index.js",
-    "./cssState": "./cssState.js",
     "./eventState": "./eventState.js",
+    "./cssState": "./cssState.js",
     "./stateSerializer": "./stateSerializer.js",
     "./templateManager": "./templateManager.js"
   },
   "files": [
     "index.js",
+    "eventState.js",
     "cssState.js",
-    "eventState.js", 
     "stateSerializer.js",
-    "templateManager.js"
+    "templateManager.js",
+    "eventTest.js",
+    "LICENSE",
+    "LICENSE-eventTest.md",
+    "examples/"
   ],
   "keywords": [
     "state-management",
-    "css-variables",
+    "event-driven",
+    "reactive",
     "dom-events",
+    "slot-orchestration",
     "zero-dependency",
-    "modular"
+    "framework-free",
+    "micro-framework",
+    "testing",
+    "event-testing"
   ],
   "author": "Ajdin Imsirovic",
   "license": "MIT",

package/stateSerializer.js

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

package/templateManager.js

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