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/009-localStorage-side-effects/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/009-localStorage-side-effects/index.html ADDED Viewed

@@ -0,0 +1,54 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>009 localStorage Side Effects - EventState</title>
+</head>
+<body>
+  <h1>Persistent Counter</h1>
+  <h2>Count: <span id="count">0</span></h2>
+  <button id="increment">+1</button>
+  <button id="decrement">-1</button>
+  <button id="reset">Reset</button>
+  <p><small>Reload the page - your count persists!</small></p>
+  <script type="module">
+    import { createEventState } from './eventState.js';
+    const STORAGE_KEY = 'eventstate-counter';
+    // Load initial state from localStorage
+    const savedCount = localStorage.getItem(STORAGE_KEY);
+    const initialCount = savedCount !== null ? parseInt(savedCount, 10) : 0;
+    // Create store with saved state
+    const store = createEventState({ count: initialCount });
+    // Side effect: save to localStorage on every change
+    store.subscribe('count', (value) => {
+      localStorage.setItem(STORAGE_KEY, value);
+      document.getElementById('count').textContent = value;
+    });
+    // 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('reset').onclick = () => {
+      store.set('count', 0);
+    };
+    // Initial render
+    document.getElementById('count').textContent = initialCount;
+  </script>
+</body>
+</html>

package/examples/010-decoupled-components/README.md ADDED Viewed

@@ -0,0 +1,74 @@
+# 010 Decoupled Components - Shared State
+Demonstrates how components can communicate through shared state without direct coupling.
+## What's Here
+- **Component A (Writer):** Sends messages
+- **Component B (Reader):** Displays current message
+- **Component C (Logger):** Logs all messages with timestamps
+- **Zero coupling:** Components don't know about each other
+## How It Works
+```javascript
+// Shared store - the ONLY connection
+const store = createEventState({ message: '' });
+// Component A: Writes to state
+document.getElementById('sendBtn').onclick = () => {
+  store.set('message', inputValue);
+};
+// Component B: Reads from state
+store.subscribe('message', (value) => {
+  document.getElementById('display').textContent = value;
+});
+// Component C: Also reads from state
+store.subscribe('message', (value) => {
+  logMessage(value);
+});
+```
+## Key Insight
+**State is the interface between components.**
+Components communicate by:
+1. Writing to shared state
+2. Subscribing to shared state
+3. **Never** calling each other directly
+This is the **pub/sub pattern** in action:
+- ✅ Components are decoupled
+- ✅ Easy to add/remove components
+- ✅ No prop drilling
+- ✅ No callbacks passed down
+Other frameworks need:
+- React: Context API, prop drilling, or state management libraries
+- Vue: Provide/inject or Vuex
+- Svelte: Context API or stores
+**EventState:** Just share the store. That's it.
+## Architecture Pattern
+This demonstrates the **mediator pattern**:
+- Components don't talk to each other
+- They talk to the store
+- The store mediates all communication
+This is how your full UIstate framework works:
+- Intents → State changes
+- State changes → UI updates
+- Everything is decoupled through events
+## Run It
+Open `index.html`, type messages, and watch all three components react independently.
+## Try This
+Add a fourth component that counts vowels in messages. It only needs to subscribe to `'message'` - no other code changes needed.

package/examples/010-decoupled-components/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/010-decoupled-components/index.html ADDED Viewed

@@ -0,0 +1,90 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>010 Decoupled Components - EventState</title>
+  <style>
+    .component {
+      border: 2px solid #333;
+      padding: 20px;
+      margin: 10px 0;
+    }
+  </style>
+</head>
+<body>
+  <h1>Decoupled Components</h1>
+  <p>Two independent "components" sharing state without knowing about each other.</p>
+  <!-- Component A: Writer -->
+  <div class="component">
+    <h2>Component A: Writer</h2>
+    <input type="text" id="messageInput" placeholder="Type a message...">
+    <button id="sendBtn">Send</button>
+  </div>
+  <!-- Component B: Reader -->
+  <div class="component">
+    <h2>Component B: Reader</h2>
+    <p><strong>Received:</strong> <span id="messageDisplay">(nothing yet)</span></p>
+    <p><small>Message count: <span id="messageCount">0</span></small></p>
+  </div>
+  <!-- Component C: Logger -->
+  <div class="component">
+    <h2>Component C: Logger</h2>
+    <ul id="messageLog"></ul>
+  </div>
+  <script type="module">
+    import { createEventState } from './eventState.js';
+    // Shared store - the ONLY connection between components
+    const store = createEventState({
+      message: '',
+      messageCount: 0
+    });
+    // ===== COMPONENT A: Writer =====
+    // Knows nothing about B or C, just writes to state
+    document.getElementById('sendBtn').onclick = () => {
+      const input = document.getElementById('messageInput');
+      const value = input.value.trim();
+      if (value) {
+        store.set('message', value);
+        store.set('messageCount', store.get('messageCount') + 1);
+        input.value = '';
+      }
+    };
+    document.getElementById('messageInput').onkeypress = (e) => {
+      if (e.key === 'Enter') {
+        document.getElementById('sendBtn').click();
+      }
+    };
+    // ===== COMPONENT B: Reader =====
+    // Knows nothing about A or C, just reads from state
+    store.subscribe('message', (value) => {
+      document.getElementById('messageDisplay').textContent = value || '(nothing yet)';
+    });
+    store.subscribe('messageCount', (value) => {
+      document.getElementById('messageCount').textContent = value;
+    });
+    // ===== COMPONENT C: Logger =====
+    // Knows nothing about A or B, just logs all messages
+    store.subscribe('message', (value) => {
+      if (value) {
+        const log = document.getElementById('messageLog');
+        const timestamp = new Date().toLocaleTimeString();
+        const li = document.createElement('li');
+        li.textContent = `[${timestamp}] ${value}`;
+        log.appendChild(li);
+      }
+    });
+  </script>
+</body>
+</html>

package/examples/011-async-patterns/README.md ADDED Viewed

@@ -0,0 +1,98 @@
+# 011 Async Patterns - Debouncing & Loading States
+Demonstrates how to handle async operations with EventState.
+## What's Here
+- **Debounced search:** Wait for user to stop typing before searching
+- **Loading states:** Show loading indicator during async operations
+- **Error handling:** Graceful failure with try/catch
+- **No async library needed** - just Promises and state
+## How It Works
+### Debounced Search
+```javascript
+let searchTimeout = null;
+store.subscribe('searchQuery', async (value) => {
+  clearTimeout(searchTimeout);
+  store.set('isSearching', true);
+  // Wait 300ms before searching
+  searchTimeout = setTimeout(async () => {
+    const result = await performSearch(value);
+    store.set('searchResult', result);
+    store.set('isSearching', false);
+  }, 300);
+});
+```
+### Loading States
+```javascript
+document.getElementById('fetchBtn').onclick = async () => {
+  store.set('isLoading', true);
+  try {
+    const data = await fetchData();
+    store.set('apiData', data);
+  } finally {
+    store.set('isLoading', false);
+  }
+};
+```
+## Key Insight
+**Async is just state changes over time.**
+Pattern for any async operation:
+1. Set loading state to `true`
+2. Perform async operation
+3. Set result state
+4. Set loading state to `false`
+Other frameworks need:
+- React: `useState` + `useEffect` + cleanup functions
+- Vue: `ref` + `watch` + async watchers
+- Svelte: Reactive statements + `#await` blocks
+**EventState:** Just use async/await in subscribers. That's it.
+## Patterns Demonstrated
+### 1. Debouncing
+Wait for user to stop typing before triggering expensive operations.
+### 2. Loading Indicators
+Show feedback during async operations to improve UX.
+### 3. Disabling Actions
+Prevent duplicate requests by disabling buttons during loading.
+### 4. Cleanup
+Clear timeouts to prevent race conditions.
+## Run It
+Open `index.html`:
+- Type in the search box (notice the 300ms delay)
+- Click "Fetch Data" (notice the loading state)
+## Try This
+Open DevTools Network tab and throttle to "Slow 3G" to see loading states more clearly.
+## Real-World Usage
+This pattern works for:
+- ✅ API calls
+- ✅ Autocomplete
+- ✅ Form submission
+- ✅ File uploads
+- ✅ Any async operation
+Just manage loading/error/success states in the store.

package/examples/011-async-patterns/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 };