@uistate/core 2.0.0 → 3.0.0

package/README.md

@@ -1,122 +1,68 @@
-# @uistate/core
+# @uistate/core v3.0.0
 
-**author**: Ajdin Imsirovic <ajdika@live.com> (GitHub),
+**author**: Ajdin Imsirovic <ajdika@live.com> (GitHub)  
 **maintainer**: uistate <ajdika.i@gmail.com> (npm)
 
-High-performance UI state management using CSS custom properties and a number of other novel ideas. Focused heavily on DX and performance, in that order.
+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
 
-- ~~🚀 44% faster state updates than Redux~~ Potentially O(1) state updates!
-- ~~📉 12.5% lower memory usage~~ Large memory usage savings (perf pending...)
+- 🚀 O(1) state updates using CSS custom properties
+- 📉 Significant memory savings compared to virtual DOM approaches
 - 🎯 Zero configuration
-- 🔄 Automatic reactivity
+- 🔄 Automatic reactivity through CSS cascade
 - 🎨 Framework agnostic
-- 📦 Tiny bundle size (~1KB)
-- ~~💪 Full TypeScript support~~ Sorry, JS-only for a while...
-- ~~📊 Optional performance monitoring~~ In progress (perf pending...)
+- 📦 Tiny bundle size (~2KB)
+- 🧩 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
-
-# Optional: Install performance monitoring
-npm install @uistate/performance
-```
-
-## Quick Start
-
-```typescript
-import { UIState } from '@uistate/core';
-
-// Initialize state
-UIState.init();
-
-// Set state
-UIState.setState('count', 0);
-
-// Get state
-const count = UIState.getState('count');
-
-// Subscribe to changes
-const unsubscribe = UIState.observe('count', (newValue) => {
-  console.log('Count changed:', newValue);
-});
-
-// React Hook
-import { useUIState } from '@uistate/core/react';
-
-function Counter() {
-  const [count, setCount] = useUIState('count', 0);
-  return (
-    <button onClick={() => setCount(count + 1)}>
-      Count: {count}
-    </button>
-  );
-}
 ```
 
 ## Why @uistate/core?
 
 ### Performance
 
-- **44% Faster Updates**: Leverages browser's CSS engine for optimal performance
-- **12.5% Lower Memory**: Efficient state storage using CSS custom properties
-- **Minimal Overhead**: No virtual DOM diffing for state updates
+- **CSS-Driven Updates**: Leverages browser's CSS engine for optimal performance with O(1) complexity
+- **DOM as Source of Truth**: Efficient state storage using CSS custom properties and data attributes
+- **Minimal Overhead**: No virtual DOM diffing or shadow DOM needed
 
 ### Developer Experience
 
-- **Simple API**: Just `setState`, `getState`, and `observe`
-- **TypeScript Support**: Full type safety and autocompletion
-- **Framework Agnostic**: Works with any framework
+- **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
 
-## Performance Monitoring
-
-The `@uistate/performance` package provides detailed performance metrics for your application:
+### Core Concepts
 
-```typescript
-import { PerformanceTracker } from '@uistate/performance';
-import { PerformanceDisplay } from '@uistate/performance';
-
-// Start tracking performance
-const tracker = PerformanceTracker.getInstance();
-tracker.start();
-
-// Optional: Add the performance display component to your React app
-function App() {
-  return (
-    <div>
-      <YourApp />
-      <PerformanceDisplay />
-    </div>
-  );
-}
-```
-
-The performance tracker monitors:
-- State update duration
-- Component render time
-- FPS (Frames Per Second)
-- Memory usage
-- Long task duration
+- **Attribute-Driven State Inheritance (ADSI)**: State represented both as CSS variables and data attributes
+- **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.ts         # Main entry
-│   ├── UIState.ts       # Core implementation
-│   └── react/           # React bindings
-│       └── index.ts     # React hooks
-├── packages/
-│   └── performance/     # Performance monitoring package
-└── examples/            # Example applications
-    ├── traditional/     # Traditional Redux app
-    └── uistate/        # UIState implementation
+├── 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
@@ -126,72 +72,38 @@ The performance tracker monitors:
 - Safari 10.1+
 - Edge 79+
 
-# Explanation of the Core Ideas Behind the UI State Management System
+# Core Ideas Behind UIstate
 
-A TypeScript-based UI state management system that leverages CSS custom properties (CSS variables) as the storage mechanism.
+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
 
-### Type Definitions
-
-```typescript
-type StateObserver<T> = (value: T) => void;
-interface UIStateType { ... }
-```
-
-- Defines a type for state change observers (callbacks)
-- Defines the interface for the state management system
-
-## Core Functionality
-
-The `UIState` object provides several key methods:
+### UIstate Core
 
-### `init()`
-- Creates a style element in the document head
-- Initializes a CSS stylesheet for managing custom properties
-- Returns the UIState instance for chaining
+The main UIstate object provides methods to manage state and templates:
 
-### `setState<T>(key: string, value: T)`
-- Stores values as CSS custom properties (--key)
-- Converts non-string values to JSON strings
-- Notifies observers when values change
+- **init()**: Initialize the UIstate system
+- **setState()**: Set state values
+- **getState()**: Get state values
+- **subscribe()**: Subscribe to state changes
+- **observe()**: Observe state paths for changes
 
-### `getState<T>(key: string)`
-- Retrieves values from CSS custom properties
-- Attempts to parse JSON values back to their original type
-- Falls back to raw string if parsing fails
+### Template Manager
 
-### `observe<T>(key: string, callback)`
-- Implements an observer pattern for state changes
-- Returns a cleanup function to remove the observer
-- Allows multiple observers per state key
+The template manager provides tools for declarative UI rendering:
 
-## Internal Mechanisms
-
-```typescript
-_sheet: CSSStyleSheet | null        // Stores the stylesheet reference
-_observers: Map<string, Set<StateObserver>>  // Stores observers per key
-```
+- **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 type safety through TypeScript generics
-3. Implements the observer pattern for reactive updates
-4. Handles serialization/deserialization of complex data types through JSON
-
-## Example Usage
-
-```typescript
-UIState.init();
-UIState.setState('theme', 'dark');
-UIState.observe('theme', (newValue) => {
-    console.log('Theme changed to:', newValue);
-});
-const currentTheme = UIState.getState<string>('theme');
-```
+2. Provides a clear separation between state storage (CSS) and behavior (JavaScript)
+3. Implements a pub/sub pattern for reactive updates
+4. Leverages CSS templates for declarative UI definition
 
-This implementation is particularly useful for managing global UI state like themes, layout preferences, or any other state that might affect multiple components simultaneously.
+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.0",
+  "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();