npm - @uistate/core - Versions diffs - 4.1.2 → 5.0.0 - Mend

@uistate/core 4.1.2 → 5.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (150) hide show

package/examples/006-list-rendering/index.html ADDED Viewed

@@ -0,0 +1,60 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>006 List Rendering - EventState</title>
+</head>
+<body>
+  <h1>Shopping List</h1>
+  <input type="text" id="itemInput" placeholder="Add item...">
+  <button id="addBtn">Add</button>
+  <ul id="itemList"></ul>
+  <script type="module">
+    import { createEventState } from './eventState.js';
+    // Create store
+    const store = createEventState({ items: [] });
+    // Render list
+    const renderList = () => {
+      const items = store.get('items');
+      const list = document.getElementById('itemList');
+      if (items.length === 0) {
+        list.innerHTML = '<li><em>No items yet</em></li>';
+      } else {
+        list.innerHTML = items.map(item => `<li>${item}</li>`).join('');
+      }
+    };
+    // Subscribe to items changes
+    store.subscribe('items', renderList);
+    // Add item
+    document.getElementById('addBtn').onclick = () => {
+      const input = document.getElementById('itemInput');
+      const value = input.value.trim();
+      if (value) {
+        const items = store.get('items');
+        store.set('items', [...items, value]);
+        input.value = '';
+      }
+    };
+    // Add on Enter key
+    document.getElementById('itemInput').onkeypress = (e) => {
+      if (e.key === 'Enter') {
+        document.getElementById('addBtn').click();
+      }
+    };
+    // Initial render
+    renderList();
+  </script>
+</body>
+</html>

package/examples/007-form-validation/README.md ADDED Viewed

@@ -0,0 +1,52 @@
+# 007 Form Validation - Real-time Feedback
+Demonstrates form validation with multiple state paths and computed validity.
+## What's Here
+- Email and password inputs
+- Real-time validation messages
+- Submit button enabled only when form is valid
+- **No form library needed** - just state and functions
+## How It Works
+```javascript
+// 1. Store input values AND validation state
+const store = createEventState({
+  email: '',
+  password: '',
+  emailValid: false,
+  passwordValid: false
+});
+// 2. Validate on input change
+store.subscribe('email', (value) => {
+  const isValid = validateEmail(value);
+  store.set('emailValid', isValid);
+  // Show error message
+});
+// 3. Enable submit when all fields valid
+store.subscribe('emailValid', updateSubmitButton);
+store.subscribe('passwordValid', updateSubmitButton);
+```
+## Key Insight
+**Validation is just derived state.**
+- Input values are **source state**
+- Validation flags are **derived state**
+- Submit button state is **computed from derived state**
+Other frameworks need:
+- React: `useForm` hooks, validation libraries
+- Vue: `v-model` + validation plugins
+- Svelte: Stores + validation actions
+**EventState:** Just subscribe to inputs, validate, and update state. That's it.
+## Run It
+Open `index.html` in a browser. Type invalid data to see error messages. Submit button enables when both fields are valid.

package/examples/007-form-validation/eventState.js ADDED Viewed

@@ -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/007-form-validation/index.html ADDED Viewed

@@ -0,0 +1,99 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>007 Form Validation - EventState</title>
+</head>
+<body>
+  <h1>Sign Up Form</h1>
+  <label>
+    Email:
+    <input type="email" id="email" placeholder="you@example.com">
+  </label>
+  <p id="emailError" style="color: red;"></p>
+  <label>
+    Password:
+    <input type="password" id="password" placeholder="Min 8 characters">
+  </label>
+  <p id="passwordError" style="color: red;"></p>
+  <button id="submitBtn" disabled>Submit</button>
+  <p id="submitMessage" style="color: green;"></p>
+  <script type="module">
+    import { createEventState } from './eventState.js';
+    // Create store
+    const store = createEventState({
+      email: '',
+      password: '',
+      emailValid: false,
+      passwordValid: false
+    });
+    // Validate email
+    const validateEmail = (email) => {
+      return email.includes('@') && email.includes('.');
+    };
+    // Validate password
+    const validatePassword = (password) => {
+      return password.length >= 8;
+    };
+    // Update submit button state
+    const updateSubmitButton = () => {
+      const emailValid = store.get('emailValid');
+      const passwordValid = store.get('passwordValid');
+      document.getElementById('submitBtn').disabled = !(emailValid && passwordValid);
+    };
+    // Subscribe to email changes
+    store.subscribe('email', (value) => {
+      const isValid = validateEmail(value);
+      store.set('emailValid', isValid);
+      const error = document.getElementById('emailError');
+      error.textContent = value && !isValid ? 'Invalid email address' : '';
+    });
+    // Subscribe to password changes
+    store.subscribe('password', (value) => {
+      const isValid = validatePassword(value);
+      store.set('passwordValid', isValid);
+      const error = document.getElementById('passwordError');
+      error.textContent = value && !isValid ? 'Password must be at least 8 characters' : '';
+    });
+    // Subscribe to validation state changes
+    store.subscribe('emailValid', updateSubmitButton);
+    store.subscribe('passwordValid', updateSubmitButton);
+    // Wire up inputs
+    document.getElementById('email').oninput = (e) => {
+      store.set('email', e.target.value);
+    };
+    document.getElementById('password').oninput = (e) => {
+      store.set('password', e.target.value);
+    };
+    // Handle submit
+    document.getElementById('submitBtn').onclick = () => {
+      const email = store.get('email');
+      const message = document.getElementById('submitMessage');
+      message.textContent = `✓ Form submitted for ${email}`;
+      // Clear form
+      document.getElementById('email').value = '';
+      document.getElementById('password').value = '';
+      store.set('email', '');
+      store.set('password', '');
+    };
+  </script>
+</body>
+</html>

package/examples/008-undo-redo/README.md ADDED Viewed

@@ -0,0 +1,70 @@
+# 008 Undo/Redo - Time Travel Debugging
+Demonstrates how EventState's event-driven architecture makes undo/redo trivial.
+## What's Here
+- Counter with multiple operations
+- Undo/Redo buttons
+- History tracking showing current position
+- **No special library needed** - just an array
+## How It Works
+```javascript
+// 1. Track history in an array
+let history = [0];
+let historyIndex = 0;
+// 2. Record state changes via subscription
+store.subscribe('count', (value) => {
+  if (!isTimeTravel) {
+    history.push(value);
+    historyIndex = history.length - 1;
+  }
+});
+// 3. Undo = go back in history
+document.getElementById('undo').onclick = () => {
+  historyIndex--;
+  isTimeTravel = true;
+  store.set('count', history[historyIndex]);
+  isTimeTravel = false;
+};
+```
+## Key Insight
+**Time travel is just replaying state.**
+Because EventState uses **events** for all state changes, you can:
+- ✅ Record every change automatically (wildcard subscription)
+- ✅ Replay any previous state
+- ✅ Build undo/redo in ~30 lines
+Other frameworks need:
+- React: Redux DevTools, Immer, or custom middleware
+- Vue: Vuex plugins or manual history tracking
+- Svelte: Custom stores with history logic
+**EventState:** Just subscribe to `'*'` and push to an array. That's it.
+## This is Telemetry
+This example shows the **foundation of telemetry**:
+- Every state change is an event
+- Events can be logged, replayed, or analyzed
+- Time-travel debugging comes for free
+In the full UIstate framework, this becomes:
+- Automatic telemetry logging
+- Event sequence testing (`eventTest.js`)
+- Production debugging and replay
+## Run It
+Open `index.html` in a browser. Click operations, then use Undo/Redo to travel through time.
+## Try This
+Make multiple changes, undo halfway, then make a new change. Notice how the "future" states are discarded (like Git branches).

package/examples/008-undo-redo/eventState.js ADDED Viewed

@@ -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/008-undo-redo/index.html ADDED Viewed

@@ -0,0 +1,105 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>008 Undo/Redo - EventState</title>
+</head>
+<body>
+  <h1>Counter with Time Travel</h1>
+  <h2>Count: <span id="count">0</span></h2>
+  <button id="increment">+1</button>
+  <button id="decrement">-1</button>
+  <button id="double">×2</button>
+  <hr>
+  <button id="undo" disabled>⟲ Undo</button>
+  <button id="redo" disabled>⟳ Redo</button>
+  <p><small>History: <span id="historyInfo">0 states</span></small></p>
+  <script type="module">
+    import { createEventState } from './eventState.js';
+    // Create store
+    const store = createEventState({ count: 0 });
+    // History tracking
+    let history = [0]; // Start with initial state
+    let historyIndex = 0;
+    let isTimeTravel = false; // Flag to prevent recording during undo/redo
+    // Update UI
+    const updateUI = () => {
+      const count = store.get('count');
+      document.getElementById('count').textContent = count;
+      // Update button states
+      document.getElementById('undo').disabled = historyIndex === 0;
+      document.getElementById('redo').disabled = historyIndex === history.length - 1;
+      // Update history info
+      document.getElementById('historyInfo').textContent =
+        `${historyIndex + 1} of ${history.length} states`;
+    };
+    // Subscribe to count changes and record history
+    store.subscribe('count', (value) => {
+      updateUI();
+      // Only record if not time traveling
+      if (!isTimeTravel) {
+        // Remove any "future" states if we're in the middle of history
+        history = history.slice(0, historyIndex + 1);
+        // Add new state
+        history.push(value);
+        historyIndex = history.length - 1;
+        updateUI();
+      }
+    });
+    // Counter operations
+    document.getElementById('increment').onclick = () => {
+      store.set('count', store.get('count') + 1);
+    };
+    document.getElementById('decrement').onclick = () => {
+      store.set('count', store.get('count') - 1);
+    };
+    document.getElementById('double').onclick = () => {
+      store.set('count', store.get('count') * 2);
+    };
+    // Undo
+    document.getElementById('undo').onclick = () => {
+      if (historyIndex > 0) {
+        historyIndex--;
+        isTimeTravel = true;
+        store.set('count', history[historyIndex]);
+        isTimeTravel = false;
+        updateUI();
+      }
+    };
+    // Redo
+    document.getElementById('redo').onclick = () => {
+      if (historyIndex < history.length - 1) {
+        historyIndex++;
+        isTimeTravel = true;
+        store.set('count', history[historyIndex]);
+        isTimeTravel = false;
+        updateUI();
+      }
+    };
+    // Initial UI update
+    updateUI();
+  </script>
+</body>
+</html>

package/examples/009-localStorage-side-effects/README.md ADDED Viewed

@@ -0,0 +1,72 @@
+# 009 localStorage Side Effects - Persistent State
+Demonstrates how to sync state with localStorage for persistence across page reloads.
+## What's Here
+- Counter that persists across browser sessions
+- Automatic save on every state change
+- Load saved state on page load
+- **No persistence library needed** - just localStorage API
+## How It Works
+```javascript
+// 1. Load initial state from localStorage
+const savedCount = localStorage.getItem('counter');
+const initialCount = savedCount !== null ? parseInt(savedCount, 10) : 0;
+// 2. Create store with saved state
+const store = createEventState({ count: initialCount });
+// 3. Side effect: save on every change
+store.subscribe('count', (value) => {
+  localStorage.setItem('counter', value);
+  // Also update UI
+  document.getElementById('count').textContent = value;
+});
+```
+## Key Insight
+**Side effects are just subscribers.**
+Subscriptions aren't only for UI updates. They're for:
+- ✅ Saving to localStorage
+- ✅ Logging to analytics
+- ✅ Syncing to server
+- ✅ Triggering other actions
+Other frameworks need:
+- React: `useEffect` with dependency arrays
+- Vue: `watch` or `watchEffect`
+- Svelte: Reactive statements with side effects
+**EventState:** Just subscribe and do whatever you want. That's it.
+## Pattern: Separation of Concerns
+Notice the subscriber does TWO things:
+1. Saves to localStorage (side effect)
+2. Updates the DOM (UI effect)
+You could split these into separate subscribers:
+```javascript
+store.subscribe('count', (value) => {
+  localStorage.setItem('counter', value);
+});
+store.subscribe('count', (value) => {
+  document.getElementById('count').textContent = value;
+});
+```
+This is the **single responsibility principle** in action.
+## Run It
+Open `index.html`, increment the counter, then reload the page. Your count persists!
+## Try This
+Open DevTools → Application → Local Storage to see the saved value update in real-time.