@jsenv/navi 0.29.81 → 0.29.83

package/docs/autofocus.md

@@ -9,6 +9,7 @@ decision.
 - [A popup that is read before it is filled](#a-popup-that-is-read-before-it-is-filled)
 - [The most precise wins](#the-most-precise-wins)
 - [On a touch device: the surface is what one arrives on](#on-a-touch-device-the-surface-is-what-one-arrives-on)
+  - [Opting a field back in](#opting-a-field-back-in)
 - [What a field says about itself](#what-a-field-says-about-itself)
 - [When the opening places nothing](#when-the-opening-places-nothing)
 
@@ -100,14 +101,33 @@ the terms checkbox, the submit button. Landing there scrolls the popup to it and
 the title is above the top edge again, keyboard or no keyboard. The cause
 changes, the user sees the same thing.
 
-Nothing to pass, and nothing to remember per call site. Whatever really is what
-the user came for still says so with its own `autoFocus`, which is where that
-decision belongs.
+Nothing to pass, and nothing to remember per call site.
+
+### Opting a field back in
+
+Some popups really are opened to type in: one comment box, one rename field.
+There, the field says so itself, and that beats the device — step 2 of the
+ladder comes before step 3 was ever skipped.
+
+```jsx
+<Dialog>
+  <Heading>Leave a comment</Heading>
+  <Textarea name="comment" autoFocus />
+</Dialog>
+```
+
+Worth saying out loud before writing it: a popup holding one field is not
+necessarily a popup opened to fill it — it is often opened to READ what the
+field holds, and raising the keyboard over it then costs the reading for nothing.
+The default answers that case; `autoFocus` on the field answers the other, and
+saying which is which is the caller's to make because nothing about the markup
+can tell them apart.
 
 ## What a field says about itself
 
-- `autoFocus` — "I am what the user came for". A picker's search box on a
-  desktop, the one field of a one-field popup.
+- `autoFocus` — "I am what the user came for". A picker's search box, the field
+  of a popup opened to type in it. It holds on a touch device too: it is how a
+  field opts back into a keyboard the surface would otherwise keep down.
 - `autoFocus="restore"` — "never on a fresh open, but bring me back". A field
   the user was typing in when a popup over it closed: reopening returns to it,
   opening for the first time does not raise a keyboard on it.

package/docs/navigation.md

@@ -243,6 +243,27 @@ gives it a `view-transition-name` of its own: the browser then moves it on the
 same clock as any transition playing — including a `RouteTravel` swipe, with no
 wiring between the two.
 
+A row of tabs is a lateral move: the neighbour is one finger away, and going
+there is not going one step deeper. `replace` says exactly that — the
+destination takes the place of the current history entry instead of stacking
+onto it, so the whole row weighs one entry and the back button (the arrow at the
+top, the phone's own) leaves by where the reader came in:
+
+```jsx
+<Link route={CANDIDATE_GAMES_ROUTE} variant="tab" replace>
+  Candidatures
+</Link>
+```
+
+The link stays a link — an address, a middle click, the keyboard, `aria-current`
+— only the way there changes. It is the same word as `navTo(url, { replace:
+true })` and `route.redirectTo()`.
+
+A replaced entry inherits the state of the one it takes the place of (so does
+`route.redirectTo()`): **an entry's state does not say how it arrived**. An app
+keeping its own count of how deep it stands cannot read it back from
+`history.state` — it has to write it down as it navigates.
+
 ## Tabs that travel: `RouteTravel`
 
 `<RouteTravel>` wraps the `<Route>` tree of a row of tabs and makes every change
@@ -276,9 +297,10 @@ place, not a step along the row, and it plays no movement. `axis="y"` lays the
 pages out as a column instead: forward is then the page rising and the next one
 coming up from below.
 
-A swipe **replaces** the current history entry (a gesture browses; a tab pressed
-aims at a place and pushes, which its `<Link>` already does). `onTravel` decides
-otherwise.
+A swipe **replaces** the current history entry, and a tab pressed says the same
+thing when its link asks for it (`<Link replace>`, see above) — the two gestures
+towards the same neighbour must not write two different histories. `onTravel`
+decides otherwise.
 
 Several `RouteTravel` boxes may live on one page — a section of the path and a
 search param of the root route are two rows of tabs, both live — and only the one

package/package.json

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