@jsenv/navi 0.29.433 → 0.29.434

package/docs/AI_INSTRUCTIONS.md

@@ -183,9 +183,10 @@ start when unsure which export solves a problem.
   hand-writing an offset to clear a `FixedBar`.
 - `scroll.md` — where scrolling happens: `header`/`body`/`footer`, a `List`'s
   `scroller`, where a list opens (a position handed back whole, `visibleCount`
-  included), a popup that scrolls, many rows (`<List.Items>`, the render window
-  and its first picture, `findText`), many sections (`<Box mount="after-paint">`
-  and what it leaves out of reach), hover while scrolling. Before writing CSS to
+  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, `findText`), 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, and before deferring part of a page.
 - `z_index.md` — DOM order first; a `z-index` without `isolation: isolate`

package/docs/route_transitions.md

@@ -467,6 +467,10 @@ What that means for a page and for the application around it:
 - **The focus it holds goes where its removal would have sent it** — to no element
   — when it is hidden: a hidden element keeps the focus otherwise, and would
   receive the keys pressed during the movement.
+- **Its lists are mounted beside the page arriving's.** A list remembering where
+  it was (`<List id>`) under the same `id` as a list of the page arriving is the
+  same list to navi, and the two overwrite each other's position (see
+  [scroll.md](./scroll.md#a-list-that-comes-back-one-id-one-list)).
 - **Never while a modal dialog is open.** An open modal keeps everything but
   itself out of reach — the page arriving could not even take the focus — and one
   in a page kept while leaving would stay open for the whole movement. The page is

package/docs/scroll.md

@@ -122,11 +122,44 @@ 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
-left and come back to, the way the page does; **`scrollResetOnNavigation`**
-opts out. 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.
+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
+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.
+
+### A list that comes back: one `id`, one list
+
+The position a list comes back to is kept under its `id` and the page's url, so
+the `id` names **one list of the app**, not one list of the page. Two lists
+mounted at the same time under the same `id` are one entry: each writes over the
+other's position, and the one that goes takes the other's with it. The list
+arriving then opens where the other one was, or comes back at its top after a
+back.
+
+Lists are mounted together more often than the screen shows:
+
+- a list in a popup and a list in the page under it;
+- a list in a bar or a sidebar kept by every page, and a list in one of the
+  pages;
+- the two pages of a **route transition**: the page being left stays mounted,
+  hidden, until the movement is over (see
+  [route_transitions.md](./route_transitions.md#the-page-being-left-stays-until-its-movement-is-over)),
+  its lists with it.
+
+So:
+
+- **Name the list for what it lists** — `players_list`, `thread_messages`, never
+  `list`, `results` or `items`.
+- **A component that draws a list on several pages takes the `id` from the page
+  using it** (a prop), rather than writing one of its own.
+- **A list with no use for coming back** says `scrollResetOnNavigation`: it keeps
+  nothing, and its `id` no longer matters for this.
+
+Not a clash: a page rendered by the same element on both sides — one route whose
+params change (`/threads/1` to `/threads/2`), two routes with one `element` — is
+carried over, and its list is one list moving from one url to the next.
 
 ### A search moves the list, and gives it back
 

package/package.json

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