@jsenv/navi 0.29.488 → 0.29.490

package/docs/resource.md

@@ -66,6 +66,25 @@ it yourself is the point:
   (see [When the backend answers a sub-route with the whole
   parent](#when-the-backend-answers-a-sub-route-with-the-whole-parent)).
 
+A pushed message is an answer — JSON, every object in it new — and enters
+through `store.upsertAnswer(row)`, which compares it in depth to the row held:
+the readers of a row that did not move stay still. `store.upsert()` compares
+each field by reference, so a pushed row equal to the one held re-renders its
+readers as soon as it carries a nested object. The store is not a list: a row
+it did not hold joins no `GET_MANY` and no `GET_RANGE` composition. Read again
+what it belongs to, as a `POST` of the resource would:
+
+```js
+socket.addEventListener("message", (message) => {
+  const run = JSON.parse(message.data);
+  const known = RUN.store.select(run.id);
+  RUN.store.upsertAnswer(run);
+  if (!known) {
+    RUN.GET_RANGE.invalidate(); // or RUN.GET_MANY.rerun()
+  }
+});
+```
+
 A list that loads its rows a slice at a time is **not** one of those cases —
 that is `GET_RANGE`, below.
 
@@ -129,6 +148,14 @@ What stays the app's, because only the app knows:
   the drawn row for the whole request. It waits on `data` being set — the
   emptiness test of data_states.md — and the refresh is shown as usual.
 
+**An identity change is a fresh document.** Sign-out, switching to another
+account, taking an invited account, leaving a "view as": write `undefined` into
+the kept signals (`persist`, `keepPageOnScreen`), then
+`window.location.replace(…)`. navi's `reload()` reruns the route actions only;
+the stores, the component reads and the lists' compositions stay, and they are
+the previous person's. A list of things to reset one by one is a list nobody
+can tell is complete.
+
 What the copy is not:
 
 - **an answer.** The `GET` goes out every time; a screen must not read `data` as
@@ -170,11 +197,17 @@ keepPageOnScreen({
 screens: `GAME.GET` for any game opened, `USER.GET_MANY` for a tab and for
 every search. Kept per resource, that is every game ever opened. The page's
 reads are what navi already runs for it: the route actions asking something for
-the page (`activeRouteActionsSignal`; `activeRouteReadsSignal` is the same set
-without the page's code, what the app reruns when it comes back to the
-foreground), and the compositions the `<List.Items>`
+the page (`activeRouteActionsSignal`), and the compositions the `<List.Items>`
 on screen read. A navigation replaces the slot with the next page's reads.
 
+The same reads are what the app reads again when it comes back to the
+foreground: `rerunActions(activeRouteReadsSignal.peek())`. That set is the
+route actions without the page's code, plus the `GET_RANGE` readers of the
+lists on screen; a reader handed to `rerunActions` revalidates — its lists ask
+again for the window they draw, their rows kept, and every composition stays
+(`reader.revalidate()`, where `invalidate()` would send the lists off screen
+back to skeletons).
+
 What is kept, for the next document's first run of the same read with the same
 params:
 
@@ -481,6 +514,37 @@ for its verb. A dependent names it like a callback —
 `{ resource: ORDER, on: ["cancel"] }` reruns after a cancel, not after an
 archive — and a resource listed bare counts it with every other write.
 
+A scoped relation takes `writes` as well. A sub-collection with several
+writes — seat a player, move one, take one out — is a `.scopedMany()` naming
+each of them, never `op`s dispatched inside the owner's `PATCH`. A
+`.scopedMany()` write may also take a plural verb, for a route answering the
+whole owner:
+
+```js
+const GAME_SEATS = GAME.scopedMany("participants", {
+  idKey: "slot",
+  writes: {
+    add: {
+      verb: "POST_MANY",
+      callback: async ({ id, ...body }) => {
+        const game = await post(`/games/${id}/participants`, body);
+        return [game.id, game.participants];
+      },
+    },
+    move: { verb: "PATCH_MANY", callback: moveParticipant },
+    remove: { verb: "DELETE", callback: removeParticipant },
+  },
+});
+const ALERT = resource("alert", {
+  dependencies: [{ resource: GAME_SEATS, on: ["add", "remove"] }],
+  GET,
+});
+```
+
+Each answers in the relation's shape for its verb — `[ownerId, items]` for a
+plural one, which replaces the collection and reruns nothing on the owner
+([Relations and autorerun](#relations-and-autorerun)).
+
 ## Callback return contracts
 
 These are not guessable — each relationship method has its own shape, written
@@ -492,9 +556,15 @@ out with an example in its JSDoc:
   `GET`/`POST` that embeds the child inline works too.
 - **`.many(propertyName, CHILD, callbacks)`** — `GET_MANY` returns the
   **parent** with the array nested inside; `GET`/`POST`/`PUT`/`PATCH` the
-  **child**, upserted into the child store but not joining the parent's array,
-  which only a `GET_MANY` rewrites; `DELETE` `[parentId, childId]`,
-  `DELETE_MANY` `[parentId, [childId, …]]`.
+  **child**, upserted into the child store but not joining the parent's array;
+  `POST` `[parentId, child]` upserts the child **and** appends it to the
+  parent's array (putting someone in a group); `POST_MANY`/`PUT_MANY`/`PATCH_MANY`
+  an array of children, upserted only, or `[parentId, [child, …]]`, which also
+  replaces the parent's array; `DELETE` `[parentId, childId]`, `DELETE_MANY`
+  `[parentId, [childId, …]]`. A `POST` never renames, so its array is always the
+  join; a child is never an array, so a plural answer is never ambiguous. A
+  parent the store does not hold yet is left alone: its array comes with its
+  next read.
 - **`.scopedOne(propertyName, callbacks)`** — every callback returns
   `[ownerId, props | null]`; the property is `null` until one does.
 - **`.scopedMany(propertyName, { idKey, … })`** — `[ownerId, props]`; `PUT` (an
@@ -540,10 +610,12 @@ const GAME_CANDIDATES = GAME.scopedMany("candidates", {
 ```
 
 For `.many()`, the equivalent is its `GET_MANY` callback, which already takes
-the parent object with the array nested inside — return the response untouched.
-Deletion is the exception: `DELETE`/`DELETE_MANY` drop by id rather than
-replace, so return `[ownerId, deletedId]` from the id you already have in the
-params, and ignore the full parent the backend sent back.
+the parent object with the array nested inside — return the response untouched
+— and, for a write, a plural callback returning `[parentId, children]` (a
+favourite toggled, answered with the whole list of favourites). Deletion is the
+exception: `DELETE`/`DELETE_MANY` drop by id rather than replace, so return
+`[ownerId, deletedId]` from the id you already have in the params, and ignore
+the full parent the backend sent back.
 
 The parent's own fields in such a response (a `status`, a `score`) are applied
 only where the callback returns the parent: `.one()`'s `GET`/`PUT` and
@@ -557,17 +629,21 @@ explicitly.
 Relationship mutations do **not** invalidate their parent by default. The rules:
 
 - `.scopedMany` child **POST** reruns the owner's singular `GET`, whether it
-  goes through the child or through a `withParams()` scope of it — but only when
-  the last GET response actually embedded that property. GET_MANY on the parent
-  is never rerun by a child POST (a list of parents is not stale because one of
-  them gained a child).
-- `.scopedMany` child **PUT / PATCH / DELETE** rerun nothing: the callback result
-  already carries the updated child.
+  goes through the child, a `withParams()` scope of it or a write named with
+  that verb — but only when the last GET response actually embedded that
+  property. GET_MANY on the parent is never rerun by a child POST (a list of
+  parents is not stale because one of them gained a child).
+- `.scopedMany` child **PUT / PATCH / DELETE**, and every **`*_MANY`** write
+  (`POST_MANY` included), rerun nothing on the owner: the callback result
+  already carries the updated child, or the whole collection. Its own reads
+  still follow its `rerunOn` (`POST` covers `POST_MANY` there).
 - `.scopedOne` mutations rerun nothing, ever — the result is the new value.
 - `.one` / `.many` children live in an independent store; mutating them never
-  reruns the parent. Declare it with
-  [`dependencies`](#dependencies-rerun-after-another-resource-writes) if you
-  need it.
+  reruns the parent. A `.many()` write changes the parent's array only through
+  the answers naming it (`[parentId, …]`, see
+  [Callback return contracts](#callback-return-contracts)); otherwise declare
+  it with [`dependencies`](#dependencies-rerun-after-another-resource-writes)
+  if you need it.
 - Within a relationship resource, the usual defaults still apply: its own
   `GET_MANY` reruns after its own `POST`. A `.one`/`.many` `GET` is reset (not
   rerun) by its own `DELETE`, as a root `GET` is; a scoped `GET` is not reset —
@@ -645,7 +721,7 @@ const ROLE_WITH_OWNERS = ROLE.withParams(
 
 Any write on a listed resource (`POST`, `PUT`, `PATCH`, `DELETE`) reruns the
 completed `GET` and `GET_MANY` of the resource that declared it, and invalidates
-its `GET_RANGE` readers when the verb is in its `rerunOn.GET_RANGE`. A
+its `GET_RANGE` readers: its own `rerunOn` is about its own writes. A
 dependency is a facade: `DATABASE` and `DATABASE.withParams(…)` are two of them,
 and only writes on the one listed count. Nothing goes the other way, and nothing
 is inferred — a relation that really is a sub-route of the parent is modelled
@@ -674,6 +750,31 @@ write, or that the resource does not define, throws at declaration — a
 dependency that never fires leaves a count on its old value with nothing to say
 so.
 
+A resource can only list one declared before it: a `const` further down the
+file is not there yet. When two resources each change what the other shows —
+the members of a group are users, and starring a user writes into a group — or
+when a file's order would decide it, give `dependencies` as a function:
+
+```js
+const USER = resource("user", {
+  dependencies: () => [
+    { resource: PLAYER_GROUP, on: ["addMember", "removeMember"] },
+  ],
+  GET,
+});
+const PLAYER_GROUP = resource("player_group", {
+  dependencies: [USER],
+  GET,
+  writes: { addMember, removeMember },
+});
+```
+
+It is called once, before the first request of any resource leaves — every
+module has been evaluated by then — and what it returns is checked as a list
+written in place is; what fails throws into that first run. A cycle is fine: a
+rerun is one hop, and it reruns reads only. `createAction`'s `dependencies` take
+the same function form.
+
 ## A function calling the verb, or the instance
 
 Both forms are real, and what separates them is narrower than it looks:

package/docs/safe_area.md

@@ -125,13 +125,16 @@ Beware of making that container a scroller by accident — see
 
 An app whose document scrolls still has screens that must fit the screen: a
 head that stays put over a part that scrolls, a wizard whose step fills what is
-left. The height of the free band is the visual viewport less both insets:
+left. The height of the free band is the visual viewport less both insets, less
+the strips that stick under a bar in the flow:
 
 ```css
 .wizard {
   height: calc(
     var(--navi-vvh) - var(--navi-safe-area-inset-top) -
-      var(--navi-safe-area-inset-bottom)
+      var(--navi-safe-area-inset-bottom) -
+      var(--navi-transition-cover-top, 0px) -
+      var(--navi-transition-cover-bottom, 0px)
   );
 }
 ```
@@ -143,6 +146,13 @@ the app's own bands and an overlaying keyboard (see
 slot is how a `FixedBar` writes what it takes, and reading it for layout misses
 the notch on an edge with no bar, the band of a capped app, and the keyboard.
 
+The covers are the strips of [the next section](#a-strip-under-a-bar): an
+offline line above the page pushes it down by its height, and a page as tall as
+the band would end that much under the bottom bar. `useTransitionCover`
+publishes the tallest strip on each edge, in the frame the strip changes, and
+removes it when the strip goes; the `0px` is for an app that has none, where the
+variable does not exist.
+
 ### A strip under a bar
 
 A strip that stays under the top bar — a status banner, an "offline" line — is
@@ -162,7 +172,8 @@ useTransitionCover(bannerRef);
 ```
 
 `useTransitionCover` publishes the strip's height, so the pictures of a route
-movement are cut under it rather than sliding over it. An anchor's
+movement are cut under it rather than sliding over it, and a page fitting the
+free band leaves room for it ([above](#a-page-that-fits-the-free-band)). An anchor's
 `scroll-margin` adds only what `:root`'s `scroll-padding` does not hold already
 — the strip's own height, a few pixels of air — never the bar or the band.
 

package/docs/scroll.md

@@ -128,7 +128,11 @@ followed — a place read from an answer that refreshes (yesterday's "today", th
 today's) — and it is compared by value, so it can be computed at every render. A list with an `id` also **comes back where it was** when its screen is
 left and come back to, or the page reloaded, the way the page does (its `id`
 must name one list of the app, see [below](#a-list-that-comes-back-one-id-one-list));
-**`scrollResetOnNavigation`** opts out. What it draws there before its source
+**`scrollResetOnNavigation`** opts out. A push to its screen is an arrival and
+forgets it, even when the address names the item one was reading: a link that is
+a return by meaning says `asReturn`, and the list comes back where that address
+was left (see
+[navigation.md](./navigation.md#where-a-navigation-lands-the-scroll)). What it draws there before its source
 answers is another matter
 ([What a run knows when it opens](#what-a-run-knows-when-it-opens)). A list scrolling the document that
 opens on an item places the document itself: the offset the page kept for its url

package/docs/testid.md

@@ -154,10 +154,13 @@ error message, a section, a row — put the testid on the surrounding component
 built on `Box` forwards it to its own element.
 
 A selectable `List.Item` is a control too, and the rule holds there: its host is
-the real checkbox or radio the row selects with, an input navi draws invisible
-and lays under the row's content. A `data-testid` on the item names that input —
-what `toBeChecked()` reads, not what the eye sees. A test that presses the row,
-or waits for it to show, targets what the row draws: a testid on its content.
+the real checkbox or radio the row selects with, an input navi draws invisible,
+as big as the row, under the row's content — content that lets the pointer
+through to it (`selectableArea="all"`, the default). A `data-testid` on the item
+names that input: it is what a press on the row reaches and what `toBeChecked()`
+reads. A test that presses the row, or waits for it, targets the item's testid.
+A testid on the content is for reading what the row says: Playwright refuses a
+click on it, since the input is what the pointer meets there.
 
 What navi builds itself is named through props. A `data-testid` on a `<Picker>`
 names the trigger; `popupTestId` names the popup it builds (the callout, under

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.488",
+  "version": "0.29.490",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {
@@ -34,8 +34,8 @@
     "preact": "^11.0.0-rc.2"
   },
   "dependencies": {
-    "@jsenv/dom": "0.17.96",
-    "@jsenv/humanize": "1.8.10",
+    "@jsenv/dom": "0.17.98",
+    "@jsenv/humanize": "1.8.11",
     "@jsenv/validity": "0.4.7"
   },
   "devDependencies": {