@uistate/core 4.1.2 → 5.0.0

package/examples/032-todo-app-with-eventTest/runtime/core/router.js

@@ -0,0 +1,271 @@
+// runtime/core/router.js — Generic SPA router factory for eventState stores
+// Usage:
+//   const router = createRouter({
+//     routes: [{ path: '/', view: 'home', component: HomeView }],
+//     store,
+//     rootSelector: '[data-route-root]',
+//     debug: true
+//   });
+//   router.start();
+
+export function createRouter(config) {
+  const {
+    routes = [],
+    store,
+    rootSelector = '[data-route-root]',
+    fallback = null,
+    debug = false,
+    linkSelector = 'a[data-link]',
+    navSelector = 'nav a[data-link]',
+  } = config;
+
+  // Detect base path from <base href> if present
+  const BASE_PATH = (() => {
+    const b = document.querySelector('base[href]');
+    if (!b) return '';
+    try {
+      const u = new URL(b.getAttribute('href'), location.href);
+      let p = u.pathname;
+      if (p.length > 1 && p.endsWith('/')) p = p.slice(0, -1);
+      return p;
+    } catch { return ''; }
+  })();
+
+  function stripBase(pathname) {
+    if (BASE_PATH && pathname.startsWith(BASE_PATH)) {
+      const rest = pathname.slice(BASE_PATH.length) || '/';
+      return rest.startsWith('/') ? rest : ('/' + rest);
+    }
+    return pathname;
+  }
+
+  function withBase(pathname) {
+    if (!BASE_PATH) return pathname;
+    if (pathname === '/') return BASE_PATH || '/';
+    return (BASE_PATH + (pathname.startsWith('/') ? '' : '/') + pathname);
+  }
+
+  function normalizePath(p) {
+    if (!p) return '/';
+    try {
+      if (p[0] !== '/') p = '/' + p;
+      if (p === '/index.html') return '/';
+      if (p.length > 1 && p.endsWith('/')) p = p.slice(0, -1);
+      return p;
+    } catch { return '/'; }
+  }
+
+  function resolve(pathname) {
+    const p = normalizePath(pathname);
+    const r = routes.find(r => r.path === p);
+    if (r) return { ...r, params: {} };
+    if (fallback) return { ...fallback, params: {} };
+    return null;
+  }
+
+  function getRoot() {
+    const el = document.querySelector(rootSelector);
+    if (!el) throw new Error('Route root not found: ' + rootSelector);
+    return el;
+  }
+
+  function setActiveNav(pathname) {
+    document.querySelectorAll(navSelector).forEach(a => {
+      const url = new URL(a.getAttribute('href'), location.href);
+      const linkPath = normalizePath(stripBase(url.pathname));
+      const here = normalizePath(pathname);
+      const isExact = linkPath === here;
+      const isParent = !isExact && linkPath !== '/' && here.startsWith(linkPath);
+      const active = isExact || isParent;
+      a.classList.toggle('active', active);
+      if (isExact) a.setAttribute('aria-current', 'page');
+      else a.removeAttribute('aria-current');
+    });
+  }
+
+  // State
+  let current = { viewKey: null, unboot: null, path: null, search: '' };
+  let navController = null;
+  const scrollPositions = new Map();
+  history.scrollRestoration = 'manual';
+
+  // Core navigate function
+  async function navigate(pathname, { replace = false, search = '', restoreScroll = false } = {}) {
+    const root = getRoot();
+    const appPath = normalizePath(stripBase(pathname));
+    const resolved = resolve(appPath);
+    
+    if (!resolved) {
+      if (debug) console.warn('[router] No route found for:', appPath);
+      return;
+    }
+
+    const viewKey = resolved.view;
+    const component = resolved.component;
+    const html = document.documentElement;
+    const prevViewKey = current.viewKey;
+
+    const searchStr = search && search.startsWith('?') ? search : (search ? ('?' + search) : '');
+
+    // Always log navigation for telemetry
+    console.log('[nav] navigate', { from: current.path, to: appPath, view: viewKey });
+    
+    if (debug) {
+      console.debug('[router] navigate', { pathname, appPath, searchStr, view: viewKey, params: resolved.params });
+    }
+
+    // Same-route no-op guard
+    if (current.path === appPath && current.search === searchStr) {
+      return;
+    }
+
+    // Abort in-flight boot
+    if (navController) navController.abort();
+    navController = new AbortController();
+    const { signal } = navController;
+
+    // Transition start
+    if (store) {
+      try { store.set('ui.route.transitioning', true); } catch {}
+    }
+    html.setAttribute('data-transitioning', 'on');
+
+    // Save scroll position
+    if (current.path) {
+      scrollPositions.set(current.path, { x: scrollX, y: scrollY });
+    }
+
+    // Unboot previous view
+    if (typeof current.unboot === 'function') {
+      try { await current.unboot(); } catch (_e) {}
+    }
+
+    // Clear DOM
+    root.replaceChildren();
+
+    // Boot new view
+    const unboot = await (component.boot?.({ store, el: root, signal }) || Promise.resolve(() => {}));
+    current = { viewKey, unboot, path: appPath, search: searchStr };
+
+    // Update nav active state
+    setActiveNav(appPath);
+
+    // Parse query params
+    const urlForQuery = new URL(location.origin + withBase(appPath) + searchStr);
+    const q = {};
+    urlForQuery.searchParams.forEach((v, k) => { q[k] = v; });
+
+    // Update store
+    if (store) {
+      try {
+        if (store.setMany) {
+          store.setMany({
+            'ui.route.view': viewKey,
+            'ui.route.path': appPath,
+            'ui.route.params': resolved.params || {},
+            'ui.route.query': q,
+          });
+        } else {
+          store.set('ui.route.view', viewKey);
+          store.set('ui.route.path', appPath);
+          store.set('ui.route.params', resolved.params || {});
+          store.set('ui.route.query', q);
+        }
+      } catch {}
+    }
+
+    // Update browser history
+    const useReplace = replace || (prevViewKey === viewKey);
+    if (useReplace) history.replaceState({}, '', withBase(appPath) + searchStr);
+    else history.pushState({}, '', withBase(appPath) + searchStr);
+
+    // Set view attribute
+    html.setAttribute('data-view', viewKey);
+
+    if (debug) {
+      console.debug('[router] view', { viewKey, path: appPath, query: q });
+    }
+
+    // Transition end
+    if (store) {
+      try { store.set('ui.route.transitioning', false); } catch {}
+    }
+    html.setAttribute('data-transitioning', 'off');
+
+    // Focus management
+    if (!root.hasAttribute('tabindex')) root.setAttribute('tabindex', '-1');
+    try { root.focus({ preventScroll: true }); } catch {}
+
+    // Scroll restoration
+    if (restoreScroll) {
+      const pos = scrollPositions.get(appPath);
+      if (pos) scrollTo(pos.x, pos.y);
+    } else {
+      scrollTo(0, 0);
+    }
+  }
+
+  function navigateQuery(patch = {}, { replace = true } = {}) {
+    const params = new URLSearchParams(current.search || '');
+    for (const [k, v] of Object.entries(patch)) {
+      if (v === null || v === undefined || v === '') params.delete(k);
+      else params.set(k, String(v));
+    }
+    const searchStr = params.toString();
+    const prefixed = searchStr ? ('?' + searchStr) : '';
+    const path = current.path || normalizePath(stripBase(location.pathname));
+    return navigate(path, { search: prefixed, replace });
+  }
+
+  function navigatePath(path, { replace = true } = {}) {
+    const appPath = normalizePath(stripBase(path));
+    const searchStr = current.search || '';
+    return navigate(appPath, { search: searchStr, replace });
+  }
+
+  function onClick(e) {
+    const a = e.target.closest(linkSelector);
+    if (!a) return;
+    if (e.defaultPrevented) return;
+    if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || e.button !== 0) return;
+    const url = new URL(a.getAttribute('href'), location.href);
+    if (url.origin !== location.origin) return;
+    e.preventDefault();
+    
+    // Log navigation click
+    console.log('[nav] click', { href: a.getAttribute('href'), text: a.textContent.trim() });
+    
+    navigate(url.pathname, { search: url.search }).catch(() => {});
+  }
+
+  function onPop() {
+    navigate(location.pathname, { replace: true, search: location.search, restoreScroll: true }).catch(() => {});
+  }
+
+  // Public API
+  return {
+    navigate,
+    navigateQuery,
+    navigatePath,
+    
+    start() {
+      window.addEventListener('click', onClick);
+      window.addEventListener('popstate', onPop);
+      navigate(location.pathname, { replace: true, search: location.search, restoreScroll: true });
+      return this;
+    },
+
+    stop() {
+      window.removeEventListener('click', onClick);
+      window.removeEventListener('popstate', onPop);
+      if (typeof current.unboot === 'function') {
+        try { current.unboot(); } catch {}
+      }
+      return this;
+    },
+
+    getCurrent() {
+      return { ...current };
+    }
+  };
+}

package/examples/032-todo-app-with-eventTest/runtime/extensions/boundary.js

@@ -0,0 +1,36 @@
+// boundary.js — Minimal boundary helper for UIstate
+// Design goals:
+// - Never throw; always resolve to a value (or undefined) so callers can remain declarative
+// - Toggle loading flags via provided setLoading(boolean)
+// - Report errors via onError(error)
+// - Optional mapError(error) to convert errors into return values
+// - Optional finally() callback invoked regardless of outcome
+
+/**
+ * @template T
+ * @param {() => Promise<T>} fn async function to execute within the boundary
+ * @param {{
+ *   setLoading?: (v:boolean)=>void,
+ *   onError?: (error:any)=>void,
+ *   mapError?: (error:any)=>any,
+ *   finally?: ()=>void,
+ * }} opts
+ * @returns {Promise<T|any|undefined>}
+ */
+export async function runWithBoundary(fn, opts = {}){
+  const { setLoading, onError, mapError, finally: onFinally } = opts;
+  try {
+    if (setLoading) try { setLoading(true); } catch {}
+    const out = await fn();
+    return out;
+  } catch (err) {
+    try { onError && onError(err); } catch {}
+    if (typeof mapError === 'function') {
+      try { return mapError(err); } catch { return undefined; }
+    }
+    return undefined;
+  } finally {
+    if (setLoading) try { setLoading(false); } catch {}
+    if (onFinally) try { onFinally(); } catch {}
+  }
+}

package/examples/032-todo-app-with-eventTest/runtime/extensions/converge.js

@@ -0,0 +1,63 @@
+// converge.js — last-write-wins (or last-local-wins) convergence helpers
+// Expects a store with get/set APIs.
+
+function pathKey(path) {
+  return String(path || '');
+}
+
+/**
+ * Apply an inbound change if its clock is newer than the local clock.
+ * @param {any} store
+ * @param {{ path: string, value: any, clock: number }} change
+ * @param {{ clocksPath?: string, arrayStrategy?: 'replace'|'keyedMerge', keyField?: string }} opts
+ */
+export function applyConverge(store, change, opts = {}) {
+  const { path, value, clock } = change || {};
+  if (!path) return false;
+  const { clocksPath = 'clocks', arrayStrategy = 'replace', keyField = 'id' } = opts;
+
+  const ck = pathKey(path);
+  const localClock = store.get(`${clocksPath}.${ck}`) || 0;
+  if (!(clock > localClock)) return false; // reject stale or equal
+
+  // Apply the value with optional array strategy
+  if (Array.isArray(value)) {
+    if (arrayStrategy === 'replace') {
+      store.set(path, value);
+    } else {
+      const local = store.get(path) || [];
+      const result = [...local];
+      for (const inc of value) {
+        const k = inc && typeof inc === 'object' ? inc[keyField] : undefined;
+        if (k == null) { result.push(inc); continue; }
+        const sk = String(k);
+        const idx = result.findIndex((x) => x && x[keyField] != null && String(x[keyField]) === sk);
+        if (idx >= 0) {
+          const old = result[idx];
+          result[idx] = (old && typeof old === 'object' && inc && typeof inc === 'object')
+            ? { ...old, ...inc }
+            : inc;
+        } else {
+          result.push(inc);
+        }
+      }
+      store.set(path, result);
+    }
+  } else {
+    store.set(path, value);
+  }
+
+  // Update clock
+  store.set(`${clocksPath}.${ck}`, clock);
+  return true;
+}
+
+/**
+ * Build an outbound change with clock and origin-id (for crossTabSync).
+ */
+export function publishChange(store, path, value, { clocksPath = 'clocks', now = () => Date.now(), origin } = {}) {
+  const clock = Number(now());
+  store.set(path, value);
+  store.set(`${clocksPath}.${pathKey(path)}`, clock);
+  return { path, value, clock, origin };
+}

package/examples/032-todo-app-with-eventTest/runtime/extensions/eventState.plus.js

@@ -0,0 +1,210 @@
+// eventState.plus.js — Open/Closed extension over eventState.js without modifying core
+// Provides: safety guards, stricter validation, unsubscribe helper, and a light batch API
+// NOTE: This module composes the existing './eventState.js' implementation and returns
+// an enhanced facade. The original fine-grained semantics (per-path events) remain intact.
+
+import createEventStateBase from '../core/eventState.js';
+
+/**
+ * Create an enhanced EventState store while preserving the original semantics.
+ * - Safety: destroyed-guard to prevent use-after-destroy
+ * - Validation: strict argument checks for subscribe/off
+ * - Ergonomics: off(unsub) helper
+ * - Batch: coalesce multiple set() calls by path within a batch() section
+ *
+ * Important: batching here deduplicates per-path updates within the batch,
+ * but still dispatches one notification per unique path at flush time.
+ * This preserves fine-grained observability while reducing churn.
+ */
+export function createEventStatePlus(initial = {}, options = {}){
+  const base = createEventStateBase(initial);
+  let destroyed = false;
+
+  // Track subscriptions we create (optional, for destroy hygiene)
+  const _subscriptions = new Set();
+
+  function assertNotDestroyed(){
+    if (destroyed) throw new Error('EventState store has been destroyed');
+  }
+
+  // Batching support: collect last value per path and flush at end
+  let batching = false;
+  let buffer = new Map(); // path -> value (last write wins)
+
+  function flushBuffer(){
+    if (buffer.size === 0) return;
+    const entries = Array.from(buffer.entries());
+    buffer.clear();
+    for (const [path, value] of entries){
+      base.set(path, value);
+    }
+  }
+
+  function batch(fn){
+    assertNotDestroyed();
+    const wasBatching = batching;
+    batching = true;
+    try {
+      fn();
+    } finally {
+      batching = wasBatching; // support nested batches: only flush on outermost
+      if (!batching) flushBuffer();
+    }
+  }
+
+  // Facade methods
+  function get(path){
+    return base.get(path);
+  }
+
+  function set(path, value){
+    assertNotDestroyed();
+    if (!path) return value;
+    if (batching){
+      buffer.set(path, value);
+      return value;
+    }
+    return base.set(path, value);
+  }
+
+  function subscribe(path, handler){
+    assertNotDestroyed();
+    if (typeof path !== 'string' || typeof handler !== 'function'){
+      throw new TypeError('subscribe(path, handler) requires a string path and function handler');
+    }
+    // eventState.js invokes callback(detail, path). We adapt the signature to (detail, meta)
+    // where meta mimics an event-like shape with type=path for ergonomics.
+    const wrapped = (detail /* from base */, subscribedPath /* string */) => {
+      handler(detail, { type: subscribedPath, detail });
+    };
+    const unsubscribe = base.subscribe(path, wrapped);
+    _subscriptions.add(unsubscribe);
+    return function off(){
+      _subscriptions.delete(unsubscribe);
+      return unsubscribe();
+    };
+  }
+
+  function off(unsubscribe){
+    if (typeof unsubscribe !== 'function'){
+      throw new TypeError('off(unsubscribe) requires a function returned by subscribe');
+    }
+    return unsubscribe();
+  }
+
+  function setMany(entries){
+    assertNotDestroyed();
+    if (!entries) return;
+    // Accept Array<[path,value]>, Map, or plain object
+    batch(() => {
+      if (Array.isArray(entries)){
+        for (const [p, v] of entries) set(p, v);
+      } else if (entries instanceof Map){
+        for (const [p, v] of entries.entries()) set(p, v);
+      } else if (typeof entries === 'object'){
+        for (const p of Object.keys(entries)) set(p, entries[p]);
+      }
+    });
+  }
+
+  function destroy(){
+    if (destroyed) return;
+    // Best-effort unsubscribe of known subs created via this facade
+    for (const unsub of Array.from(_subscriptions)){
+      try { unsub(); } catch {}
+      _subscriptions.delete(unsub);
+    }
+    // Forward to base.destroy if present
+    if (typeof base.destroy === 'function'){
+      try { base.destroy(); } catch {}
+    }
+    destroyed = true;
+    // Drop buffered writes (safer than flushing after destroy)
+    buffer.clear();
+  }
+
+  return {
+    // Core parity
+    get,
+    set,
+    subscribe,
+    // Added ergonomics
+    off,
+    destroy,
+    // Batching utilities
+    batch,
+    setMany,
+    // Introspection
+    get destroyed(){ return destroyed; },
+  };
+}
+
+/**
+ * Upgrade an existing base store into a Plus facade, without duplicating state.
+ * Accepts any object implementing { get, set, subscribe, destroy? }.
+ */
+export function upgradeEventState(base){
+  // Wrap an existing store with the same facade used above. This avoids creating a new base.
+  // Reuse the createEventStatePlus mechanics but without constructing a new base store.
+  // Implementation mirrors createEventStatePlus, substituting `base` for the newly created one.
+
+  let destroyed = false;
+  const _subscriptions = new Set();
+  const assertNotDestroyed = () => { if (destroyed) throw new Error('EventState store has been destroyed'); };
+
+  let batching = false;
+  let buffer = new Map();
+  const flushBuffer = () => {
+    if (buffer.size === 0) return;
+    const entries = Array.from(buffer.entries());
+    buffer.clear();
+    for (const [path, value] of entries){ base.set(path, value); }
+  };
+  const batch = (fn) => {
+    assertNotDestroyed();
+    const wasBatching = batching;
+    batching = true;
+    try { fn(); } finally { batching = wasBatching; if (!batching) flushBuffer(); }
+  };
+
+  const get = (path) => base.get(path);
+  const set = (path, value) => { assertNotDestroyed(); if (!path) return value; if (batching){ buffer.set(path, value); return value; } return base.set(path, value); };
+  const subscribe = (path, handler) => {
+    assertNotDestroyed();
+    if (typeof path !== 'string' || typeof handler !== 'function') throw new TypeError('subscribe(path, handler) requires a string path and function handler');
+    const wrapped = (detail, subscribedPath) => { handler(detail, { type: subscribedPath, detail }); };
+    const unsubscribe = base.subscribe(path, wrapped);
+    _subscriptions.add(unsubscribe);
+    return function off(){ _subscriptions.delete(unsubscribe); return unsubscribe(); };
+  };
+  const off = (unsubscribe) => {
+    if (typeof unsubscribe !== 'function') throw new TypeError('off(unsubscribe) requires a function returned by subscribe');
+    return unsubscribe();
+  };
+  const setMany = (entries) => {
+    assertNotDestroyed();
+    if (!entries) return;
+    batch(() => {
+      if (Array.isArray(entries)) for (const [p,v] of entries) set(p,v);
+      else if (entries instanceof Map) for (const [p,v] of entries.entries()) set(p,v);
+      else if (typeof entries === 'object') for (const p of Object.keys(entries)) set(p, entries[p]);
+    });
+  };
+  const destroy = () => {
+    if (destroyed) return;
+    for (const unsub of Array.from(_subscriptions)){
+      try { unsub(); } catch {}
+      _subscriptions.delete(unsub);
+    }
+    if (typeof base.destroy === 'function') { try { base.destroy(); } catch {} }
+    destroyed = true;
+    buffer.clear();
+  };
+
+  return {
+    get, set, subscribe, off, destroy, batch, setMany,
+    get destroyed(){ return destroyed; },
+  };
+}
+
+export default createEventStatePlus;