@jsenv/navi 0.29.156 → 0.29.157

package/docs/AI_INSTRUCTIONS.md

@@ -65,8 +65,10 @@ consistency across the app, not from any single call site.
   routing, actions, layout (`Box`), typography, icons, forms/validation,
   `Table`, dialogs, popovers.
 - `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`.
+  contracts, autorerun rules, and the second question a screen asks over one
+  collection (searching it is that collection's own `GET_MANY`). 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,
@@ -342,7 +344,10 @@ consistency across the app, not from any single call site.
   sub-resource (`/games/:id/candidates`) as an `op`/`type` discriminator inside
   one verb's callback. Read `docs/resource.md` before writing a resource — the
   callback return contracts differ per relationship method and are not
-  guessable.
+  guessable. Searching a collection is that collection's `GET_MANY` with one
+  more param, never a resource or an action of its own: two `GET_MANY` on one
+  resource do not compete (each holds its own ids, the store is shared), and
+  rows a search returns are then the same objects as everywhere else.
 - **`Box`** is the layout primitive (Flexbox wrapper: `flex`, `flex="y"` for
   column, `grid`, `alignX`/`alignY`). Prefer it over raw CSS for layout inside
   Navi apps.

package/docs/actions.md

@@ -63,6 +63,28 @@ const userAction = getUser.bindParams({ id: userIdSignal });
 // a new params value reruns it
 ```
 
+`{ debounce }` puts a delay between the signal and the instance, for params that
+move faster than a request should — a search box, a wheel, a slider:
+
+```js
+const searchAction = USER.GET_MANY.bindParams(questionSignal, {
+  debounce: 300,
+});
+const [found, searching] = useAsyncData(searchAction, {
+  run: true,
+  loading: true,
+});
+```
+
+There is no effect here and nothing to own: the delay lives in the binding, and
+two call sites passing the same signal and the same delay get the same instance,
+so the four components of one screen reading the same question ask it once. That
+is the shape to reach for whenever the screen owns its params signal.
+`actionRunEffect` is the other one, and what it adds is the run: use it when the request must go out whether or not something
+is drawing it. During the delay the instance is still the previous one, holding
+the previous answer — `loading` is what says a newer one is coming, don't
+compare params by hand to find out.
+
 ## Running: `run`, `rerun`, `prerun`, `reset`
 
 | Method     | Does                                                                     |

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", {

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