@buoy-gg/zustand 7.0.38 → 7.0.40

package/lib/module/zustand/utils/editableState.js

@@ -1 +1,138 @@
-"use strict";export const STRIP_MAX_DEPTH=8;export function isPlainObjectLike(t){if("object"!=typeof t||null===t||Array.isArray(t))return!1;const e=Object.getPrototypeOf(t);return e===Object.prototype||null===e}export function stripFunctions(t,e,n,r,i){if("function"==typeof t)return void n.push(e);if("object"!=typeof t||null===t||i>=8)return t;if(r.has(t))return;if(r.add(t),Array.isArray(t))return t.map((t,o)=>"function"==typeof t?(n.push(`${e}[${o}]`),null):stripFunctions(t,`${e}[${o}]`,n,r,i+1));if(!isPlainObjectLike(t))return t;const o={};for(const[s,a]of Object.entries(t))"function"!=typeof a?o[s]=stripFunctions(a,e?`${e}.${s}`:s,n,r,i+1):n.push(e?`${e}.${s}`:s);return o}export function editableStateOf(t){if(isPlainObjectLike(t)&&!0===t.__buoyStateOnDevice)return{data:null,fnPaths:[],blockedReason:"Store state hasn't synced from the device yet."};if(!isPlainObjectLike(t))return{data:null,fnPaths:[],blockedReason:"Only stores whose state is a plain object can be edited — a merge write has nothing to address in "+(Array.isArray(t)?"an array":"a "+typeof t)+"."};const e=[],n=stripFunctions(t,"",e,new WeakSet,0),r=e.filter(t=>t.includes(".")||t.includes("["));return r.length>0?{data:null,fnPaths:e,blockedReason:`State keeps a function inside "${r[0]}" — a merge write of that key would drop it, so this store can't be edited here.`}:{data:n,fnPaths:e,blockedReason:null}}export function computeMergePartial(t,e){if(!isPlainObjectLike(e))throw new Error("The store's state must stay an object.");const n=Object.keys(t).filter(t=>!(t in e));if(n.length>0)throw new Error(`Can't remove top-level ${1===n.length?"key":"keys"} ${n.map(t=>`"${t}"`).join(", ")} — zustand merge writes can't delete. Edit the value instead.`);const r={};for(const n of Object.keys(e))n in t&&JSON.stringify(e[n])===JSON.stringify(t[n])||(r[n]=e[n]);return r}
+"use strict";
+
+/**
+ * What of a zustand store's state can be EDITED, and how an edit is written.
+ *
+ * The two zustand facts every rule here follows from:
+ *
+ * 1. Stores conventionally keep their action functions IN state
+ *    (`increment: () => …`). Functions can't be typed into a tree editor and
+ *    don't survive serialization, so the editor works on a function-free view
+ *    of state.
+ * 2. `setState` is either a TOP-LEVEL SHALLOW MERGE (`Object.assign({}, state,
+ *    partial)`) or a full replace that deletes every key not present — actions
+ *    included. So the editor writes merge-only, always: every edit, however
+ *    deep, is expressed as "replace the top-level key(s) that contain it"
+ *    ({@link computeMergePartial}), and the two edits a merge cannot express —
+ *    removing or renaming a top-level key — are refused rather than silently
+ *    not happening.
+ *
+ * `stripFunctions` lives here (the Time Machine snapshot provider imports it)
+ * because capture and editing need the identical answer to "what is this
+ * store's data".
+ */
+
+/** Bounds every recursive walk over store state. */
+export const STRIP_MAX_DEPTH = 8;
+export function isPlainObjectLike(v) {
+  // Only objects whose own enumerable keys ARE their data. A Map, Set, Date,
+  // RegExp or typed array has none, so walking it with Object.entries turns
+  // it into `{}` — which is how a restored store once got `{}` where the app
+  // kept a Map and crashed on `.values()`. Those go through as-is; the vault's
+  // superjson knows how to carry them.
+  if (typeof v !== "object" || v === null || Array.isArray(v)) return false;
+  const proto = Object.getPrototypeOf(v);
+  return proto === Object.prototype || proto === null;
+}
+
+/** Clone `value` without functions, recording their paths. */
+export function stripFunctions(value, path, fnPaths, seen, depth) {
+  if (typeof value === "function") {
+    fnPaths.push(path);
+    return undefined;
+  }
+  if (typeof value !== "object" || value === null || depth >= STRIP_MAX_DEPTH) {
+    return value;
+  }
+  if (seen.has(value)) return undefined; // cycle — drop the back-reference
+  seen.add(value);
+  if (Array.isArray(value)) {
+    return value.map((item, i) => typeof item === "function" ? (fnPaths.push(`${path}[${i}]`), null) : stripFunctions(item, `${path}[${i}]`, fnPaths, seen, depth + 1));
+  }
+  if (!isPlainObjectLike(value)) return value; // Date/Map/Set/etc. — superjson handles
+  const out = {};
+  for (const [k, v] of Object.entries(value)) {
+    if (typeof v === "function") {
+      fnPaths.push(path ? `${path}.${k}` : k);
+      continue;
+    }
+    out[k] = stripFunctions(v, path ? `${path}.${k}` : k, fnPaths, seen, depth + 1);
+  }
+  return out;
+}
+/**
+ * The editor's view of one store's state, with the reasons it may refuse.
+ *
+ * - A remote mirror that hasn't hydrated yet holds a marker, not state — the
+ *   real value is one `getStoreState` round trip away, so "wait" rather than
+ *   "can't".
+ * - Non-object state (`create(() => 5)`) has no top-level keys, so a merge
+ *   write cannot address any part of it. Editing it would require a replace,
+ *   which is the destructive path this editor exists to avoid.
+ * - A function nested BELOW the top level (rare — the convention keeps actions
+ *   at the top) sits inside the very key an edit would rewrite, and a merge
+ *   write of that key would silently drop it. Refusing the whole store is
+ *   blunt but honest; per-key locks can come later if this ever bites.
+ */
+export function editableStateOf(state) {
+  if (isPlainObjectLike(state) && state.__buoyStateOnDevice === true) {
+    return {
+      data: null,
+      fnPaths: [],
+      blockedReason: "Store state hasn't synced from the device yet."
+    };
+  }
+  if (!isPlainObjectLike(state)) {
+    return {
+      data: null,
+      fnPaths: [],
+      blockedReason: "Only stores whose state is a plain object can be edited — " + "a merge write has nothing to address in " + (Array.isArray(state) ? "an array" : `a ${typeof state}`) + "."
+    };
+  }
+  const fnPaths = [];
+  const data = stripFunctions(state, "", fnPaths, new WeakSet(), 0);
+  const nested = fnPaths.filter(p => p.includes(".") || p.includes("["));
+  if (nested.length > 0) {
+    return {
+      data: null,
+      fnPaths,
+      blockedReason: `State keeps a function inside "${nested[0]}" — a merge write of ` + "that key would drop it, so this store can't be edited here."
+    };
+  }
+  return {
+    data,
+    fnPaths,
+    blockedReason: null
+  };
+}
+
+/**
+ * Diff an edited draft against the state it was seeded from, as a `setState`
+ * MERGE partial: only the top-level keys whose contents changed.
+ *
+ * Diffed against the SEED, not the live state at save time, on purpose — the
+ * partial then carries exactly what the user changed, so a key the app wrote
+ * while the editor was open and the user never touched keeps the app's value
+ * (per-key last-write-wins, the same contract the draft's own dirtiness uses).
+ *
+ * Throws on the two edits a merge cannot express, naming the key: a draft
+ * that dropped a top-level key (which is also what a raw-JSON rename produces
+ * — the old key dropped, a new one added), because `setState(partial, false)`
+ * would leave it exactly as it was while the editor showed it gone.
+ */
+export function computeMergePartial(seed, draft) {
+  if (!isPlainObjectLike(draft)) {
+    throw new Error("The store's state must stay an object.");
+  }
+  const dropped = Object.keys(seed).filter(k => !(k in draft));
+  if (dropped.length > 0) {
+    throw new Error(`Can't remove top-level ${dropped.length === 1 ? "key" : "keys"} ` + `${dropped.map(k => `"${k}"`).join(", ")} — zustand merge writes ` + "can't delete. Edit the value instead.");
+  }
+  const partial = {};
+  for (const key of Object.keys(draft)) {
+    if (!(key in seed) || JSON.stringify(draft[key]) !== JSON.stringify(seed[key])) {
+      partial[key] = draft[key];
+    }
+  }
+  return partial;
+}

package/lib/module/zustand/utils/snapshotProvider.js

@@ -1 +1,209 @@
-"use strict";import{classifyPreviewItem,createRestoreScope,emptyRestoreResult,failedRestore,registerStateSnapshotProvider,unionKeys}from"@buoy-gg/shared-ui";import{zustandStateStore}from"./zustandStateStore";import{isPlainObjectLike,stripFunctions,STRIP_MAX_DEPTH}from"./editableState";const MAX_DEPTH=STRIP_MAX_DEPTH;function graftFunctions(t,e,s,n){if(isPlainObjectLike(e)&&isPlainObjectLike(t)&&!(n>=MAX_DEPTH||s.has(e))){s.add(e);for(const[o,r]of Object.entries(e))if("function"==typeof r)t[o]=r;else if(isPlainObjectLike(r)){if(!isPlainObjectLike(t[o])){if(!containsFunction(r,new WeakSet,n+1))continue;t[o]={}}graftFunctions(t[o],r,s,n+1)}}}function containsFunction(t,e,s){if(s>=MAX_DEPTH||e.has(t))return!1;e.add(t);for(const n of Object.values(t)){if("function"==typeof n)return!0;if(isPlainObjectLike(n)&&containsFunction(n,e,s+1))return!0}return!1}function status(){return 0===zustandStateStore.getStores().length?{canCapture:!1,canRestore:!1,detail:"No Zustand stores registered — pass `zustandStores` to FloatingDevTools or add the buoyDevTools middleware"}:{canCapture:!0,canRestore:!0}}async function capture(){const t=[],e={};for(const s of zustandStateStore.getStores()){const n=[];let o;try{o=stripFunctions(s.api.getState(),"",n,new WeakSet,0)}catch(e){t.push(`store "${s.name}": capture failed (${String(e)})`);continue}e[s.name]={state:o,fnPaths:n}}return{data:{stores:e},warnings:t}}async function restore(t,e){const s=t,n=createRestoreScope(e),o=emptyRestoreResult();if(!s?.stores)return failedRestore("empty zustand snapshot");for(const[t,e]of Object.entries(s.stores)){if(!n.allows(t))continue;const s=zustandStateStore.getStore(t);if(s)try{const n=e.state;graftFunctions(n,s.api.getState(),new WeakSet,0),s.api.setState(n,!0),s.api.getState()===n?o.applied+=1:(o.warnings.push(`store "${t}": setState did not take effect`),o.ok=!1)}catch(e){o.skipped.push({id:t,reason:String(e)}),o.ok=!1}else o.skipped.push({id:t,reason:"store not registered (renamed, or created after snapshot?)"})}const r=n.excludedWarning("store(s)");return r&&o.warnings.push(r),o}async function previewItems(t,e){const s=t?.stores??{},n=void 0===e,o={};if(n)for(const t of zustandStateStore.getStores()){const e=[];try{o[t.name]={state:stripFunctions(t.api.getState(),"",e,new WeakSet,0),fnPaths:e}}catch{}}else Object.assign(o,e?.stores??{});const r=[],a=[];let i=0;for(const t of unionKeys(o,s)){const e=t in o;t in s?(i+=s[t].fnPaths?.length??0,!n||zustandStateStore.getStore(t)?r.push(classifyPreviewItem({key:t,label:t,oldValue:o[t]?.state,newValue:s[t].state,inOld:e,inNew:!0},{tooLargeReason:"store too large to render a diff — restore still applies it"})):r.push({key:t,label:t,verdict:"wont-apply",reason:"store not registered (renamed, or created after snapshot?)"})):n?a.push(`store "${t}" not in snapshot — untouched`):r.push({key:t,label:t,verdict:"removed",oldValue:o[t].state})}return i>0&&a.push(`${i} store action function${1===i?"":"s"} preserved on restore (not diffed)`),{items:r,notes:a}}registerStateSnapshotProvider({id:"zustand",label:"Zustand",status:status,capture:capture,restore:restore,previewItems:previewItems});
+"use strict";
+
+/**
+ * Time Machine snapshot provider for Zustand.
+ *
+ * Registered into @buoy-gg/shared-ui's stateSnapshotRegistry at module init;
+ * consumed by @buoy-gg/time-machine. Neither package imports the other.
+ *
+ * The Zustand-specific hazard: stores conventionally keep their action
+ * functions IN state (`increment: () => ...`). Functions don't survive
+ * serialization, and a full `setState(snapshot, true)` replace would wipe
+ * them, breaking every `useStore(s => s.increment)` call site. So capture
+ * strips functions (recording where they were), and restore re-grafts the
+ * LIVE store's functions onto the snapshot before replacing.
+ */
+import { classifyPreviewItem, createRestoreScope, emptyRestoreResult, failedRestore, registerStateSnapshotProvider, unionKeys } from "@buoy-gg/shared-ui";
+import { zustandStateStore } from "./zustandStateStore";
+import { isPlainObjectLike, stripFunctions, STRIP_MAX_DEPTH } from "./editableState";
+
+// The function-stripping walk is shared with the store editor (editableState
+// .ts) — capture and editing must agree on what a store's "data" is.
+const MAX_DEPTH = STRIP_MAX_DEPTH;
+/**
+ * Copy every function-valued property from the LIVE state onto the restored
+ * snapshot (creating containers as needed), so store actions keep working
+ * after a full replace.
+ */
+function graftFunctions(target, live, seen, depth) {
+  if (!isPlainObjectLike(live) || !isPlainObjectLike(target)) return;
+  if (depth >= MAX_DEPTH || seen.has(live)) return;
+  seen.add(live);
+  for (const [k, v] of Object.entries(live)) {
+    if (typeof v === "function") {
+      target[k] = v;
+    } else if (isPlainObjectLike(v)) {
+      if (!isPlainObjectLike(target[k])) {
+        // Branch missing from the snapshot — only recreate it if it holds
+        // functions somewhere; otherwise the snapshot's absence wins.
+        if (!containsFunction(v, new WeakSet(), depth + 1)) continue;
+        target[k] = {};
+      }
+      graftFunctions(target[k], v, seen, depth + 1);
+    }
+  }
+}
+function containsFunction(value, seen, depth) {
+  if (depth >= MAX_DEPTH || seen.has(value)) return false;
+  seen.add(value);
+  for (const v of Object.values(value)) {
+    if (typeof v === "function") return true;
+    if (isPlainObjectLike(v) && containsFunction(v, seen, depth + 1)) return true;
+  }
+  return false;
+}
+function status() {
+  const count = zustandStateStore.getStores().length;
+  if (count === 0) {
+    return {
+      canCapture: false,
+      canRestore: false,
+      detail: "No Zustand stores registered — pass `zustandStores` to FloatingDevTools or add the buoyDevTools middleware"
+    };
+  }
+  return {
+    canCapture: true,
+    canRestore: true
+  };
+}
+async function capture() {
+  const warnings = [];
+  const stores = {};
+  for (const info of zustandStateStore.getStores()) {
+    const fnPaths = [];
+    let state;
+    try {
+      state = stripFunctions(info.api.getState(), "", fnPaths, new WeakSet(), 0);
+    } catch (e) {
+      warnings.push(`store "${info.name}": capture failed (${String(e)})`);
+      continue;
+    }
+    stores[info.name] = {
+      state,
+      fnPaths
+    };
+  }
+  return {
+    data: {
+      stores
+    },
+    warnings
+  };
+}
+async function restore(data, options) {
+  const snapshot = data;
+  const scope = createRestoreScope(options);
+  const result = emptyRestoreResult();
+  if (!snapshot?.stores) {
+    return failedRestore("empty zustand snapshot");
+  }
+  for (const [name, envelope] of Object.entries(snapshot.stores)) {
+    if (!scope.allows(name)) continue;
+    const info = zustandStateStore.getStore(name);
+    if (!info) {
+      result.skipped.push({
+        id: name,
+        reason: "store not registered (renamed, or created after snapshot?)"
+      });
+      continue;
+    }
+    try {
+      const next = envelope.state;
+      graftFunctions(next, info.api.getState(), new WeakSet(), 0);
+      info.api.setState(next, true);
+      if (info.api.getState() === next) {
+        result.applied += 1;
+      } else {
+        result.warnings.push(`store "${name}": setState did not take effect`);
+        result.ok = false;
+      }
+    } catch (e) {
+      result.skipped.push({
+        id: name,
+        reason: String(e)
+      });
+      result.ok = false;
+    }
+  }
+  const excludedWarning = scope.excludedWarning("store(s)");
+  if (excludedWarning) result.warnings.push(excludedWarning);
+  return result;
+}
+
+/**
+ * Per-store restore preview. Both sides are function-stripped through the
+ * SAME depth-8 normalizer as capture — diffing snapshot-vs-RAW-live would
+ * report every stripped function and every beyond-depth subtree as removed.
+ */
+async function previewItems(target, base) {
+  const targetStores = target?.stores ?? {};
+  const liveMode = base === undefined;
+  const baseStores = {};
+  if (liveMode) {
+    for (const info of zustandStateStore.getStores()) {
+      const fnPaths = [];
+      try {
+        baseStores[info.name] = {
+          state: stripFunctions(info.api.getState(), "", fnPaths, new WeakSet(), 0),
+          fnPaths
+        };
+      } catch {
+        // unreadable live store — treated as absent
+      }
+    }
+  } else {
+    Object.assign(baseStores, base?.stores ?? {});
+  }
+  const items = [];
+  const notes = [];
+  let preservedFns = 0;
+  for (const name of unionKeys(baseStores, targetStores)) {
+    const inTarget = name in targetStores;
+    const inBase = name in baseStores;
+    if (!inTarget) {
+      // Restore never touches stores the snapshot doesn't know about.
+      if (liveMode) notes.push(`store "${name}" not in snapshot — untouched`);else items.push({
+        key: name,
+        label: name,
+        verdict: "removed",
+        oldValue: baseStores[name].state
+      });
+      continue;
+    }
+    preservedFns += targetStores[name].fnPaths?.length ?? 0;
+    if (liveMode && !zustandStateStore.getStore(name)) {
+      items.push({
+        key: name,
+        label: name,
+        verdict: "wont-apply",
+        reason: "store not registered (renamed, or created after snapshot?)"
+      });
+      continue;
+    }
+    items.push(classifyPreviewItem({
+      key: name,
+      label: name,
+      oldValue: baseStores[name]?.state,
+      newValue: targetStores[name].state,
+      inOld: inBase,
+      inNew: true
+    }, {
+      tooLargeReason: "store too large to render a diff — restore still applies it"
+    }));
+  }
+  if (preservedFns > 0) {
+    notes.push(`${preservedFns} store action function${preservedFns === 1 ? "" : "s"} preserved on restore (not diffed)`);
+  }
+  return {
+    items,
+    notes
+  };
+}
+registerStateSnapshotProvider({
+  id: "zustand",
+  label: "Zustand",
+  status,
+  capture,
+  restore,
+  previewItems
+});

package/lib/module/zustand/utils/testIDs.js

@@ -1 +1,74 @@
-"use strict";export const ZUSTAND_TEST_ID="buoy-zustand";export function slugForTestID(e){return String(e??"").toLowerCase().replace(/[^a-z0-9]+/g,"-").replace(/^-+|-+$/g,"")||"unknown"}export function changeRowTestID(e,t){return`buoy-zustand-row-${slugForTestID(e)}-${t}`}export function storeRowTestID(e){return`buoy-zustand-store-${slugForTestID(e)}`}export function buildChangeRowTestIDs(e){const t=new Map,o=new Map;for(const n of e){const e=(t.get(n.storeName)??0)+1;t.set(n.storeName,e),o.set(n.id,changeRowTestID(n.storeName,e))}return o}
+"use strict";
+
+/**
+ * Zustand tool test handles.
+ *
+ * Every tappable and every value the e2e suite reads back is addressed
+ * `buoy-zustand-<thing>`. Two rules in here need explaining.
+ *
+ * **A change row's handle carries an ORDINAL, and it counts per STORE.** The
+ * Events tool can address a row by what it is about, because an event is a
+ * thing that happened to a named subject — one key, one URL, one atom. A
+ * zustand state change is not: a store that a screen writes to fifty times
+ * produces fifty separate, equally real rows. Addressing them by store name
+ * alone would give fifty views one handle, and Detox fails a *matcher* that
+ * hits more than one element — so a suite would break on `toExist()`, before
+ * any assertion, with an error that says nothing about duplicate changes.
+ *
+ * So the handle is `buoy-zustand-row-<slug(storeName)>-<n>`, where n counts
+ * back from the newest row of that store (1 = newest). Deliberately relative:
+ * a state change has no identity a host could know in advance — `id` is a
+ * timestamp plus a per-process counter whose value depends on how many
+ * changes the app happened to make before the test looked. What a test CAN
+ * know is "the set I just fired is the newest change to that store". Read and
+ * tap in one beat: a row's ordinal moves the instant another change lands.
+ *
+ * **A store row's handle does NOT.** A store is registered once under a name
+ * that is unique by construction (`zustandStateStore.registerStore` returns
+ * early on a name it already holds), so `buoy-zustand-store-<slug(name)>` is
+ * as stable as the store itself — and unlike a change, it is a thing the host
+ * knows the name of before the app has booted.
+ *
+ * The suite mirrors these rules in CommonJS (`example-dev-build/utils/
+ * zustandBench.js`) and asserts the two agree — Detox runs in Node on the host
+ * and cannot import TypeScript.
+ */
+
+/** Prefix every handle in this tool shares. */
+export const ZUSTAND_TEST_ID = "buoy-zustand";
+
+/** `zbenchWatch` → `zbenchwatch`. Shared with every Buoy tool. */
+export function slugForTestID(value) {
+  return String(value ?? "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "unknown";
+}
+
+/**
+ * Handle for one change row: `buoy-zustand-row-zbenchwatch-1`.
+ *
+ * `ordinal` is 1-based and counts back from the newest row of this store.
+ */
+export function changeRowTestID(storeName, ordinal) {
+  return `${ZUSTAND_TEST_ID}-row-${slugForTestID(storeName)}-${ordinal}`;
+}
+
+/** Handle for one store row in the browser: `buoy-zustand-store-zbenchwatch`. */
+export function storeRowTestID(storeName) {
+  return `${ZUSTAND_TEST_ID}-store-${slugForTestID(storeName)}`;
+}
+
+/**
+ * Row handle per change id for one rendered list, newest-first.
+ *
+ * Built once for the whole list rather than per row, because an ordinal is a
+ * fact about the list and a row cannot compute its own.
+ */
+export function buildChangeRowTestIDs(changes) {
+  const seen = new Map();
+  const handles = new Map();
+  for (const change of changes) {
+    const ordinal = (seen.get(change.storeName) ?? 0) + 1;
+    seen.set(change.storeName, ordinal);
+    handles.set(change.id, changeRowTestID(change.storeName, ordinal));
+  }
+  return handles;
+}