@jsenv/navi 0.29.459 → 0.29.461

package/docs/AI_INSTRUCTIONS.md

@@ -58,7 +58,8 @@ start when unsure which export solves a problem.
 
 - `navigation.md` — the position of the user belongs in the URL by default:
   routes and which branch renders, search params, redirections, the back arrow
-  (`navBack`), where a navigation lands (a `#id` for an element), a
+  (`navBack`), where a navigation lands (a `#id` for an element; a page not
+  whole yet holds its position with `useHoldScrollRestoration`), a
   `SlideContainer` read from the URL, what a layer drawn over the screen may say
   in its address. Before any routing code.
 - `route_transitions.md` — a transition states a relation between two pages;

package/docs/actions.md

@@ -202,8 +202,9 @@ this one cannot start before the component that draws it exists — a render lat
 at best, a gesture late in a popup. It is for a parameter chosen inside the
 component and dying with it. Outside a component,
 `actionRunEffect(action, () => …)` is that same run declared once — it runs on
-the first truthy params, reruns when they change, aborts when they go false —
-and the machinery `routeAction` is built on.
+the first truthy params, reruns when they change (unless the action declared
+`keep` and still holds the answer for the new ones), aborts when they go
+false — and the machinery `routeAction` is built on.
 
 **Which of the two it is, is decided by the parameter, not by what draws it.**
 If the parameter is in the address — a path param, a search param bound to a
@@ -222,6 +223,21 @@ decided to write, whatever its parameter, and `{ run: true }` says it — a toke
 a share button must already hold when pressed, for instance, since the OS share
 sheet only opens inside the gesture, never after an `await`.
 
+**A head start is `{ prerun: true }`.** When the params are known before the
+component owning the read exists — a card already says which chapter a book
+has, the book page draws its pages once the book is there — a component
+drawing nothing can send the read ahead, on the instance the owner will read:
+
+```jsx
+// draws nothing: the pages leave with the book instead of after it
+useAsyncData(chapterPagesAction, { prerun: true });
+```
+
+It needs no `<Loading>`, and its failure reaches no boundary: nothing on screen
+asked for a prerun, so the owner's `{ run: true }` asks again, once, when it
+reads it. A failure of the owner's own run is shown, and asked again by a
+`rerun()`, never by a render. A head start still running is the owner's wait.
+
 `{ onLoad }` is what the screen does with the data **once, when it becomes
 known** — seed the fields someone is about to edit, focus something, remember
 where a list was:

package/docs/dynamic_import.md

@@ -68,6 +68,10 @@ Everything the data layer decides then holds for the code:
   `activeRouteReadsSignal`, which leaves the code out: rerun, it would take a
   page reading it delegated off the screen for a frame.
 - **Fetched ahead**, on intent ([below](#ahead-of-the-render-intent)).
+- **A reload lands where the reader was.** The scroll position waits for the
+  code and the render that draws the page, rather than being written into the
+  pending screen and clamped to its height
+  ([navigation.md](./navigation.md#a-page-that-is-not-whole-yet)).
 
 ## A component inside a page that stays: who asks for its code
 

package/docs/mobile_touch.md

@@ -17,6 +17,7 @@ changes, measure again before trusting a number here.
 - [The browser decides about 8px in, and does not wait](#the-browser-decides-about-8px-in-and-does-not-wait)
 - [touch-action stops at the first scroller](#touch-action-stops-at-the-first-scroller)
 - [Only the start is contested](#only-the-start-is-contested)
+- [A rounded clip makes the scroll wait for the main thread](#a-rounded-clip-makes-the-scroll-wait-for-the-main-thread)
 - [The click is the browser's call as much as ours](#the-click-is-the-browsers-call-as-much-as-ours)
 - [A tap dropped after a touch drag](#a-tap-dropped-after-a-touch-drag)
 - [A finger is captured to what it touched, inside shadow trees too](#a-finger-is-captured-to-what-it-touched-inside-shadow-trees-too)
@@ -122,6 +123,48 @@ it back:
 A gesture that has won the start keeps the touch. What loses gestures is the
 first ~8px.
 
+## A rounded clip makes the scroll wait for the main thread
+
+Before it scrolls under a finger, Chrome's compositor finds the scroller under
+it. Where it cannot tell on its own, it asks the main thread, and the scroll
+starts when the main thread answers — after whatever task is running there.
+Meanwhile the finger keeps moving: the content holds still, then catches up in
+one step. A small scroll is mostly its start, so that is where it is felt. The
+wheel asks the same way on a desktop, where the main thread is rarely busy at
+that moment.
+
+Two things make Chrome ask (Chrome 155, mobile emulation; not measured in
+Safari):
+
+- **A rounded clip on the scroller or around it**: `overflow` other than
+  `visible` with a `border-radius`, or a rounded `clip-path`. Every scroll
+  start inside it is asked, wherever the finger lands. A popup that scrolls is
+  one: a rounded `overflow: auto` box.
+- **Anything painted over the scroller**, even with `pointer-events: none` and
+  square corners (an overlay drawing an edge above the items, say), but only
+  where it covers it: a 6px band along the top leaves the rest decided on the
+  compositor.
+
+The wait costs whatever runs at the touch: 0.1–2ms when nothing does; with a
+render built on the touch at 6× CPU, 7.5ms median and up to 27ms, and a scroll
+started a frame late one time in three. So navi keeps both away from what
+scrolls. A framed `List` does not clip to its rounded corners: its edge stays
+under the items, and one with a background covers the inside of the curve. A
+picker popup whose list scrolls itself does not clip either. And a finger on
+something that opens builds nothing before it has been held ~80ms. Wrapping a
+`List` in a rounded box of your own with `overflow: hidden` brings the wait
+back.
+
+A box that stops clipping needs `min-height: 0` if it is a flex or grid item
+holding the scroller: without a clip its minimum height is its content's, so a
+box given a height grows to all its items and the page scrolls instead. Nothing
+waits for the main thread then, because the wrong thing scrolls — check that
+the scroller's own `scrollTop` moved.
+
+Reference: `.navi_list_container` in `src/control/list/list.jsx`, the
+`[data-picker-popup]` rules in `src/control/picker/picker_custom.jsx`,
+`TOUCH_WARM_HOLD_MS` in `src/layout/popup_content_mount.js`.
+
 ## The click is the browser's call as much as ours
 
 - **Chrome** clicks after a touch that moved up to 8px and never beyond, whether
@@ -221,6 +264,19 @@ configuration: "mobile" })`, then `Input.dispatchMouseEvent` with
 through the desktop configuration instead: a 15px slop. Anything deciding at
 10px wins there, and the race that loses swipes on a phone is invisible.
 
+Where a scroll's start is decided shows only in a trace, never in the page's
+events: `Tracing.start` with `input`, `cc` and `disabled-by-default-cc.debug`.
+After the last `InputHandlerProxy::HandleTouchStart`, a
+`WidgetInputHandlerManager::FindScrollTargetOnMainThread` is the scroller looked
+up on the main thread, the gap between the two
+`InputHandlerProxy::HandleGestureScrollBegin` is how long that took, and a
+`delta_y` larger than one move on the first
+`InputHandler::ScrollLatchedScroller` says the first step merged two moves.
+Not under Playwright: its injected script puts a non-passive `touchstart`
+listener on `window`, which makes every touch blocking and changes the path
+being measured. Start Chrome by hand (`--headless=new
+--remote-debugging-port`) and drive the page's websocket directly.
+
 **Safari**: the iOS simulator, driven by `safaridriver`, which turns W3C touch
 actions into real UIKit touches — Safari's own pan recognizers compete for
 them exactly as on a phone:

package/docs/navigation.md

@@ -16,6 +16,7 @@ linking to them, and turning them into tabs.
 - [The back arrow: `navBack`](#the-back-arrow-navback)
 - [Tabs that travel: `RouteTravel`](#tabs-that-travel-routetravel)
 - [Where a navigation lands: the scroll](#where-a-navigation-lands-the-scroll)
+  - [A page that is not whole yet](#a-page-that-is-not-whole-yet)
   - [Landing on an element: the fragment](#landing-on-an-element-the-fragment)
 - [Creating something, then editing it](#creating-something-then-editing-it)
 - [Tabs that are not routes](#tabs-that-are-not-routes)
@@ -481,7 +482,8 @@ Five cases, and they are not a policy to configure but five different facts:
 - **Replacing the entry** (`<Link replace>`, `route.redirectTo()`, a param
   settling) moves nothing: the same place said differently — except in a row of
   tabs, below.
-- **A reload** lands where one was, as it would have without navi.
+- **A reload** lands where one was, as it would have without navi, once the
+  page is there ([below](#a-page-that-is-not-whole-yet)).
 
 Where the browser exposes its stack (the Navigation API), **a `<Link>` whose
 destination is the entry right next to the current one becomes a real
@@ -490,6 +492,47 @@ A, B, A, B… growth, and the scroll comes back — and one step forward too. On
 towards entries of this document, and never when the push carries explicit
 state. An arrow that must ALWAYS behave as a back is `navBack()`.
 
+### A page that is not whole yet
+
+A position is put back into whatever the page shows at that moment. When that is
+a stand-in — a pending screen, a `<Loading>` fallback, a list of three skeletons
+— the document is shorter than the page the position was taken on, the offset is
+clamped to it, and the reader lands at the top of a page that arrives a moment
+later.
+
+**After a reload, navi waits for the route actions** that the first render had
+nothing to draw for: the page's code arriving on its own
+([dynamic_import.md](./dynamic_import.md)), a read the previous document did not
+keep ([`keepPageOnScreen`](./resource.md#keeppageonscreen-the-page-on-screen-drawn-again-by-the-next-document) draws a kept one at once, and that one
+is not waited for). The position is put back once they have answered and the
+page has rendered. When one of them fails, nothing is written: the screen saying
+so is not the page the position was taken on, and the position stays for the
+reload that brings it back. What it costs: a slow read that every page asks for
+delays the position of every page, since nothing tells navi which reads set the
+height.
+
+**What navi cannot see, the page says**: a read it starts itself
+(`useAsyncData(…, { run: true })`), content whose height arrives late. While
+`useHoldScrollRestoration(held)` is given `true`, the position of a reload or of
+a back/forward waits; it is put back after the render that turns it `false`:
+
+```jsx
+const [games] = useAsyncData(GAMES, { loading: true, run: true });
+useHoldScrollRestoration(games === undefined);
+```
+
+A read that fails leaves it `true`, and nothing is written, for the same reason
+as above. A row of tabs is not held: it gives a tab its position as it travels,
+and measures right after (see [below](#a-row-of-tabs-where-a-replace-is-an-arrival)).
+
+**The reader taking over cancels it.** A finger, a click, a wheel or a key
+before the position is written, and it is not written: moved afterwards, they
+would lose whatever they had started on. Going elsewhere cancels it too.
+
+A `<List>` that opens on an item is the opposite case, and needs nothing: it
+places the document itself, by measuring the item, and the url's offset is not
+put back over it ([scroll.md](./scroll.md#where-the-list-opens-and-where-it-is)).
+
 ### Landing on an element: the fragment
 
 A link meant to bring one element under the reader's eyes — a notification
@@ -564,9 +607,10 @@ the viewport may scroll, and a row inside a scroller of its own leaves that
 offset alone. An `overflow: hidden` on any ancestor is enough to take the row out
 of the document's scrollport — it holds an offset even without a scrollbar, where
 `overflow: clip` holds none — so it is the first thing to look for when a row
-does not give positions back. And a page whose height depends on something still
-loading is not tall enough when its position is put back: only the page knows
-when it is whole. What navi itself builds after the first frame
+does not give positions back. And a tab whose height depends on something still
+loading is not tall enough when its position is put back: the row does not wait
+for it ([A page that is not whole yet](#a-page-that-is-not-whole-yet) is for a
+reload and a back). What navi itself builds after the first frame
 (`<Box mount="after-paint">`, see
 [scroll.md](./scroll.md#many-sections-box-mountafter-paint)) is not such a
 page: the part the position shows is built before it is written.

package/docs/resource.md

@@ -613,6 +613,27 @@ is inferred — a relation that really is a sub-route of the parent is modelled
 with the relationship methods ([above](#relations-and-autorerun)), never
 declared as a dependency.
 
+When only some writes change what the reads show — a count of videos moves
+when one is created or deleted, not when a chapter is rated — name them with
+`on`:
+
+```js
+const SUMMARY = resource("summary", {
+  dependencies: [
+    BOOK, // every write
+    { resource: VIDEO, on: ["PATCH_MANY", "DELETE"] },
+    { resource: VIDEO_FILE, on: ["POST", "DELETE"] },
+  ],
+  GET: …,
+});
+```
+
+`on` names callbacks, not verbs: `PATCH` does not cover `PATCH_MANY` the way it
+does in `rerunOn`, so each write keeps its own answer. A name that is not a
+write, or that the resource does not define, throws at declaration — a
+dependency that never fires leaves a count on its old value with nothing to say
+so.
+
 ## A function calling the verb, or the instance
 
 Both forms are real, and what separates them is narrower than it looks:

package/package.json

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