@jsenv/navi 0.29.131 → 0.29.133

package/docs/AI_INSTRUCTIONS.md

@@ -278,7 +278,9 @@ consistency across the app, not from any single call site.
   than a param, search params bound to signals, rendering with `<Route>`,
   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), a back arrow that stays inside the app (`useCanNavBack()` /
+  was left, a replace moves nothing — except in a `RouteTravel`, where each tab
+  is given back the offset it was read at, and only when the row owns the
+  document scroll), a back arrow that stays inside the app (`useCanNavBack()` /
   `navBack({ fallback })`), 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

package/docs/navigation.md

@@ -473,7 +473,9 @@ coming up from below.
 A swipe **replaces** the current history entry, and a tab pressed says the same
 thing when its link asks for it (`<Link replace>`, see above) — the two gestures
 towards the same neighbour must not write two different histories. `onTravel`
-decides otherwise.
+decides otherwise. A replace normally leaves the scroll where it is; a row of
+tabs is the exception, and gives each tab back the offset it was read at — see
+[A row of tabs, where a replace IS an arrival](#a-row-of-tabs-where-a-replace-is-an-arrival).
 
 Several `RouteTravel` boxes may live on one page — a section of the path and a
 search param of the root route are two rows of tabs, both live — and only the one
@@ -491,7 +493,7 @@ 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:
+Four cases, and they are not a policy to configure but four 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
@@ -503,6 +505,10 @@ Three cases, and they are not a policy to configure but three different facts:
   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.
+- **Replacing the entry** (`<Link replace>`, `route.redirectTo()`, a param
+  settling, a state written) moves nothing. It is the same place said
+  differently, and the reader is still in the page they were reading — a row of
+  tabs is the one shape where that reading is wrong, see below.
 - **A reload** lands where one was, as it would have without navi.
 
 One consequence is softened where the browser exposes its stack (the
@@ -521,6 +527,39 @@ in a browser with no Navigation API — 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.
 
+### A row of tabs, where a replace IS an arrival
+
+The tabs of a `<RouteTravel>` navigate by replacing, and yet each one is another
+route. They also share a single scrollport — the document — and the tab on
+screen is what makes it tall. So leaving the offset alone does not keep it: the
+moment the arriving tab is shorter, the browser clamps, and the reader's place
+is gone before anything of navi's is asked.
+
+The row is the only thing that knows this, so the row is what says it. On every
+travel — a tab pressed, a thumb dragging the pages, a wheel, a travel let go of
+too early and put back:
+
+- the arriving tab is given back the offset it was read at, once it is really
+  rendered;
+- a tab never read opens at its **top**, rather than wherever its neighbour
+  happened to be;
+- the clamp itself is never recorded. It is not the reader scrolling, and the
+  url it would be written against is already the arriving tab's — recorded, it
+  destroys that tab's own position, which is then what a later back or forward
+  hands out.
+
+**Only where the row owns the document**: nothing between the travelling box and
+the viewport may scroll or clip. A row inside a scroller of its own — a frame in
+an article, a panel beside other content — shares nothing with the document, and
+the offset there belongs to the page around it, which the reader never left; the
+travel leaves it alone. An `overflow: hidden` or `clip` on any ancestor is
+enough to put the row outside the document's scrollport, so a row that should
+give positions back and does not is worth looking at from that angle first.
+
+Pages that scroll inside themselves rather than scrolling the document are not
+concerned either way: each one brings its own scrollport, which goes away with
+the page and has nothing to give back.
+
 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.

package/docs/scroll.md

@@ -3,6 +3,11 @@
 Where scrolling happens in a navi app, and how the pieces that live inside a
 scrolling area (`Box header/body/footer`, `List`, a popup) are told about it.
 
+Where a navigation LANDS is another subject — a push at the top, a back or
+forward where the page was left, a row of tabs giving each tab back the offset
+it was read at: see
+[navigation.md](./navigation.md#where-a-navigation-lands-the-scroll).
+
 - [What makes header/body/footer work: the overflow](#what-makes-headerbodyfooter-work-the-overflow)
 - [1. The document scrolls](#1-the-document-scrolls)
 - [2. A part of the document scrolls](#2-a-part-of-the-document-scrolls)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.131",
+  "version": "0.29.133",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {
@@ -29,7 +29,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@jsenv/dom": "0.17.32",
+    "@jsenv/dom": "0.17.33",
     "@jsenv/humanize": "1.7.8",
     "@jsenv/validity": "0.4.3"
   },