@jsenv/navi 0.29.82 → 0.29.84

package/docs/AI_INSTRUCTIONS.md

@@ -204,7 +204,9 @@ consistency across the app, not from any single call site.
   than a param, search params bound to signals, rendering with `<Route>`,
   tab rows (`Nav` / `Link` / `RouteTravel`), where a navigation lands
   (scroll: a push arrives at the top, a back or forward lands where the page
-  was left), and the few cases where tabs are legitimately not URLs. Read it before writing any routing code — the
+  was left), a back arrow that stays inside the app (`useCanNavBack()` /
+  `navBack({ fallback })`), and the few cases where tabs are legitimately not
+  URLs. Read it before writing any routing code — the
   position of the user belongs in the URL by default, and that decision is
   not retrofittable.
 - Source code and demos on GitHub:

package/docs/control_object.md

@@ -11,6 +11,7 @@ whose value is an object needs in its popup.
 - [`<Form>`: the shape, plus a send](#form-the-shape-plus-a-send)
 - [Naming, and what a nameless group does](#naming-and-what-a-nameless-group-does)
 - [A picker whose value is an object](#a-picker-whose-value-is-an-object)
+- [A settings sheet](#a-settings-sheet)
 - [`Group` is not `ControlGroup`](#group-is-not-controlgroup)
 
 ## `<ControlGroup>`: the shape
@@ -113,6 +114,88 @@ Two things to get right:
   object lands on one control, which is how `"[object Object]"` ends up in a
   url.
 
+## A settings sheet
+
+A popup that is not one choice but a handful of settings — four tabs, a select,
+a field, a button that answers with a place — and ONE answer, which must reach
+the app only when the popup closes. The list behind it must not move while it is
+open, and Escape must leave things exactly as they were found.
+
+Nothing new is needed for that: it is the object picker above, with the group in
+its popup. A picker's `action` runs on close and only on close (its `uiAction`
+follows every gesture, which is what the popup shows), so what is inside acts on
+nothing until the user is done.
+
+```jsx
+<Picker
+  type="object"
+  mode="dialog"
+  value={zone}
+  ui={<ZoneSummary zone={zone} />}
+  action={save}
+>
+  <ControlGroup>
+    <Nav slideContainer="zone_slides" currentIndicator>
+      <Link slide="city">Ville</Link>…
+    </Nav>
+    <Input type="hidden" name="origin" signal={originSignal} />
+    <SlideContainer id="zone_slides" signal={originSignal}>
+      <Slide area="city">
+        <Input name="city" />
+      </Slide>
+      …
+    </SlideContainer>
+  </ControlGroup>
+</Picker>
+```
+
+```js
+// what `save` receives, on close and once
+{ origin: "city", city: "Antibes", radius: "30", department: "" }
+```
+
+**Which tab is showing is part of the answer.** The same fields mean different
+things depending on the tab they were filled on, so the tab is a key of the
+value like the rest — a sheet handing back `{ city: "Antibes" }` without saying
+which tab it was left on has not said what was chosen. A tab bar is a navigation
+(`<Nav slideContainer>` + `<Link slide>`), so nothing in it is a field: the
+current area reaches the value through an `<Input type="hidden">` bound to the
+same signal as the container. That is what a hidden field is for — a
+piece of the answer with no control to be read from, here because the tabs are
+places rather than choices. A tab bar made of radios needs none: it is a field
+already, under its own name.
+
+That signal is written in both directions, which is what makes the sheet reopen
+where it was left: a value handed DOWN to a control writes it too — on open, and
+when Escape puts back what the picker held — so the tabs go back to the answer
+rather than staying on the one that was being tried.
+
+**Every field answers, including the ones the current tab does not use.** A
+field on another tab stays mounted, keeps what was typed in it, and comes back
+in the object. Which of them count is read from `origin` by whoever receives the
+value — the group has no opinion about it, and does not need one. Deriving
+something narrower (a stored string, an id) is that reader's business too:
+`action` receives the object and stores whatever it wants, `value` hands the
+object back.
+
+A group CAN be worth a single value of its own — `aggregateChildStates` and
+`distributeChildUIState`, see the top of this file — and a sheet is precisely
+where that is the wrong reach: it throws away the state that makes the answer
+readable, starting with the tab.
+
+**A button inside is not a field.** The one asking for a position acts on the
+press, like anywhere else; what it answers goes into a control that IS a field
+(a read-only one showing the place it found), and the group picks it up from
+there.
+
+The façade stays on what is saved by reading the app's own state
+(`value={zone}` + a `ui` rendered from `zone`), while the picker holds the
+draft: the summary behind the open dialog then shows the answer, not the
+attempt.
+
+Seen working — the tabs, the geolocation button, the cancel — in
+`control/demos/picker/9_picker_settings_sheet_demo.html`.
+
 ## `Group` is not `ControlGroup`
 
 Two names, two subjects, no relation:

package/docs/control_value.md

@@ -46,6 +46,15 @@ const minutesSignal = useSignal(0);
 minutesSignal.value = 30;
 ```
 
+"Every change" includes the ones the control did not decide: a group placing
+its children, a picker filling its popup at open, and the same picker putting
+back what it held when Escape cancels. The signal mirrors the control, so it
+always says where the control actually is — which is what lets a settings sheet
+reopen on the tab it was left on (see
+[control_object.md](./control_object.md#a-settings-sheet)). What it does NOT
+mirror is a picker's popup being played with: a picker's own signal is written
+when the picker commits, on close.
+
 Both halves are worth knowing about, because each replaces a habit:
 
 - the write-back replaces `uiAction={(v) => (mySignal.value = v)}`;
@@ -115,6 +124,10 @@ All of them: `Input` (every type), `Picker`, `Select`, `Wheel`, `Spin`,
 that is a navi control goes through the same state controller, and the same
 `signal` prop.
 
+`SlideContainer` takes one too, though it is layout rather than a control: the
+area it shows is a piece of state like any other, and binding it is what lets
+something else read where the slides are — or move them by writing it.
+
 Inside a `List selectable` you can bind the list, or give each `List.Item` its
 own `selected` — but not expect the two to arbitrate. An item that declares
 `selected` is answering for itself, and the list's signal does not reposition

package/docs/navigation.md

@@ -243,6 +243,63 @@ 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**. Only
+the navigation being applied says that, and navi is the one applying it — see
+the back arrow below, which is what that fact is usually needed for.
+
+## The back arrow: `navBack`
+
+An arrow drawn inside the app promises the screen the reader came from — never
+the page they were on before the app. Both cases are real for the same url: one
+descends into a profile from a list, or one opens it cold from a shared link, a
+bookmark, a notification. `history.back()` answers the first and, on the second,
+gives back the conversation the link came from.
+
+`window.history.length` cannot tell them apart — it counts the whole tab — and
+neither can an entry's state, for the reason just above. What answers is a count
+of how many entries of THIS document stand underneath, kept as the navigations
+are applied and written into each entry so it survives a reload mid-stack. navi
+keeps it: an app that kept its own would have to be told about every single
+`replace` it performs, and the one it forgets shows up only on a cold-opened
+screen after a precise gesture.
+
+```jsx
+const BackButton = () => {
+  const canNavBack = useCanNavBack();
+  ...
+};
+```
+
+`useCanNavBack()` (or `canNavBackSignal` outside a component) is reactive: the
+arrow appears and disappears as the stack moves, it is not decided at mount.
+
+```js
+navBack({ fallback: USER_ME_ROUTE.buildUrl() });
+```
+
+The `fallback` takes the place of the current entry rather than stacking on it:
+pushed, it would put the screen just left one press ahead, and the phone's own
+back button would walk straight back into it — a loop with no way out of the
+app. Without a `fallback`, a `navBack()` with nothing of ours behind does
+nothing.
+
 ## Tabs that travel: `RouteTravel`
 
 `<RouteTravel>` wraps the `<Route>` tree of a row of tabs and makes every change
@@ -276,9 +333,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.82",
+  "version": "0.29.84",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {