@jsenv/navi 0.29.66 → 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

@@ -6,9 +6,10 @@ decides which movement (if any) a navigation deserves. The API grammar itself
 (accepted forms, shipped type names) lives in the JSDoc of
 `defineRouteTransition`; this file holds what a signature cannot say.
 
-Demos:
-[../src/nav/demos/route_transition/route_transition.html](../src/nav/demos/route_transition/route_transition.html),
-[../src/nav/demos/route_transition/route_transition_default.html](../src/nav/demos/route_transition/route_transition_default.html)
+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_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
 
@@ -76,21 +77,69 @@ A default has no direction (nothing says which of two arbitrary pages is
 "before" the other), so only directionless movements make sense there. Written
 relations, and `"none"`, always win over it.
 
-## Pages between fixed bars: mark the area
+## Pages between fixed bars: the transition area
 
 By default the movement plays on the document itself — right when pages are the
 whole viewport. With fixed bars it is not: the root snapshot spans the viewport
-and the bars' regions are blank in it, so a vertical movement drags a blank
-band across the screen. Mark the region the pages live in instead:
+and the bars' regions are blank in it, so the moving picture drags a blank band
+across the screen where they stand. Wrap the pages instead:
 
-```html
-<div class="app" data-navi-route-transition-area>…routes…</div>
+```jsx
+<RouteTransitionArea className="app">
+  <Route>…</Route>
+</RouteTransitionArea>
 ```
 
-One attribute, on an element the layout already has. The movement then plays on
-that region's own pictures, clipped at its bounds, and the bars never move —
-without being named one by one. An app with fixed bars should consider this
-attribute part of declaring transitions at all, not an option.
+The movement then plays on that region's own pictures, and the bars never move
+— without being named one by one. An app with fixed bars should consider this
+part of declaring transitions at all, not an option.
+
+The pages are cut twice: at the area's own bounds, and at the app's **safe
+area** (see [safe_area.md](./safe_area.md)). The second cut is not a detail. A
+fixed bar is fixed to the window while the area is a long box in the document —
+the room the bar gives back is padding, so the content runs under it by design.
+The pictures are drawn in the top layer, above everything the document can
+clip, so without that cut a page taller than the screen, or a scrolled one,
+would be watched sliding over the bars for the whole movement. The band is read
+from the safe area rather than from the bars, so every kind of furniture is
+covered at once and one that unmounts mid-movement is followed without anything
+being told.
+
+For the same reason, how far a page travels is the **window** it is seen
+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
+_animate_ rather than stand still — a title that changes with the route — needs
+a `view-transition-name` of its own; named, the browser moves it on the same
+clock as the pages.
+
+It is a `Box`, so the layout the pages need is written on it directly (`flex`,
+`className`, `style`, …). An app that already has an element holding its pages
+can mark that one with `data-navi-route-transition-area` rather than nesting
+another — the component does exactly that.
+
+**The area is a real box, and it has to be**: what gets photographed and
+clipped IS its rectangle. So `display: contents` cannot be used on it — an
+element with no box is never captured, and the movement then plays on nothing
+(the browser also aborts the transition). This is measured behaviour, not a
+precaution.
+
+Three misconfigurations are silent enough to be worth a console warning, each
+said once: an area that was not captured (the case above), several elements
+marked at once (they would share one `view-transition-name`, and the browser
+then refuses **every** view transition of the document), and pages travelling
+on the document while something else is captured on its own — the blank band.
+A warning here is a bug to fix, not a mechanism to lean on.
 
 ## Custom movements
 
@@ -111,13 +160,52 @@ shape, and the `spin` type in the demo for a working one.
 - **`defineRouteTransition`** declares individual relations, with no gesture
   and no order beyond each pair.
 
-A given pair of routes must be animated by one of the two, never both: a
+A given PAIR of routes must be animated by one of the two, never both: a
 travel's pictures can be under a finger, and a transition starting on top would
 skip them mid-slide — and a page one can drag has promised a translation, which
 a cross-fade would break. The runtime enforces the priority (a travel in flight
 wins; the route transition is skipped with a console warning); the warning is
 the sign of a misconfiguration to fix, not a mechanism to rely on.
 
+The two DO live together in one app, on different pairs, including a
+`<RouteTravel>` nested inside a `<RouteTransitionArea>` — a row of sections the
+thumb pushes, inside pages one goes into. Write the relations on the routes the
+row does not own: the tabs of the row travel, and opening something from any of
+them plays its own movement. A relation written on a bare route covers every
+one of its params at once, which is what makes "from any section" one line
+rather than one per tab. Demo:
+[../src/nav/demos/route_transition/route_transition_with_travel.html](../src/nav/demos/route_transition/route_transition_with_travel.html)
+
+One trap that belongs to `RouteTravel` rather than to transitions, but bites
+here first: the travelling box must stay MOUNTED across the changes it
+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.66",
+  "version": "0.29.68",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {