wenay-react2 1.0.34 → 1.0.35

package/lib/common/src/hooks/useObserveStore.d.ts

@@ -1,5 +1,6 @@
 import { ObserveAll2 } from "wenay-common2";
 type StoreChange = ObserveAll2.StoreChange;
+type StoreEachCtx = ObserveAll2.StoreEachCtx;
 type StoreSubOpts = ObserveAll2.StoreSubOpts;
 type StoreSyncOpts = ObserveAll2.StoreSyncOpts;
 type StoreDrain = ObserveAll2.StoreDrain;
@@ -55,6 +56,20 @@ export type StoreKeysController<T extends object = any> = {
 };
 export declare function useStoreKeys<T extends object>(node: StoreNode<T>, options?: Omit<UseStoreNodeOptions<T>, "mode">): StoreKeysController<T>;
 export declare function useStoreSelect<T, M extends StoreMask<T>>(selection: StoreSelection<T, M>, options?: UseStoreSelectOptions<StorePick<T, M>>): StoreSelectionController<T, M>;
+export type UseStoreEachOptions = {
+    /** false = do not subscribe (and drop the current subscription). Default true. */
+    enabled?: boolean;
+};
+/**
+ * Per-changed-top-level-key feed of a store (`store.each()` of wenay-common2): cb fires once per
+ * CHANGED key per drain window with the current `store.state[key]` (`undefined` = key deleted);
+ * a root replace (store.replace / mirror keyframe) EXPANDS into one call per key, so cold start
+ * is not a special case for per-key consumers (grid rows, canvas layers, ...). The fold target
+ * should live outside React state (ref/store/grid api) — this hook renders nothing by itself.
+ * cb goes through a ref — a new identity does not resubscribe.
+ * The remote (wire) counterpart is useStoreReplayEach in useReplay.ts.
+ */
+export declare function useStoreEach<T extends object>(store: ObserveAll2.Store<T> | null | undefined, cb: (key: string, value: T[keyof T] | undefined, ctx: StoreEachCtx) => void, options?: UseStoreEachOptions): void;
 export type RemoteStoreLike<T extends object> = {
     get(mask?: any): T | Promise<T>;
     changed: ListenLike<readonly []>;
@@ -102,4 +117,4 @@ export declare function useListenValue<T, TArgs extends readonly unknown[] = rea
     current?: boolean | (() => TArgs | undefined);
     map?: (...args: TArgs) => T;
 }): T | undefined;
-export type { StoreChange, StoreDrain, StoreMask, StoreNode, StorePick, StoreSelection, StoreSubOpts, StoreSyncOpts };
+export type { StoreChange, StoreDrain, StoreEachCtx, StoreMask, StoreNode, StorePick, StoreSelection, StoreSubOpts, StoreSyncOpts };

package/lib/common/src/hooks/useObserveStore.js

@@ -96,6 +96,25 @@ export function useStoreSelect(selection, options = {}) {
         get: () => selection.get(),
     }), [selection, value, refresh]);
 }
+/**
+ * Per-changed-top-level-key feed of a store (`store.each()` of wenay-common2): cb fires once per
+ * CHANGED key per drain window with the current `store.state[key]` (`undefined` = key deleted);
+ * a root replace (store.replace / mirror keyframe) EXPANDS into one call per key, so cold start
+ * is not a special case for per-key consumers (grid rows, canvas layers, ...). The fold target
+ * should live outside React state (ref/store/grid api) — this hook renders nothing by itself.
+ * cb goes through a ref — a new identity does not resubscribe.
+ * The remote (wire) counterpart is useStoreReplayEach in useReplay.ts.
+ */
+export function useStoreEach(store, cb, options = {}) {
+    const { enabled = true } = options;
+    const cbRef = useLatestRef(cb);
+    useEffect(() => {
+        if (!store || !enabled)
+            return;
+        // each() is created lazily per subscription: it runs while it has subscribers and closes on off()
+        return store.each().on((key, value, ctx) => cbRef.current(key, value, ctx));
+    }, [store, enabled, cbRef]);
+}
 export function useStoreMirror(remote, initial, options) {
     const { mask, auto = true, current = true, drain, key, partial, onError } = options;
     const stableMask = useStableStoreMask(mask);

package/lib/common/src/hooks/useReplay.d.ts

@@ -1,4 +1,6 @@
 import { ObserveAll2, Replay } from "wenay-common2";
+type StoreDrain = ObserveAll2.StoreDrain;
+type StoreEachCtx = ObserveAll2.StoreEachCtx;
 type StorePatch = ObserveAll2.StorePatch;
 type ReplayEvent<Z extends any[]> = Replay.ReplayEvent<Z>;
 type ReplayRemote<Z extends any[]> = Replay.ReplayRemote<Z>;
@@ -78,6 +80,31 @@ export type StoreReplayMirrorController<T extends object> = StoreReplaySyncContr
  * so reconnect is a journal tail, not a keyframe. A new `remote` recreates the store.
  */
 export declare function useStoreReplayMirror<T extends object>(remote: ReplayRemote<[StorePatch]> | null | undefined, initial: T, options?: UseStoreReplaySyncOptions): StoreReplayMirrorController<T>;
+export type UseStoreReplayEachOptions<T extends object> = UseStoreReplaySyncOptions & {
+    /**
+     * Seed of the internal mirror store. Creation-time only (a later identity change does nothing).
+     * Reconnect after a FULL unmount: pass the saved snapshot together with `since`
+     * ({since: prev.seq(), initial: prev.store.snapshot()}) — the tail lands ON TOP of the previous
+     * state; a fresh empty mirror would not converge.
+     */
+    initial?: T;
+    /** Drain of the internal mirror store — the coalescing window of the per-key feed. Creation-time only. */
+    drain?: StoreDrain;
+};
+/**
+ * Per-key fold over a store replay line — React counterpart of `ObserveAll2.syncStoreReplayEach`
+ * (internal mirror store + syncStoreReplay + store.each()). cb fires once per CHANGED top-level
+ * key per drain window with the current value; the first delivery is the keyframe EXPANDED per
+ * key; (key, undefined) = key deleted — cold start / reconnect are not special cases for per-key
+ * consumers (grid rows, canvas layers, ...). The fold target should live outside React state.
+ *
+ * Unlike the library one-call (a fresh store per call), the mirror here lives in a ref: within
+ * one mounted component every resubscribe (StrictMode double-effect, restart(), enabled toggling,
+ * staleMs/policy change) reconnects by tail ON TOP of the kept state — no snapshot/initial dance.
+ * A new `remote` identity recreates the store (fresh keyframe). Direct reads / extra
+ * subscriptions: controller.store (useStoreNode/useStoreKeys work on it as usual).
+ */
+export declare function useStoreReplayEach<T extends object>(remote: ReplayRemote<[StorePatch]> | null | undefined, cb: (key: string, value: T[keyof T] | undefined, ctx: StoreEachCtx) => void, options?: UseStoreReplayEachOptions<T>): StoreReplayMirrorController<T>;
 export type UseReplayFrameOptions = {
     /** Pull period, ms. Default 300. */
     intervalMs?: number;

package/lib/common/src/hooks/useReplay.js

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { ObserveAll2, Replay } from "wenay-common2";
+import { useStoreEach } from "./useObserveStore";
 /**
  * React bridge over the Replay stack (snapshot + sequenced delta line) of wenay-common2.
  *
@@ -201,6 +202,32 @@ export function useStoreReplayMirror(remote, initial, options = {}) {
     const sync = useStoreReplaySync(store, remote, options);
     return useMemo(() => ({ ...sync, store }), [sync, store]);
 }
+/**
+ * Per-key fold over a store replay line — React counterpart of `ObserveAll2.syncStoreReplayEach`
+ * (internal mirror store + syncStoreReplay + store.each()). cb fires once per CHANGED top-level
+ * key per drain window with the current value; the first delivery is the keyframe EXPANDED per
+ * key; (key, undefined) = key deleted — cold start / reconnect are not special cases for per-key
+ * consumers (grid rows, canvas layers, ...). The fold target should live outside React state.
+ *
+ * Unlike the library one-call (a fresh store per call), the mirror here lives in a ref: within
+ * one mounted component every resubscribe (StrictMode double-effect, restart(), enabled toggling,
+ * staleMs/policy change) reconnects by tail ON TOP of the kept state — no snapshot/initial dance.
+ * A new `remote` identity recreates the store (fresh keyframe). Direct reads / extra
+ * subscriptions: controller.store (useStoreNode/useStoreKeys work on it as usual).
+ */
+export function useStoreReplayEach(remote, cb, options = {}) {
+    const { initial, drain, ...syncOptions } = options;
+    const storeRef = useRef(null);
+    if (!storeRef.current || storeRef.current.remote !== remote) {
+        storeRef.current = { remote, store: ObserveAll2.createStore((initial ?? {}), drain !== undefined ? { drain } : undefined) };
+    }
+    const store = storeRef.current.store;
+    // each BEFORE sync: effects run in hook-call order, so the per-key subscriber already exists
+    // when the keyframe applies to the store (the expansion is not missed)
+    useStoreEach(store, cb, { enabled: syncOptions.enabled });
+    const sync = useStoreReplaySync(store, remote, syncOptions);
+    return useMemo(() => ({ ...sync, store }), [sync, store]);
+}
 /**
  * Pull a replay line at YOUR pace (the frame model of common2): a timer around
  * `remote.frame(seq, hint)` — the server condenses the tail via the line's `frame` lambda

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wenay-react2",
-  "version": "1.0.34",
+  "version": "1.0.35",
   "description": "Common react",
   "strict": true,
   "main": "dist/index.js",
@@ -23,7 +23,7 @@
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "react-rnd": "^10.5.3",
-    "wenay-common2": "^1.0.58"
+    "wenay-common2": "^1.0.61"
   },
   "peerDependencies": {
     "react": "^19.2.0",