@uistate/core 4.1.2 → 5.0.1

package/LICENSE-eventTest.md

@@ -0,0 +1,26 @@
+# Proprietary License for eventTest.js
+
+Copyright (c) 2025 Ajdin Imsirovic
+
+## Permitted Uses
+
+You may use `eventTest.js` for:
+- Personal projects
+- Open-source projects
+- Educational purposes
+
+## Restrictions
+
+You may NOT:
+- Use this file in commercial products without a license
+- Modify or create derivative works
+- Redistribute this file separately from @uistate/core
+- Remove or alter this license notice
+
+## Commercial Licensing
+
+For commercial use, please contact: your@email.com
+
+---
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED.

package/README.md

@@ -1,11 +1,19 @@
-# UIstate
+# UIstate v5
 
-A revolutionary approach to UI state management using CSS custom properties and DOM attributes, featuring Attribute-Driven State Inheritance (ADSI).
+**Lightweight event-driven state management for modern web applications**
 
-**Current Version**: 4.1.2
+[![npm version](https://img.shields.io/npm/v/@uistate/core.svg)](https://www.npmjs.com/package/@uistate/core)
+[![License: MIT + Commercial](https://img.shields.io/badge/License-MIT%20%2B%20Commercial-blue.svg)](#license)
 
-**Author**: Ajdin Imsirovic <ajdika@live.com> (GitHub)  
-**Maintainer**: uistate <ajdika.i@gmail.com> (npm)
+After many experiments exploring different state management paradigms, UIstate v5 emerges as a focused, production-ready solution for complex UIs. Born from real-world challenges like building data tables, dashboards, and interactive applications.
+
+## What's New in v5
+
+- **EventState Core**: Path-based subscriptions with wildcard support (~80 LOC)
+- **Slot Orchestration**: Atomic component swapping without layout shift
+- **Intent-Driven**: Declarative command handling for decoupled architecture
+- **Zero Dependencies**: Pure JavaScript, works in any modern browser
+- **Framework-Free**: No build step required (but works great with Vite)
 
 ## Installation
 
@@ -15,48 +23,351 @@ npm install @uistate/core
 
 ## Quick Start
 
-UIstate v4.1.2 provides four core modules that can be imported individually:
+```javascript
+import { createEventState } from '@uistate/core';
+
+const store = createEventState({
+  user: { name: 'Alice' },
+  count: 0
+});
+
+// Subscribe to specific paths
+store.subscribe('user.name', (value) => {
+  console.log('Name changed:', value);
+});
+
+// Subscribe with wildcards
+store.subscribe('user.*', ({ path, value }) => {
+  console.log(`${path} changed to:`, value);
+});
+
+// Update state
+store.set('user.name', 'Bob');  // → Name changed: Bob
+store.set('count', 1);
+```
+
+## Core API
+
+### `createEventState(initial?)`
+
+Creates a new reactive store.
+
+```javascript
+const store = createEventState({ count: 0 });
+```
+
+### `store.get(path)`
+
+Retrieves a value by path.
+
+```javascript
+const count = store.get('count');
+const user = store.get('user');  // Returns entire user object
+const all = store.get();          // Returns entire store
+```
+
+### `store.set(path, value)`
+
+Sets a value and triggers subscriptions.
 
 ```javascript
-import { createCssState, createEventState, stateSerializer, createTemplateManager } from '@uistate/core';
+store.set('count', 42);
+store.set('user.email', 'alice@example.com');
+```
 
-// Create CSS-based state management
-const cssState = createCssState();
+### `store.subscribe(path, handler)`
 
-// Create event-based state management  
-const eventState = createEventState();
+Subscribes to changes. Returns an unsubscribe function.
 
-// Use state serialization utilities
-const serialized = stateSerializer.serialize(myState);
+```javascript
+// Exact path
+const unsub = store.subscribe('count', (value) => {
+  console.log('Count:', value);
+});
 
-// Create template manager for declarative UI
-const templateManager = createTemplateManager();
+// Wildcard (child changes)
+store.subscribe('user.*', ({ path, value }) => {
+  console.log(`User property ${path} changed`);
+});
+
+// Global wildcard (all changes)
+store.subscribe('*', ({ path, value }) => {
+  console.log('Something changed');
+});
+
+// Cleanup
+unsub();
+```
+
+### `store.destroy()`
+
+Cleans up the event bus and prevents further updates.
+
+```javascript
+store.destroy();
 ```
 
-## Core Modules
+# Changelog
 
-### `createCssState`
-Manages state using CSS custom properties for optimal performance and automatic reactivity.
+## [5.0.0] - 2025-12-09
 
-### `createEventState` 
-Provides event-driven state management with pub/sub patterns.
+### Breaking Changes
+- eventState is now primary export (was cssState)
+- DOM element event bus replaced with EventTarget
+- ...
 
-### `stateSerializer`
-Utilities for serializing and deserializing state data.
+### Added
+- Slot orchestration pattern
+- Intent-driven architecture
+- Event-sequence testing (experimental)
+- Example 009: Financial dashboard
+- Example 010: Event testing
 
-### `createTemplateManager`
-Declarative template management system for building UIs with CSS-based templates.
+## Architecture Patterns
 
-## Key Features
+UIstate v5 introduces battle-tested patterns from many experiments:
 
-- Potentially O(1) state updates
-- Significant memory savings compared to virtual DOM approaches
-- DOM as the single source of truth
-- CSS-driven state derivation
-- Framework agnostic
-- Tiny bundle size (~30KB uncompressed, ~8-10KB gzipped)
-- Zero dependencies
-- Modular architecture - import only what you need
+### 1. **Intent-Driven Updates** (Declarative Commands)
+
+Intents are just regular state paths—no special API needed. Components subscribe to intent paths and execute logic when triggered:
+
+```javascript
+// Subscribe to an intent path
+store.subscribe('intent.todo.add', ({ text }) => {
+  const items = store.get('todos.items') || [];
+  store.set('todos.items', [...items, { id: Date.now(), text, done: false }]);
+});
+
+// Trigger intent from UI by setting the path
+button.addEventListener('click', () => {
+  store.set('intent.todo.add', { text: input.value });
+});
+```
+
+**Key insight**: Intents are paths, not events. This means:
+- Subscribe once at component mount
+- Multiple components can listen to the same intent
+- Easy to test (just `set()` the intent path)
+- No special event emitter needed
+
+### 2. **Slot Orchestration** (Flicker-free component loading)
+
+Load layouts and components separately for atomic, layout-shift-free updates:
+
+```javascript
+// 1. Mount persistent layout once
+async function mountMaster(master) {
+  const layout = await fetchHTML(master.layout);
+  document.getElementById('app').innerHTML = layout;
+}
+
+// 2. Load components into slots atomically
+async function loadSlot({ slot, url }) {
+  const config = await fetchJSON(url);
+  const html = await fetchHTML(config.component);
+
+  // Find slot container
+  const slotHost = document.querySelector(`[data-slot="${slot}"]`);
+
+  // Atomic replacement - no layout shift!
+  const fragment = createFragment(html);
+  slotHost.replaceChildren(fragment);
+
+  // Wire up component subscriptions
+  wireComponent(slotHost, config.bindings);
+}
+
+// Trigger slot loading via intent
+store.subscribe('intent.slot.load', loadSlot);
+store.set('intent.slot.load', { slot: 'main', url: '/slots/todo.json' });
+```
+
+**Key insight**: Separate layout (skeleton) from content (slots):
+- Layout provides stable structure
+- Slots swap atomically without reflow
+- Each component manages its own subscriptions
+- Clean separation of concerns
+
+### 3. **Component Bindings** (Path-based reactivity)
+
+Components subscribe to specific state paths, not global wildcards:
+
+```javascript
+function wireComponent(root, bindings) {
+  const input = root.querySelector('#input');
+  const list = root.querySelector('#list');
+  const itemsPath = bindings.items || 'domain.items';
+
+  // Subscribe to specific path for this component
+  const unsubscribe = store.subscribe(itemsPath, (items) => {
+    list.replaceChildren();
+    items.forEach(item => {
+      const li = document.createElement('li');
+      li.textContent = item.text;
+      list.appendChild(li);
+    });
+  });
+
+  // Initial render
+  const items = store.get(itemsPath);
+  if (items) store.set(itemsPath, items);
+
+  // Return cleanup function
+  return unsubscribe;
+}
+```
+
+**Key insight**: Each component subscribes to its own paths:
+- No global `*` wildcards in production code
+- Components are isolated and testable
+- Easy cleanup when unmounting
+- Clear data dependencies
+
+### 4. **Component Lifecycle Pattern**
+
+Proper mount/unmount with subscription cleanup:
+
+```javascript
+const componentRegistry = new Map();
+
+async function loadSlot({ slot, url }) {
+  // Cleanup previous component in this slot
+  const existing = componentRegistry.get(slot);
+  if (existing?.cleanup) {
+    existing.cleanup();
+  }
+
+  // Load and mount new component
+  const config = await fetchJSON(url);
+  const html = await fetchHTML(config.component);
+  const slotHost = document.querySelector(`[data-slot="${slot}"]`);
+  slotHost.replaceChildren(createFragment(html));
+
+  // Wire up with cleanup function
+  const cleanup = wireComponent(slotHost, config.bindings);
+
+  // Store for later cleanup
+  componentRegistry.set(slot, { cleanup });
+}
+```
+
+**Key insight**: Always clean up subscriptions:
+- Prevents memory leaks
+- Allows safe component swapping
+- Components are truly hot-swappable
+- No zombie subscriptions
+
+### 5. **Content-Driven Layout** (Layout morphs based on active content)
+
+One layout HTML can adapt to different use cases by subscribing to state and toggling CSS classes:
+
+```javascript
+function wireLayout(root, bindings) {
+  // ...existing button wiring...
+
+  // Layout adapts based on which slot is active
+  store.subscribe('ui.view.active', (active) => {
+    const kpiCol = root.querySelector('[data-slot="kpi"]').closest('.col-12');
+    const newsCol = root.querySelector('[data-slot="news"]').closest('.col-12');
+    const positionsCol = root.querySelector('[data-slot="positions"]').closest('.col-12');
+
+    if (active === 'todos') {
+      // Full-width editing mode
+      kpiCol.classList.add('d-none');
+      newsCol.classList.add('d-none');
+      positionsCol.classList.remove('col-md-6', 'col-lg-4');
+      positionsCol.classList.add('col-md-12', 'col-lg-8');
+    } else {
+      // Multi-column dashboard mode
+      kpiCol.classList.remove('d-none');
+      newsCol.classList.remove('d-none');
+      positionsCol.classList.remove('col-md-12', 'col-lg-8');
+      positionsCol.classList.add('col-md-6', 'col-lg-4');
+    }
+  });
+}
+```
+
+**Key insight**: Content configures layout, not the other way around:
+- One layout HTML handles all scenarios
+- Panels show/hide based on active content
+- Sections expand/collapse responsively
+- Pure CSS class manipulation - no DOM restructuring
+- Declarative layout rules via state subscription
+
+**Real-world applications**:
+```javascript
+// E-commerce: hide sidebar, expand product grid
+if (active === 'products') hideSlots(['filters', 'cart']); expandSlot('grid');
+
+// Admin: hide navigation, expand table
+if (active === 'report') hideSlots(['nav', 'sidebar']); expandSlot('table');
+
+// Editor: focus mode - hide everything except content
+if (active === 'editor') hideSlots(['toolbar', 'preview']); expandSlot('content');
+```
+
+This pattern eliminates the "rigid layout" criticism - UIstate layouts are as flexible as any framework, with zero VDOM overhead.
+
+## Complete Example
+
+See `examples/009-financial-dashboard` for a real-world application featuring:
+
+- Multi-slot dashboard layout
+- TodoList with filtering
+- Financial data tables (KPI, Positions, Debts, Sales, News)
+- Intent-driven architecture
+- Atomic slot swapping
+- State inspector
+
+Run the example:
+
+```bash
+cd node_modules/@uistate/core/examples/009-financial-dashboard
+npx serve .
+```
+
+Open http://localhost:3000 and explore the multi-slot dashboard!
+
+## Why UIstate v5?
+
+### vs. React/Vue
+
+- ✅ **No VDOM overhead** - Direct DOM manipulation with surgical updates
+- ✅ **No build step required** - Works in browsers directly
+- ✅ **Simpler mental model** - Paths + subscriptions, not components + lifecycle hooks
+- ✅ **Smaller bundle** - ~3KB core vs ~40KB+ frameworks
+- ✅ **Explicit reactivity** - Know exactly what triggers what
+- ❌ No component ecosystem
+- ❌ Manual DOM updates (but that's the point!)
+
+### vs. Alpine.js
+
+- ✅ **Better for complex state** - Nested paths, cross-component communication
+- ✅ **First-class SPA patterns** - Slot orchestration, intent-driven updates
+- ✅ **More powerful subscriptions** - Path-based, wildcard support, granular control
+- ✅ **Explicit data flow** - No magic, clear cause and effect
+- ❌ More JavaScript required (Alpine is more declarative HTML)
+
+### vs. Zustand/Jotai
+
+- ✅ **Framework-agnostic** - Not tied to React
+- ✅ **Path-based state** - More intuitive for deeply nested data
+- ✅ **Wildcard subscriptions** - Subscribe to entire subtrees when needed
+- ✅ **Simpler API** - Just get/set/subscribe, no atoms or stores
+- ❌ Smaller ecosystem
+- ❌ No React DevTools integration
+
+## Use Cases
+
+UIstate v5 excels at:
+
+- ✅ **Internal dashboards** - Complex state, multiple data sources
+- ✅ **Admin panels** - CRUD operations, forms, data tables
+- ✅ **Financial applications** - Real-time updates, calculations
+- ✅ **Data-heavy UIs** - Large datasets, filtered views
+- ✅ **Multi-pane interfaces** - Independent but coordinated components
+- ✅ **Progressive enhancement** - Add interactivity to server-rendered HTML
 
 ## Browser Support
 
@@ -65,21 +376,77 @@ Declarative template management system for building UIs with CSS-based templates
 - Safari 10.1+
 - Edge 79+
 
+## Migration from v4
+
+UIstate v5 shifts focus from CSS-driven state to event-driven state. Key changes:
+
+1. **eventState is now primary** - Import from root or `/eventState`
+2. **cssState still available** - Import from `/cssState`
+3. **New examples** - See `009-financial-dashboard`
+4. **Breaking changes** - Major version bump
+
 ## Philosophy
 
-UIstate challenges traditional assumptions in web development by using the DOM as the source of truth for state, leveraging CSS variables and data attributes for state storage, and using the CSS cascade for state inheritance and derivation.
+UIstate challenges traditional assumptions:
+
+- **State should be simple** - Paths + subscriptions, not selectors + reducers
+- **Reactivity should be explicit** - Know what updates what
+- **DOM updates can be fast** - Atomic replacements beat VDOM for many use cases
+- **Components should own their subscriptions** - No global wildcards in production
+- **Frameworks aren't always needed** - Pure JS + patterns can go far
+- **Build steps should be optional** - ESM works in browsers
+- **Intents are just paths** - No special event system needed
+
+UIstate v5 represents lessons learned from building:
+- Data tables with 1M+ rows
+- Multi-tab synchronized state
+- Workflowy-style nested lists
+- Financial dashboards
+- Admin panels
 
-The v4.1.0 release focuses on simplicity and modularity - providing clean, individual modules that can be composed together as needed, without the complexity of a unified framework.
+The core insight: **Most web UIs need reactive state and component orchestration, not a full framework.**
 
-## Examples
+## Testing (Experimental)
 
-Explore our documentation and examples to see UIstate in action:
+UIstate includes `eventTest.js` for event-sequence testing:
 
-- Range sliders with different state derivation approaches
-- Button toggles with CSS state projection
-- Font adjusters with domain-based state management
-- And more!
+**Note:** `eventTest.js` is dual-licensed. Free for personal/OSS use. Commercial use requires a separate license. See LICENSE-eventTest.md for details.
+
+```javascript
+import { createEventTest } from '@uistate/core/eventTest';
+
+const test = createEventTest({ count: 0 });
+
+test
+  .trigger('intent.increment')
+  .assertPath('count', 1)
+  .assertEventFired('count', 1);
+```
+
+See `examples/010-event-testing` for more.
 
 ## License
 
-MIT  Ajdin Imsirovic
+**@uistate/core** is licensed under the **MIT License**, with an exception, as decribed next.
+
+**Exception:** `eventTest.js` is licensed under a **proprietary license** that permits:
+- ✅ Personal use
+- ✅ Open-source projects
+- ✅ Educational use
+
+For **commercial use** of `eventTest.js`, please contact: [ajdika@live.com](mailto:ajdika@live.com)
+
+See the file header in `eventTest.js` for full terms.
+
+---
+
+Copyright © 2025 Ajdin Imsirovic (ajdika@live.com)
+
+- Core library: MIT License
+- eventTest.js: Commercial License (free for personal/OSS)
+
+## Links
+
+- [GitHub](https://github.com/ImsirovicAjdin/uistate)
+- [npm](https://www.npmjs.com/package/@uistate/core)
+- [Issues](https://github.com/ImsirovicAjdin/uistate/issues)

package/cssState.js

@@ -1,3 +1,9 @@
+/**
+ * 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) => {
@@ -6,7 +12,7 @@ const createCssState = (initialState = {}, serializer = StateSerializer) => {
         _observers: new Map(),
         _serializer: serializer,
         _specialHandlers: {},
-        _eventHandlers: new Map(),
+        _eventHandlers: new Map(), // Store custom event binding handlers
 
         init(serializerConfig) {
             if (!this._sheet) {
@@ -16,10 +22,12 @@ 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);
@@ -30,11 +38,14 @@ 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;
         },
@@ -50,6 +61,7 @@ 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);
         },
 
@@ -78,6 +90,7 @@ const createCssState = (initialState = {}, serializer = StateSerializer) => {
             return this;
         },
 
+        // New method for registering event bindings
         registerEventBinding(eventType, handler) {
             this._eventHandlers.set(eventType, handler);
             return this;
@@ -88,21 +101,27 @@ 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;
                 }
 
@@ -112,6 +131,7 @@ 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;
@@ -119,11 +139,13 @@ 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);
@@ -136,16 +158,20 @@ 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));
@@ -160,6 +186,7 @@ const createCssState = (initialState = {}, serializer = StateSerializer) => {
             }
         },
 
+        // Add serializer configuration method
         configureSerializer(config) {
             if (this._serializer.configure) {
                 this._serializer.configure(config);
@@ -167,14 +194,18 @@ 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 };