@jsenv/navi 0.29.156 → 0.29.158

package/docs/resource.md

@@ -119,6 +119,64 @@ screen until the rows are asked for again. Give the screen its own way to ask
 It reads a collection, so it lives on the resource itself (or on a
 `withParams()` of it), not on a relation.
 
+## Searching the same collection
+
+A screen showing a collection asks a second question about it soon enough: the
+list draws a page, a search box goes looking in the whole base for what the page
+does not hold. Same entity, same ids — so it is the same `GET_MANY`, with one
+more param:
+
+```js
+const USER = resource("user", {
+  GET_MANY: ({ scope, search }, { signal }) =>
+    fetchJson(`/users?${new URLSearchParams({ scope, search })}`, { signal }),
+});
+
+const pageAction = USER.GET_MANY.bindParams({ scope: "seatable" });
+const searchAction = USER.GET_MANY.bindParams({
+  scope: "seatable",
+  search: searchSignal,
+});
+```
+
+Not a resource of its own, and not a `createAction` sitting beside the resource.
+Those answer with **detached copies**: the user a search found is a different
+object from the same user everywhere else on screen — it does not follow an
+update, and a mutation writes to the one it is not. The resource's own
+`GET_MANY` upserts what comes back like any other read, so one object per user
+answers both questions.
+
+**Two `GET_MANY` on one resource do not compete.** Each bound instance keeps its
+own array of ids and resolves it against the shared store, so answering the
+search leaves the page's list as it was — clear the search box and every row it
+had is still there. ["A `*_MANY` callback replaces the collection
+wholesale"](#when-the-backend-answers-a-sub-route-with-the-whole-parent), below,
+is about the rows the store keeps for one owner — not about what some other
+action reading the same resource is showing.
+
+It is `bindParams`, not `withParams`: a `withParams()` carves an autorerun scope
+(a POST at the root does not reach into it), and a word someone typed is not a
+scope — the search must refresh after a write like the list does
+([resource_with_params.md](./resource_with_params.md)).
+
+The lifecycle a search wants comes with being an action: `loading` while the
+word is in flight, the run before it aborted through its `signal`, typing
+debounced by the effect driving it —
+`actionRunEffect(searchAction, () => …, { debounce: 300 })` where the app owns
+the request, a `stateSignal` when the word is in the address. A word already
+asked is answered by the instance that asked it, with no second request
+([actions.md](./actions.md#reading-an-action)).
+
+What stays the app's is what to KEEP of a search once the word changes — the
+rows someone picked out of it and expects to still see under the next word.
+Keep their **ids**, not the objects: an object is a snapshot, and it stops
+following its row the moment anything writes to it. `RESOURCE.useAllByIds(ids)`
+reads those rows as they are now — a kept id turned back into something that
+stays fresh, and the ids the store no longer holds simply drop out.
+`RESOURCE.useById(id)` is the singular, `RESOURCE.useArray()` the whole store;
+all three subscribe the render that calls them, and none is a hook (a `.map()`
+over them is fine).
+
 ## Relations: pick one of the four methods
 
 A backend sub-route (`/games/:id/candidates`, `/games/:id/candidates/:userId/seen`)
@@ -282,7 +340,9 @@ This is the common REST shape, and it is the reason `op` dispatch feels
 attractive: a full-parent response absorbs into a parent `PATCH` with no
 thinking. Model the relation anyway and absorb the response in the callback —
 `resource()` gives a plural callback for exactly this: **any `*_MANY` callback
-replaces the collection wholesale**.
+replaces the collection wholesale** — the rows the store keeps for that owner,
+not what some other action reading the same resource is showing (see
+[Searching the same collection](#searching-the-same-collection)).
 
 ```js
 const GAME_CANDIDATES = GAME.scopedMany("candidates", {
@@ -340,33 +400,53 @@ graph: what used to be refreshed by the parent's own response is now refreshed
 only by these rules. When a parent field genuinely depends on a child mutation,
 say so with `dependencies` rather than relying on a rerun that will not happen.
 
-## Binding params instead of wrapping in an arrow
+## A function calling the verb, or the instance
 
-Every action exposes `bindParams()`, which returns an action instance with its
-own state. Pass that instance to a component:
+Both forms are real, and what separates them is narrower than it looks:
 
 ```jsx
-// ✓ loading, error and disabled states come for free
+// a function that calls the verb — the nominal form
+<Button action={() => GAME_CANDIDATES.POST({ id: game.id, user_id })}>
+  Accept
+</Button>
+
+// the instance, bound to its params
 <Button action={GAME_CANDIDATES.POST.bindParams({ id: game.id, user_id })}>
   Accept
 </Button>
 ```
 
+The function gives up almost nothing. Either way the button is busy while the
+write runs, shows the error if it fails and goes back to what it held; either way
+what runs inside is the same resource run, so the store is updated and the
+actions this mutation invalidates rerun the same. The failure travels too — the
+call fails, so the action around it fails
+([error_handling.md](./error_handling.md#what-a-failing-action-does)).
+
+What `bindParams` adds, and it adds only this, is **identity**: everyone binding
+the same params holds one instance, so a run started in one place is visible from
+another. Reach for it when something else on screen has to see this very run — a
+user row in a side explorer going loading while the main page renames that user,
+two affordances for the same delete that must both go busy at once. Nothing else
+in the stack answers that question: the store holds the data, not who is
+currently writing it.
+
+Where it does not pay, and most call sites are here: one affordance, in one
+place, that nobody else watches. A `bindParams({ id })` written per row builds an
+identity nothing reads, and a plain function says the gesture more directly.
+
+What genuinely loses what a resource gives is neither of those two, but a
+callback that goes around the verb:
+
 ```jsx
-// ✗ an inline arrow throws away the per-params action state
+// ✗ no resource run at all: nothing updates the store, nothing is invalidated
 <Button
-  action={async () => {
-    await acceptCandidate(game.id, user_id);
-  }}
+  action={() => fetch(`/games/${game.id}/candidates`, { method: "POST" })}
 >
   Accept
 </Button>
 ```
 
-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()`.

package/docs/route_transitions.md

@@ -60,7 +60,11 @@ Two recommendations that matter more than the individual choices:
 - **Keep reciprocity.** The way back being the same movement reversed is what
   makes the map hold together; it is the default, and breaking it (a relation
   written for the exact way travelled wins over being the reverse of another)
-  should answer a real asymmetry in the app, not a styling whim.
+  should answer a real asymmetry in the app, not a styling whim. Write the way
+  back only to say something DIFFERENT — another movement, or `"none"`. Written
+  with the same one, both crossings find their own relation and both play
+  forward, and the pair can never say "back" again, the back button included;
+  navi warns when it sees that pair defined.
 
 ## A default transition — when
 
@@ -103,7 +107,7 @@ and no other**:
 <Link
   route={GAME_ROUTE}
   routeParams={{ id }}
-  transition={{ direction: "back" }}
+  routeTransition={{ direction: "back" }}
 >
   {badge.gameName}
 </Link>

package/docs/testid.md

@@ -94,10 +94,28 @@ found by nothing, while the host is what the user focuses and what
 </div>
 ```
 
-Which role that host answers to is the control's own: a picker's host is an
-`<input>` (`textbox`), a button's is a `<button>`. A picker trigger is not
-`getByRole("button")`, whatever it is drawn like — target its name, or give it
-a `data-testid`.
+Which role that host answers to is what the control really is, not what it is
+drawn like: a button's host is a `<button>`, and a picker's host is an
+`<input>` — a `textbox`, because it holds text the user chose.
+
+A picker that picks nothing is the exception, and answers to `button`: its
+popup is a question (`type="confirm"`) or something to read
+(`mode="callout"`), so it is a door, and a door is pressed. Its name is the
+label it draws — the `ui` you gave it, or its placeholder — unless you name it
+yourself:
+
+```jsx
+<Picker type="confirm" ui="Delete" action={deleteFile} />
+<Picker mode="callout" aria-label="Aide" ui={<Icon>…</Icon>}>…</Picker>
+```
+
+```js
+await page.getByRole("button", { name: "Delete" }).click();
+await page.getByRole("button", { name: "Aide" }).click();
+```
+
+A trigger drawn as an icon draws no words, so `aria-label` is the only thing
+that can name it — for the test and for a screen reader alike.
 
 When the wrapper IS what the test wants — a whole field with its label and its
 error message, a section, a row — put the testid on the surrounding component

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.156",
+  "version": "0.29.158",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {
@@ -29,7 +29,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@jsenv/dom": "0.17.36",
+    "@jsenv/dom": "0.17.37",
     "@jsenv/humanize": "1.7.8",
     "@jsenv/validity": "0.4.3"
   },