react-narrow 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 James Karlsson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,153 @@
-# Temporary Holding Version
+# react-narrow
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`useState` for nested data. Mutate it like a plain object, keep it as plain immutable React state, and hand any component just the slice it needs.
+
+No global store, no selectors, no actions. State is plain data that lives in your component tree and flows through props and context, so React and the React Compiler treat it like any other state. Writes go through [Mutative](https://github.com/unadlib/mutative), which turns your mutations into immutable updates.
+
+```tsx
+// Before: rebuild every level by hand
+setState((s) => ({
+  ...s,
+  projects: s.projects.map((p, i) =>
+    i === pi ? { ...p, tasks: p.tasks.map((t, j) => (j === ti ? { ...t, done: true } : t)) } : p,
+  ),
+}))
+
+// After
+setState((s) => { s.projects[pi].tasks[ti].done = true })
+```
+
+> **Warning:** `react-narrow` is still a 0.x release, so the API may change. Found a bug, or a case it doesn't handle? Please [open an issue](https://github.com/jaaamesey/narrow/issues).
+
+## First, create a store
+
+It works like `useState`, except a function you pass to the setter mutates a draft.
+
+```tsx
+import { useNewStore } from 'react-narrow'
+
+function TodoApp() {
+  const [state, setState] = useNewStore({ todos: [] as Todo[], settings: { showDone: true } })
+
+  const add = (title: string) =>
+    setState((s) => {
+      s.todos.push({ id: crypto.randomUUID(), title, done: false })
+    })
+  // ...
+}
+```
+
+To replace the state instead, pass a value, or a function with `'swap'`:
+
+```ts
+setState({ todos: [], settings: { showDone: true } })
+setState((s) => ({ ...s, todos: [] }), 'swap')
+```
+
+Returning a new object from a mutating function is a type error, so a forgotten `'swap'` doesn't slip through.
+
+## Then narrow it
+
+Narrowing gives you one part of the state and a setter for just that part. Writes still land in the original store.
+
+```tsx
+const [settings, setSettings] = useNarrowedStore(state, (s) => s.settings, setState)
+
+setSettings((s) => { s.showDone = false })  // updates state.settings.showDone
+```
+
+`(s) => s.settings` is the narrow function: it picks the part of the state to narrow to. A narrowed store works like any other, so you can pass it down and narrow it again.
+
+You can use `NarrowList` to pass just a single item in a store down to a component. This helper doesn't just isolate reads/writes to that item. Here (assuming you've enabled the React Compiler, or are manually memoizing), it also ensures that a `TodoRow` only re-renders when its own `todo` changes.
+
+```tsx
+const [todos, setTodos] = useNarrowedStore(state, (s) => s.todos, setState)
+
+<NarrowList items={todos} setStore={setTodos} getKey={(t) => t.id}>
+  {(todo, setTodo) => <TodoRow todo={todo} setTodo={setTodo} />}
+</NarrowList>
+
+function TodoRow({ todo, setTodo }: { todo: Todo; setTodo: SetStore<Todo> }) {
+  return <input type="checkbox" checked={todo.done} onChange={() => setTodo((t) => { t.done = !t.done })} />
+}
+```
+
+`NarrowList` also takes a record or a `Map`, for normalized state. Those are keyed already, so there's no `getKey`. `children` gets each entry's key as a third argument.
+
+## Share it through context
+
+```tsx
+const appStore = createContextStore<AppState>()
+
+<appStore.Provider initial={…}>…</appStore.Provider>              // the Provider owns a new store
+<appStore.Provider store={state} setStore={setState}>…</appStore.Provider>  // or share one from useNewStore
+
+const state = appStore.useVal()     // re-renders when the state changes
+const setState = appStore.useSet()  // doesn't
+```
+
+Narrowed contexts only re-render their consumers when their slice changes:
+
+```tsx
+const settingsStore = createNarrowedStoreContext(appStore, (s) => s.settings)
+
+<settingsStore.Provider>…</settingsStore.Provider>  // settingsStore.useVal() / useSet() inside
+```
+
+## Why react-narrow?
+
+### What it's particularly useful for
+- Relatively deep, global-ish state that's frequently written to
+- Document editors: slide decks, whiteboards, diagrams, page builders
+- Builders: forms, surveys, workflows, product configurators
+- Large editable tables and lists: spreadsheets, Kanban boards, outliners
+- Timeline and layout editors: video, scheduling, floor plans, game levels
+
+### Where it's less useful
+- Data fetching (seriously, use react-query or something for that)
+- Anywhere outside of React (like `useState`, you can only pass down data and callbacks from the component tree)
+- Wherever extremely fine-grained rendering is needed (use a signals-based state library for that, or avoid React entirely)
+- Codebases that don't have the React Compiler enabled (a lot of the library's ergonomics lean on it)
+
+### Why use this over useState and context?
+
+- A deep update is one line, not a spread at every level, where missing one level silently drops data
+- A child gets its slice and a setter scoped to it. It can make any edit to that slice, can't touch anything else, and doesn't need to know where the slice lives
+- Value and setter come in separate contexts, so components that only write never re-render. Put `[state, setState]` in one context and every consumer re-renders on every change
+
+### Why use this over useImmer?
+
+- `useImmer` makes the top-level update easy, but a child still needs the whole state or a callback for every kind of edit (`onToggle`, `onRename`, …). Here it gets `[todo, setTodo]` and makes the edit itself
+- Context stores are built in, so you don't hand-roll a provider and a memoized value. Narrowed contexts re-render only for their slice
+- `NarrowList` gives every item a stable setter, so unchanged rows skip re-rendering (with the React Compiler, or `useCallback`). With `useImmer`, you'd thread ids and memoized callbacks through by hand to get the same result
+
+### Why use this over Zustand, Jotai or Valtio?
+
+- It's React state: it still lives in your component tree, behaves exactly as React would expect (making it safe with concurrent and compiler features), and doesn't need snapshots to be taken 
+- Updates are ordinary `useState` updates, so they batch and work with transitions. Zustand and Valtio read through `useSyncExternalStore`, so an update inside `startTransition` still blocks
+- Components take a slice and a setter as props, so they work with any store and test with plain values, instead of being wired to one global store by path
+
+
+## Narrowing to an item picked at runtime
+
+Give the narrow function a second parameter, and pass it to the Provider:
+
+```tsx
+const todoStore = createNarrowedStoreContext(appStore, (s, id: string) => s.todos.find((t) => t.id === id))
+
+<todoStore.Provider narrowArg={selectedId}>…</todoStore.Provider>
+```
+
+## Edge cases
+
+- Setter functions run as React state updaters, so like `useState` updaters they must be pure. Strict Mode calls them twice.
+- Index keys (`getKey={(_, i) => i}`) need the full array as `items`. With a filtered list, the indexes point at the wrong items.
+- Reading narrowed data that no longer exists throws. Writing to it does nothing, so late async callbacks are safe.
+- Following Mutative, plain objects, arrays, Maps and Sets can be mutated. Dates and class instances are replaced, not mutated.
+
+## Examples
+
+- [`examples/slides`](examples/slides): a slide deck editor. Dragging a shape re-renders only that shape and its slide's thumbnail.
+- [`examples/todomvc`](examples/todomvc): TodoMVC.
+
+Both use the React Compiler and no `memo`. Run one with `npm install && npm run dev -w examples/slides`.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { SetStore, Narrower } from './store.js';
+export { useNewStore, useNarrowedStore, NarrowList, createContextStore, createNarrowedStoreContext, } from './react.js';
+export type { ContextStore, StoreContext } from './react.js';

package/dist/index.js

@@ -0,0 +1 @@
+export { useNewStore, useNarrowedStore, NarrowList, createContextStore, createNarrowedStoreContext, } from './react.js';

package/dist/react.d.ts

@@ -0,0 +1,65 @@
+import { type Key, type ReactNode } from 'react';
+import type { Draft } from 'mutative';
+import { type Narrower, type SetStore } from './store.js';
+/** Like `useState`, but a function passed to the setter mutates a draft. */
+export declare function useNewStore<T extends object>(initial: T | (() => T)): [T, SetStore<T>];
+/** Narrows a store to the part `narrow` picks, returning that part and a setter that writes back into the store. */
+export declare function useNarrowedStore<T extends object, N extends object>(store: T, narrow: Narrower<T, N>, setStore: SetStore<T>): [N, SetStore<N>];
+type RenderItem<T extends object, K> = (item: T, setItem: SetStore<T>, key: K) => ReactNode;
+interface NarrowListComponent {
+    <T extends object>(props: {
+        items: T[];
+        setStore: SetStore<T[]>;
+        getKey: (item: T, index: number) => Key;
+        children: RenderItem<T, Key>;
+    }): ReactNode;
+    <K extends string, T extends object>(props: {
+        items: Record<K, T>;
+        setStore: SetStore<Record<K, T>>;
+        getKey?: undefined;
+        children: RenderItem<T, K>;
+    }): ReactNode;
+    <K extends Key, T extends object>(props: {
+        items: Map<K, T>;
+        setStore: SetStore<Map<K, T>>;
+        getKey?: undefined;
+        children: RenderItem<T, K>;
+    }): ReactNode;
+}
+/** Renders every item of an array, record or Map with its own narrowed store; only changed items re-render. */
+export declare const NarrowList: NarrowListComponent;
+/** A store shared through context: `useVal()` re-renders on changes, `useSet()` never does. */
+export interface ContextStore<T extends object> {
+    useVal(): T;
+    useSet(): SetStore<T>;
+}
+type ProviderProps<T extends object> = {
+    store: T;
+    setStore: SetStore<T>;
+    initial?: never;
+    children?: ReactNode;
+} | {
+    initial: T | (() => T);
+    store?: never;
+    setStore?: never;
+    children?: ReactNode;
+};
+export interface StoreContext<T extends object> extends ContextStore<T> {
+    Provider(props: ProviderProps<T>): ReactNode;
+}
+/** Creates a context store. `fallback` is a read-only value used when no Provider is above. */
+export declare function createContextStore<T extends object>(fallback?: T): StoreContext<T>;
+/** Creates a context store narrowed from `parent`, whose consumers only re-render when their part changes. */
+export declare function createNarrowedStoreContext<T extends object, N extends object, A = void>(parent: ContextStore<T>, narrow: ((state: T, arg: A) => N | undefined) | {
+    get: (state: T, arg: A) => N | undefined;
+    swap: (draft: Draft<T>, value: N, arg: A) => void;
+}, fallback?: N): ContextStore<N> & {
+    Provider(props: {
+        children?: ReactNode;
+    } & ([A] extends [void] ? {
+        narrowArg?: undefined;
+    } : {
+        narrowArg: A;
+    })): ReactNode;
+};
+export {};

package/dist/react.js

@@ -0,0 +1,94 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, memo, useContext, useMemo, useState, } from 'react';
+import { applyUpdate, getterOf, narrowSetter } from './store.js';
+/** Like `useState`, but a function passed to the setter mutates a draft. */
+export function useNewStore(initial) {
+    const [state, setState] = useState(initial);
+    const [set] = useState(() => ((next, mode) => setState((prev) => applyUpdate(prev, next, mode))));
+    return [state, set];
+}
+/** Narrows a store to the part `narrow` picks, returning that part and a setter that writes back into the store. */
+export function useNarrowedStore(store, narrow, setStore) {
+    const set = useMemo(() => narrowSetter(setStore, narrow), [setStore, narrow]);
+    const value = getterOf(narrow)(store);
+    if (value == null)
+        throw new Error('react-narrow: the narrowed node is missing (narrow returned null/undefined)');
+    return [value, set];
+}
+/** Renders every item of an array, record or Map with its own narrowed store; only changed items re-render. */
+export const NarrowList = memo(function NarrowList({ items, setStore, getKey, children }) {
+    const kind = Array.isArray(items) ? 'array' : items instanceof Map ? 'map' : 'record';
+    const entries = Array.isArray(items)
+        ? items.map((item, i) => [getKey(item, i), item])
+        : items instanceof Map
+            ? [...items]
+            : Object.entries(items);
+    return entries.map(([key, item]) => (_jsx(NarrowListItem, { itemKey: key, item: item, kind: kind, setStore: setStore, getKey: getKey, render: children }, key)));
+});
+const narrowToItem = (kind, key, getKey) => kind === 'array'
+    ? (items) => items.find((x, i) => getKey(x, i) === key)
+    : kind === 'map'
+        ? { get: (m) => m.get(key), swap: (d, v) => void d.set(key, v) }
+        : (r) => r[String(key)];
+const NarrowListItem = memo(function NarrowListItem(props) {
+    const { itemKey, item, kind, setStore, getKey, render } = props;
+    const setItem = useMemo(() => narrowSetter(setStore, narrowToItem(kind, itemKey, getKey)), [setStore, kind, getKey, itemKey]);
+    return render(item, setItem, itemKey);
+});
+const NONE = Symbol('no provider');
+const readOnlyDefault = (() => {
+    throw new Error('react-narrow: no store in context; the default value is read-only');
+});
+// Separate value and setter contexts, so setter-only consumers don't re-render.
+function makeContext(fallback) {
+    const ValueCtx = createContext(NONE);
+    const SetCtx = createContext(NONE);
+    const missing = () => new Error('react-narrow: no store found in context and no default was given');
+    const def = {
+        useVal() {
+            const value = useContext(ValueCtx);
+            if (value !== NONE)
+                return value;
+            if (fallback !== undefined)
+                return fallback;
+            throw missing();
+        },
+        useSet() {
+            const set = useContext(SetCtx);
+            if (set !== NONE)
+                return set;
+            if (fallback !== undefined)
+                return readOnlyDefault;
+            throw missing();
+        },
+    };
+    const Provide = (p) => (_jsx(ValueCtx, { value: p.value, children: _jsx(SetCtx, { value: p.set, children: p.children }) }));
+    return { def, Provide };
+}
+/** Creates a context store. `fallback` is a read-only value used when no Provider is above. */
+export function createContextStore(fallback) {
+    const { def, Provide } = makeContext(fallback);
+    function Owned(p) {
+        const [value, set] = useNewStore(p.initial);
+        return _jsx(Provide, { value: value, set: set, children: p.children });
+    }
+    function Provider({ store, setStore, initial, children }) {
+        if (initial !== undefined)
+            return _jsx(Owned, { initial: initial, children: children });
+        return _jsx(Provide, { value: store, set: setStore, children: children });
+    }
+    return { ...def, Provider };
+}
+/** Creates a context store narrowed from `parent`, whose consumers only re-render when their part changes. */
+export function createNarrowedStoreContext(parent, narrow, fallback) {
+    const { def, Provide } = makeContext(fallback);
+    function Provider(props) {
+        const arg = props.narrowArg;
+        const narrowed = useMemo(() => typeof narrow === 'function'
+            ? (s) => narrow(s, arg)
+            : { get: (s) => narrow.get(s, arg), swap: (d, v) => narrow.swap(d, v, arg) }, [arg]);
+        const [value, set] = useNarrowedStore(parent.useVal(), narrowed, parent.useSet());
+        return _jsx(Provide, { value: value, set: set, children: props.children });
+    }
+    return { ...def, Provider };
+}

package/dist/store.d.ts

@@ -0,0 +1,18 @@
+import { type Draft } from 'mutative';
+type Primitive = string | number | boolean | bigint | symbol | null | undefined;
+type MutateResult<R> = [R] extends [void | Primitive] ? R : 'recipe returned an object: it mutates by default. Pass "swap" as the second argument to replace the state';
+/** Mutates a draft when given a function, replaces the state when given a value or a function with `'swap'`. */
+export interface SetStore<T extends object> {
+    (next: T): void;
+    <R>(recipe: (draft: Draft<T>) => MutateResult<R>, mode?: 'mutate'): void;
+    (recipe: (current: T) => T, mode: 'swap'): void;
+}
+export declare function applyUpdate<T>(prev: T, next: unknown, mode?: 'mutate' | 'swap'): T;
+/** A narrow function, or `{ get, swap }` when the function can't be traced. */
+export type Narrower<T, N> = ((state: T) => N | undefined) | {
+    get: (state: T) => N | undefined;
+    swap: (draft: Draft<T>, value: N) => void;
+};
+export declare const getterOf: <T, N>(narrow: Narrower<T, N>) => (state: T) => N | undefined;
+export declare function narrowSetter<T extends object, N extends object>(parentSet: SetStore<T>, narrow: Narrower<T, N>): SetStore<N>;
+export {};

package/dist/store.js

@@ -0,0 +1,84 @@
+import { create } from 'mutative';
+const modeOf = (next, mode) => mode ?? (typeof next === 'function' ? 'mutate' : 'swap');
+export function applyUpdate(prev, next, mode) {
+    if (modeOf(next, mode) === 'swap')
+        return (typeof next === 'function' ? next(prev) : next);
+    return create(prev, (draft) => void next(draft));
+}
+export const getterOf = (narrow) => (typeof narrow === 'function' ? narrow : narrow.get);
+const PATH = Symbol('path');
+const untraceable = (cause) => new Error('react-narrow: could not trace narrowFn to a node inside the state (it returned a copy/computed value, ' +
+    'or used an identity comparison or Map lookup). Pass { get, swap } instead.', { cause });
+// The path of keys narrowFn reads to reach the node it returns, or null if it returns nothing.
+function pathOf(state, narrowFn) {
+    // Proxy a stand-in, not `v`: proxy invariants forbid wrapping frozen properties.
+    const track = (v, path) => {
+        if (v === null || typeof v !== 'object')
+            return v;
+        const isArray = Array.isArray(v);
+        return new Proxy(isArray ? [] : {}, {
+            get: (_, k) => {
+                if (k === PATH)
+                    return path;
+                // A write to a getter would be lost, so don't trace through one.
+                if (Reflect.getOwnPropertyDescriptor(v, k)?.get)
+                    return Reflect.get(v, k);
+                return track(Reflect.get(v, k), [...path, k]);
+            },
+            has: (_, k) => k in v,
+            ownKeys: () => Reflect.ownKeys(v),
+            getPrototypeOf: () => Object.getPrototypeOf(v),
+            getOwnPropertyDescriptor: (_, k) => {
+                // The stand-in array's own `length` is non-configurable.
+                if (isArray && k === 'length')
+                    return { value: v.length, writable: true, enumerable: false, configurable: false };
+                const d = Reflect.getOwnPropertyDescriptor(v, k);
+                return d && { ...d, configurable: true };
+            },
+        });
+    };
+    // On failure, rerun narrowFn on the real state: if it fails there too, that error is narrowFn's own bug.
+    let node;
+    try {
+        node = narrowFn(track(state, []));
+    }
+    catch (cause) {
+        narrowFn(state);
+        throw untraceable(cause);
+    }
+    if (node == null) {
+        if (narrowFn(state) == null)
+            return null;
+        throw untraceable();
+    }
+    const path = node[PATH];
+    if (!path)
+        throw untraceable();
+    return path;
+}
+const getAt = (v, path) => path.reduce((o, k) => o[k], v);
+export function narrowSetter(parentSet, narrow) {
+    const set = (next, mode) => parentSet((current) => {
+        if (typeof narrow !== 'function') {
+            const node = narrow.get(current);
+            // Deliberately silent: late async writes to deleted items are normal (React dropped its similar warning).
+            if (node == null)
+                return current;
+            const value = applyUpdate(node, next, mode);
+            return value === node ? current : create(current, (d) => void narrow.swap(d, value));
+        }
+        const path = pathOf(current, narrow);
+        if (!path)
+            return current; // see above
+        if (modeOf(next, mode) === 'mutate')
+            return create(current, (d) => void next(getAt(d, path)));
+        const node = getAt(current, path);
+        const value = typeof next === 'function' ? next(node) : next;
+        if (value === node)
+            return current;
+        if (!path.length)
+            return value;
+        return create(current, (d) => void (getAt(d, path.slice(0, -1))[path.at(-1)] = value));
+    }, 'swap');
+    return set;
+}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "react-narrow",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jaaamesey/narrow.git"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=19"
+  },
+  "dependencies": {
+    "mutative": "^2.0.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^8.0.7",
+    "@rolldown/plugin-babel": "^0.2.4",
+    "@testing-library/dom": "^10.4.2",
+    "@testing-library/react": "^16.3.3",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.2",
+    "babel-plugin-react-compiler": "^1.0.0",
+    "jsdom": "^29.1.1",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.5"
+  },
+  "workspaces": [
+    "examples/*"
+  ]
+}