@jsenv/navi 0.29.449 → 0.29.450

package/docs/AI_INSTRUCTIONS.md

@@ -92,7 +92,8 @@ start when unsure which export solves a problem.
   `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.
 - `list_refresh.md` — what a write sends back and what stays on screen meanwhile;
-  `rerunOn` and its defaults; coming back to a list. Before adding verbs to
+  `rerunOn` and its defaults; coming back to a list (Back keeps its
+  composition, a reload only under `keepPageOnScreen`). Before adding verbs to
   `rerunOn` or remounting a list to refresh it.
 - `list_action.md` — where the `action` lives decides who waits; a row whose
   button works is `readOnly`, not `loading`; `parallelGuard`. Before
@@ -187,13 +188,14 @@ start when unsure which export solves a problem.
   `scroller`, where a list opens (a position handed back whole, `visibleCount`
   included), a list that comes back (its `id` names one list of the app), a
   popup that scrolls, many rows (`<List.Items>`, the render window and its first
-  picture, skeletons at the size of their item, `itemSize`, `findText`, how far
+  picture, what a run knows when it opens — `count`, a composition kept, Back
+  versus a reload —, skeletons at the size of their item, `itemSize`, `findText`, how far
   ahead its images load and `loading` before `src`), many
   sections (`<Box mount="after-paint">` and what it leaves out of reach), hover
   while scrolling. Before writing CSS to make something scroll, before
   rendering a collection as `<List.Item>` children, before writing a
-  `renderSkeleton`, before putting images in a run, and before deferring part
-  of a page.
+  `renderSkeleton`, before deciding whether to give a run its `count`, before
+  putting images in a run, and before deferring part of a page.
 - `z_index.md` — DOM order first; a `z-index` without `isolation: isolate`
   competes with the page; navi's bands. Before writing a `z-index`.
 - `typography.md` — text is a component; `maxLines` is the one truncation; one

package/docs/list_refresh.md

@@ -127,10 +127,16 @@ 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. 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.
+which are asked for again if the user goes back to them.
+
+A composition lives as long as the document. **Back keeps it; a reload keeps it
+only under `keepPageOnScreen`.** Coming back within the same document finds it
+on its own. A reload, a link opened in another tab, a tab the system discarded
+open a new document, where the list gets back its position (kept under its
+`id`) and nothing to draw there: skeletons, and a first load. A page kept with
+[`keepPageOnScreen`](./resource.md#keeppageonscreen-the-page-on-screen-drawn-again-by-the-next-document)
+writes the ranks around the window each list on screen draws, with their rows,
+and a reload is then the same return after a longer absence.
 
 ### Who decides the re-read — and who does not
 

package/docs/scroll.md

@@ -124,9 +124,11 @@ already provided; keep the position whole, its `visibleCount` sizes the first
 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
+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
+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 a row places the document itself: the offset the page kept for its url
 is not put back over it — the rows held off screen are fillers of an estimated
 height, and the same pixels now fall on other rows.
@@ -199,7 +201,8 @@ whole list. `<List.Items count>` says "I know how many rows are coming": the
 rows not held yet are skeletons in their own place, at their own size (see
 [What the list knows, and what it guesses](#what-the-list-knows-and-what-it-guesses)),
 asked for as they enter the render window — a list that knows its count has no
-use for the first one.
+use for the first one. A run that does not know it learns it from its first
+answer ([What a run knows when it opens](#what-a-run-knows-when-it-opens)).
 
 Reference: `src/control/list/list.jsx` (JSDoc on `List` and `List.Items`).
 
@@ -352,6 +355,35 @@ keeps the items it does not draw (`--navi-select` reaches them by id), and a
 group keeps the keys of named controls that are not there
 ([control_object.md](./control_object.md#a-control-that-is-not-there)).
 
+### What a run knows when it opens
+
+A run reading a source (`itemsAction`) asks for what its window misses. What it
+can draw before the first answer, and how many asks it takes to stand where the
+list opens, follow from what it knows when it mounts:
+
+| When it mounts, the run knows                                     | Before the first answer                                                                | It asks for                                                                                     |
+| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| nothing                                                           | skeletons where the list opens, the scrollbar a guess (up to there and a page past it) | the window, naming the item it opens on — and again if the answer ends the collection inside it |
+| how many items there are (`count`)                                | skeletons where the list opens, the scrollbar right                                    | the window                                                                                      |
+| the composition it left (Back; a reload under `keepPageOnScreen`) | the rows from before, `refreshing`                                                     | the window, read again                                                                          |
+
+So `count` is worth giving when the app already has it: a total shown
+elsewhere, a profile saying how many games there are. It is not worth a request
+of its own, since the first answer gives it anyway. Without it, a list opening
+near the end of its collection asks twice: the first answer is the one that
+says where the end is.
+
+A reload is a new document. A list with an `id` gets its position back, but the
+composition is gone with the document that read it: skeletons and a first load,
+unless the page is kept
+([list_refresh.md](./list_refresh.md#leaving-the-screen-and-coming-back)).
+
+A list coming back to a remembered position draws first the items that were on
+screen, and sizes its whole window once the browser has painted them (see
+`renderBudget`'s `initial`). Its first ask is a page around what was on screen;
+the edge of the window past that page, below the screen, comes with the next
+one.
+
 ### What the list knows, and what it guesses
 
 A virtualized list has one aim: draw as few items as it can, and never show a

package/package.json

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