@jsenv/navi 0.29.20 → 0.29.21

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/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,6 +342,10 @@ 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

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.20",
+  "version": "0.29.21",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {