@uistate/core 4.1.2 → 5.0.0

package/examples/003-input-reactive/README.md

@@ -0,0 +1,44 @@
+# 001 Counter - Minimal EventState Example
+
+The simplest possible EventState example: a counter with one button.
+
+## What's Here
+
+- `eventState.js` - ~60 lines of reactive state management
+- `index.html` - Counter UI with subscription
+
+## How It Works
+
+```javascript
+// 1. Create store
+const store = createEventState({ count: 0 });
+
+// 2. Subscribe to changes
+store.subscribe('count', ({ value }) => {
+  document.getElementById('count').textContent = value;
+});
+
+// 3. Update state
+store.set('count', store.get('count') + 1);
+```
+
+That's it. No framework, no build step, just reactive data.
+
+## Run It
+
+Open `index.html` in a browser. Click the `+` button to increment.
+
+## Key Concepts
+
+- **`createEventState(initial)`** - Creates a reactive store
+- **`store.get(path)`** - Read state at dot-path
+- **`store.set(path, value)`** - Write state and notify subscribers
+- **`store.subscribe(path, handler)`** - React to changes
+
+## Next Steps
+
+See `examples/009-todo-app-with-eventTest/` for a full application with:
+- Router
+- Bridges (intent → domain pattern)
+- Tests with type generation
+- Dev tools

package/examples/003-input-reactive/eventState.js

@@ -0,0 +1,86 @@
+const createEventState = (initial = {}) => {
+    const store = JSON.parse(JSON.stringify(initial));
+
+    const bus = new EventTarget();
+    let destroyed = false;
+
+    return {
+        get: (path) => {
+            if (destroyed) throw new Error('Cannot get from destroyed store');
+            if (!path) return store;
+
+            // Parse dot-paths: 'items.0' → ['items', '0']
+            const parts = path.split('.').flatMap(part => {
+                const match = part.match(/([^\[]+)\[(\d+)\]/);
+                return match ? [match[1], match[2]] : part;
+            });
+
+            return parts.reduce(
+                (obj, prop) => (obj && obj[prop] !== undefined ? obj[prop] : undefined),
+                store
+            );
+        },
+        set: (path, value) => {
+            if (destroyed) throw new Error('Cannot set on destroyed store');
+            if (!path) return;
+            const parts = path.split('.');
+            const last = parts.pop();
+            let target = store;
+
+            for (const key of parts) {
+              // create intermediate objects as needed
+              if (typeof target[key] !== 'object' || target[key] === null) {
+                target[key] = {};
+              }
+              target = target[key];
+            }
+
+            target[last] = value;
+
+            if (!destroyed) {
+                // exact path
+                bus.dispatchEvent(new CustomEvent(path, { detail: value }));
+
+                // parent wildcards: a, a.b -> 'a.*', 'a.b.*'
+                for (let i = 1; i <= parts.length; i++) {
+                    const parent = parts.slice(0, i).join('.');
+                    bus.dispatchEvent(new CustomEvent(`${parent}.*`, { detail: { path, value } }));
+                }
+
+                // root wildcard
+                bus.dispatchEvent(new CustomEvent('*', { detail: { path, value } }));
+            }
+
+            return value;
+        },
+        subscribe(path, handler) {
+            if (destroyed) throw new Error('store destroyed');
+            if (!path || typeof handler !== 'function') {
+                throw new TypeError('subscribe(path, handler) requires a string path and function handler');
+            }
+            const onEvent = (evt) => handler(evt.detail, evt);
+            bus.addEventListener(path, onEvent);
+
+            return function unsubscribe() {
+                bus.removeEventListener(path, onEvent);
+            };
+        },
+        off(unsubscribe) {
+            if (typeof unsubscribe !== 'function') {
+                throw new TypeError('off(unsubscribe) requires a function returned by subscribe');
+            }
+            return unsubscribe();
+        },
+
+        destroy() {
+            if (!destroyed) {
+                destroyed = true;
+                // EventTarget has no parentNode - just mark as destroyed
+                // Future sets/subscribes will be blocked by destroyed flag
+            }
+        }
+    };
+}
+
+export default createEventState;
+export { createEventState };

package/examples/003-input-reactive/index.html

@@ -0,0 +1,30 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>003 Input Reactive - EventState</title>
+</head>
+<body>
+  <h1>Type something:</h1>
+  <input type="text" id="textInput" placeholder="Start typing...">
+  <p id="output"></p>
+
+  <script type="module">
+    import { createEventState } from './eventState.js';
+
+    // Create store
+    const store = createEventState({ text: '' });
+
+    // Subscribe to text changes
+    store.subscribe('text', (value) => {
+      document.getElementById('output').textContent = value;
+    });
+
+    // Update state on input
+    document.getElementById('textInput').oninput = (e) => {
+      store.set('text', e.target.value);
+    };
+  </script>
+</body>
+</html>

package/examples/004-computed-state/README.md

@@ -0,0 +1,45 @@
+# 004 Computed State - Derived Values
+
+Shows how trivial it is to create computed/derived state in EventState.
+
+## What's Here
+
+- Two inputs: `firstName` and `lastName`
+- Two computed values: `fullName` and `charCount`
+- **Zero framework magic** - just functions
+
+## How It Works
+
+```javascript
+// 1. Define a function that computes derived state
+const updateFullName = () => {
+  const first = store.get('firstName');
+  const last = store.get('lastName');
+  const fullName = `${first} ${last}`.trim();
+  document.getElementById('fullName').textContent = fullName;
+};
+
+// 2. Subscribe to wildcard to catch all changes
+store.subscribe('*', () => {
+  updateFullName();
+  updateCharCount();
+});
+
+// 3. That's it. No special API needed.
+```
+
+## Key Insight
+
+**Computed state is just a function.** 
+
+Other frameworks need:
+- Vue: `computed()`
+- React: `useMemo()`
+- Svelte: `$:` reactive declarations
+- MobX: `@computed` decorators
+
+**EventState:** Just write a function and call it when state changes.
+
+## Run It
+
+Open `index.html` in a browser. Type in the inputs and watch the computed values update.

package/examples/004-computed-state/eventState.js

@@ -0,0 +1,86 @@
+const createEventState = (initial = {}) => {
+    const store = JSON.parse(JSON.stringify(initial));
+
+    const bus = new EventTarget();
+    let destroyed = false;
+
+    return {
+        get: (path) => {
+            if (destroyed) throw new Error('Cannot get from destroyed store');
+            if (!path) return store;
+
+            // Parse dot-paths: 'items.0' → ['items', '0']
+            const parts = path.split('.').flatMap(part => {
+                const match = part.match(/([^\[]+)\[(\d+)\]/);
+                return match ? [match[1], match[2]] : part;
+            });
+
+            return parts.reduce(
+                (obj, prop) => (obj && obj[prop] !== undefined ? obj[prop] : undefined),
+                store
+            );
+        },
+        set: (path, value) => {
+            if (destroyed) throw new Error('Cannot set on destroyed store');
+            if (!path) return;
+            const parts = path.split('.');
+            const last = parts.pop();
+            let target = store;
+
+            for (const key of parts) {
+              // create intermediate objects as needed
+              if (typeof target[key] !== 'object' || target[key] === null) {
+                target[key] = {};
+              }
+              target = target[key];
+            }
+
+            target[last] = value;
+
+            if (!destroyed) {
+                // exact path
+                bus.dispatchEvent(new CustomEvent(path, { detail: value }));
+
+                // parent wildcards: a, a.b -> 'a.*', 'a.b.*'
+                for (let i = 1; i <= parts.length; i++) {
+                    const parent = parts.slice(0, i).join('.');
+                    bus.dispatchEvent(new CustomEvent(`${parent}.*`, { detail: { path, value } }));
+                }
+
+                // root wildcard
+                bus.dispatchEvent(new CustomEvent('*', { detail: { path, value } }));
+            }
+
+            return value;
+        },
+        subscribe(path, handler) {
+            if (destroyed) throw new Error('store destroyed');
+            if (!path || typeof handler !== 'function') {
+                throw new TypeError('subscribe(path, handler) requires a string path and function handler');
+            }
+            const onEvent = (evt) => handler(evt.detail, evt);
+            bus.addEventListener(path, onEvent);
+
+            return function unsubscribe() {
+                bus.removeEventListener(path, onEvent);
+            };
+        },
+        off(unsubscribe) {
+            if (typeof unsubscribe !== 'function') {
+                throw new TypeError('off(unsubscribe) requires a function returned by subscribe');
+            }
+            return unsubscribe();
+        },
+
+        destroy() {
+            if (!destroyed) {
+                destroyed = true;
+                // EventTarget has no parentNode - just mark as destroyed
+                // Future sets/subscribes will be blocked by destroyed flag
+            }
+        }
+    };
+}
+
+export default createEventState;
+export { createEventState };

package/examples/004-computed-state/index.html

@@ -0,0 +1,62 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>004 Computed State - EventState</title>
+</head>
+<body>
+  <h1>Computed State</h1>
+  
+  <label>First Name: <input type="text" id="firstName" placeholder="Abraham"></label><br>
+  <label>Last Name: <input type="text" id="lastName" placeholder="Lincoln"></label><br>
+  
+  <p><strong>Full Name:</strong> <span id="fullName"></span></p>
+  <p><strong>Character Count:</strong> <span id="charCount">0</span></p>
+
+  <script type="module">
+    import { createEventState } from './eventState.js';
+
+    // Create store
+    const store = createEventState({ 
+      firstName: '', 
+      lastName: '' 
+    });
+
+    // Computed: full name (derived from firstName + lastName)
+    const updateFullName = () => {
+      const first = store.get('firstName');
+      const last = store.get('lastName');
+      const fullName = `${first} ${last}`.trim();
+      document.getElementById('fullName').textContent = fullName || '(empty)';
+    };
+
+    // Computed: character count
+    const updateCharCount = () => {
+      const first = store.get('firstName');
+      const last = store.get('lastName');
+      const total = (first + last).length;
+      document.getElementById('charCount').textContent = total;
+    };
+
+    // Subscribe to any state change and recompute
+    store.subscribe('*', () => {
+      updateFullName();
+      updateCharCount();
+    });
+
+    // Wire up inputs
+    document.getElementById('firstName').oninput = (e) => {
+      store.set('firstName', e.target.value);
+    };
+
+    document.getElementById('lastName').oninput = (e) => {
+      store.set('lastName', e.target.value);
+    };
+
+    // Initial render
+    updateFullName();
+    updateCharCount();
+  </script>
+</body>
+</html>

package/examples/005-conditional-rendering/README.md

@@ -0,0 +1,42 @@
+# 005 Conditional Rendering - Show/Hide Elements
+
+Demonstrates how to conditionally render elements based on state.
+
+## What's Here
+
+- Checkbox to toggle visibility
+- Message that shows/hides based on state
+- **No `v-if` or `{#if}` needed** - just DOM manipulation
+
+## How It Works
+
+```javascript
+// 1. Store boolean state
+const store = createEventState({ isVisible: false });
+
+// 2. Subscribe and toggle display
+store.subscribe('isVisible', (value) => {
+  const message = document.getElementById('message');
+  message.style.display = value ? 'block' : 'none';
+});
+
+// 3. Update state on checkbox change
+document.getElementById('toggle').onchange = (e) => {
+  store.set('isVisible', e.target.checked);
+};
+```
+
+## Key Insight
+
+**Conditional rendering is just DOM manipulation.**
+
+Other frameworks need:
+- React: `{isVisible && <p>Message</p>}`
+- Vue: `v-if="isVisible"`
+- Svelte: `{#if isVisible}`
+
+**EventState:** Just set `style.display` in a subscriber. That's it.
+
+## Run It
+
+Open `index.html` in a browser. Check the box to reveal the message.

package/examples/005-conditional-rendering/eventState.js

@@ -0,0 +1,86 @@
+const createEventState = (initial = {}) => {
+    const store = JSON.parse(JSON.stringify(initial));
+
+    const bus = new EventTarget();
+    let destroyed = false;
+
+    return {
+        get: (path) => {
+            if (destroyed) throw new Error('Cannot get from destroyed store');
+            if (!path) return store;
+
+            // Parse dot-paths: 'items.0' → ['items', '0']
+            const parts = path.split('.').flatMap(part => {
+                const match = part.match(/([^\[]+)\[(\d+)\]/);
+                return match ? [match[1], match[2]] : part;
+            });
+
+            return parts.reduce(
+                (obj, prop) => (obj && obj[prop] !== undefined ? obj[prop] : undefined),
+                store
+            );
+        },
+        set: (path, value) => {
+            if (destroyed) throw new Error('Cannot set on destroyed store');
+            if (!path) return;
+            const parts = path.split('.');
+            const last = parts.pop();
+            let target = store;
+
+            for (const key of parts) {
+              // create intermediate objects as needed
+              if (typeof target[key] !== 'object' || target[key] === null) {
+                target[key] = {};
+              }
+              target = target[key];
+            }
+
+            target[last] = value;
+
+            if (!destroyed) {
+                // exact path
+                bus.dispatchEvent(new CustomEvent(path, { detail: value }));
+
+                // parent wildcards: a, a.b -> 'a.*', 'a.b.*'
+                for (let i = 1; i <= parts.length; i++) {
+                    const parent = parts.slice(0, i).join('.');
+                    bus.dispatchEvent(new CustomEvent(`${parent}.*`, { detail: { path, value } }));
+                }
+
+                // root wildcard
+                bus.dispatchEvent(new CustomEvent('*', { detail: { path, value } }));
+            }
+
+            return value;
+        },
+        subscribe(path, handler) {
+            if (destroyed) throw new Error('store destroyed');
+            if (!path || typeof handler !== 'function') {
+                throw new TypeError('subscribe(path, handler) requires a string path and function handler');
+            }
+            const onEvent = (evt) => handler(evt.detail, evt);
+            bus.addEventListener(path, onEvent);
+
+            return function unsubscribe() {
+                bus.removeEventListener(path, onEvent);
+            };
+        },
+        off(unsubscribe) {
+            if (typeof unsubscribe !== 'function') {
+                throw new TypeError('off(unsubscribe) requires a function returned by subscribe');
+            }
+            return unsubscribe();
+        },
+
+        destroy() {
+            if (!destroyed) {
+                destroyed = true;
+                // EventTarget has no parentNode - just mark as destroyed
+                // Future sets/subscribes will be blocked by destroyed flag
+            }
+        }
+    };
+}
+
+export default createEventState;
+export { createEventState };

package/examples/005-conditional-rendering/index.html

@@ -0,0 +1,36 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>005 Conditional Rendering - EventState</title>
+</head>
+<body>
+  <h1>Conditional Rendering</h1>
+  
+  <label>
+    <input type="checkbox" id="toggle">
+    Show secret message
+  </label>
+  
+  <p id="message" style="display: none;">🎉 You found the secret message!</p>
+
+  <script type="module">
+    import { createEventState } from './eventState.js';
+
+    // Create store
+    const store = createEventState({ isVisible: false });
+
+    // Subscribe to visibility changes
+    store.subscribe('isVisible', (value) => {
+      const message = document.getElementById('message');
+      message.style.display = value ? 'block' : 'none';
+    });
+
+    // Toggle on checkbox change
+    document.getElementById('toggle').onchange = (e) => {
+      store.set('isVisible', e.target.checked);
+    };
+  </script>
+</body>
+</html>

package/examples/006-list-rendering/README.md

@@ -0,0 +1,49 @@
+# 006 List Rendering - Dynamic Arrays
+
+Demonstrates how to render lists from array state.
+
+## What's Here
+
+- Input to add items
+- Dynamic list that updates on state change
+- **No `v-for` or `.map()` in JSX** - just `innerHTML`
+
+## How It Works
+
+```javascript
+// 1. Store array in state
+const store = createEventState({ items: [] });
+
+// 2. Render function
+const renderList = () => {
+  const items = store.get('items');
+  const list = document.getElementById('itemList');
+  list.innerHTML = items.map(item => `<li>${item}</li>`).join('');
+};
+
+// 3. Subscribe to array changes
+store.subscribe('items', renderList);
+
+// 4. Add items by creating new array
+const items = store.get('items');
+store.set('items', [...items, newItem]);
+```
+
+## Key Insight
+
+**List rendering is just string concatenation.**
+
+Other frameworks need:
+- React: `{items.map(item => <li>{item}</li>)}`
+- Vue: `v-for="item in items"`
+- Svelte: `{#each items as item}`
+
+**EventState:** Just use `.map()` and `innerHTML`. That's it.
+
+## Important
+
+We create a **new array** with `[...items, newItem]` instead of mutating. This ensures the subscription fires (new reference = change detected).
+
+## Run It
+
+Open `index.html` in a browser. Type items and click Add (or press Enter).

package/examples/006-list-rendering/eventState.js

@@ -0,0 +1,86 @@
+const createEventState = (initial = {}) => {
+    const store = JSON.parse(JSON.stringify(initial));
+
+    const bus = new EventTarget();
+    let destroyed = false;
+
+    return {
+        get: (path) => {
+            if (destroyed) throw new Error('Cannot get from destroyed store');
+            if (!path) return store;
+
+            // Parse dot-paths: 'items.0' → ['items', '0']
+            const parts = path.split('.').flatMap(part => {
+                const match = part.match(/([^\[]+)\[(\d+)\]/);
+                return match ? [match[1], match[2]] : part;
+            });
+
+            return parts.reduce(
+                (obj, prop) => (obj && obj[prop] !== undefined ? obj[prop] : undefined),
+                store
+            );
+        },
+        set: (path, value) => {
+            if (destroyed) throw new Error('Cannot set on destroyed store');
+            if (!path) return;
+            const parts = path.split('.');
+            const last = parts.pop();
+            let target = store;
+
+            for (const key of parts) {
+              // create intermediate objects as needed
+              if (typeof target[key] !== 'object' || target[key] === null) {
+                target[key] = {};
+              }
+              target = target[key];
+            }
+
+            target[last] = value;
+
+            if (!destroyed) {
+                // exact path
+                bus.dispatchEvent(new CustomEvent(path, { detail: value }));
+
+                // parent wildcards: a, a.b -> 'a.*', 'a.b.*'
+                for (let i = 1; i <= parts.length; i++) {
+                    const parent = parts.slice(0, i).join('.');
+                    bus.dispatchEvent(new CustomEvent(`${parent}.*`, { detail: { path, value } }));
+                }
+
+                // root wildcard
+                bus.dispatchEvent(new CustomEvent('*', { detail: { path, value } }));
+            }
+
+            return value;
+        },
+        subscribe(path, handler) {
+            if (destroyed) throw new Error('store destroyed');
+            if (!path || typeof handler !== 'function') {
+                throw new TypeError('subscribe(path, handler) requires a string path and function handler');
+            }
+            const onEvent = (evt) => handler(evt.detail, evt);
+            bus.addEventListener(path, onEvent);
+
+            return function unsubscribe() {
+                bus.removeEventListener(path, onEvent);
+            };
+        },
+        off(unsubscribe) {
+            if (typeof unsubscribe !== 'function') {
+                throw new TypeError('off(unsubscribe) requires a function returned by subscribe');
+            }
+            return unsubscribe();
+        },
+
+        destroy() {
+            if (!destroyed) {
+                destroyed = true;
+                // EventTarget has no parentNode - just mark as destroyed
+                // Future sets/subscribes will be blocked by destroyed flag
+            }
+        }
+    };
+}
+
+export default createEventState;
+export { createEventState };