@jsenv/navi 0.29.67 → 0.29.68

package/docs/AI_INSTRUCTIONS.md

@@ -72,8 +72,11 @@ consistency across the app, not from any single call site.
   what updates from a response without any request, `rerunOn` and its defaults,
   and how a paginated `<List.Items>` re-reads its slices without disappearing,
   including on its way back from a screen that unmounted it.
-  Read it before adding verbs to `rerunOn`, hiding a list on `loading`, or
-  remounting a list with a `key` to refresh it.
+  It also says who decides a re-read on the way back — the source the list
+  reads through, never the navigation and never a route transition.
+  Read it before adding verbs to `rerunOn`, hiding a list on `loading`,
+  remounting a list with a `key` to refresh it, or reporting that a page
+  stopped refreshing since a transition was defined on its pair.
 - `docs/error_handling.md` — the two kinds of error and how navi keeps them
   apart: where an error is shown depending on where it came from (a control's
   action shows it on what was clicked, a route action replaces the page, a
@@ -168,8 +171,9 @@ consistency across the app, not from any single call site.
 - `docs/navigation.md` — how to build navigation: declaring routes
   (`route()` / `setupRoutes()`), when a section is a route of its own rather
   than a param, search params bound to signals, rendering with `<Route>`,
-  tab rows (`Nav` / `Link` / `RouteTravel`), and the few cases where tabs are
-  legitimately not URLs. Read it before writing any routing code — the
+  tab rows (`Nav` / `Link` / `RouteTravel`), where a navigation lands
+  (scroll: a push arrives at the top, a back or forward lands where the page
+  was left), and the few cases where tabs are legitimately not URLs. Read it before writing any routing code — the
   position of the user belongs in the URL by default, and that decision is
   not retrofittable.
 - Source code and demos on GitHub:

package/docs/list_refresh.md

@@ -132,8 +132,9 @@ stale copy of anything.
 A run that finds a composition takes the `refreshing` line of the table above
 rather than the loading one: the rows are on screen while it asks again for the
 window it draws. So the two lists an app cannot tell apart from the outside —
-one reading `GET_MANY`, one reading `GET_RANGE` — behave the same on the way
-back.
+one reading `GET_MANY`, one reading `GET_RANGE` — look the same on the way back:
+neither blanks, neither shows a first load. What they do behind that is not the
+same, and the next section is about exactly that.
 
 What a composition is about is the **values** its params hold, not the reader
 instance: `GET_RANGE.bindParams({ scope: "thread" })` called from two places
@@ -145,6 +146,36 @@ The rest follows the rules already stated: a verb in `rerunOn.GET_RANGE`, or
 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.
 
+### Who decides the re-read — and who does not
+
+The navigation decides nothing. Neither the back button, nor the movement
+playing between the two pages: the **source** the list reads through is what
+answers, and it answers the same way whether the user arrived by a link, by
+`history.back()`, or under a route transition.
+
+| The list reads through          | Coming back to it                                                                                     |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `routeAction` over `GET_MANY`   | **nothing goes out** — the action holds its response, and `.run()` on a `COMPLETED` action is a no-op |
+| `<List.Items>` over `GET_RANGE` | **one ask goes out** — the reader kept ranks, not rows, and revalidates the window it draws           |
+
+Both are deliberate, and they are not in tension: an action that kept its answer
+has the answer, while a composition is a claim about an order that any write
+elsewhere may have made false. What a `GET_MANY` list wants on the way back it
+has to say itself — `.rerun()` when the route becomes current again, or a verb
+in `rerunOn` if a write is what makes it stale.
+
+Nothing above changes when `defineRouteTransition` is written for the pair the
+list is walked through. A transition states a relation between two pages (see
+[route_transitions.md](./route_transitions.md)); it takes the document's
+rendering hold for the one frame the browser needs to photograph it, and gives
+it back. It never decides what the page arriving is allowed to ask for. Held by
+`tests/route_transition_list_revisit/`, which mounts the same app twice — with
+and without a relation on the pair — and compares both counts.
+
+So a list that stopped refreshing after a transition was added has, in the
+overwhelming majority of cases, never refreshed on its own: it was reading
+through `GET_MANY`, and something else in the app was doing the re-read.
+
 ## `rerunOn`, verb by verb
 
 `rerunOn` says which verbs invalidate this resource's `GET` / `GET_MANY` /

package/docs/navigation.md

@@ -294,6 +294,32 @@ settings page rising over whatever showed it — are animated with
 `defineRouteTransition` instead, and a given pair must be animated by one of
 the two, never both: see [route_transitions.md](./route_transitions.md).
 
+## Where a navigation lands: the scroll
+
+Three cases, and they are not a policy to configure but three different facts:
+
+- **Going somewhere new** (a `<Link>`, anything that pushes) lands at the top.
+  It is an arrival: the offset one had elsewhere means nothing here, and left
+  alone the new entry would be born holding the previous page's offset — which
+  the browser would then hand back as if it were this page's own.
+- **Going back or forward** (the browser's buttons, `navBack()`,
+  `history.back()`) lands where that page was left. navi keeps the position and
+  puts it back once the page is really rendered, which is what the browser
+  cannot do: it restores at the instant the entry changes, when the document
+  still holds the page being left, so anything further down than that page is
+  tall is clamped away.
+- **A reload** lands where one was, as it would have without navi.
+
+The consequence worth knowing when building a screen: **a "back" written as a
+`<Link>` is a push**, so it lands at the top like any arrival — no mechanism
+can guess that a push was morally a return. A back arrow that should feel like
+one is `navBack()`. Where there may be nothing to go back to (a shared link
+opened cold), decide what the arrow does from the history, not from the link.
+
+What is not covered: a page whose height depends on something still loading is
+not tall enough at the moment its position is put back, so a deep position is
+clamped as it was before. Only the page knows when it is whole.
+
 ## Creating something, then editing it
 
 The create screen, the page of what was created, the edit screen — three routes,

package/docs/route_transitions.md

@@ -8,7 +8,7 @@ decides which movement (if any) a navigation deserves. The API grammar itself
 
 Demos: [the movements](../src/nav/demos/route_transition/route_transition.html),
 [a default transition](../src/nav/demos/route_transition/route_transition_default.html),
-[pages between fixed bars](../src/nav/demos/route_transition/route_transition_fixed_bars.html),
+[pages between fixed bars](../src/nav/demos/route_transition_fixed_bars/route_transition_fixed_bars.html),
 [with a RouteTravel inside](../src/nav/demos/route_transition/route_transition_with_travel.html)
 
 ## What a transition is for
@@ -110,6 +110,12 @@ through, not the page's own size: a page is as tall as its content, and a
 vertical movement measured on the picture would send it several screens away —
 off screen for most of the transition, flying past at the end.
 
+A page that was **scrolled** is photographed where the reader was, and travels
+from there: the document is not put back to its top until the picture has been
+taken. Without that wait the picture keeps only the band the browser had
+already painted at the new offset, and the movement carries a fragment of the
+page instead of the page.
+
 With an area marked, the page around it is left LIVE rather than photographed:
 the bars keep answering the pointer for the whole movement, which a captured
 element cannot do. The flip side is that anything around the area which must
@@ -176,6 +182,30 @@ animates. A `<RouteTravel>` rendered inside the `element` of each of the routes
 it travels between is destroyed mid-travel by the router. Give the row a single
 branch — its tabs as params of one route is the usual shape.
 
+## A transition says nothing about data
+
+A relation is about the map of the app, and about nothing else. Defining one
+does not change what the page arriving loads, reloads, or keeps:
+
+- an action that `COMPLETED` still holds its response, on the way back as on the
+  way in — a page wanting fresh data says `.rerun()`, with or without a
+  movement;
+- a `<List.Items>` reading through `GET_RANGE` still revalidates the window it
+  draws when it is mounted again.
+
+What a transition takes is the document's **rendering** for the one frame the
+browser needs to photograph the page being left (see `rendering_hold.js`), and
+it gives it back in the same callback. The hold is about a picture, not about
+data: nothing waits on it, nothing is skipped because of it.
+
+So "this list stopped refreshing since we animated the pair" is a claim worth
+checking twice before believing: it is held by
+`tests/route_transition_list_revisit/`, which mounts one app twice — the two
+mounts differing by a single `defineRouteTransition` line — and compares what
+each one sends to the network on the way back. See
+[list_refresh.md](./list_refresh.md#who-decides-the-re-read--and-who-does-not)
+for which source refreshes on a revisit and which does not.
+
 ## The rest, briefly
 
 - Pace: `--navi-route-transition-duration` (CSS, default 300ms) for everyone;

package/package.json

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