@jsenv/navi 0.29.155 → 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

@@ -78,6 +78,45 @@ than to the box around it (`id`, `name`, `type`, `value`, `tabIndex`,
 so a `data-test-id` or a `data-qa` of your own would name the wrapper, which is
 the second reason to keep the standard spelling.
 
+`aria-label` and `aria-labelledby` take the same road, and for the reason the
+section above gives: the name has to be where the role is. The root box has no
+role — it is a wrapper — so a name left on it would be announced by nothing and
+found by nothing, while the host is what the user focuses and what
+`getByRole(role, { name })` and `getByLabel()` read.
+
+```jsx
+<Picker variant="icon" aria-label="Aide" ui={<Icon>…</Icon>} />
+```
+
+```html
+<div class="navi_picker" navi-control="picker" aria-expanded="false">
+  <input navi-control-host="picker" aria-label="Aide" readonly />
+</div>
+```
+
+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
 (`<Field data-testid="email-field">`, `<Box data-testid="cart-row">`); anything
@@ -97,7 +136,32 @@ Most tests do not need it — a testid on what the popup holds (`<Box
 data-testid="place-pick">` among the children) names the screen, not the frame,
 and is the better name for a test that reads or clicks the content. Reach for
 `popupTestId` when the frame IS what the test looks at: a screenshot of the
-popup's surface, its position, its size, its backdrop.
+popup's surface, its position, its size, its backdrop. It names the popup in
+every mode, including `mode="callout"`, where the frame is a callout rather
+than a sheet.
+
+## A callout is a role first
+
+A callout — a control's `readOnlyMessage` or failing constraint, a
+`mode="callout"` picker, a direct `openCallout()` — is drawn by navi from end to
+end: the application supplies the sentence and nothing else, so there is often
+nothing of its own to name. It carries a role for that, and the role is the
+contract: `alert` when it says something went wrong (`warning`, `error`),
+`status` otherwise (`info`, `success`, or no status at all).
+
+```js
+await page.getByRole("button", { name: "Publier" }).click();
+await expect(page.getByRole("alert")).toHaveText("Il manque le lieu");
+```
+
+That is not a testing convenience: a message appearing without the user asking
+for it is what a live region is for, and the role is what makes a screen reader
+read it out. A test targeting it asserts that.
+
+When the role is not enough — two callouts up at once, a screenshot of one
+particular surface — `openCallout` takes a `testId`, and a picker's
+`popupTestId` covers the one it opens. Waiting on `.navi_callout` is the thing
+to replace: it is a navi class like any other.
 
 `<ControlSwap.Side>` answers the same situation the other way: the cap at the
 end of the row is drawn by navi, and every prop the side does not use for

package/package.json

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