@jsenv/navi 0.29.413 → 0.29.415

package/docs/AI_INSTRUCTIONS.md

@@ -77,15 +77,20 @@ to start when unsure which export solves a problem.
   writing any routing code, and before scrolling to an element on arrival.
 - `route_transitions.md` — a transition states a relation the user reads as a
   map; a pair of routes is animated by `RouteTravel` or by a transition, never
-  both; a test waits for the page arriving, never for its address. Read before
-  animating a navigation, and before believing a symptom that only appears once
-  a pair is animated.
+  both; a test waits for the page arriving, never for its address; the page
+  being left stays mounted, hidden, until the movement is over (so what it
+  registers globally must let the last arrival win); what a transition costs.
+  Read before animating a navigation, before writing a custom movement, and
+  before believing a symptom that only appears once a pair is animated.
 - `view_transitions.md` — what the browser does to any transition an app
   starts itself: names unique per document, the fallback fade, rendering
   suspended for the whole callback, `ready` rejecting on a skip while
   `finished` fulfills, the top layer painted only through the root's picture,
-  and the two frames that show the live document. Read before calling
-  `document.startViewTransition`.
+  the two frames that show the live document, what makes the start of a
+  transition restyle the whole document (an unscoped `::highlight()`, a value
+  changed on `:root`), and a hidden popup photographed on one side only. Read
+  before calling `document.startViewTransition`, and before putting a value on
+  `:root` for a movement.
 - `drag_to_travel.md` — a pointer or a wheel pushing a whole screen aside, and
   who owns a press several boxes want. Read before putting anything that reads the pointer
   inside a box that travels.

package/docs/autofocus.md

@@ -15,6 +15,7 @@ at the end of this page.
 - [What a field says about itself](#what-a-field-says-about-itself)
 - [When the opening places nothing](#when-the-opening-places-nothing)
 - [The ring is decided too](#the-ring-is-decided-too)
+- [When a popup closes](#when-a-popup-closes)
 - [Moving the focus yourself](#moving-the-focus-yourself)
 
 ## What we want
@@ -202,6 +203,24 @@ focused while the input is). Style the standard name and you get that for free.
 }
 ```
 
+## When a popup closes
+
+The focus goes back to what held it when the popup opened — the trigger, most
+of the time — so the user carries on where they were.
+
+A popup that closes because it **leaves the tree** — its component unmounted,
+the page holding it left — gives the focus back once that change is over, and
+only to an element still in the document: the trigger often leaves in the same
+render, and focusing it just before it goes would be focusing nothing (and
+making its removal cost more). It gives the focus back only into a void, too:
+when something else took the focus meanwhile — the page arriving, focusing a
+field of its own — that one keeps it.
+
+So `{editing && <Dialog open>…</Dialog>}` unmounted from a button inside it
+lands the focus back on the button that opened it, and a dialog left along
+with the page around it lands it nowhere (`<body>`), exactly as if the page
+had simply been removed.
+
 ## Moving the focus yourself
 
 Prefer saying where the focus belongs over moving it: `autoFocus` on the field

package/docs/route_transitions.md

@@ -23,7 +23,9 @@ Demos: [the movements](../src/nav/demos/route_transition/route_transition.html),
 - [Two routes matching one url](#two-routes-matching-one-url)
 - [Route transitions and `RouteTravel` — one pair, one system](#route-transitions-and-routetravel--one-pair-one-system)
 - [A transition says nothing about data](#a-transition-says-nothing-about-data)
+- [The page being left stays until its movement is over](#the-page-being-left-stays-until-its-movement-is-over)
 - [Waiting for a navigation: the address is not the page](#waiting-for-a-navigation-the-address-is-not-the-page)
+- [What a transition costs](#what-a-transition-costs)
 - [The rest, briefly](#the-rest-briefly)
 
 ## What a transition is for
@@ -417,6 +419,23 @@ pages so the sheet comes over it (see the transition area above). The shipped
 `cover-*` types say exactly this; a movement where neither page covers the
 other publishes nothing.
 
+Those three values are read by navi from the root, so they are written there,
+and navi registers them as not inherited: writing them costs nothing. Any other
+value a custom movement's pictures read goes on `::view-transition` instead:
+
+```css
+:root[data-navi-route-transition-type="spin"] {
+  &::view-transition {
+    --spin-turns: 0.5;
+  }
+}
+```
+
+The pictures inherit it from there, and no element of the document does.
+Written on the root, every element would, and the page being left would be
+restyled in full in the frame it is photographed (see
+[What a transition costs](#what-a-transition-costs)).
+
 ## Two routes matching one url
 
 A relation is written between two pages, and it is resolved through **which page
@@ -516,6 +535,49 @@ below. 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 page being left stays until its movement is over
+
+The picture of the page being left is taken before the change; the page
+arriving is built inside the transition's update callback, and everything done
+there delays the first frame of the movement. Taking a page down is a large
+part of it — every hook of every component in it cleaned up: on a page of
+thirty game cards, about 67 of the callback's 90 ms with the CPU throttled 4×,
+more than building the page arriving. Its picture already exists, so it only
+has to stay out of the second one: a container that changes page during the
+callback keeps the page it was showing, hidden (`display: none`), and takes it
+down once the movement is over (`keepLeavingPages` in `nav/route.jsx`).
+Measured on that page, first frame of the movement: 63 → 45 ms at full speed,
+211 → 188 ms at 4×.
+
+What that means for a page and for the application around it:
+
+- **It is still mounted for the length of the movement.** Its effects keep
+  running, and it still reads the address: whatever re-renders when the URL
+  changes re-renders in it too, hidden (see
+  [What a transition costs](#what-a-transition-costs)).
+- **It is taken down after the page arriving is up.** A cleanup that puts back
+  what it found — a document title, a class on `<body>`, a value in a shared
+  store — puts a stale value back over the new page's. Such a registration is
+  written as "the last to arrive wins": navi's `<Head>` keeps its titles as a
+  stack, and a slot shows the last `SlotFill` to arrive.
+- **What it fills outside its own nodes leaves at once.** A `SlotFill` in a
+  page kept while leaving steps out of its slot, so a bar each page fills shows
+  the page arriving — or nothing, when that page fills none.
+- **Its popups leave with it.** A popup it holds open is no longer rendered: it
+  is photographed on the old side only, leaves with its page, and is closed
+  when the page is taken down (see
+  [view_transitions.md](./view_transitions.md#a-hidden-element-is-not-photographed-even-in-the-top-layer)).
+- **The focus it holds goes where its removal would have sent it** — to no
+  element — when it is hidden: a hidden element keeps the focus otherwise,
+  and would receive the keys pressed during the movement.
+- **Never while a modal dialog is open.** An open modal keeps everything but
+  itself out of reach — the page arriving could not even take the focus — and
+  one in a page kept while leaving would stay open for the whole movement. The
+  page is then taken down at once, as without a movement.
+- **Only where the page would have been taken down anyway.** A page rendered by
+  the same element on both sides — two routes, one component — is the same
+  instance carried over, as without a movement.
+
 ## Waiting for a navigation: the address is not the page
 
 A navigation changes the URL first and the screen after — always. Under a
@@ -559,10 +621,48 @@ without a movement is a real one every time. No thumb moves in one frame; an
 automated click continues in the same millisecond. This is a testing trap, not
 a user-facing behaviour.
 
+## What a transition costs
+
+A transition adds one frame to a navigation: the browser photographs the page
+being left at its next rendering opportunity, and the page arriving is built
+only then, inside the update callback. Anything beyond that is avoidable, and
+each of these was measured doing it on a list of thirty cards (~4,700
+elements):
+
+- **Restyling the whole page being left in the frame it is photographed** —
+  17–21 ms at full speed, 60–90 ms at 4× CPU. Two browser facts cause it: a
+  `::highlight()` rule every element matches, and a custom property changed on
+  the root as the movement starts (see
+  [view_transitions.md](./view_transitions.md#what-makes-a-transition-restyle-the-whole-document)).
+  navi's movements declare nothing inheritable on the root; a custom type
+  publishing values of its own writes them on `::view-transition` (see
+  [Custom movements](#custom-movements)).
+- **The page being left reacting to what the navigation changed.** Every
+  component in it that re-renders on the change does so inside the update
+  callback, next to the page arriving being built. A link or a button pointing
+  at a route (`<Link route>`, `<Button route>`) reads one flag — whether it is
+  current — and stays still unless that flips: a profile opening leaves the
+  links to a hundred other profiles exactly as they were (on the list of
+  thirty cards: 90 re-renders gone, first frame 58 → 41 ms). What else reacts
+  is worth keeping to what has to — measured: every card of the page being
+  left re-rendering when the page arriving loads its own games into the store
+  the cards read theirs from.
+- **Re-rendering what did not change, on the press itself.** A component that
+  only wants a yes or a no reads a computed flag, not the signal it is derived
+  from: a list whose rows each read the count of runs in flight re-rendered
+  all thirty cards twice when a link in one of them was pressed — 774
+  component renders before the navigation even started, 18 once the rows read
+  whether the list is full instead.
+- **Nothing is gained by starting at the press.** The click's own work is the
+  navigation, and the picture can only be taken on the frame after it; work
+  moved to the pointer-down is paid again, for nothing, by every press that
+  turns into a scroll.
+
 ## The rest, briefly
 
 - Pace: `--navi-route-transition-duration` (CSS, default 300ms) for everyone;
-  a per-relation `{ type, duration }` for one relation.
+  a per-relation `{ type, duration }` for one relation, worn by that
+  movement's pictures only.
 - The URL leads: transitions play on navigations somebody else started (a
   `<Link>`, the back button, `history.back()`). Nothing here navigates.
 - A browser without view transitions navigates with a cut. The app

package/docs/view_transitions.md

@@ -12,6 +12,8 @@ they are met once.
 - [`ready` rejects when the transition is skipped, `finished` when the update fails](#ready-rejects-when-the-transition-is-skipped-finished-when-the-update-fails)
 - [The top layer is painted through the root's picture](#the-top-layer-is-painted-through-the-roots-picture)
 - [Two frames show the live document](#two-frames-show-the-live-document)
+- [What makes a transition restyle the whole document](#what-makes-a-transition-restyle-the-whole-document)
+- [A hidden element is not photographed, even in the top layer](#a-hidden-element-is-not-photographed-even-in-the-top-layer)
 
 ## A name is unique per document
 
@@ -129,6 +131,65 @@ Two consequences for the switch itself:
   lands in the wrong place; and on the capture frame it is displayed while the
   real thing is still there.
 
+## What makes a transition restyle the whole document
+
+Starting a transition restyles what changed and nothing more: in a bare page,
+the capture of the old state restyles a handful of elements, however long the
+page is. Two things make it restyle every one of them, in the frame the old
+state is photographed — on a page of ~4,700 elements, 17–21 ms at full speed
+and 60–90 ms with the CPU throttled 4×, added to every transition before
+anything moves:
+
+- **A `::highlight()` rule every element matches.** Written for the whole
+  document, `::highlight(x) { … }` makes Chrome restyle every element when a
+  view transition starts (Chrome 153, bare page: 10,009 of 10,009 elements; 6
+  once the rule is scoped). Scope it to the elements that hold the ranges —
+  `.results::highlight(x), .results ::highlight(x)` (both: a browser without
+  highlight inheritance only paints what the rule matches). navi's own search
+  highlight is scoped to list rows.
+- **A custom property changed on `:root`.** Every element inherits it, so
+  changing one restyles the document — and a movement changes its values as it
+  starts. What the pictures read belongs on `::view-transition` instead: the
+  pseudo-element tree inherits from it, and no element of the document does.
+
+  ```css
+  :root[data-my-movement] {
+    &::view-transition {
+      --my-distance: 120px;
+    }
+  }
+  ```
+
+  A value computed in JS cannot get there through an inline style, which
+  cannot target a pseudo-element: it goes in a rule of a sheet of its own,
+  `:root::view-transition {}`, set with `rule.style.setProperty()` (navi does
+  this in `nav/transition_values.js`).
+
+  A value JS has to read back is the exception: what JS reads off
+  `::view-transition` is not reliable outside a live transition —
+  `getComputedStyle(root, "::view-transition")` answers while none runs, but
+  in Chrome and WebKit alike it went on answering empty for rules added after
+  its first read. Such a value stays on `:root`, registered with `@property`
+  and `inherits: false` so that the document does not inherit it, and is
+  handed to the pictures explicitly: `--x: inherit` on `::view-transition` and
+  on the pseudo-elements below it.
+
+Whatever does depend on the root is paid once, by the frame of the capture —
+unless a style read follows a write on the root, which forces the restyle on
+the spot, in the click. Read what the transition needs (names, rectangles)
+before writing anything on the root.
+
+## A hidden element is not photographed, even in the top layer
+
+A popover or a modal `<dialog>` whose ancestor is `display: none` still matches
+`:popover-open` or `:modal`, but it is not rendered: `checkVisibility()` is
+false, its rectangle is empty, and a transition taking its pictures then has it
+on the old side only — it leaves, as if it were gone. `isConnected` says
+nothing about it; `checkVisibility()` is what tells which of the two states an
+element is part of. navi relies on it to keep the page left by a route
+transition mounted but out of the second picture (see
+[route_transitions.md](./route_transitions.md#the-page-being-left-stays-until-its-movement-is-over)).
+
 ## See also
 
 - [route_transitions.md](./route_transitions.md) — pages moving against each

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.413",
+  "version": "0.29.415",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {
@@ -34,7 +34,7 @@
     "preact": "^11.0.0-rc.2"
   },
   "dependencies": {
-    "@jsenv/dom": "0.17.82",
+    "@jsenv/dom": "0.17.83",
     "@jsenv/humanize": "1.8.6",
     "@jsenv/validity": "0.4.5"
   },