@uistate/core 4.1.2 → 5.0.0

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

@@ -0,0 +1,157 @@
+// SPDX-License-Identifier: Apache-2.0
+// hydrate.js — general JSON→store utilities
+// Minimal, framework-agnostic helpers that operate on a simple store interface:
+//   - store.get(path: string): any
+//   - store.set(path: string, value: any): void
+// Options are defensive and production-oriented but remain tiny.
+
+/**
+ * @typedef {Object} Store
+ * @property {(path:string)=>any} get
+ * @property {(path:string, value:any)=>void} set
+ * @property {(path:string, fn:(v:any)=>void)=>(()=>void)=} subscribe
+ */
+
+/**
+ * Execute a function intended to perform multiple set() calls.
+ * Note: Without native store batching, this is a semantic wrapper.
+ * Consumers may swap this with a true batch if available.
+ *
+ * @template T
+ * @param {Store} store
+ * @param {() => T} fn
+ * @returns {T}
+ */
+export function withBatch(store, fn) {
+  return fn();
+}
+
+function inWhitelist(path, whitelistPaths) {
+  if (!whitelistPaths || whitelistPaths.length === 0) return true;
+  return whitelistPaths.some((p) => path === p || path.startsWith(p + '.'));
+}
+
+/**
+ * Replace top-level subtrees.
+ *
+ * @param {Store} store
+ * @param {Record<string, any>} payload - e.g. { demo: {...}, ui: {...} }
+ * @param {Object} [opts]
+ * @param {string[]} [opts.whitelistPaths] - Allowed path prefixes (e.g., ['form'])
+ * @param {boolean} [opts.batch] - If true, wraps changes in {@link withBatch}
+ * @returns {void}
+ */
+export function hydrateReplace(store, payload, opts = {}) {
+  const { whitelistPaths, batch } = opts;
+  const apply = () => {
+    for (const [k, v] of Object.entries(payload || {})) {
+      if (!inWhitelist(k, whitelistPaths)) continue;
+      store.set(k, v);
+    }
+  };
+  return batch ? withBatch(store, apply) : apply();
+}
+
+/**
+ * Deep merge a payload into the store, starting from a root path.
+ *
+ * Arrays: `replace` (default) or `keyedMerge` by a `keyField` (default: `id`).
+ * Conflicts: optional `onConflict(path, prev, next)` on leaf writes.
+ * Version: optional guard to avoid stale apply via `version` + `getVersion()`.
+ *
+ * @param {Store} store
+ * @param {string} root - Path prefix to merge under (e.g., 'demo')
+ * @param {any} payload - Arbitrary JSON-compatible structure
+ * @param {Object} [opts]
+ * @param {(path:string, prev:any, next:any)=>any} [opts.onConflict]
+ * @param {('replace'|'keyedMerge')} [opts.arrayStrategy]
+ * @param {string} [opts.keyField]
+ * @param {string[]} [opts.whitelistPaths]
+ * @param {number} [opts.version]
+ * @param {()=>number} [opts.getVersion]
+ * @param {boolean} [opts.batch]
+ * @returns {void}
+ */
+export function hydrateMerge(store, root, payload, opts = {}) {
+  const {
+    onConflict,
+    arrayStrategy = 'replace',
+    keyField = 'id',
+    whitelistPaths,
+    version,
+    getVersion,
+    batch,
+  } = opts;
+
+  if (version != null && typeof getVersion === 'function') {
+    const current = getVersion();
+    if (current != null && version <= current) {
+      // Incoming is stale or equal; skip.
+      return;
+    }
+  }
+
+  const setLeaf = (path, nextVal) => {
+    if (!inWhitelist(path, whitelistPaths)) return;
+    const prev = store.get(path);
+    if (onConflict && typeof nextVal !== 'object') {
+      if (typeof prev !== 'undefined') {
+        const resolved = onConflict(path, prev, nextVal);
+        store.set(path, resolved);
+        return;
+      }
+    }
+    store.set(path, nextVal);
+  };
+
+  const mergeArray = (path, incomingArr) => {
+    if (arrayStrategy === 'replace') {
+      setLeaf(path, incomingArr);
+      return;
+    }
+    // keyedMerge
+    const local = store.get(path) || [];
+    const byKey = new Map();
+    for (const item of local) {
+      const k = item && typeof item === 'object' ? item[keyField] : undefined;
+      if (k != null) byKey.set(String(k), item);
+    }
+    const result = [...local];
+    for (const inc of incomingArr) {
+      const k = inc && typeof inc === 'object' ? inc[keyField] : undefined;
+      if (k == null) { result.push(inc); continue; }
+      const sk = String(k);
+      const existingIdx = result.findIndex((x) => x && x[keyField] != null && String(x[keyField]) === sk);
+      if (existingIdx >= 0) {
+        const old = result[existingIdx];
+        // shallow merge; objects only
+        if (old && typeof old === 'object' && inc && typeof inc === 'object') {
+          result[existingIdx] = { ...old, ...inc };
+        } else {
+          result[existingIdx] = inc;
+        }
+      } else {
+        result.push(inc);
+      }
+    }
+    setLeaf(path, result);
+  };
+
+  const recurse = (prefix, value) => {
+    if (Array.isArray(value)) {
+      mergeArray(prefix, value);
+      return;
+    }
+    if (value && typeof value === 'object') {
+      for (const [k, v] of Object.entries(value)) {
+        const path = prefix ? `${prefix}.${k}` : k;
+        recurse(path, v);
+      }
+    } else {
+      setLeaf(prefix, value);
+    }
+  };
+
+  const apply = () => recurse(root || '', payload);
+  return batch ? withBatch(store, apply) : apply();
+}

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

@@ -0,0 +1,69 @@
+// queryBinding.js — bind a URL query param to a store path (two-way, minimal loops)
+// Usage:
+//   import { bindQueryParam } from './queryBinding.js';
+//   const unbind = bindQueryParam(store, { param: 'tab', path: 'ui.nav.tab', coerce: (v)=>v });
+// Notes:
+// - Reads current ui.route.query on navigation and applies to `path`.
+// - When the store path changes, updates the URL query via history.replaceState.
+// - Avoids re-entrancy loops with a tiny guard.
+
+export function bindQueryParam(store, { param, path, coerce, defaultValue, omitDefault, mode = 'replace' } = {}){
+  if (!param || !path) throw new Error('bindQueryParam: `param` and `path` are required');
+  let internalUpdate = false;
+  let lastValue; // track last store value to drive smart push/replace
+
+  // Apply query -> store on any route query change
+  const applyFromQuery = () => {
+    const q = store.get('ui.route.query') || {};
+    const raw = q[param];
+    let val = typeof coerce === 'function' ? coerce(raw) : raw;
+    if (typeof raw === 'undefined' && typeof defaultValue !== 'undefined') {
+      val = defaultValue;
+    }
+    internalUpdate = true;
+    try { if (typeof val !== 'undefined') store.set(path, val); }
+    finally { internalUpdate = false; }
+    lastValue = store.get(path);
+  };
+
+  // Apply store -> URL on path change
+  const applyToUrl = () => {
+    if (internalUpdate) return;
+    const current = store.get(path);
+    // Build next query object from ui.route.query, then set/clear our param
+    const q = Object.assign({}, store.get('ui.route.query') || {});
+    const isDefault = omitDefault && typeof defaultValue !== 'undefined' && current === defaultValue;
+    if (typeof current === 'undefined' || current === null || current === '' || isDefault) delete q[param];
+    else q[param] = String(current);
+    // Write new query into URL (replaceState), and reflect into store.ui.route.query
+    const p = store.get('ui.route.path') || location.pathname;
+    const sp = new URLSearchParams(q);
+    const next = p + (sp.toString() ? ('?' + sp.toString()) : '') + location.hash;
+    // Decide push vs replace per mode
+    let doPush = false;
+    if (mode === 'push') doPush = true;
+    else if (mode === 'replace') doPush = false;
+    else if (mode === 'smart') {
+      const prev = lastValue;
+      if (isDefault) doPush = false; // returning to default cleans URL
+      else if (typeof prev === 'undefined') doPush = true; // first set
+      else if (prev !== current) doPush = true; // switching between non-defaults
+      else doPush = false;
+    }
+    if (doPush) history.pushState({}, '', next); else history.replaceState({}, '', next);
+    // Reflect new query map into store without recursion back to `path`
+    internalUpdate = true;
+    try { store.set('ui.route.query', Object.fromEntries(sp.entries())); }
+    finally { internalUpdate = false; }
+    lastValue = current;
+  };
+
+  // Subscriptions
+  const unsubA = store.subscribe('ui.route.query', applyFromQuery);
+  const unsubB = store.subscribe(path, applyToUrl);
+
+  // Initial sync from query
+  applyFromQuery();
+
+  return () => { unsubA(); unsubB(); };
+}

package/examples/032-todo-app-with-eventTest/runtime/forms/computed.js

@@ -0,0 +1,78 @@
+// forms/computed.js — explicit-deps computed helper for eventState-like stores
+// Requirements for store: get(path), set(path, value), subscribe(path, handler)
+// Features: explicit deps, loop-avoidance, optional debounce, optional memo by dep tuple, optional gatePath, immediate compute
+
+import { withBatch } from '../extensions/hydrate.js';
+
+function tupleKey(vals) {
+  // Simple, deterministic key for small tuples
+  try { return JSON.stringify(vals); } catch { return String(vals); }
+}
+
+/**
+ * Register a computed field derived from explicit dependencies.
+ * @param {any} store
+ * @param {string} targetPath
+ * @param {string[]} deps
+ * @param {(get:(p:string)=>any)=>any} fn
+ * @param {{ debounce?: number, memo?: boolean, immediate?: boolean, gatePath?: string }} options
+ * @returns {() => void} unsubscribe function
+ */
+export function computed(store, targetPath, deps, fn, options = {}) {
+  const { debounce = 0, memo = false, immediate = true, gatePath } = options;
+  let timer = null;
+  let lastKey = undefined;
+  let destroyed = false;
+
+  const get = (p) => store.get(p);
+
+  const doCompute = () => {
+    if (destroyed) return;
+    if (gatePath) {
+      const gateVal = store.get(gatePath);
+      if (!gateVal) return; // gate closed
+    }
+    const depVals = deps.map((d) => store.get(d));
+    if (memo) {
+      const k = tupleKey(depVals);
+      if (k === lastKey) return;
+      lastKey = k;
+    }
+    const nextVal = fn(get);
+    // Loop avoidance: only write if value actually changed (best-effort)
+    const prev = store.get(targetPath);
+    if (prev !== nextVal) {
+      withBatch(store, () => {
+        store.set(targetPath, nextVal);
+      });
+    }
+  };
+
+  const schedule = () => {
+    if (debounce > 0) {
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(doCompute, debounce);
+    } else {
+      doCompute();
+    }
+  };
+
+  const unsubs = deps.map((d) => store.subscribe(d, () => schedule()));
+  // Ignore self-updates if someone else sets targetPath explicitly
+  const unsubSelf = store.subscribe(targetPath, () => {
+    // no-op; presence prevents some stores from GC-ing path observers
+  });
+  // If a gate is used, subscribe to it so opening/closing the gate retriggers compute
+  if (gatePath) {
+    unsubs.push(store.subscribe(gatePath, () => schedule()));
+  }
+
+  if (immediate) schedule();
+
+  return () => {
+    destroyed = true;
+    if (timer) { try { clearTimeout(timer); } catch {} }
+    for (const u of unsubs) { try { u && u(); } catch {} }
+    try { unsubSelf && unsubSelf(); } catch {}
+  };
+}

package/examples/032-todo-app-with-eventTest/runtime/forms/meta.js

@@ -0,0 +1,51 @@
+// forms/meta.js — touched/dirty helpers and simple a11y reflection
+// Generic, path-agnostic helpers. Caller passes concrete value/meta paths.
+
+/**
+ * Initialize field meta with an initial value.
+ * @param {any} store
+ * @param {{ valuePath: string, metaPath: string, initialValue?: any }} opts
+ */
+export function initFieldMeta(store, { valuePath, metaPath, initialValue }) {
+  const init = (typeof initialValue !== 'undefined') ? initialValue : store.get(valuePath);
+  store.set(`${metaPath}.initial`, init);
+  store.set(`${metaPath}.touched`, false);
+  store.set(`${metaPath}.dirty`, false);
+  store.set(`${metaPath}.invalid`, false);
+}
+
+/** Mark as touched (e.g., on blur) */
+export function markTouched(store, metaPath) {
+  store.set(`${metaPath}.touched`, true);
+}
+
+/** Update dirty flag by comparing current value to initial */
+export function updateDirty(store, { valuePath, metaPath }) {
+  const current = store.get(valuePath);
+  const initial = store.get(`${metaPath}.initial`);
+  store.set(`${metaPath}.dirty`, current !== initial);
+}
+
+/** Reset meta flags (preserves initial) */
+export function resetFieldMeta(store, metaPath) {
+  store.set(`${metaPath}.touched`, false);
+  store.set(`${metaPath}.dirty`, false);
+  store.set(`${metaPath}.invalid`, false);
+}
+
+/** Reset value to initial and clear flags */
+export function resetToInitial(store, { valuePath, metaPath }) {
+  const initial = store.get(`${metaPath}.initial`);
+  store.set(valuePath, initial);
+  resetFieldMeta(store, metaPath);
+}
+
+/**
+ * Reflect invalid based on errorsByField[fieldKey].length
+ * @param {any} store
+ * @param {{ metaPath: string, errorsByField: Record<string, string[]>, fieldKey: string }} opts
+ */
+export function reflectInvalid(store, { metaPath, errorsByField, fieldKey }) {
+  const invalid = Array.isArray(errorsByField?.[fieldKey]) && errorsByField[fieldKey].length > 0;
+  store.set(`${metaPath}.invalid`, invalid);
+}

package/examples/032-todo-app-with-eventTest/runtime/forms/submitWithBoundary.js

@@ -0,0 +1,28 @@
+// forms/submitWithBoundary.js — thin wrapper over runWithBoundary for forms
+// Usage: submitWithBoundary(store, asyncFn, { submittingPath, errorPath, successPath })
+// Ensures submitting flag toggles, errors are mapped to a path, and optional success payload is written.
+
+import { runWithBoundary } from '../extensions/boundary.js';
+
+/**
+ * @template T
+ * @param {any} store - eventState-like store with get/set
+ * @param {() => Promise<T>} fn - async submit function
+ * @param {{ submittingPath: string, errorPath?: string, successPath?: string, mapError?: (e:any)=>any }} opts
+ * @returns {Promise<T|any|undefined>}
+ */
+export function submitWithBoundary(store, fn, opts) {
+  const { submittingPath, errorPath, successPath, mapError } = opts || {};
+  if (submittingPath) store.set(submittingPath, true);
+  if (errorPath) store.set(errorPath, null);
+
+  return runWithBoundary(fn, {
+    setLoading: (b) => { if (submittingPath) store.set(submittingPath, b); },
+    onError: (err) => { if (errorPath) store.set(errorPath, err); },
+    mapError,
+    finally: () => {}
+  }).then((res) => {
+    if (typeof successPath === 'string') store.set(successPath, res ?? null);
+    return res;
+  });
+}

package/examples/032-todo-app-with-eventTest/runtime/forms/validators.js

@@ -0,0 +1,55 @@
+// forms/validators.js — minimal sync/async validation helper
+// Shape:
+//   validate(model, rules) -> Promise<{ valid: boolean, errorsByField: Record<string,string[]>, errorsGlobal: string[] }>
+// Rules shape:
+//   {
+//     fieldName: [ ruleFn, ... ],
+//     _global?: [ ruleFn, ... ]
+//   }
+// ruleFn signature:
+//   (value, model) => string|undefined|Promise<string|undefined>
+//   Returns a message when invalid; undefined when valid.
+
+/**
+ * @param {any} model
+ * @param {Record<string, Array<Function>>} rules
+ */
+export async function validate(model, rules = {}) {
+  const errorsByField = {};
+  const errorsGlobal = [];
+
+  const entries = Object.entries(rules).filter(([k]) => k !== '_global');
+
+  for (const [field, fns] of entries) {
+    const val = field.split('.').reduce((acc, k) => (acc ? acc[k] : undefined), model);
+    for (const fn of fns || []) {
+      const res = await fn(val, model);
+      if (typeof res === 'string' && res) {
+        (errorsByField[field] ||= []).push(res);
+      }
+    }
+  }
+
+  const globals = rules._global || [];
+  for (const fn of globals) {
+    const res = await fn(model);
+    if (typeof res === 'string' && res) errorsGlobal.push(res);
+  }
+
+  const valid = Object.keys(errorsByField).length === 0 && errorsGlobal.length === 0;
+  return { valid, errorsByField, errorsGlobal };
+}
+
+// Some tiny reusable rules
+export const Rules = {
+  required: (msg = 'This field is required.') => (v) => (v == null || v === '' ? msg : undefined),
+  minLen: (n, msg) => (v) => (typeof v === 'string' && v.length < n ? (msg || `Must be at least ${n} characters.`) : undefined),
+  pattern: (re, msg) => (v) => (v && !re.test(String(v)) ? (msg || 'Invalid format.') : undefined),
+  email: (msg = 'Enter a valid email.') => (v) => (!v ? undefined : /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(String(v)) ? undefined : msg),
+  // Async example: simulate uniqueness check
+  asyncUnique: (checkFn, msg = 'Already taken.') => async (v) => {
+    if (!v) return undefined;
+    const ok = await checkFn(v);
+    return ok ? undefined : msg;
+  },
+};

package/examples/032-todo-app-with-eventTest/store.d.ts

@@ -0,0 +1,23 @@
+// Auto-generated from test assertions
+// DO NOT EDIT - regenerate by running: node tests/generateTypes.js
+
+export interface StoreState {
+  domain: {
+    todos: {
+      items: Array<{ id: number; text: string; done: boolean }>;
+    };
+  };
+  ui: {
+    todos: {
+      filter: string;
+    };
+  };
+  intent: {
+    todo: {
+      add: { text: string };
+      toggle: { id: number };
+    };
+  };
+}
+
+export default StoreState;

package/examples/032-todo-app-with-eventTest/style.css

@@ -0,0 +1,170 @@
+body {
+    font: 14px/1.4 system-ui, sans-serif;
+    margin: 0;
+}
+
+/* Hide focus outline on route container (set programmatically for a11y) */
+[data-route-root]:focus {
+    outline: none;
+}
+
+nav {
+    padding: 10px 14px;
+    border-bottom: 1px solid #eee;
+    position: sticky;
+    top: 0;
+    background: #fff;
+    z-index: 10;
+}
+
+nav a {
+    margin-right: 12px;
+    text-decoration: none;
+    color: #0366d6;
+}
+
+nav a.active {
+    font-weight: 600;
+}
+
+main {
+    padding: 16px;
+}
+
+.loading-badge {
+    margin-left: 8px;
+    font-size: 12px;
+    color: #666;
+    display: none;
+}
+
+html[data-transitioning="on"] .loading-badge {
+    display: inline;
+}
+
+/* 404 view demo: tint the top bar only on notfound */
+html[data-view="notfound"] nav {
+    background: #fff7f7;
+    border-bottom-color: #f5c2c2;
+}
+
+html[data-view="notfound"] nav a {
+    color: #b91c1c;
+}
+
+html[data-view="notfound"] .loading-badge {
+    color: #b91c1c;
+}
+
+/* Tabs styling (used by views/demo.js) */
+.tabs {
+    margin-top: 12px;
+}
+
+.tab-bar {
+    display: flex;
+    gap: 8px;
+    border-bottom: 1px solid #eee;
+    padding-bottom: 6px;
+}
+
+.tab {
+    appearance: none;
+    border: 1px solid #ddd;
+    background: #fafafa;
+    border-radius: 6px;
+    padding: 6px 10px;
+    cursor: pointer;
+}
+
+.tab:hover {
+    background: #f3f4f6;
+}
+
+.tab.active {
+    background: #e5efff;
+    border-color: #bcd1ff;
+}
+
+.tab-panels {
+    padding-top: 10px;
+}
+
+.tab-panel {
+    display: none;
+}
+
+.tab-panel[data-active] {
+    display: block;
+}
+
+:root {
+    --bg: #ffffff;
+    --fg: #111111;
+    --muted: #555;
+    --card: #f6f6f6;
+    --border: #e5e5e5;
+    --btn-bg: #f8f8f8;
+    --btn-fg: #111;
+    --btn-border: #ddd;
+    --input-bg: #fff;
+    --input-fg: #222;
+    --input-border: #d6d6d6;
+}
+
+body[data-theme='dark'] {
+    --bg: #0f1115;
+    --fg: #cfd3dc;
+    --muted: #9aa3b2;
+    --card: #151923;
+    --border: #242a36;
+    --btn-bg: #1a2030;
+    --btn-fg: #cfd3dc;
+    --btn-border: #2b3242;
+    --input-bg: #1b2130;
+    --input-fg: #cfd3dc;
+    --input-border: #2b3242;
+}
+
+body {
+    background: var(--bg);
+    color: var(--fg);
+}
+
+a {
+    color: inherit;
+}
+
+nav {
+    background: var(--card);
+    border-bottom: 1px solid var(--border);
+}
+
+.btn {
+    appearance: none;
+    border: 1px solid var(--btn-border);
+    background: var(--btn-bg);
+    color: var(--btn-fg);
+    border-radius: 6px;
+    padding: 6px 10px;
+    cursor: pointer;
+}
+
+input,
+select,
+textarea {
+    background: var(--input-bg);
+    color: var(--input-fg);
+    border: 1px solid var(--input-border);
+    border-radius: 6px;
+    padding: 6px 8px;
+}
+
+input::placeholder,
+textarea::placeholder {
+    color: color-mix(in srgb, var(--input-fg) 55%, transparent);
+}
+
+.btn:hover {
+    filter: brightness(1.05);
+}