@jsenv/navi 0.29.436 → 0.29.437

package/docs/AI_INSTRUCTIONS.md

@@ -84,8 +84,9 @@ start when unsure which export solves a problem.
   action and a command on one press. Before running an action from a component.
 - `resource.md` — `resource()` and its relations (never an `op` discriminator),
   `GET_RANGE`, a search as the same `GET_MANY`, `withParams()` scopes and
-  `dependencies`, `persist`, a function versus the verb's instance. Before
-  writing a resource, and before caching a response yourself.
+  `dependencies`, `persist` (and `keepPageOnScreen` for the page on screen), a
+  function versus the verb's instance. Before writing a resource, and before
+  caching a response yourself.
 - `data_states.md` — `data`, `loading` and `error` are three questions;
   `loading: true` never suspends; a skeleton is told whether it is loading.
   Before drawing a skeleton on `!data` or hiding content because `error` is set.

package/docs/data_states.md

@@ -79,7 +79,9 @@ action, a `bindParams` holding one) included, when the signal moves to other
 params. A row known from the previous page load counts too, when the resource
 asks for it:
 [`persist`](./resource.md#persist-the-last-answer-drawn-again-after-a-reload)
-puts a reload on the second line as well.
+puts a reload on the second line as well, and so does
+[`keepPageOnScreen`](./resource.md#keeppageonscreen-the-page-on-screen-drawn-again-by-the-next-document) for
+what the page on screen reads — a `GET_MANY` and a `GET_RANGE` included.
 
 **The emptiness test is `data === undefined`, never `loading`.** Reading
 `loading` as "there is nothing to display" blanks the screen on every refresh —

package/docs/list_refresh.md

@@ -127,7 +127,10 @@ A composition is about the **values** its params hold, not the reader instance:
 writes the same one. A verb in `rerunOn.GET_RANGE`, or `reader.invalidate()`,
 drops the compositions — they stand for an order that is gone — and
 `memoryBudget` (1000 ranks by default) trims the ranks far from any window,
-which are asked for again if the user goes back to them.
+which are asked for again if the user goes back to them. A composition read by a
+list on screen also outlives the document when the page is kept
+([`keepPageOnScreen`](./resource.md#keeppageonscreen-the-page-on-screen-drawn-again-by-the-next-document)): the ranks around the window it draws are written with
+their rows, and a reload is the same return after a longer absence.
 
 ### Who decides the re-read — and who does not
 

package/docs/network_policy.md

@@ -67,9 +67,13 @@ was asked:
   what it holds instead of falling into its error boundary. A route opening a
   user by id **or** by slug gives navi both keys to look by:
   `resource("user", { uniqueKeys: ["slug"], … })`.
-- **A completed read stays completed.** `GET_MANY` (and every other read) has
-  nowhere to answer from: the store holds items, not queries, and only the
-  action's own value knows which ids answered `/users?scope=shareable`. So a
+- **A read drawing a kept answer completes with it.** A root `GET` or
+  `GET_MANY` whose first run drew what the page kept from the previous document
+  ([`keepPageOnScreen`](./resource.md#keeppageonscreen-the-page-on-screen-drawn-again-by-the-next-document)) answers with those rows: a reload with no network reopens
+  on the page.
+- **A completed read stays completed.** Otherwise `GET_MANY` (and every other
+  read) has nowhere to answer from: the store holds items, not queries, and only
+  the action's own value knows which ids answered `/users?scope=shareable`. So a
   rerun asked of a completed read under the policy is held — the action keeps
   its state, its value and its data, exactly as a `run()` on a completed action
   would.
@@ -185,7 +189,8 @@ has nothing to decide which one says why.
   which signal, for which session: a resource declaring
   [`persist`](./resource.md#persist-the-last-answer-drawn-again-after-a-reload)
   has its kept row answer the `GET` under the policy, so a reload offline
-  reopens on it.
+  reopens on it; [`keepPageOnScreen`](./resource.md#keeppageonscreen-the-page-on-screen-drawn-again-by-the-next-document) does the same for the page
+  on screen.
 - **A queue of writes to replay** once the network is back — not navi's: what a
   replayed write means (a score entered twice? a seat taken since?) is the app's
   business.

package/docs/resource.md

@@ -34,6 +34,7 @@ Actions are read in components through the action system (`useAsyncData`,
 
 - [`store.upsert()` is not how data enters the store](#storeupsert-is-not-how-data-enters-the-store)
 - [`persist`: the last answer, drawn again after a reload](#persist-the-last-answer-drawn-again-after-a-reload)
+- [`keepPageOnScreen`: the page on screen, drawn again by the next document](#keeppageonscreen-the-page-on-screen-drawn-again-by-the-next-document)
 - [`GET_RANGE`: feeding a list that loads as it scrolls](#get_range-feeding-a-list-that-loads-as-it-scrolls)
 - [Searching the same collection](#searching-the-same-collection)
 - [Relations: pick one of the four methods](#relations-pick-one-of-the-four-methods)
@@ -129,11 +130,102 @@ What the copy is not:
 - **an answer.** The `GET` goes out every time; a screen must not read `data` as
   "the server confirmed" — that is `loading`, and the two are independent.
 - **a store on disk.** One row per params key, `GET` only: meant for a singleton
-  or a handful of rows, not a resource whose `GET` is asked for every id.
+  or a handful of rows, not a resource whose `GET` is asked for every id. What
+  the page on screen reads, lists included, is
+  [`keepPageOnScreen`](#keeppageonscreen-the-page-on-screen-drawn-again-by-the-next-document),
+  below.
 - **seeded at declaration.** The row enters the store at the first run of the
   `GET`, once the relations are declared, so its relation values are normalized
   as a real answer's are. `ME.store` read before that first run is empty.
 
+## `keepPageOnScreen`: the page on screen, drawn again by the next document
+
+A reload, a pull-to-refresh, a tab the system discarded in the background: a
+new document opens at the same address, on the page that was left, and what
+that page reads almost always answers what it answered a moment ago. `persist`
+keeps one row of one resource. A page reads several things, lists included,
+and which ones depends on the page. `keepPageOnScreen` keeps that set, one
+slot, replaced when the user moves:
+
+```js
+const pageKeptSignal = stateSignal(undefined, {
+  id: `page@${APP_VERSION}`,
+  persists: true,
+  type: "object",
+});
+// Before the routes start: the first runs are the ones that look.
+keepPageOnScreen({
+  signal: pageKeptSignal,
+  when: () => !viewAsSignal.value,
+  always: [MY_GAMES_PAGE],
+});
+```
+
+**The unit is the page, not the resource.** One resource is read by several
+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`, which the app also reads to rerun the page
+when it comes back to the foreground), and the compositions the `<List.Items>`
+on screen read. A navigation replaces the slot with the next page's reads.
+
+What is kept, for the next document's first run of the same read with the same
+params:
+
+| read                                    | kept                                                         |
+| --------------------------------------- | ------------------------------------------------------------ |
+| a route action on a resource `GET`      | the row, its relations inline                                |
+| a route action on a resource `GET_MANY` | the rows in order, written the same way                      |
+| a `<List.Items>` reading a `GET_RANGE`  | the count and the ranks around the window drawn, rows inline |
+
+The `GET` and the `GET_MANY` draw it as their provisional value: `data` set
+while `loading` is `true`, the answer replacing it. The list finds it as a
+composition it left
+([list_refresh.md](./list_refresh.md#leaving-the-screen-and-coming-back)): every
+rank stale, one request for the window. Under a network policy answering reads
+from the store, the kept answer answers the read
+([network_policy.md](./network_policy.md)).
+
+What is not kept, and why:
+
+- **a relationship read** (`.one()`, `.many()`, `.scopedOne()`,
+  `.scopedMany()`). Its answer enters the store through its owner: the parent
+  row it is nested in, or the store of the owner it is scoped to. It is not rows
+  of its own that could be written back alone.
+- **a plain `createAction`** (a summary, a count the server computes). Its value
+  is whatever the callback returns, with no store to give it a shape to write
+  and to read back. A page's code is a route action too, and it is a function.
+- **a read that is not a route action**: a search typed on the page, a popup's
+  own load.
+
+A read writes what it shows once it has answered in this document. Until then
+the slot keeps what the previous document kept for it, never what the read
+shows meanwhile: an answer handed over from other params (a list standing in
+for the next search) is not about these. The write waits for the page to settle
+and is flushed when the document is hidden, which is when the system may discard
+it. Between those moments a navigation goes through half-built pages: the route
+matched but its list not mounted, or the page left still drawn under a
+transition.
+
+**The start page.** An installed app launched after being killed opens at its
+start address, not on the page that was left. The reads made while a route of
+`always` matches stay kept once that page is left, until the next visit
+replaces them.
+
+What stays the app's, as for `persist`: **the key** (the deployed version in the
+signal's `id`), **`when`** (`false` reads nothing, writes nothing, and empties
+the signal), and **the moment**: sign-out writes `undefined` into the signal,
+whatever page it holds, and nothing is written again until a read lands. Also
+**what the reads feed beside their data**: a count the app sets from an answer
+is its own signal to keep. When a list's opening position comes from such a
+count, `defaultScrolled` follows the fresh value as long as nobody has moved the
+list ([scroll.md](./scroll.md#where-the-list-opens-and-where-it-is)).
+
+What it costs: the copy follows the store, so a `PUT` on a row rewrites it, and
+every change in the stores the page reads serializes the page's reads again.
+Only the write to the signal is coalesced. A list's window with its rows inline
+is tens of kilobytes.
+
 ## `GET_RANGE`: 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.

package/docs/scroll.md

@@ -121,7 +121,9 @@ say so with `"document"` or the element itself.
 by MEASURING it: it lands where it was even if rows were inserted before it,
 whatever the screen it was saved on. "Reopen a thread where I left it" is
 already provided; keep the position whole, its `visibleCount` sizes the first
-paint. A list with an `id` also **comes back where it was** when its screen is
+paint. A `defaultScrolled` that changes before anyone has moved the list is
+followed — a place read from an answer that refreshes (yesterday's "today", then
+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, 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. A list scrolling the document that

package/package.json

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