@jsenv/navi 0.30.4 → 0.30.6

package/docs/drag_to_travel.md

@@ -51,6 +51,18 @@ What stays ours:
 - **A travel asked for** (a tab, a key, a command, a state) plays in `duration`,
   one box long whatever the distance, in `SlideContainer`. In `RouteTravel` it is
   the browser's smooth scroll.
+- **A press beats a row still moving.** It sets off at once from what is on screen,
+  and the row never lands where the hand was sending it. In `SlideContainer`
+  `onCurrentChange` hears about the slide pressed and not about that one, and on iOS a
+  swipe during that travel is ignored, and the next one works.
+- **What says where one is follows the screen.** While a hand holds the row, one is on
+  the page held. Once it has let go, what reads the row reads where it is going:
+  `useSlideContainer` (`current`, `can`, `held`), a `Nav`'s tabs, a `StepList`'s steps
+  and the chevrons in `SlideContainer`, so Next pressed during a snap counts from there;
+  a link's current state and `routeTravelSettledPageSignal` in `RouteTravel`. A trackpad
+  has no lift, so the nearest page answers. What the state holds waits for rest: the
+  bound signal and `onCurrentChange`, and in `RouteTravel` the address, except where it
+  runs ahead to build a page.
 - **A direction that is refused is the end of the row.** Whatever holds the user
   where they are (a `<Slide required>` waiting for its answer, a `preventNavNext`)
   takes what lies beyond off the row, so nothing can be scrolled to. There is no
@@ -235,7 +247,9 @@ A row of screens is a scroll container, and contains itself.
 
 A `RouteTravel` page not visited yet can only be built by the address moving, since
 a route's actions ask only while it matches. So the address moves once the hand has
-really pulled, 16px, and the page fills in under the finger. See
+really pulled, 16px, and the page fills in under the finger. Before that its pane
+is empty and the box's background shows, unless `renderNeighbour` says what stands
+there. See
 [navigation.md](./navigation.md#tabs-that-travel-routetravel).
 
 Both tell what follows them how far the row has come. `SlideContainer` writes

package/docs/mobile_touch.md

@@ -9,8 +9,8 @@ fixed, they differ between engines, and **none of them shows with a mouse**. A
 gesture can pass a whole session of desktop testing and still fail one swipe
 in three on a phone.
 
-What follows is measured, not remembered: Chromium 153 through its mobile touch
-emulator, and Safari on the iOS 26.5 simulator driven with real touches (see
+What follows is measured, not remembered: Chromium 153 and Chrome 156 through the
+mobile touch emulator, and Safari on the iOS 26.5 simulator driven with real touches (see
 [Verifying without a device](#verifying-without-a-device)). When an engine
 changes, measure again before trusting a number here.
 
@@ -22,6 +22,7 @@ changes, measure again before trusting a number here.
 - [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)
 - [A finger never makes a wheel event](#a-finger-never-makes-a-wheel-event)
+- [A snap keeps running after the finger](#a-snap-keeps-running-after-the-finger)
 - [Verifying without a device](#verifying-without-a-device)
 
 ## The browser decides about 8px in, and does not wait
@@ -229,6 +230,11 @@ where it lands, never asked for: on a touch press, a capture announced on the
 press's own target (compared from the same tree) is the browser's, and a gesture
 taking the press onto that same element has to say so another way.
 
+The rest of the touch goes there too, **even once that element has left the document**:
+a page re-rendering under the finger takes it out, and its `touchend` is dispatched on
+the detached node and reaches no ancestor. Nothing on the page around it hears the
+lift. What has to hear it listens on `event.target` from the `touchstart`.
+
 Measured in Chromium 153 (`Input.dispatchTouchEvent`: the capture does not
 depend on the slop) and on an Android phone (Chrome 153); not in Safari.
 Reference: `implicitCaptureHolder` and `takePress` in `@jsenv/dom`'s
@@ -243,6 +249,51 @@ paths differ in timing: a wheel gesture is claimed and refused on its very first
 event, so the browser never gets a moment to decide, while a finger has to
 travel a few pixels before anything can be read.
 
+## A snap keeps running after the finger
+
+A row with `scroll-snap-type: mandatory` goes on moving once the finger has lifted:
+about 600ms in Chrome, about 700ms in Safari, slowing all the way, so the last 300ms
+cover barely 40px of a 390px box. A press on something outside the row arrives during
+that time and gets its click, in Safari too. What it does to the row depends on the
+engine, because neither plays that movement on the main thread:
+
+| Asked of a row mid-snap           | Chrome                                                                | Safari on iOS               |
+| --------------------------------- | --------------------------------------------------------------------- | --------------------------- |
+| Instant `scrollTo`                | Ignored: the snap goes on and overwrites it                           | Stops it                    |
+| Smooth `scrollTo`                 | Replaces it until it ends: a short trip gets the snap back, and loses | Not measured                |
+| `scroll-snap-type: none`          | Ignored                                                               | Jumps to the target at once |
+| `overflow: hidden`, held          | Moves nothing, but the snap resumes when it is taken back             | Stops it                    |
+| `overflow: clip`, held two frames | Stops it: there is no scroller left to play it on                     | Stops it                    |
+| `display` changed for one layout  | Stops it (see below)                                                  | Stops it (see below)        |
+
+A change undone in the same task reaches nothing in Chrome, whatever the property,
+since the compositor never hears of it: only a `display` change acts that fast. It
+rebuilds the box, and it costs: `display: none` starts every CSS animation and
+transition inside over, `display: block` brings a scroller inside back to its top
+unless what the row holds keeps its size for that layout, and WebKit (desktop, under a
+synthetic wheel) then ignores the next write to the position and loses a scroller's
+own position inside.
+
+On Safari the last three rows were measured with a write following them, and a write
+alone is enough, so they say nothing of their own there.
+
+`scrollend` says little here: in Chrome a write gets one at once, with the row still
+moving. A row moved by other means with its snap left running ends worse than late:
+with a track animated over it, tens of pixels off any slide in Chrome, half a box off
+in Safari, and it stays there. Anything that moves a row on a press has to end the snap
+first.
+
+A box given `overflow: clip` is no scroller until it is given back, and that has its
+own cost: **a touch landing meanwhile starts no scroll in Safari**, even when the page
+gives the scroller back on `pointerdown`, since the scroll view does not exist yet when
+the finger lands. Chrome takes that swipe. Given back, the row stands where it stood
+with nothing written, but for the rest of that task WebKit still starts from 0: a smooth
+scroll to 0 sees nothing to do, and the row stays where it is, off any page. Ask a frame
+later.
+
+Firefox is not in this table: Playwright's synthetic wheel never leaves its row
+mid-snap, so it takes real input, events posted through the OS (`CGEvent` on macOS).
+
 ## Verifying without a device
 
 Both engines can show the browser's own answers — the pan, the
@@ -262,6 +313,10 @@ configuration: "mobile" })`, then `Input.dispatchMouseEvent` with
 - those calls are **never acknowledged**: send them without awaiting, with a
   sleep between moves (~16ms is a frame).
 
+A tap through this path waits about 300ms for a possible double tap, under
+`isMobile` too, so a press meant for a moment in a movement lands 300ms after it, at
+the end of a snap. `touch-action: manipulation` on what is pressed removes the wait.
+
 `Input.dispatchTouchEvent` — what Playwright's `touchscreen` uses — goes
 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.
@@ -304,9 +359,13 @@ its momentum included (over 3 s: flings closer than that add up). The window
 has to be on screen in the current Space: when it is not, activating the
 Simulator does not bring it, and the events land in whatever window is under
 the pointer — check which window is topmost at the points of the drag before
-sending any, and wait for the Space to switch after activating. What the page
-records is read back through a request it sends itself (the page runs on a
-local server), since nothing can query it.
+sending any, and wait for the Space to switch after activating. On screen is not
+on top: behind another app's window, activating does not raise it either, System
+Events does (`set frontmost to true`, then `AXRaise`), and another app can come back
+over it within seconds, so raise it and check right before each gesture, and again
+after any pause inside one. A tap works the same way, and reaches other elements
+during momentum. What the page records is read back through a request it sends itself
+(the page runs on a local server), since nothing can query it.
 
 What to synthesize is the hand's imperfection — a gesture simulated as clean,
 evenly spaced points passes forever and proves nothing: a slow start landing a

package/docs/navigation.md

@@ -569,6 +569,29 @@ given again around the page on screen as the reader moves through the list: it i
 taken once the row has come to rest, and nothing is seen moving for it. With fewer
 than two pages, the box is not a scroller at all.
 
+**A neighbour not there yet is empty until the hand has pulled**, a page of a window
+or a tab never visited, and it is the box's background one sees there.
+`renderNeighbour` says what stands in its place: the page's background, its
+skeleton, the name the list already holds.
+
+```jsx
+<RouteTravel
+  routes={players.map(({ id, name }) => ({
+    route: PLAYER_ROUTE,
+    params: { id },
+    name,
+  }))}
+  renderNeighbour={(page) => <PlayerSkeleton name={page.name} />}
+>
+  <PlayerPage />
+</RouteTravel>
+```
+
+It stands on each side of the page on screen, already painted when a finger lands,
+since the browser moves the row whatever the main thread is doing. So it renders
+with the page, and is worth keeping light. It is not the page: its route does not
+match yet, so it asks for nothing.
+
 **The box has a height, or the document scrolls.** Pages may scroll themselves in a
 box the page gives a height to. If the document is what scrolls, it goes on doing
 so, and a page brought in stands where the reader is looking; what is lost is
@@ -590,9 +613,10 @@ const shownId = settledPage ? settledPage.params.gameId : currentId;
 
 It holds the `{ route, params }` the hand set off from, and is `null` from the moment
 a lifted finger leaves the row moving, the URL being the truth again: the row is only
-playing out what the browser decided. A trackpad has no lift, so there it lasts until
-the row has come to rest, and a tab already built waits for that too. A tab pressed
-holds nothing, and `null` is all it ever reads. One signal for the document: on a
+playing out what the browser decided. A trackpad has no lift, so there it holds the
+page nearest the row until the row has come to rest, and the URL of a tab already built
+waits for that too. A tab pressed holds nothing, and `null` is all it ever reads, even
+over a row a hand has left moving: the press wins at once. One signal for the document: on a
 page with several boxes, `route` says which row it is.
 
 `RouteTravel` is for pages that form a ROW the finger can push; pages related
@@ -1063,6 +1087,33 @@ is shown. A popup's `value` answers another one, WHICH of several popups is open
 (one sheet per card under a single `?seat=<gameId>`), not what varies inside one
 (see [popup_open.md](./popup_open.md#signal--the-app-holds-it-both-ways)).
 
+**What a tab reads is asked for while the layer is open, not while the tab is
+shown.** Under a hand the signal is only written once the row has landed, and a
+neighbour is on screen from the first pixel. So a read whose params depend on the
+signal asks after the travel, and its slide travels without it. `mount="near"` keeps
+the slide built, not what it reads. Ask from the opening, and let the slide read its
+question, as
+[a popup that loads data](./popup_open.md#a-popup-that-loads-data) does:
+
+```js
+// asked while the layer is open, whichever tab is on screen
+export const LINKED_ACCOUNTS = routeAction(ANY_PAGE, ACCOUNT.GET_MANY, () => {
+  return settingsSignal.value;
+});
+// read by the slide, on screen, sliding away, or with the layer closing
+export const LINKED_ACCOUNTS_SHOWN = ACCOUNT.GET_MANY.bindParams(true);
+```
+
+Read through the route action, a slide loses its data as soon as there is
+[nothing to ask](./actions.md#nothing-to-ask-and-coming-back): while the layer
+closes, or as soon as the tab is left if the params follow it. The question standing,
+reopening finds the answer and sends nothing, unless the action's `keep` says that
+answer is too old.
+
+The cost is one request per read at each first opening, for tabs that may never be
+looked at. navi does not tell an application which slides a hand can bring in, so a
+row too heavy to ask for everything has no finer answer than this.
+
 ### A link inside the layer leads to a page
 
 The terms of use behind an About dialog, a profile behind a name in the

package/package.json

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