@uistate/core 2.0.1 → 3.0.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.0.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,12 +1,16 @@
 /**
- * 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
+ * Includes built-in serialization for complex objects and special characters
  */
-const createCssState = (initialState = {}) => {
+import StateSerializer from './stateSerializer.js';
+
+const createCssState = (initialState = {}, serializer = StateSerializer) => {
     const state = {
         _sheet: null,
         _observers: new Map(),
+        _serializer: serializer,
         
         init() {
             if (!this._sheet) {
@@ -27,20 +31,52 @@ const createCssState = (initialState = {}) => {
         },
         
         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);
+            
+            // For data attributes, handle objects specially
+            if (value !== null && value !== undefined) {
+                if (typeof value === 'object') {
+                    // Use the serializer for the data attribute value
+                    document.documentElement.setAttribute(`data-${key}`, this._serializer.serialize(key, value));
+                    
+                    // For objects, also set each property as a separate data attribute
+                    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') {
+                                    document.documentElement.setAttribute(
+                                        attributeKey, 
+                                        this._serializer.serialize(`${key}.${propKey}`, propValue)
+                                    );
+                                } else {
+                                    document.documentElement.setAttribute(attributeKey, propValue);
+                                }
+                            } else {
+                                document.documentElement.removeAttribute(attributeKey);
+                            }
+                        });
+                    }
+                } else {
+                    // For primitives, set directly
+                    document.documentElement.setAttribute(`data-${key}`, value);
+                }
+            } else {
+                document.documentElement.removeAttribute(`data-${key}`);
+            }
+            
             this._notifyObservers(key, value);
             return value;
         },
         
         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) {
@@ -69,6 +105,14 @@ const createCssState = (initialState = {}) => {
             }
         },
         
+        // Add serializer configuration method
+        configureSerializer(config) {
+            if (this._serializer.configure) {
+                this._serializer.configure(config);
+            }
+            return this;
+        },
+        
         // Clean up resources
         destroy() {
             this._observers.clear();