@yakocloud/state-vocab 4.0.2 → 4.0.3

package/README.md

@@ -260,6 +260,81 @@ By default `ssr: true`:
 
 This guarantees the server and client produce identical markup, and the value from storage is applied without a visible flash.
 
+### Next.js Pages Router (SSR without RSC)
+
+If you use Next.js with the **Pages Router** (or any SSR setup without React Server Components), you still need `ssr: true` to prevent hydration mismatches — but you don't have server components to wrap with `StateVocabProvider` from `serverify`.
+
+In this case, wrap your app with `StateVocabClientProvider` from `@yakocloud/state-vocab/client`. It creates an isolated `VocabStore` per render, preventing state from leaking between concurrent SSR requests.
+
+```tsx
+// pages/_app.tsx
+import type { AppProps } from 'next/app'
+import { StateVocabClientProvider } from '@yakocloud/state-vocab/client'
+
+export default function App({ Component, pageProps }: AppProps) {
+  return (
+    <StateVocabClientProvider>
+      <Component {...pageProps} />
+    </StateVocabClientProvider>
+  )
+}
+```
+
+Storage is still configured with `ssr: true` (the default):
+
+```ts
+// lib/storage.ts
+import { setupStorage, defineState } from '@yakocloud/state-vocab'
+import { clientify } from '@yakocloud/state-vocab/client'
+
+const storage = setupStorage({
+  preference: {
+    theme: defineState<'Dark' | 'White' | 'System'>({
+      storage: localStorage,
+      defaultValue: 'Dark',
+    }),
+  },
+  // ssr: true is the default — storage reads are deferred until after hydration
+})
+
+export const clientStorage = clientify(storage)
+```
+
+Use `clientStorage` directly in any page or component — no additional wiring needed:
+
+```tsx
+// pages/settings.tsx
+import { clientStorage } from '@/lib/storage'
+
+export default function Settings() {
+  const [theme, setTheme] = clientStorage.preference.theme.useState()
+
+  return (
+    <select value={theme} onChange={(e) => setTheme(e.target.value as 'Dark' | 'White' | 'System')}>
+      <option value="Dark">Dark</option>
+      <option value="White">White</option>
+      <option value="System">System</option>
+    </select>
+  )
+}
+```
+
+`StateVocabClientProvider` also accepts an optional `value` prop to pre-seed the store with server-fetched data (e.g., from `getServerSideProps`):
+
+```tsx
+// pages/_app.tsx
+import type { AppProps } from 'next/app'
+import { StateVocabClientProvider } from '@yakocloud/state-vocab/client'
+
+export default function App({ Component, pageProps }: AppProps) {
+  return (
+    <StateVocabClientProvider value={pageProps.initialVocab}>
+      <Component {...pageProps} />
+    </StateVocabClientProvider>
+  )
+}
+```
+
 ### React Server Components (RSC)
 
 For Next.js apps using the App Router, state-vocab provides dedicated server and client entry points that let you read state in async server components and pass it down to client components via `StateVocabProvider`.
@@ -270,7 +345,7 @@ For Next.js apps using the App Router, state-vocab provides dedicated server and
 |---|---|
 | `@yakocloud/state-vocab` | Shared files — `defineState`, `setupStorage` |
 | `@yakocloud/state-vocab/server` | Server Components — `serverify` |
-| `@yakocloud/state-vocab/client` | Client Components — `clientify` |
+| `@yakocloud/state-vocab/client` | Client Components — `clientify`, `StateVocabClientProvider` |
 
 **1. Define the shared storage schema** (used on both server and client):
 
@@ -607,6 +682,18 @@ const { StateVocabProvider } = serverStorage
 </StateVocabProvider>
 ```
 
+### `StateVocabClientProvider`
+
+A client-only provider for SSR setups **without** React Server Components (e.g. Next.js Pages Router). Import from `@yakocloud/state-vocab/client` and place it at your app root to ensure per-request store isolation. Accepts an optional `value` prop to pre-seed the store.
+
+```tsx
+import { StateVocabClientProvider } from '@yakocloud/state-vocab/client'
+
+<StateVocabClientProvider value={initialVocab}>
+  <App />
+</StateVocabClientProvider>
+```
+
 ### `serverify<T>(storage: T)`
 
 Converts a storage tree to its server-side counterpart. Available from `@yakocloud/state-vocab/server`.

package/dist/client.cjs.js

@@ -1 +1 @@
-"use client";"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const u=require("react"),v=require("./constants-CbsduCZ7.js"),a=require("./utils-0CTNJ4ZE.js"),y=require("./provider-client-B4XQ24JB.js");function D(t,e,n=[]){return u.useMemo(()=>a.debounce(t,e),n)}const g=t=>{const{vocabStore:e,storage:n,statePath:o,value:s,deserialize:S,serialize:l}=t,f=n.getItem(o);f===null?a.isValueDefined(s)&&n.setItem(o,l(s)):e.set(o,S(f))},z=typeof window>"u",m=z?u.useEffect:u.useLayoutEffect,A=new y.VocabStore,C="Make sure your component is wrapped in StateVocabProvider (RSC) or disable ssr option in setupStorage for SPA (RCC only)";function I(t){t??={};const e=z?void 0:a.valueOrFactory(t.storage),n=a.valueOrFactory(t.defaultValue),o=t.bidirectional,s=this[v.STATE_PATH],S=this[v.STATE_VERBOSE],l=this[v.STATE_VERBOSE_PATH],f=this[v.STATE_SSR];let i=y.useStateVocabClientContext({verbose:S});if(!(i instanceof y.VocabStore)){if(f)throw new Error(C);i=A}const d=t.serialize??JSON.stringify,c=t.deserialize??JSON.parse,V=D(t.onSet??(()=>{}),t.delayedSet,[]),E=u.useRef(void 0),w=u.useRef(!1);if(!w.current){w.current=!0;let r=i.get(s);a.isValueDefined(r)||(r=n,a.isValueDefined(r)&&i.set(s,r)),!f&&e&&g({vocabStore:i,storage:e,statePath:s,value:r,serialize:d,deserialize:c})}const h=u.useSyncExternalStore(i.subscribe.bind(i),i.getClientSnapshot.bind(i),i.getServerSnapshot.bind(i));if(S)if(l){const r=a.get(h,l);r&&a.logStyled(r)}else a.logStyled(h);const T=a.get(h,s,n);E.current=T,m(()=>{!f||!e||g({vocabStore:i,storage:e,statePath:s,value:T,serialize:d,deserialize:c})},[]);const O=u.useEffectEvent(r=>{if(r.key!==s)return;const b=r.newValue,R=(b===null?null:c(b))??n;a.isValueDefined(R)&&(i.set(s,R),V(R,E.current))});u.useEffect(()=>{if(o)return window.addEventListener("storage",O),()=>window.removeEventListener("storage",O)},[o]);const p=u.useCallback(r=>{const b=a.isTransformer(r)?r(E.current):r;i.set(s,b),V(b,E.current),e&&e.setItem(s,d(b))},[i,s,V,e,d]),_=u.useCallback(()=>{const r=n;if(!a.isValueDefined(r)){e?.removeItem(s);return}i.set(s,r),V(r,E.current),e&&e.setItem(s,d(r))},[n,i,s,V,e,d]);return[T,p,_]}function k(t){t??={};const e=z?void 0:a.valueOrFactory(t.storage),n=a.valueOrFactory(t.defaultValue),o=this[v.STATE_PATH],s=this[v.STATE_VERBOSE],S=this[v.STATE_SSR];let l=y.useStateVocabClientContext({verbose:s});if(!(l instanceof y.VocabStore)){if(S)throw new Error(C);l=A}const f=t.serialize??JSON.stringify,i=t.deserialize??JSON.parse,d=u.useRef(!1);let c;d.current||(d.current=!0,c=l.get(o),a.isValueDefined(c)||(c=n,a.isValueDefined(c)&&l.set(o,c)),!S&&e&&g({vocabStore:l,storage:e,statePath:o,value:c,serialize:f,deserialize:i})),m(()=>{!S||!e||g({vocabStore:l,storage:e,statePath:o,value:c,serialize:f,deserialize:i})},[])}function q(t){return typeof t=="object"&&t!==null&&"clientSlot"in t}function P(t){const e={};for(const n in t){const o=t[n];q(o)?(e[n]=o.clientSlot({useState(...s){return I.apply(this,s)},useInitialState(...s){k.apply(this,s)}}),delete e[n].serverSlot,delete e[n].clientSlot):o!==null&&typeof o=="object"?e[n]=P(o):e[n]=o}return e}exports.clientify=P;
+"use client";"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const u=require("react"),v=require("./constants-CbsduCZ7.js"),a=require("./utils-0CTNJ4ZE.js"),V=require("./provider-client-B4XQ24JB.js");function D(t,e,n=[]){return u.useMemo(()=>a.debounce(t,e),n)}const g=t=>{const{vocabStore:e,storage:n,statePath:o,value:i,deserialize:S,serialize:l}=t,f=n.getItem(o);f===null?a.isValueDefined(i)&&n.setItem(o,l(i)):e.set(o,S(f))},z=typeof window>"u",O=z?u.useEffect:u.useLayoutEffect,m=new V.VocabStore,A="Make sure your component is wrapped in StateVocabProvider (RSC) or disable ssr option in setupStorage for SPA (RCC only)";function I(t){t??={};const e=z?void 0:a.valueOrFactory(t.storage),n=a.valueOrFactory(t.defaultValue),o=t.bidirectional,i=this[v.STATE_PATH],S=this[v.STATE_VERBOSE],l=this[v.STATE_VERBOSE_PATH],f=this[v.STATE_SSR];let s=V.useStateVocabClientContext({verbose:S});if(!(s instanceof V.VocabStore)){if(f)throw new Error(A);s=m}const d=t.serialize??JSON.stringify,c=t.deserialize??JSON.parse,E=D(t.onSet??(()=>{}),t.delayedSet,[]),y=u.useRef(void 0),C=u.useRef(!1);if(!C.current){C.current=!0;let r=s.get(i);a.isValueDefined(r)||(r=n,a.isValueDefined(r)&&s.set(i,r)),!f&&e&&g({vocabStore:s,storage:e,statePath:i,value:r,serialize:d,deserialize:c})}const h=u.useSyncExternalStore(s.subscribe.bind(s),s.getClientSnapshot.bind(s),s.getServerSnapshot.bind(s));if(S)if(l){const r=a.get(h,l);r&&a.logStyled(r)}else a.logStyled(h);const T=a.get(h,i,n);y.current=T,O(()=>{!f||!e||g({vocabStore:s,storage:e,statePath:i,value:T,serialize:d,deserialize:c})},[]);const w=u.useEffectEvent(r=>{if(r.key!==i)return;const b=r.newValue,R=(b===null?null:c(b))??n;a.isValueDefined(R)&&(s.set(i,R),E(R,y.current))});u.useEffect(()=>{if(o)return window.addEventListener("storage",w),()=>window.removeEventListener("storage",w)},[o]);const p=u.useCallback(r=>{const b=a.isTransformer(r)?r(y.current):r;s.set(i,b),E(b,y.current),e&&e.setItem(i,d(b))},[s,i,E,e,d]),_=u.useCallback(()=>{const r=n;if(!a.isValueDefined(r)){e?.removeItem(i);return}s.set(i,r),E(r,y.current),e&&e.setItem(i,d(r))},[n,s,i,E,e,d]);return[T,p,_]}function k(t){t??={};const e=z?void 0:a.valueOrFactory(t.storage),n=a.valueOrFactory(t.defaultValue),o=this[v.STATE_PATH],i=this[v.STATE_VERBOSE],S=this[v.STATE_SSR];let l=V.useStateVocabClientContext({verbose:i});if(!(l instanceof V.VocabStore)){if(S)throw new Error(A);l=m}const f=t.serialize??JSON.stringify,s=t.deserialize??JSON.parse,d=u.useRef(!1);let c;d.current||(d.current=!0,c=l.get(o),a.isValueDefined(c)||(c=n,a.isValueDefined(c)&&l.set(o,c)),!S&&e&&g({vocabStore:l,storage:e,statePath:o,value:c,serialize:f,deserialize:s})),O(()=>{!S||!e||g({vocabStore:l,storage:e,statePath:o,value:c,serialize:f,deserialize:s})},[])}function q(t){return typeof t=="object"&&t!==null&&"clientSlot"in t}function P(t){const e={};for(const n in t){const o=t[n];q(o)?(e[n]=o.clientSlot({useState(...i){return I.apply(this,i)},useInitialState(...i){k.apply(this,i)}}),delete e[n].serverSlot,delete e[n].clientSlot):o!==null&&typeof o=="object"?e[n]=P(o):e[n]=o}return e}exports.StateVocabClientProvider=V.StateVocabClientProvider;exports.clientify=P;

package/dist/client.es.js

@@ -1,10 +1,11 @@
 "use client";
-import { useMemo as B, useRef as V, useSyncExternalStore as D, useEffectEvent as H, useEffect as I, useCallback as T, useLayoutEffect as x } from "react";
-import { S as O, a as P, b as _, c as F } from "./constants-BB1YAX6c.mjs";
-import { a as d, d as G, v as g, g as A, l as C, i as q } from "./utils-xV3x3fTc.mjs";
+import { useMemo as x, useRef as y, useSyncExternalStore as B, useEffectEvent as D, useEffect as A, useCallback as T, useLayoutEffect as H } from "react";
+import { S as I, a as O, b as _, c as F } from "./constants-BB1YAX6c.mjs";
+import { a as d, d as G, v as g, g as C, l as P, i as q } from "./utils-xV3x3fTc.mjs";
 import { V as z, u as k } from "./provider-client-C2Aw0Lmi.mjs";
+import { S as ie } from "./provider-client-C2Aw0Lmi.mjs";
 function K(t, e, n = []) {
-  return B(
+  return x(
     () => G(t, e),
     // eslint-disable-next-line react-hooks/exhaustive-deps
     n
@@ -20,10 +21,10 @@ const E = (t) => {
     serialize: a
   } = t, c = n.getItem(o);
   c === null ? d(s) && n.setItem(o, a(s)) : e.set(o, f(c));
-}, w = typeof window > "u", J = w ? I : x, L = new z(), N = "Make sure your component is wrapped in StateVocabProvider (RSC) or disable ssr option in setupStorage for SPA (RCC only)";
+}, p = typeof window > "u", J = p ? A : H, L = new z(), N = "Make sure your component is wrapped in StateVocabProvider (RSC) or disable ssr option in setupStorage for SPA (RCC only)";
 function Q(t) {
   t ??= {};
-  const e = w ? void 0 : g(t.storage), n = g(t.defaultValue), o = t.bidirectional, s = this[O], f = this[P], a = this[F], c = this[_];
+  const e = p ? void 0 : g(t.storage), n = g(t.defaultValue), o = t.bidirectional, s = this[I], f = this[O], a = this[F], c = this[_];
   let r = k({ verbose: f });
   if (!(r instanceof z)) {
     if (c)
@@ -35,9 +36,9 @@ function Q(t) {
     }),
     t.delayedSet,
     []
-  ), b = V(void 0), p = V(!1);
-  if (!p.current) {
-    p.current = !0;
+  ), b = y(void 0), w = y(!1);
+  if (!w.current) {
+    w.current = !0;
     let i = r.get(s);
     d(i) || (i = n, d(i) && r.set(s, i)), !c && e && E({
       vocabStore: r,
@@ -48,18 +49,18 @@ function Q(t) {
       deserialize: l
     });
   }
-  const h = D(
+  const h = B(
     r.subscribe.bind(r),
     r.getClientSnapshot.bind(r),
     r.getServerSnapshot.bind(r)
   );
   if (f)
     if (a) {
-      const i = A(h, a);
-      i && C(i);
+      const i = C(h, a);
+      i && P(i);
     } else
-      C(h);
-  const m = A(h, s, n);
+      P(h);
+  const m = C(h, s, n);
   b.current = m, J(() => {
     !c || !e || E({
       vocabStore: r,
@@ -70,13 +71,13 @@ function Q(t) {
       deserialize: l
     });
   }, []);
-  const R = H((i) => {
+  const R = D((i) => {
     if (i.key !== s)
       return;
-    const S = i.newValue, y = (S === null ? null : l(S)) ?? n;
-    d(y) && (r.set(s, y), v(y, b.current));
+    const S = i.newValue, V = (S === null ? null : l(S)) ?? n;
+    d(V) && (r.set(s, V), v(V, b.current));
   });
-  I(() => {
+  A(() => {
     if (o)
       return window.addEventListener("storage", R), () => window.removeEventListener("storage", R);
   }, [o]);
@@ -99,14 +100,14 @@ function Q(t) {
 }
 function U(t) {
   t ??= {};
-  const e = w ? void 0 : g(t.storage), n = g(t.defaultValue), o = this[O], s = this[P], f = this[_];
+  const e = p ? void 0 : g(t.storage), n = g(t.defaultValue), o = this[I], s = this[O], f = this[_];
   let a = k({ verbose: s });
   if (!(a instanceof z)) {
     if (f)
       throw new Error(N);
     a = L;
   }
-  const c = t.serialize ?? JSON.stringify, r = t.deserialize ?? JSON.parse, u = V(!1);
+  const c = t.serialize ?? JSON.stringify, r = t.deserialize ?? JSON.parse, u = y(!1);
   let l;
   u.current || (u.current = !0, l = a.get(o), d(l) || (l = n, d(l) && a.set(o, l)), !f && e && E({
     vocabStore: a,
@@ -145,5 +146,6 @@ function X(t) {
   return e;
 }
 export {
+  ie as StateVocabClientProvider,
   X as clientify
 };

package/dist/types/client.d.ts

@@ -1 +1,2 @@
 export { clientify } from "./setup.client";
+export { StateVocabClientProvider } from "./provider.client";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yakocloud/state-vocab",
-  "version": "4.0.2",
+  "version": "4.0.3",
   "main": "dist/index.cjs.js",
   "module": "dist/index.es.js",
   "types": "dist/types/index.d.ts",