@jsenv/navi 0.29.365 → 0.29.367

package/docs/popup_lift.md

@@ -245,6 +245,15 @@ bound to is the shortest way to say it, the row's tiles carrying the matching
 ids. Left out, the box comes back where it came from, which is right exactly
 as long as nothing walked.
 
+When the walk signal is the address's — the popup's `signal`, so the sheet
+comes back open on the same card after leaving the page (see
+[popup_open.md](./popup_open.md#signal--the-app-holds-it-both-ways)) — a close
+that comes through the address, the back button, empties it before the popup
+knows it is closing, and a name built from it at that render says nothing:
+the box flies home into the first tile. Name the tile from the last key the
+walk held — a ref written while the signal holds one — not from the signal
+itself.
+
 **A press on the surface that dismisses is `data-navi-popup-outside`.** Marking
 the see-through box as backdrop (see
 [popup_backdrop.md](./popup_backdrop.md)) is read on the press itself. A close

package/docs/popup_open.md

@@ -875,6 +875,14 @@ the id from the signal, a card's press writes it, and the popup never writes
 over it: opening writes `true` only into a signal that reads closed, closing
 writes `undefined` (or `false`, where the signal held `true`).
 
+When the popup is opened ON a card (`<Button command="--navi-open" value={id}>`),
+`onOpen` is where the id is written: it runs before the popup writes its own
+open, and a signal that already reads open is left as it is — the address holds
+the card, never `true`. With the route's search-param `stateSignal` as the walk
+signal, that is how [a row of
+cards](./popup_lift.md#a-row-of-cards-one-popup-that-walks) survives leaving
+the page: the address names the card, and the sheet reopens on it.
+
 ```jsx
 <SidePanel signal={errorOpenSignal} side="right">
   <ErrorPanel /> {/* reads errorOpenSignal.value to know which card */}
@@ -892,8 +900,13 @@ finds the popup as it was, and so does a reload. `true` stores it under the
 popup's own `id`; a string names the key instead. `{ type: "push" }` makes the
 opening an entry of its own — the back button then closes the popup rather than
 leaving the screen, and the cancel takes back with it whatever was written to
-the url while it was open. A `Picker` needs none of this: its popup's open state
-is nav state by construction.
+the url while it was open. A `Picker` given an `id` needs none of this: its
+popup's open state is nav state by construction, under that id, and in dialog
+mode the opening is an entry of its own. Without an `id` the key is a generated
+one, which names one mount: the page left with the picker open and come back to
+is a new mount with a new id, and the state stays in the entry with nothing to
+read it — navi warns when a mount finds such a key. A picker whose popup leads
+somewhere, a link inside it, has an `id`.
 
 The two meet when the signal IS a route's: a search-param `stateSignal` given to
 `signal` puts the open state in the address itself, where a link can point at

package/docs/route_transitions.md

@@ -17,6 +17,7 @@ Demos: [the movements](../src/nav/demos/route_transition/route_transition.html),
 - [Choosing a movement](#choosing-a-movement)
 - [A default transition — when](#a-default-transition--when)
 - [When one navigation knows better](#when-one-navigation-knows-better)
+- [A traversal retraces its crossing](#a-traversal-retraces-its-crossing)
 - [Pages between fixed bars: the transition area](#pages-between-fixed-bars-the-transition-area)
 - [Custom movements](#custom-movements)
 - [Two routes matching one url](#two-routes-matching-one-url)
@@ -62,13 +63,10 @@ Leave the `from` out:
 defineRouteTransition(null, SETTINGS_PAGE, "cover-top");
 ```
 
-Arriving there plays forward from wherever, leaving plays back to wherever. The
-back half is what this exists for: closing such a page is almost always a back —
-the close button running `--navi-nav-back`, the browser's back button, a swipe —
-and a traversal carries no link and therefore no request, so `routeTransition` on
-the way in has no counterpart on the way out. Written on the destination, the way
-out is found the same way the way in was, with nothing to remember per history
-entry.
+Arriving there plays forward from wherever, leaving plays back to wherever. A
+back out of it retraces the crossing that opened it (see
+[A traversal retraces its crossing](#a-traversal-retraces-its-crossing)); a link
+out of it, to wherever, finds the relation the same way the way in did.
 
 It is tried last, after every written pair, so a pair naming the same destination
 still owns its crossing — the map, where it was drawn, is more precise than "from
@@ -151,8 +149,9 @@ in both directions, with one direction common and one rare:
   out.
 
 Written for the common direction, the rare one plays backwards. And `"none"`
-cannot fix it: navi does not tell a link from the back button, so silencing the
-bad direction silences the good one too.
+cannot fix it: a relation written for a way holds for every crossing of it,
+the back button's included (see below), so silencing the bad direction
+silences the good one too.
 
 So the navigation itself may ask, and what it asks holds for **that navigation
 and no other**:
@@ -189,8 +188,9 @@ the routes say, and a link that asks for a movement gets it, forward unless it
 says otherwise. That is the whole shape of the control:
 `defineRouteTransition` is what the app's map says and applies by default; a
 link, or a programmatic `navTo`, overrides it for the length of one navigation.
-Navigate again by any other means and the relation is back in charge — nothing
-is remembered.
+Navigate again by any other means and the relation is back in charge — with one
+exception, which is what makes a request complete: a history traversal undoing
+that navigation plays what it asked for, reversed (next section).
 
 The link wears what it asks as an attribute, so a plain `<a>` says it too (a
 type name, or the object as JSON):
@@ -203,10 +203,56 @@ type name, or the object as JSON):
 
 **Not yet: a movement chosen by HOW one navigated.** Playing one movement for
 the back button and another for a link would be written on the same request —
-`{ back: "slide-x", forward: "slide-y" }` — but the History API does not say
-which way a traversal went, and navi runs on it today (see
-`browser_integration/via_history.js`). The Navigation API does; the notation is
-kept in mind for the day navi navigates through it.
+`{ back: "slide-x", forward: "slide-y" }`. The notation is kept in mind for the
+day it is asked for.
+
+## A traversal retraces its crossing
+
+The back button, `navBack()`, `history.back()`, the browser's "next": a
+traversal is not a walk on the map, it undoes one (or redoes one). The entry a
+push creates remembers the crossing that created it — what played, which way,
+from which url — in its own state. A back onto the page that crossing came
+from plays it reversed; a forward onto an entry whose crossing came from the
+page being left plays it again as it was.
+
+That replay outranks everything the relations **deduce**, and nothing the
+author **wrote** for that exact way:
+
+| back from B to A                                | plays                         |
+| ----------------------------------------------- | ----------------------------- |
+| nothing written for `B → A`                     | the way in, reversed          |
+| `B → A` written from anywhere (`null → …`)      | the way in, reversed          |
+| `B → A` covered by a default transition         | the way in, reversed          |
+| the way in asked for by a link (`direction: …`) | what the link asked, reversed |
+| `defineRouteTransition(B, A, "none")`           | nothing                       |
+| `defineRouteTransition(B, A, "flip")`           | flip, forward                 |
+
+The line is drawn there because the two halves answer two different needs.
+Reciprocity is the default, and the one tool for breaking it is writing the
+way back by hand — so that tool must reach the back button, which is the way
+back most often taken: a `"none"` written for `B → A` silences every return
+from B to A, whatever pressed it. Everything else `findRelation` answers is a
+deduction from a sentence about something else (the reverse of a pair, a
+destination reached from anywhere), and a traversal that knows the crossing it
+undoes knows better than a deduction.
+
+What this settles:
+
+- a page reached from anywhere whose links walk the map the other way (the
+  author of a place's sheet, from the place): the link says
+  `routeTransition={{ direction: "forward" }}`, and the back undoes exactly
+  that — there is no reverse pair to write, and none that would collide with
+  the other pages reaching the place;
+- a `routeTransition` request covers its own way back: a request is about one
+  crossing, so nothing written for the pair outranks its replay;
+- the "two ways of a pair" trade-off above is about pairs written in one
+  direction: the reverse is deduced, and the traversal wins over it.
+
+The relations alone answer a traversal that retraces no remembered crossing:
+several entries at once, or an entry another document wrote. And a link to the
+page one just came from is a traversal too where the browser exposes its stack
+(navi turns such a push into a back, see `browser_integration/via_history.js`),
+so it retraces as the button does — under the same rule.
 
 ## Pages between fixed bars: the transition area
 

package/package.json

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