react-stateshape 0.2.1 → 0.2.3

package/README.md

@@ -1,6 +1,6 @@
 # react-stateshape
 
-Shared state management and routing in React apps. Under the hood, routing is shared state management, too, with the shared data being the URL.
+A shared state management and routing lib for React apps. Under the hood, routing is shared state management, too, with the shared data being the URL.
 
 Contents: [useExternalState](#useexternalstate) · [useRoute](#useroute) · [useNavigationStart / useNavigationComplete](#usenavigationstart--usenavigationcomplete) · [useRouteState](#useroutestate) · [Type-safe routes](#type-safe-routes) · [useTransientState](#usetransientstate) · [Annotated examples](#annotated-examples) · [Internals](#internals)
 
@@ -66,16 +66,19 @@ let App = () => (
 
 ### Filtering state updates
 
-⬥ Use the optional `false` parameter in `useExternalState(state, false)`, as in `<ResetButton>` above, to tell the hook not to subscribe the component to tracking the external state updates. The common use case for it is when a component makes use of the external state value setter without using the state value itself.
+⬥ Use the optional `false` parameter in `useExternalState(state, false)`, as in `ResetButton` above, to tell the hook not to subscribe the component to tracking the external state updates. The common use case for it is when a component makes use of the external state value setter without using the state value itself.
 
 ⬥ Apart from setting the optional second parameter of `useExternalState(state, callback)` to a boolean value, use it as a render callback for more fine-grained control over component's re-renders in response to state changes:
 
 ```js
+let itemState = new State({/* A map of `<id>: <item>` */});
+
+// Renders a specific item from `itemState`
 let ItemCard = ({ id }) => {
   let [items, setItems] = useExternalState(itemState, (render, { current, previous }) => {
-    // Assuming that the items have a `revision` property, re-render
-    // `ItemCard` only if the relevant item's `revision` has changed.
-    if (current[id].revision !== previous[id].revision) render();
+    // Assuming that the items have a `timestamp` property, re-render
+    // `ItemCard` only if the relevant item's `timestamp` has increased
+    if (current[id].timestamp > previous[id].timestamp) render();
   });
 
   // ...
@@ -102,7 +105,7 @@ let counterState = new PersistentState(0, { key: "counter" });
 
 ⬥ Set up interaction with a custom storage by setting `{ read(), write(value)? }` as `options` in `new PersistentState(value, options)`.
 
-⬥ `PersistentState` skips interaction with the browser storage in non-browser environments, which makes it usable with SSR.
+⬥ `PersistentState` skips interaction with the browser storage in non-browser environments, which makes it usable with SSR. One way to avoid mismatch errors while hydrating SSR content based on a persisent state restored in the browser is using client-side rendering detection utilities such as [`react-clientside`](https://www.npmjs.com/package/react-clientside).
 
 ## useRoute
 
@@ -130,7 +133,7 @@ let App = () => {
 
 ⬥ `params` in dynamic values (as in `({ params }) => <Section id={params.id}/>` above) contains the URL pattern's capturing groups.
 
-⬥ By default, `useRoute` and the other routing hooks described here make use of the browser's URL, if it's available. Otherwise, use `<RouteProvider href="/x">` to set a specific URL value. Common use cases: SSR and tests. A less common use case: custom routing behavior, including custom non-URL-based routing ([example](https://codesandbox.io/p/sandbox/tykt44?file=%252Fsrc%252FApp.tsx)).
+⬥ By default, `useRoute` makes use of the browser's URL, if it's available. Otherwise, use `<RouteProvider href={url}>` to set a specific URL value. Common use cases: SSR and tests. A less common use case: custom routing behavior, including custom non-URL-based routing ([example](https://codesandbox.io/p/sandbox/tykt44?file=%252Fsrc%252FApp.tsx)).
 
 ⬥ See also the [Type-safe routes](#type-safe-routes) section.
 

package/package.json

@@ -1,49 +1,49 @@
-{
-  "name": "react-stateshape",
-  "version": "0.2.1",
-  "description": "Concise shared state management and routing in React apps",
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.mjs",
-  "types": "./dist/index.d.ts",
-  "type": "module",
-  "scripts": {
-    "demo": "npx auxsrv tests/Shared_state_without_Context",
-    "preversion": "npx npm-run-all shape test",
-    "shape": "npx codeshape",
-    "t3": "npx auxsrv tests/Tic-tac-toe",
-    "test": "npx playwright test --project=chromium",
-    "typecheck": "npx codeshape typecheck"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/axtk/react-stateshape.git"
-  },
-  "keywords": [
-    "state",
-    "state management",
-    "react state management",
-    "shared state",
-    "global state",
-    "routing",
-    "react router"
-  ],
-  "license": "MIT",
-  "author": "axtk",
-  "peerDependencies": {
-    "react": ">=16.8"
-  },
-  "devDependencies": {
-    "@playwright/test": "^1.58.2",
-    "@types/node": "^25.5.0",
-    "@types/react": "^19.2.14",
-    "@types/react-dom": "^19.2.3",
-    "auxsrv": "^0.3.2",
-    "immer": "^11.1.4",
-    "react-dom": "^19.2.4",
-    "url-shape": "^1.3.15",
-    "zod": "^4.3.6"
-  },
-  "dependencies": {
-    "stateshape": "^0.2.1"
-  }
-}
+{
+  "name": "react-stateshape",
+  "version": "0.2.3",
+  "description": "A shared state management and routing lib for React apps",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "demo": "npx auxsrv tests/Shared_state_without_Context",
+    "preversion": "npx npm-run-all shape test",
+    "shape": "npx codeshape",
+    "t3": "npx auxsrv tests/Tic-tac-toe",
+    "test": "npx playwright test --project=chromium",
+    "typecheck": "npx codeshape typecheck"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/axtk/react-stateshape.git"
+  },
+  "keywords": [
+    "state",
+    "state management",
+    "react state management",
+    "shared state",
+    "global state",
+    "routing",
+    "react router"
+  ],
+  "license": "MIT",
+  "author": "axtk",
+  "peerDependencies": {
+    "react": ">=16.8"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.58.2",
+    "@types/node": "^25.5.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "auxsrv": "^0.3.2",
+    "immer": "^11.1.4",
+    "react-dom": "^19.2.4",
+    "url-shape": "^1.3.15",
+    "zod": "^4.3.6"
+  },
+  "dependencies": {
+    "stateshape": "^0.2.1"
+  }
+}