@uistate/core 2.0.1 → 3.1.0

package/README.md

@@ -1,72 +1,35 @@
-# @uistate/core
+# @uistate/core v3.0.0
 
 **author**: Ajdin Imsirovic <ajdika@live.com> (GitHub)  
 **maintainer**: uistate <ajdika.i@gmail.com> (npm)
 
-High-performance UI state management using CSS custom properties and ADSI (Attribute-Driven State Inheritance). Focused heavily on DX and performance.
+High-performance UI state management using CSS custom properties and ADSI (Attribute-Driven State Inheritance). Focused heavily on DX and performance with a fully declarative approach.
+
+## What's New in v3.0.0
+
+- 🔄 Fully declarative state management approach
+- 🧩 Enhanced template system with CSS-based templates
+- 🚀 Improved performance through optimized state propagation
+- 📦 New state serialization and inspection capabilities
+- 🔍 Telemetry plugin for better debugging
 
 ## Features
 
-- 🚀 Potentially O(1) state updates using CSS custom properties
+- 🚀 O(1) state updates using CSS custom properties
 - 📉 Significant memory savings compared to virtual DOM approaches
 - 🎯 Zero configuration
 - 🔄 Automatic reactivity through CSS cascade
 - 🎨 Framework agnostic
 - 📦 Tiny bundle size (~2KB)
-- 🧩 Modular architecture with dedicated modules for CSS state and events
+- 🧩 Modular architecture with dedicated modules for CSS state and templates
+- 📝 Declarative HTML-in-CSS templates
 
 ## Installation
 
 ```bash
-# Install the core package
 npm install @uistate/core
 ```
 
-## Quick Start
-
-```javascript
-import { cssState, eventState } from '@uistate/core';
-
-// Initialize state
-cssState.init();
-
-// Set state via CSS variables
-cssState.set('--counter-value', '0');
-
-// Get state
-const count = parseInt(cssState.get('--counter-value'));
-
-// Subscribe to changes
-const unsubscribe = eventState.on('counter:change', (newValue) => {
-  console.log('Counter changed:', newValue);
-});
-
-// Set state with an attribute
-document.documentElement.dataset.counterValue = count + 1;
-```
-
-### HTML Usage Example
-
-```html
-<button data-counter-value="0" id="counter-btn">Count: 0</button>
-```
-
-```css
-[data-counter-value] {
-  /* Style based on state */
-}
-```
-
-```javascript
-document.getElementById('counter-btn').addEventListener('click', () => {
-  const btn = document.getElementById('counter-btn');
-  const currentValue = parseInt(btn.dataset.counterValue);
-  btn.dataset.counterValue = currentValue + 1;
-  btn.textContent = `Count: ${currentValue + 1}`;
-  eventState.emit('counter:change', currentValue + 1);
-});
-```
-
 ## Why @uistate/core?
 
 ### Performance
@@ -77,7 +40,7 @@ document.getElementById('counter-btn').addEventListener('click', () => {
 
 ### Developer Experience
 
-- **Simple API**: Modular `cssState` and `eventState` for clear separation of concerns
+- **Declarative API**: Define UI structure in CSS templates
 - **Framework Agnostic**: Works with any framework or vanilla JavaScript
 - **Zero Config**: No store setup, no reducers, no actions
 - **CSS-Native**: Leverages the power of CSS selectors and the cascade
@@ -85,21 +48,21 @@ document.getElementById('counter-btn').addEventListener('click', () => {
 ### Core Concepts
 
 - **Attribute-Driven State Inheritance (ADSI)**: State represented both as CSS variables and data attributes
-- **Hierarchical State Machines**: Model complex UI states with nested state machines
-- **CSS-Driven State Derivation**: Derive complex states using CSS without JavaScript
+- **Declarative Templates**: Define UI components directly in CSS
+- **Automatic State Propagation**: State changes automatically update the UI
 
 ## Project Structure
 
 ```
 @uistate/core/
-├── src/                  # Core library
-│   ├── index.js         # Main entry 
-│   ├── cssState.js      # CSS variables management
-│   ├── eventState.js    # Event-based state transitions
-│   └── templateManager.js # Component management
-└── examples/            # Example applications
-    ├── basic/          # Simple examples (range sliders, toggles, etc)
-    └── advanced/       # Advanced patterns and techniques
+├── src/                    # Core library
+│   ├── index.js           # Main entry 
+│   ├── cssState.js        # CSS variables management
+│   ├── templateManager.js # Declarative template management
+│   ├── stateInspector.js  # State inspection tools
+│   └── stateSerializer.js # State serialization
+└── examples/              # Example applications
+    └── 001-slider-and-cards/ # Advanced slider example
 ```
 
 ## Browser Support
@@ -111,63 +74,36 @@ document.getElementById('counter-btn').addEventListener('click', () => {
 
 # Core Ideas Behind UIstate
 
-UIstate is a JavaScript-based UI state management system that leverages CSS custom properties and data attributes as the storage mechanism, paired with event-based state transitions.
+UIstate is a JavaScript-based UI state management system that leverages CSS custom properties and HTML-in-CSS templates for a fully declarative approach to building UIs.
 
 ## Key Components
 
-### cssState
-
-The `cssState` module provides methods to manage state through CSS custom properties:
-
-```javascript
-// Initialize CSS state management
-cssState.init();
-
-// Set a CSS custom property
-cssState.set('--theme-mode', 'dark');
-
-// Get a CSS custom property value
-const theme = cssState.get('--theme-mode');
-```
-
-### eventState
+### UIstate Core
 
-The `eventState` module provides an event system for state transitions:
+The main UIstate object provides methods to manage state and templates:
 
-```javascript
-// Listen for state changes
-eventState.on('theme:change', (newTheme) => {
-  console.log('Theme changed to:', newTheme);
-});
+- **init()**: Initialize the UIstate system
+- **setState()**: Set state values
+- **getState()**: Get state values
+- **subscribe()**: Subscribe to state changes
+- **observe()**: Observe state paths for changes
 
-// Trigger state changes
-eventState.emit('theme:change', 'light');
-
-// Clean up listeners
-eventState.off('theme:change');
-```
+### Template Manager
 
-### templateManager
+The template manager provides tools for declarative UI rendering:
 
-The `templateManager` module helps with component initialization and templating:
-
-```javascript
-// Initialize components from templates
-templateManager.init();
-
-// Create a component from a template
-const button = templateManager.createFromTemplate('button-template');
-document.body.appendChild(button);
-```
+- **renderTemplateFromCss()**: Render UI components from CSS-defined templates
+- **registerActions()**: Register event handlers for UI components
+- **attachDelegation()**: Set up event delegation for efficient event handling
 
 ## Key Features
 
 1. Uses CSS custom properties as a storage mechanism, making state changes automatically trigger UI updates
 2. Provides a clear separation between state storage (CSS) and behavior (JavaScript)
 3. Implements a pub/sub pattern for reactive updates
-4. Leverages the CSS cascade for hierarchical state inheritance
+4. Leverages CSS templates for declarative UI definition
 
-This implementation is particularly useful for building UI components with clean separation of concerns and optimal performance.
+This implementation is particularly useful for building UI components with clean separation of concerns, optimal performance, and a fully declarative approach.
 
 ## Contributing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uistate/core",
-  "version": "2.0.1",
+  "version": "3.1.0",
   "description": "High-performance UI state management using CSS custom properties and ADSI (Attribute-Driven State Inheritance)",
   "main": "src/index.js",
   "module": "src/index.js",

package/src/cssState.js

@@ -1,48 +1,70 @@
 /**
- * UIstate - CSS-based state management module
+ * 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
  */
-const createCssState = (initialState = {}) => {
+import StateSerializer from './stateSerializer.js';
+
+const createCssState = (initialState = {}, serializer = StateSerializer) => {
     const state = {
         _sheet: null,
         _observers: new Map(),
-        
-        init() {
+        _serializer: serializer,
+        _specialHandlers: {},
+        _eventHandlers: new Map(), // Store custom event binding handlers
+
+        init(serializerConfig) {
             if (!this._sheet) {
                 const style = document.createElement('style');
                 document.head.appendChild(style);
                 this._sheet = style.sheet;
                 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);
                 });
             }
-            
+
             return this;
         },
-        
+
         setState(key, value) {
-            const cssValue = typeof value === 'string' ? value : JSON.stringify(value);
+            // Use serializer for CSS variables
+            const cssValue = this._serializer.serialize(key, value);
             document.documentElement.style.setProperty(`--${key}`, cssValue);
-            document.documentElement.setAttribute(`data-${key}`, value);
+
+            // 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;
         },
-        
+
+        setStates(stateObject) {
+            Object.entries(stateObject).forEach(([key, value]) => {
+                this.setState(key, value);
+            });
+            return this;
+        },
+
         getState(key) {
             const value = getComputedStyle(document.documentElement).getPropertyValue(`--${key}`).trim();
-            try {
-                return JSON.parse(value);
-            } catch (e) {
-                return value;
-            }
+            if (!value) return '';
+
+            // Use serializer for deserialization
+            return this._serializer.deserialize(key, value);
         },
-        
+
         observe(key, callback) {
             if (!this._observers.has(key)) {
                 this._observers.set(key, new Set());
@@ -55,20 +77,123 @@ const createCssState = (initialState = {}) => {
                 }
             };
         },
-        
+
         _notifyObservers(key, value) {
             const observers = this._observers.get(key);
             if (observers) {
                 observers.forEach(cb => cb(value));
             }
         },
-        
+
+        registerSpecialHandler(stateKey, handlerFn) {
+            this._specialHandlers[stateKey] = handlerFn;
+            return this;
+        },
+
+        // New method for registering event bindings
+        registerEventBinding(eventType, handler) {
+            this._eventHandlers.set(eventType, handler);
+            return this;
+        },
+
+        setupObservers(container = document) {
+            container.querySelectorAll('[data-observe]:not([data-observing])').forEach(el => {
+                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;
+                }
+
+                el.dataset.observing = 'true';
+            });
+
+            return this;
+        },
+
+        // Default event handlers available for implementations to use
+        defaultClickHandler(e) {
+            const target = e.target.closest('[data-state-action]');
+            if (!target) return;
+
+            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);
+            }
+        },
+
+        defaultInputHandler(e) {
+            const target = e.target;
+            const stateAction = target.dataset.stateAction;
+
+            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));
+            }
+
+            return this;
+        },
+
         _addRule(rule) {
             if (this._sheet) {
                 this._sheet.insertRule(rule, this._sheet.cssRules.length);
             }
         },
-        
+
+        // Add serializer configuration method
+        configureSerializer(config) {
+            if (this._serializer.configure) {
+                this._serializer.configure(config);
+            }
+            return this;
+        },
+
         // Clean up resources
         destroy() {
             this._observers.clear();
@@ -76,12 +201,12 @@ const createCssState = (initialState = {}) => {
             // as removing it would affect the UI state
         }
     };
-    
+
     return state.init();
 };
 
-// Legacy singleton for backward compatibility
-const CssState = createCssState();
+// Create a singleton instance for easy usage
+const UIstate = createCssState();
 
-export default createCssState;
-export { createCssState, CssState };
+export { createCssState };
+export default UIstate;

package/src/eventState.js

@@ -23,12 +23,12 @@ const createEventState = (initial = {}) => {
             return path
                 .split(".")
                 .reduce(
-                    (obj, prop) => 
+                    (obj, prop) =>
                         obj && obj[prop] !== undefined ? obj[prop] : undefined,
                     store
                 );
         },
-        
+
         // set a value in the store by path
         set: (path, value) => {
             if(!path) return;
@@ -84,10 +84,10 @@ const createEventState = (initial = {}) => {
 
             return () => bus.removeEventListener(path, handler);
         },
-        
+
         // Optional method to clean up resources
         destroy: () => {
-            if (bus.parentNode) { 
+            if (bus.parentNode) {
                 bus.parentNode.removeChild(bus);
             }
         },