@jsenv/navi 0.29.19 → 0.29.21

package/docs/AI_INSTRUCTIONS.md

@@ -33,6 +33,10 @@ consistency across the app, not from any single call site.
 - `docs/resource.md` — REST state: `resource()`, relationships, callback return
   contracts, autorerun rules. Companion files: `docs/actions.md`,
   `docs/resource_with_params.md`, `docs/resource_dependencies.md`.
+- `docs/list_refresh.md` — what a write sends back to the network and what stays
+  on screen meanwhile: stale data returned by `useAsyncData({ loading: true })`,
+  what updates from a response without any request, `rerunOn` and its defaults.
+  Read it before adding verbs to `rerunOn` or hiding a list on `loading`.
 - `docs/css_architecture.md` — how Navi's CSS layering works, and the
   supported ways to override component styles (props > CSS variables > direct
   rule overrides, in that preference order).

package/docs/actions.md

@@ -1,250 +1,117 @@
-/\*\*
-
-- # Actions System - Declarative Resource Management for Frontend Applications
--
-- This module provides a comprehensive system for managing asynchronous resources (API calls, data fetching)
-- in a declarative, signal-based architecture. It's designed for complex frontend applications that need
-- fine-grained control over loading states, caching, and resource lifecycle management.
--
-- ## Core Concepts
--
-- ### 🔧 **Action Templates**
-- Factory functions that define how to load resources. Templates are pure and reusable.
-- ```js
-
-  ```
-
-- const getUserTemplate = createActionTemplate(async ({ userId }) => {
-- const response = await fetch(`/api/users/${userId}`);
-- return response.json();
-- });
-- ```
-
-  ```
-
--
-- ### 🎯 **Action Instances**
-- Stateful objects created from templates with specific parameters. Each unique parameter set
-- gets its own cached instance (automatic memoization).
-- ```js
-
-  ```
-
-- const userAction = getUserTemplate.instantiate({ userId: 123 });
-- const status = useActionStatus(userAction); // { pending, data, error, ... }
-- ```
-
-  ```
-
--
-- ### 🔄 **Action Proxies**
-- Dynamic actions that react to signal changes, automatically reloading when parameters change.
-- ```js
-
-  ```
-
-- const userProxy = createActionProxy(getUserTemplate, {
-- userId: userIdSignal, // Signal - reactive
-- includeProfile: true // Static - not reactive
-- });
-- // Automatically reloads when userIdSignal changes
-- ```
-
-  ```
-
--
-- ## Loading States & Lifecycle
--
-- ### 📊 **State Management**
-- Each action has a well-defined state machine:
-- - `IDLE` → `LOADING` → `LOADED` (success)
-- - `IDLE` → `LOADING` → `FAILED` (error)
-- - `IDLE` → `LOADING` → `ABORTED` (cancelled)
--
-- ### ⚡ **Load Types**
-- - **`.load()`** - Load with user intent (sets `loadRequested: true`)
-- - **`.preload()`** - Background loading (sets `loadRequested: false`)
-- - **`.reload()`** - Force reload even if already loaded
-- - **`.unload()`** - Cancel loading and reset state
--
-- ### 🛡️ **Preload Protection**
-- Preloaded actions are protected from garbage collection for 5 minutes to ensure
-- they remain available for components that may load later (e.g., via dynamic imports).
--
-- ## Key Features
--
-- ### 🧠 **Intelligent Memoization**
-- - Actions with identical parameters share the same instance
-- - Uses deep equality comparison with `compareTwoJsValues`
-- - Supports `SYMBOL_IDENTITY` for fast recognition of "conceptually same" objects
-- - Memory-efficient with automatic garbage collection
--
-- ### 🔗 **Parameter Binding & Composition**
-- ```js
-
-  ```
-
-- const baseAction = getUserTemplate.instantiate({ userId: 123 });
-- const enrichedAction = baseAction.bindParams({ includeProfile: true });
-- // Result: { userId: 123, includeProfile: true }
--
-- // Supports objects, primitives, and signals
-- const dynamicAction = baseAction.bindParams(filtersSignal);
-- ```
-
-  ```
-
--
-- ### 🎮 **Concurrent Loading Control**
-- - Prevents duplicate requests for same resource
-- - Smart request deduplication and racing condition handling
-- - Coordinated loading/unloading of multiple actions via `updateActions()`
--
-- ### 🔧 **Side Effects & Cleanup**
-- ```js
-
-  ```
-
-- const actionTemplate = createActionTemplate(callback, {
-- sideEffect: (params, loadParams) => {
--     // Setup logic (analytics, subscriptions, etc.)
--     return () => {
--       // Cleanup logic - called on unload/abort
--     };
-- }
-- });
-- ```
-
-  ```
-
--
-- ## Usage Patterns
--
-- ### 🏗️ **Basic Resource Loading**
-- ```js
-
-  ```
-
-- const getUserAction = createActionTemplate(async ({ userId }) => {
-- return await api.getUser(userId);
-- });
--
-- // In component
-- const userAction = getUserAction.instantiate({ userId: 123 });
-- const { pending, data, error } = useActionStatus(userAction);
--
-- useEffect(() => {
-- userAction.load();
-- }, []);
-- ```
-
-  ```
-
--
-- ### 🔄 **Reactive Data Loading**
-- ```js
-
-  ```
-
-- const searchProxy = createActionProxy(searchTemplate, {
-- query: searchSignal,
-- filters: filtersSignal
-- });
-- // Automatically reloads when signals change
-- ```
-
-  ```
-
--
-- ### 📋 **Master-Detail Pattern**
-- ```js
-
-  ```
-
-- const usersAction = getUsersTemplate.instantiate();
-- const selectedUser = signal(null);
--
-- const userDetailsProxy = createActionProxy(getUserTemplate, {
-- userId: computed(() => selectedUser.value?.id)
-- });
-- ```
-
-  ```
-
--
-- ### 🏃 **Progressive Loading**
-- ```js
-
-  ```
-
-- // Preload on hover, load on click
-- <button
-- onMouseEnter={() => action.preload()}
-- onClick={() => action.load()}
-- >
-- Load User
-- </button>
-- ```
-
-  ```
-
--
-- ## Advanced Features
--
-- ### 🎭 **Custom Data Transformation**
-- ```js
-
-  ```
-
-- const actionTemplate = createActionTemplate(fetchUser, {
-- computedDataSignal: computed(() => {
--     const rawData = dataSignal.value;
--     return rawData ? transformUser(rawData) : null;
-- })
-- });
-- ```
-
-  ```
-
--
-- ### 🎨 **Async Rendering Support**
-- ```js
-
-  ```
-
-- const actionTemplate = createActionTemplate(fetchData, {
-- renderLoadedAsync: async () => {
--     const { UserComponent } = await import('./UserComponent.js');
--     return (user) => <UserComponent user={user} />;
-- }
-- });
-- ```
-
-  ```
-
--
-- ### 🛠️ **Debugging & Observability**
-- Built-in debug mode with detailed logging of state transitions, loading coordination,
-- and memory management. Enable with `debug = true`.
--
-- ## Integration Points
--
-- - **Signals**: Built on @preact/signals for reactive state management
-- - **Navigation**: Integrates with navigation systems for route-based loading
-- - **Components**: Use `useActionStatus()` hook for component integration
-- - **Memory Management**: Automatic cleanup with WeakMap-based private properties
--
-- ## Performance Characteristics
--
-- - **Memory Efficient**: Weak references prevent memory leaks
-- - **Request Deduplication**: Identical requests are automatically merged
-- - **Minimal Re-renders**: Signal-based updates only trigger when data actually changes
-- - **Lazy Loading**: Actions only created when needed, with intelligent memoization
--
-- This system is particularly well-suited for:
-- - SPAs with complex data fetching requirements
-- - Applications needing fine-grained loading state control
-- - Systems requiring request coordination and deduplication
-- - Progressive loading and preloading scenarios
-- - Master-detail interfaces with dynamic parameter binding
-    \*/
+# Actions
+
+An action is an async callback plus the state of its last run, held in signals:
+running or not, the error it failed with, the data it produced. Components read
+that state instead of keeping their own.
+
+```js
+import { createAction } from "@jsenv/navi";
+
+const getUser = createAction(async ({ id }, { signal }) => {
+  const response = await fetch(`/users/${id}`, { signal });
+  return response.json();
+});
+```
+
+The callback receives `(params, { reason, event, signal, isPrerun })`. `signal`
+is aborted when the run is called off — pass it to `fetch`.
+
+`resource()` creates one action per REST callback rather than having you write
+them by hand — see [resource.md](./resource.md).
+
+## Params: `bindParams`, and calling the action
+
+`createAction` gives one action for the callback; the params make instances of
+it, each with its own state:
+
+```js
+const getUser123 = getUser.bindParams({ id: 123 });
+await getUser123.run();
+```
+
+Two `bindParams` with equal params give **the same instance** (deep equality),
+which is what makes state shared between two components asking for the same
+thing, and what deduplicates their requests.
+
+An action is callable, and calling it is the short way to bind and run in one
+go:
+
+```js
+getUser({ id: 123 }); // getUser.bindParams({ id: 123 }).rerun()
+getUser(); // getUser.rerun()
+```
+
+Use it wherever a run is a **gesture** — a click handler, an event, a step in a
+flow — where the params are known at that moment and the run is the point:
+
+```js
+const deleteGame = (game) => GAME.DELETE({ id: game.id });
+```
+
+Use `bindParams` when what you need is the **instance**, not the run: to hand it
+to a component that will run it and read its state
+(`<Button action={GAME.DELETE.bindParams({ id })}>`), or to keep a handle on it.
+Note that calling the action `rerun()`s it — the run happens even if that
+instance already holds data, which is what you want from a gesture and not what
+you want from a component asking for data.
+
+Params may be signals, and then the action follows them:
+
+```js
+const userAction = getUser.bindParams({ id: userIdSignal });
+// a new params value reruns it
+```
+
+## Running: `run`, `rerun`, `prerun`, `reset`
+
+| Method     | Does                                                                     |
+| ---------- | ------------------------------------------------------------------------ |
+| `run()`    | Asks for the data. An action already running or completed has it: no-op. |
+| `rerun()`  | Runs again whatever state it is in — a refresh, an explicit "check now". |
+| `prerun()` | Same as `run()`, in the background: nothing asked for it on screen yet.  |
+| `reset()`  | Aborts what is running and puts the action back to idle, data and all.   |
+| `abort()`  | Calls off the run in flight, keeping the data it had.                    |
+
+## Reading an action
+
+```jsx
+const [user] = useAsyncData(userAction);
+```
+
+`useAsyncData` suspends until the data is there and throws on failure, leaving
+both to the nearest `<Loading>` and `<ErrorBoundary>`; pass `{ loading: true }`
+or `{ error: true }` to handle either inside the component (stale data stays
+available while a rerun is in flight). `useActionStatus(action)` gives the whole
+state at once — `{ idle, loading, completed, aborted, error, data, params }` —
+for a component that needs to look at it rather than render it.
+
+Controls take the action itself and wire the rest: `<Button action>` runs it on
+click, shows its loading state, and puts its error where the user can see it.
+That is the reason to pass an action instance rather than an arrow calling the
+callback:
+
+```jsx
+// ✓ loading, error and disabled states come from the action
+<Button action={GAME_CANDIDATES.POST.bindParams({ id: game.id, user_id })}>
+  Accept
+</Button>
+```
+
+## Reruns
+
+Actions do not stay stale on their own: a resource's `POST` reruns the
+`GET_MANY` that lists it, a `DELETE` resets the `GET` that loaded the item, and
+`dependencies`/`rerunOn` declare the rest. What re-runs after a write, and what
+stays on screen while it does, is in [list_refresh.md](./list_refresh.md) and
+[resource_dependencies.md](./resource_dependencies.md).
+
+`rerunActions(actions)` / `updateActions(actions)` drive several at once (route
+changes do exactly that).
+
+## See also
+
+- [resource.md](./resource.md) — actions created from REST callbacks, and the
+  store behind them
+- [resource_with_params.md](./resource_with_params.md) — `withParams()` and
+  isolated rerun scopes
+- [list_refresh.md](./list_refresh.md) — what a write refreshes

package/docs/list_refresh.md

@@ -0,0 +1,131 @@
+# A list while it refreshes
+
+When a write touches one item of a list, two questions decide what the user
+sees: **what goes back to the network**, and **what stays on screen meanwhile**.
+Getting either wrong turns "pause one row" into a full page reload.
+
+The short answer:
+
+- A write that returns the modified item fixes every list containing it, with
+  no request and no loading state at all.
+- `useAsyncData(action, { loading: true })` keeps returning the previous data
+  while the action re-runs — the list is never taken away unless the component
+  throws it away.
+
+## `loading: true` returns the previous value
+
+`useAsyncData` returns `[data, loading, error]`. During a re-run, `data` is the
+**previous data**, not `undefined`:
+
+| Moment                | `data`      | `loading` |
+| --------------------- | ----------- | --------- |
+| never completed yet   | `undefined` | `true`    |
+| running after success | previous    | `true`    |
+| completed             | fresh       | `false`   |
+
+So the emptiness test is `data === undefined`, never `loading`:
+
+```js
+const [items, loading] = useAsyncData(ACTION, { loading: true });
+if (items === undefined) {
+  return null; // first load: there is nothing to show yet
+}
+return <RadarList radars={items} busy={loading} />; // re-read: stay on screen
+```
+
+```js
+// ✗ blanks the page on every re-run, for a checkbox on one row
+if (loading) {
+  return null;
+}
+```
+
+Read `loading` as "what you are displaying is from before", not "there is
+nothing to display".
+
+`<List loading>` is the first-load answer, not the refresh one: it replaces the
+rows with skeletons. Pass it while stale rows exist and they disappear — same
+mistake as `loading ? null :`, one level down.
+
+## What updates without a request
+
+An action's `data` is a computation over the resource store, not a snapshot of
+its own last response. Any write that puts an item into the store recomputes
+every list holding it, while the `GET_MANY` action stays `COMPLETED` — no
+request, no loading state, no flicker.
+
+The condition is the whole hinge of the system:
+
+> **the write's callback must return the item, with its key** — `{ id, … }`.
+
+Partial props are fine (`{ id, paused: true }` merges into the stored item); the
+key is what cannot be missing. The corollary matters just as much: a callback
+that returns nothing — a `204`, or a `fetch` whose result is dropped — writes
+nothing to the store, and the change never reaches the screen. There, the only
+way back is a re-read.
+
+`DELETE` is symmetric: returning the id drops the item from the store, and every
+list containing it drops it too.
+
+## `rerunOn`, verb by verb
+
+`rerunOn` says which verbs invalidate this resource's `GET` / `GET_MANY`:
+
+```js
+const GAME_RADAR = resource("game_radar", {
+  rerunOn: { GET_MANY: ["POST", "DELETE"] },
+  …
+});
+```
+
+Defaults are `{ GET: false, GET_MANY: ["POST"] }`:
+
+| Default              | Why                                                                                                                                                                                                                                                                                 |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GET: false`         | `PUT`/`PATCH` already update the UI through the store; `DELETE` resets the `GET` rather than re-running it, so a deleted item shows nothing instead of a spinner then a 404. Give the deleted case its own UI (an "item not found" panel, a redirect) instead of `GET: ["DELETE"]`. |
+| `GET_MANY: ["POST"]` | Whether a new item belongs in this list depends on filters, pagination, sort — the backend knows, the client does not. `DELETE` is excluded because the store already removes the item from every list.                                                                             |
+
+Adding `PUT`/`PATCH` to `GET_MANY` is the usual over-correction: it costs a
+request and a `loading` pass to obtain something the response already contained.
+When a `PATCH` "doesn't show", the fix is almost always server-side — return the
+updated item — not client-side refreshing.
+
+## Decision table
+
+| What changed              | Re-read the list?                                    |
+| ------------------------- | ---------------------------------------------------- |
+| a field of one item       | no — the write's response is enough                  |
+| membership of the list    | yes (`POST`) — the backend decides who belongs       |
+| the ORDER of the list     | yes — the store stores, it does not sort (see below) |
+| nothing came back (`204`) | yes — there is nothing to put in the store           |
+
+## The store stores, it does not sort
+
+Each `*_MANY` action holds its own array of ids; its data is those ids resolved
+against the store, in that order. A `PUT_MANY` returning the collection in a new
+order updates every item, and sets the order **of the `PUT_MANY` action** — the
+`GET_MANY` list keeps the order it already had.
+
+That is the design (a store is not an index), but it has a sharp edge: a
+drag-and-drop that "works" on screen — because local state holds the order —
+comes back in the old order on the next visit. After a reorder, re-read the list
+explicitly:
+
+```js
+await REORDER_ACTION.run({ … });
+GET_MANY_ACTION.rerun();
+```
+
+## `.rerun()`, not `.run()`, to refresh
+
+`.run()` on an action that already `COMPLETED` does nothing: it is a request to
+have the data, and the data is there. Wiring a "check now" button to `.run()`
+therefore checks nothing, silently. Use `.rerun()`, which resets the action and
+runs it again.
+
+## See also
+
+- [resource.md](./resource.md) — `resource()`, relations, callback return
+  contracts
+- [resource_dependencies.md](./resource_dependencies.md) — invalidating a
+  resource from another one

package/docs/resource.md

@@ -25,10 +25,94 @@ Each callback returns the data to upsert into the store:
 | GET / POST / PUT / PATCH | the full item object, `{ id, … }` |
 | DELETE                   | the id, or `{ id }`               |
 | GET_MANY / POST_MANY / … | an array of item objects          |
+| GET_PAGE                 | `{ items, start, count }` (below) |
 
 Actions are read in components through the action system (`useAsyncData`,
 `<Button action>`, …) — see [actions.md](./actions.md).
 
+## `store.upsert()` is not how data enters the store
+
+navi writes the store. Declare the resource and its relations, return the shape
+each callback owes (tables above and below), and the write happens. A hand
+written `store.upsert()` in the path of a normal request of the resource is the
+sign that something is missing: a relation that is not declared, or a callback
+that does not return what it should.
+
+`store` is exposed for what is **not** a request of the resource, where writing
+it yourself is the point:
+
+- seeding it with data that came from elsewhere — state rendered by the server,
+  a local cache, a websocket message;
+- absorbing the parent object a relation route answered with: the relation
+  callback only writes the relation, so the parent's own fields have nowhere
+  else to land (see [When the backend answers a sub-route with the whole
+  parent](#when-the-backend-answers-a-sub-route-with-the-whole-parent)).
+
+A list that loads its rows page by page is **not** one of those cases — that is
+`GET_PAGE`, right below.
+
+## `GET_PAGE`: feeding a list that loads as it scrolls
+
+A `<List.Items>` asks for the rows it is about to draw and keeps what it gets.
+`GET_PAGE` is the resource's answer to that question — one slice at a time:
+
+```js
+const GAME = resource("game", {
+  GET: ({ id }) => fetchJson(`/games/${id}`),
+  GET_PAGE: ({ radar, start, limit }) =>
+    fetchJson(`/radars/${radar.id}/games?start=${start}&limit=${limit}`),
+  // { items: [{ id, … }, …], start: 20, count: 137 }
+});
+```
+
+```jsx
+<List.Items
+  count={radar.match_count}
+  itemsAction={GAME.GET_PAGE.bindParams({ radar })}
+  renderItem={(game) => <GameCard game={game} />}
+/>
+```
+
+The callback receives the bound params merged with the range the list asks for
+(`start`, `end`, `limit`, `before`, `after`, `around`, `count`), and a `signal`
+as second argument — aborted when the list stops wanting those rows. It returns
+a page the way a `Content-Range` does: **`{ items, start, count }`** — these
+rows, at this place, out of that many. `start` may be omitted when the list
+asked for a positive one; `count` defaults to `start + items.length` (a source
+that does not know its total). The items are upserted on their way in, so the
+list draws store items — never copies of the JSON — and a request sent from a
+row is read back on that row.
+
+A row that must follow its **own fields** through a write reads them from the
+store rather than from the object it was handed:
+
+```jsx
+const GameCard = ({ id }) => {
+  const game = GAME.useById(id); // the item as it is now
+  …
+};
+```
+
+An update replaces the item object (the store holds values, and that is what
+makes a change detectable), so the one the list is holding is the one it was
+given. Relations are not concerned: they are keyed by owner, and a row reading
+`game.candidates` reads the shared collection whatever object carries it.
+
+`GET_PAGE` is a **reader, not an action**. It keeps no value and takes no place
+in the rerun graph, which is what makes it usable per slice:
+
+- the list already holds the pages it received and glues them back together —
+  a second memory holding one of them would fight it;
+- a `POST` invalidating "the collection" would otherwise send every page ever
+  loaded back to the network at once.
+
+What it does not give is membership: an item that leaves the collection stays on
+screen until the rows are asked for again. Give the screen its own way to ask
+(a refresh gesture, a `key` on the run).
+
+It reads a collection, so it lives on the resource itself (or on a
+`withParams()` of it), not on a relation.
+
 ## Relations: pick one of the four methods
 
 A backend sub-route (`/games/:id/candidates`, `/games/:id/candidates/:userId/seen`)
@@ -258,10 +342,16 @@ The arrow works, but nothing tracks it: no per-row spinner, no error surfaced on
 the button that caused it, no deduplication of concurrent runs, no autorerun of
 the actions this mutation should invalidate. See [actions.md](./actions.md).
 
+Away from a component, where the run is a gesture and not something to render,
+an action is callable: `GAME.DELETE({ id })` is
+`GAME.DELETE.bindParams({ id }).rerun()`.
+
 ## See also
 
 - [resource_with_params.md](./resource_with_params.md) — `withParams()` and
   isolated lifecycles
 - [resource_dependencies.md](./resource_dependencies.md) — cross-resource
   autorerun
+- [list_refresh.md](./list_refresh.md) — what re-runs after a write, and what
+  stays on screen while it does
 - [actions.md](./actions.md) — action lifecycle, `bindParams`, `useAsyncData`

package/docs/scroll.md

@@ -229,7 +229,7 @@ is a trade, not a leak.
 own body) but never grows on its own. Growing is the caller's decision —
 `expandY`.
 
-Pass `keyboardTravel={false}` when the arrow keys belong to the content (a list
+Pass `travelByKeyboard={false}` when the arrow keys belong to the content (a list
 one walks through, a picker whose slides are steps): otherwise the right arrow
 changes screen mid-reading.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.19",
+  "version": "0.29.21",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {