@jsenv/navi 0.29.372 → 0.29.374

package/docs/route_transitions.md

@@ -307,7 +307,11 @@ about the bar:
   that takes the whole screen (a full-screen wizard whose banner is its own
   header) is this case, on the way in and on the way back.
 
-The pages are ordered above the bars for that reason. The price of being
+The pages are ordered above a bar only one state has for that reason, and
+below a bar both states have: the frame stands over the pages as it does at
+rest, so what a bar paints outside its box — a button standing up out of a tab
+bar, a shadow on the page — is seen for the length of the movement instead of
+being cut at the bar's edge. The price of being
 photographed is that a bar cannot answer the pointer for those few hundred
 milliseconds, which is what a route transition wants anyway: both pages are
 pictures too, and a press landing on either would be an accident. `RouteTravel`
@@ -316,6 +320,21 @@ is the opposite case — a finger is on the box — and leaves the bars live.
 A bar the application names itself keeps its name and its own movement: navi
 names only what is unnamed.
 
+A **modal `Dialog` open on a page** is furniture of the same kind: its box is
+photographed on its own and travels with its page, or holds where it stands if
+both states have it. Its **wall** cannot be photographed (see
+[view_transitions.md](./view_transitions.md#the-top-layer-is-painted-through-the-roots-picture)),
+and dropping it for the movement makes the whole window blink under the press.
+So the wall is painted where it would be seen: into the pages' picture, into
+each bar's picture, and, for what no picture covers (the glass beside a
+narrowed app, the window below a short page), as a live element under the
+pictures that fades on the movement's clock. The outcome is derived from the
+pair of states like everything else here — a page leaving from under a wall
+leaves dimmed and the bars fade their dim with it; a page arriving under one
+arrives dimmed and the bars dim with it; a wall both states have holds. The real
+wall is switched off for exactly the length of the movement, so no frame shows
+two walls. Demo: [a dialog leaving with its page](../src/nav/demos/route_transition_dialog/route_transition_dialog.html).
+
 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

package/docs/view_transitions.md

@@ -11,6 +11,7 @@ they are met once.
 - [Rendering is suspended for the whole callback](#rendering-is-suspended-for-the-whole-callback)
 - [`finished` rejects when another transition replaces it](#finished-rejects-when-another-transition-replaces-it)
 - [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)
 
 ## A name is unique per document
 
@@ -85,3 +86,45 @@ past a few thousand pixels of scroll, which is how it hid). A transition that
 opens or closes a top-layer surface keeps the root's default name and pays the
 frozen page — under a modal wall that costs nothing. navi's own lift
 (`popup_lift.md`) does exactly that.
+
+When the root cannot be kept — a route transition splits the bars from the
+pages, which only works with the root opted out — the top layer has to be
+**stood in for**. A dialog's box is an element, so it can be named and
+photographed on its own. Its wall cannot: `::backdrop` wears no name. What
+works is painting what the wall paints into the pictures themselves: a plain
+element appended inside each photographed box (the pages, each bar) before
+each capture, and one `position: fixed` element in the live document for what
+no picture covers, with a hole cut where each picture stands. The live one is
+not a picture, so nothing cross-fades it: it is animated on the movement's own
+clock. Where a picture stands changes over the movement — the frame the first
+picture is taken on shows the leaving state, the last frame the arriving one,
+and in between only the intersection of the two states' rectangles is under a
+picture at every moment — so the holes are cut three times. Reference:
+`paintTransitionWalls` and `paintRestWalls` in `nav/transition_furniture.js`;
+the measured story is in [route_transitions.md](./route_transitions.md#pages-between-fixed-bars-the-transition-area).
+
+## Two frames show the live document
+
+A view transition is not pictures from the call to `finished`. **The frame the
+first picture is taken on is rendered and shown**, with the top layer painted
+as usual, and `:active-view-transition` already matches on it (it matches from
+the `startViewTransition` call). **The frame after the pictures are dropped is
+shown too**, before the `finished` callbacks run — they are a frame late.
+Whatever is switched on for the movement is therefore on screen one frame
+before the pictures and one frame after; anything it stands in for must be
+switched off for exactly the same span, or that frame shows both (measured: a
+wall twice as dark under the press, read as a flash).
+
+Two consequences for the switch itself:
+
+- **Switch both on the same DOM write**, at the same moment: an attribute set
+  before the call and removed in `finished`. The late frame then shows the
+  stand-in alone, which is what the real thing looked like — one frame nobody
+  can see.
+- **`:active-view-transition` is the only same-frame signal at the end**: it
+  stops matching in the rendering step that drops the pictures, before that
+  frame is painted. It is what to use when the last frame must differ from the
+  movement (see the holes above). It is NOT what to gate a stand-in's
+  `display` on: hidden before the call, a stand-in measures as a zero rect and
+  lands in the wrong place; and on the capture frame it is displayed while the
+  real thing is still there.

package/package.json

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