@nice-code/state 0.4.1 → 0.4.3

package/README.md

@@ -1 +1,262 @@
-# @nice-code/state
+# @nice-code/state
+
+Framework-agnostic, Immer-backed state container with fine-grained selector subscriptions, derived reactions, patch streams, and a drop-in React adapter + devtools panel.
+
+## Install
+
+```bash
+bun add @nice-code/state immer
+```
+
+`react` is an optional peer dependency (>=19) — only needed for the `@nice-code/state/react` adapter.
+
+## Why
+
+- **One immutable store, mutated with Immer** — write plain mutations (`s.count += 1`), get structural sharing for free.
+- **No-op updates are genuinely free** — listeners only fire when the root reference actually changes.
+- **Fine-grained selectors** — components and side-effects re-run only when their watched slice changes structurally, not on every update.
+- **Tear-free React** — the adapter is built on `useSyncExternalStore` (React 18+ concurrent-safe), no provider/context required.
+- **Patches + devtools** — every mutation can emit Immer patches; the optional devtools panel gives you a timeline, state inspector, diff view, and revert.
+
+---
+
+## Core concepts
+
+- **Store** — owns one immutable state value and a set of listeners.
+- **update** — mutate the state through an Immer draft.
+- **watch** — subscribe to a derived slice; fires only on structural change (outside React).
+- **createReaction** — derive further state from the store's own mutations.
+- **useStoreState** — subscribe a React component to a store or a selected slice.
+
+---
+
+## Create a store
+
+```ts
+import { Store } from "@nice-code/state";
+
+interface ICounterState {
+  count: number;
+  step: number;
+}
+
+// Pass a value, or a factory function (re-used by SSR / reset).
+export const counterStore = new Store<ICounterState>({ count: 0, step: 1 });
+```
+
+## Update state
+
+Mutations run through Immer — mutate the `draft` freely, the store commits a new immutable state.
+
+```ts
+// Single update
+counterStore.update((s) => {
+  s.count += s.step;
+});
+
+// Batched — an array of updaters applied in order, committed as one change
+counterStore.update([
+  (s) => { s.count += 1; },
+  (s) => { s.count += 1; },
+]);
+
+// Replace the whole state
+counterStore.replace({ count: 0, step: 1 });
+
+// Replace by mapping from the current state
+counterStore.replaceFromCurrent((s) => ({ ...s, count: 0 }));
+```
+
+The second argument to an updater is a readonly snapshot of the pre-update state:
+
+```ts
+counterStore.update((draft, original) => {
+  draft.count = original.count * 2;
+});
+```
+
+## Read state
+
+```ts
+const { count } = counterStore.getRawState();
+```
+
+> Reach for `getRawState()` only in plain logic. In components use `useStoreState`; for side-effects use `watch`.
+
+---
+
+## React adapter
+
+Import from `@nice-code/state/react`. No provider needed — pass the store directly.
+
+```tsx
+import { useStoreState } from "@nice-code/state/react";
+
+function Counter() {
+  // Select a slice — re-renders only when `count` changes.
+  const count = useStoreState(counterStore, (s) => s.count);
+
+  return (
+    <button onClick={() => counterStore.update((s) => { s.count += 1; })}>
+      {count}
+    </button>
+  );
+}
+```
+
+```tsx
+// No selector → subscribe to the whole state.
+const state = useStoreState(counterStore);
+```
+
+### Selecting derived/inline values
+
+By default selection uses a strict-reference check (perfect for state branches, thanks to Immer's structural sharing). When a selector builds a **new** object/array each call, pass an equality function so equal-but-new results don't re-render:
+
+```tsx
+import { useStoreState } from "@nice-code/state/react";
+import { deepEqual } from "fast-equals";
+
+const activeTodos = useStoreState(
+  store,
+  (s) => s.todos.filter((t) => !t.done),
+  deepEqual,
+);
+```
+
+### Component-local stores
+
+`useLocalStore` creates a store scoped to a component instance, persisted across renders. Pass a `deps` array to re-create it (with fresh initial state) when dependencies change.
+
+```tsx
+import { useLocalStore, useStoreState } from "@nice-code/state/react";
+
+function Editor({ docId }: { docId: string }) {
+  const store = useLocalStore(() => ({ draft: "" }), [docId]);
+  const draft = useStoreState(store, (s) => s.draft);
+  // ...
+}
+```
+
+### Render-prop binding
+
+`InjectStoreState` subscribes inline without writing a hook:
+
+```tsx
+import { InjectStoreState } from "@nice-code/state/react";
+
+<InjectStoreState store={counterStore} on={(s) => s.count}>
+  {(count) => <span>{count}</span>}
+</InjectStoreState>
+```
+
+---
+
+## Reactions — derive state from state
+
+A reaction watches a slice and, when it changes, runs a recipe inside Immer to derive further state on the **same** store. Reactions run before subscribers are notified, so derived fields are always consistent in a single render.
+
+```ts
+interface IState {
+  count: number;
+  doubled: number;      // derived — never written by hand
+  history: number[];    // derived
+}
+
+const store = new Store<IState>({ count: 0, doubled: 0, history: [] });
+
+store.createReaction(
+  (s) => s.count,                       // watch
+  (count, draft) => {                   // derive
+    draft.doubled = count * 2;
+    draft.history = [...draft.history, count].slice(-12);
+  },
+  { runNow: true },                     // run once immediately to seed derived state
+);
+```
+
+`createReaction` returns a disposer to remove the reaction.
+
+---
+
+## Watch — side-effects outside React
+
+`watch` subscribes to a derived slice and fires the listener only when it changes structurally. Ideal for logging, persistence, or syncing to non-React code.
+
+```ts
+const unsubscribe = store.watch(
+  (s) => s.count,
+  (count, allState, previousCount) => {
+    console.log(`count: ${previousCount} → ${count}`);
+  },
+);
+```
+
+The low-level `store.subscribe(() => { ... })` fires on every committed update (no slice, no args) — this is the primitive the React adapter builds on.
+
+---
+
+## Patches
+
+Every update can emit [Immer patches](https://immerjs.github.io/immer/patches/), enabling undo/redo, sync, and the devtools. Patches are only computed when there's a consumer, so the common path stays allocation-free.
+
+```ts
+import { applyPatchesToStore } from "@nice-code/state";
+
+// Listen to patches for every update
+const stop = store.listenToPatches((patches, inversePatches) => {
+  sendToServer(patches);
+});
+
+// Or collect patches for a single update
+store.update((s) => { s.count += 1; }, (patches, inverse) => {
+  undoStack.push(inverse);
+});
+
+// Apply patches (e.g. received from elsewhere, or to undo)
+store.applyPatches(patches);
+```
+
+---
+
+## Devtools
+
+A zero-config inspector for your stores — timeline of changes, before/after diffs, live state inspector with direct editing, and patch-based revert. Import the panel from `@nice-code/state/devtools/browser`.
+
+```ts
+// devtools.ts — register the stores you want to observe
+import { StateDevtoolsCore } from "@nice-code/state/devtools/browser";
+import { counterStore } from "./counterStore";
+
+export const stateDevtools = new StateDevtoolsCore();
+stateDevtools.registerStore("counterStore", counterStore);
+```
+
+```tsx
+// Mount once near your app root. Renders nothing in production
+// (NODE_ENV !== "development").
+import { NiceStateDevtools } from "@nice-code/state/devtools/browser";
+import { stateDevtools } from "./devtools";
+
+<NiceStateDevtools core={stateDevtools} position="dock-bottom" />
+```
+
+`position` is one of `"dock-bottom"` | `"dock-top"` | `"dock-left"` | `"dock-right"`. The panel lets you filter by store, inspect/edit live state, view per-change diffs and patches, pause the timeline, and revert a change via its inverse patches.
+
+> Registering a store attaches a patch listener (a negligible dev-time cost). Keep devtools setup out of production bundles.
+
+---
+
+## SSR
+
+`useStoreState` is built on `useSyncExternalStore` with a server snapshot, so it renders the store's current value on the server without subscribing. Construct stores with a factory (`new Store(() => initialState())`) so each request can seed its own state.
+
+---
+
+## Exports
+
+| Entry | Contents |
+| --- | --- |
+| `@nice-code/state` | `Store`, `update`, `applyPatchesToStore`, and all core types |
+| `@nice-code/state/react` | `useStoreState`, `useLocalStore`, `InjectStoreState` |
+| `@nice-code/state/devtools/browser` | `StateDevtoolsCore`, `NiceStateDevtools` |

package/build/devtools/browser/index.js

@@ -472,9 +472,15 @@ import {
 import { jsxDEV as jsxDEV3 } from "react/jsx-dev-runtime";
 var DOCKED_SIZE_MIN = 160;
 var POSITION_GRID = [
-  [null, "dock-top", null],
-  ["dock-left", null, "dock-right"],
-  [null, "dock-bottom", null]
+  { key: "tl", pos: null },
+  { key: "tc", pos: "dock-top" },
+  { key: "tr", pos: null },
+  { key: "ml", pos: "dock-left" },
+  { key: "mc", pos: null },
+  { key: "mr", pos: "dock-right" },
+  { key: "bl", pos: null },
+  { key: "bc", pos: "dock-bottom" },
+  { key: "br", pos: null }
 ];
 function getDockSide(pos) {
   switch (pos) {
@@ -606,12 +612,11 @@ function PositionPicker({
   return /* @__PURE__ */ jsxDEV3("div", {
     title: "Move / dock panel",
     style: { display: "grid", gridTemplateColumns: "repeat(3, 9px)", gap: "2px", padding: "2px" },
-    children: POSITION_GRID.flat().map((pos) => {
+    children: POSITION_GRID.map(({ key, pos }) => {
       if (pos == null)
         return /* @__PURE__ */ jsxDEV3("div", {
           style: { width: "9px", height: "9px" }
-        }, "center-empty", false, undefined, this);
-      const isDock = pos.startsWith("dock-");
+        }, key, false, undefined, this);
       const isTopBottom = pos === "dock-top" || pos === "dock-bottom";
       const isActive = pos === position;
       return /* @__PURE__ */ jsxDEV3("div", {
@@ -627,13 +632,13 @@ function PositionPicker({
         },
         children: /* @__PURE__ */ jsxDEV3("div", {
           style: {
-            width: isDock ? isTopBottom ? "9px" : "3px" : "7px",
-            height: isDock ? isTopBottom ? "3px" : "9px" : "7px",
-            borderRadius: isDock ? "1px" : "50%",
+            width: isTopBottom ? "9px" : "3px",
+            height: isTopBottom ? "3px" : "9px",
+            borderRadius: "1px",
             background: isActive ? DEVTOOL_COLOR_SEMANTIC_SYSTEM : DEVTOOL_COLOR_TEXT_FAINT
           }
         }, undefined, false, undefined, this)
-      }, pos, false, undefined, this);
+      }, key, false, undefined, this);
     })
   }, undefined, false, undefined, this);
 }
@@ -1467,12 +1472,12 @@ function NiceStateDevtools_Panel({
   const [selectedChangeCuid, setSelectedChangeCuid] = useState4(null);
   useEffect2(() => core.subscribe(setSnapshot), [core]);
   const setPrefs = (update) => {
-    setPrefsRaw((prev) => {
-      const next = { ...prev, ...update };
-      writePrefs(next);
-      return next;
-    });
+    setPrefsRaw((prev) => ({ ...prev, ...update }));
   };
+  useEffect2(() => {
+    const timer = setTimeout(() => writePrefs(prefs), 250);
+    return () => clearTimeout(timer);
+  }, [prefs]);
   const { stores, changes, paused } = snapshot;
   const { position, isOpen, dockedHeight, dockedWidth, detailRatio } = prefs;
   const dockSide = getDockSide(position);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nice-code/state",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "private": false,
   "type": "module",
   "exports": {