@jsenv/navi 0.29.141 → 0.29.143

package/docs/AI_INSTRUCTIONS.md

@@ -153,6 +153,16 @@ consistency across the app, not from any single call site.
   given a `ui` draws no placeholder of its own. Read it before putting a
   `BadgeList` in a picker's `ui`, before wrapping its fallback in a `Badge`,
   and before setting `maxLines` on the list rather than on the picker.
+- `docs/state_binding.md` — the rule the whole API rests on: state navi shows is
+  BOUND (`signal`), not copied back by a callback. The three shapes an
+  application ever has to say (`signal` / `action` / `command` + `commandFor`),
+  the four ways the same mistake is written (`onCurrentChange`, `uiAction`,
+  `onClick` and `onOpen`/`onClose` all writing a signal), why a binding is not
+  merely shorter (it is written by every gesture, it moves the component when
+  written, and it goes through the interaction gate), what is left for the
+  callback, and what to conclude when the state being wired has no prop for it —
+  a parallel copy, or a binding navi is missing. Read it before writing any
+  handler whose body only assigns state.
 - `docs/control_value.md` — who holds a control's value: nobody, a bound
   `signal` (two-way, in both directions), or you (`value`/`checked`). What
   `signal` + `defaultValue` says, what a signal holds for each kind of control,
@@ -282,9 +292,13 @@ consistency across the app, not from any single call site.
   is given back the offset it was read at, and only when the row owns the
   document scroll), 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.
+  URLs. It also holds the middle answer — a position READ from the URL and
+  restored on reload without a route and without an entry per step: a search
+  param signal handed to a `SlideContainer`, walked to rather than jumped to,
+  and `history: "push"` for the states whose values ARE places (with the write
+  that says otherwise, `signal.set(v, { history })`). 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:
   https://github.com/jsenv/core/tree/main/packages/frontend/navi — where to go
   when the built export's JSDoc doesn't answer the question (see "Where the

package/docs/actions.md

@@ -268,6 +268,9 @@ changes do exactly that).
 
 ## See also
 
+- [state_binding.md](./state_binding.md) — `signal`, `action` or
+  `command` + `commandFor`: the three shapes, and the callback that only
+  remembers
 - [resource.md](./resource.md) — actions created from REST callbacks, and the
   store behind them
 - [resource_with_params.md](./resource_with_params.md) — `withParams()` and

package/docs/control_value.md

@@ -243,7 +243,10 @@ that is a navi control goes through the same state controller, and the same
 
 `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.
+something else read where the slides are — or move them by writing it. Bind it
+to a `stateSignal` a route declares as a search param and the area is in the
+address, with no route per slide — see
+[navigation.md](./navigation.md#a-slidecontainer-in-the-url-a-position-that-is-not-a-place-one-came-from).
 
 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
@@ -348,6 +351,9 @@ directions; it just has nothing extra to say.
 
 ## See also
 
+- [state_binding.md](./state_binding.md) — the same rule beyond controls:
+  a `SlideContainer`'s area, a popup being open, the position in the app — all
+  bound rather than copied back by a callback
 - [form_changed.md](./form_changed.md) — what a form makes of each of these:
   which fields it counts as already answered, and when it sends nothing
 - [control_object.md](./control_object.md) — several controls reading as one

package/docs/css_architecture.md

@@ -41,7 +41,7 @@ This means an app can override a Navi default from its own unlayered CSS, withou
 }
 ```
 
-Targeting the same element is not a detail — see [`--navi-*` vs `--component-*`](#--navi-vs---component-where-the-override-has-to-go) below.
+Targeting the same element is not a detail — see [`--navi-*` vs `--component-*`](#--navi--vs---component--where-the-override-has-to-go) below.
 
 ### Why actual rules stay outside any layer
 

package/docs/navigation.md

@@ -3,6 +3,23 @@
 How to build navigation with `@jsenv/navi`: declaring routes, rendering them,
 linking to them, and turning them into tabs.
 
+- [The rule that decides everything else: the position belongs in the URL](#the-rule-that-decides-everything-else-the-position-belongs-in-the-url)
+- [Declaring routes](#declaring-routes)
+  - [A section is allowed to be a route of its own](#a-section-is-allowed-to-be-a-route-of-its-own)
+  - [Which values a param accepts](#which-values-a-param-accepts)
+  - [An address that only sends elsewhere](#an-address-that-only-sends-elsewhere)
+  - [Search params](#search-params)
+- [Rendering routes](#rendering-routes)
+  - [Loading data](#loading-data)
+- [Links and tab rows](#links-and-tab-rows)
+- [The back arrow: `navBack`](#the-back-arrow-navback)
+- [Tabs that travel: `RouteTravel`](#tabs-that-travel-routetravel)
+- [Where a navigation lands: the scroll](#where-a-navigation-lands-the-scroll)
+- [Creating something, then editing it](#creating-something-then-editing-it)
+- [Tabs that are not routes](#tabs-that-are-not-routes)
+  - [A `SlideContainer` in the URL: a position that is not a place one came from](#a-slidecontainer-in-the-url-a-position-that-is-not-a-place-one-came-from)
+  - [A state whose values ARE places: `history: "push"`](#a-state-whose-values-are-places-history-push)
+
 ## The rule that decides everything else: the position belongs in the URL
 
 Where the user is — which section, which tab, which sub-page — is state. Put it
@@ -21,8 +38,10 @@ retrofitted later:
 So the default shape of a tab row is routes: `<Nav>` + `<Link route>` +
 `<RouteTravel>`. `SlideContainer` is the exception, not the starting point — see
 [Tabs that are not routes](#tabs-that-are-not-routes) for the cases that
-genuinely are one, and for the middle answer: a position READ from the URL and
-restored on reload, without a route and without a history entry per step.
+genuinely are one, and
+[A `SlideContainer` in the URL](#a-slidecontainer-in-the-url-a-position-that-is-not-a-place-one-came-from)
+for the middle answer: a position READ from the URL and restored on reload,
+without a route and without a history entry per step.
 
 ## Declaring routes
 
@@ -289,6 +308,11 @@ Declared on the **root route**, a search param is a position that holds wherever
 one is in the application — a view mode that survives moving from page to page.
 Declared on one route, it exists only there.
 
+Writing it AMENDS the history entry one is on rather than stacking a new one: a
+param that qualifies a screen is not a place, and one entry per write turns a
+single back-press into as many as the user moved. A state whose values ARE
+places says so — see [`history: "push"`](#a-state-whose-values-are-places-history-push).
+
 ## Rendering routes
 
 `<Route>` is the only primitive. With `children` it is a container that renders
@@ -575,9 +599,9 @@ match at once; the first matching branch wins).
 ## Tabs that are not routes
 
 `SlideContainer` holds slides that replace one another in one box, with the same
-gestures and the same travelling bar, and — unless it is given a `urlParam`, see
-below — nothing written to the URL. Use it when the position genuinely is not a
-place one should be able to link to:
+gestures and the same travelling bar, and — unless the signal it is bound to is
+one the URL holds, see below — nothing written to the URL. Use it when the
+position genuinely is not a place one should be able to link to:
 
 - the steps of a wizard, or the screens of a picker, inside a dialog or a popover
   — a popup is promoted to the browser's top layer, so no container can hold two
@@ -604,7 +628,7 @@ page. It reads which slide is on screen from the container itself, and its bar
 follows the slides, a finger dragging them included. `<Link slide>` has no href
 and behaves like a button: this is not a link to anywhere.
 
-### The middle answer: a position in the URL that is not a place one came from
+### A `SlideContainer` in the URL: a position that is not a place one came from
 
 "Should a link be able to open the app on this?" has a third answer, and a wizard
 is exactly it: **yes for reading and for reloading, no for history.** The step one
@@ -615,48 +639,106 @@ and it should NOT stack an entry per step, because the back arrow of a form mean
 back-press into four, and walk the reader backwards through a form they thought
 they had left.
 
-Neither pure answer fits: routes would want one route per step, a real navigation
-per move (so a push per move), and the walk's own rules — a step held until it is
-answered, a confirmation reachable only by publishing — re-expressed as route
-guards. A plain `SlideContainer` writes nothing at all.
+There is nothing to invent for it: a search param already IS a position in the
+URL that replaces rather than pushes ([Search params](#search-params)). Declare
+the step as one, and hand its signal to the container:
 
-`urlParam` is that middle answer: the container owns one search param, writes
-where it stands into it **by replacement**, and opens on what it names.
+```js
+const stepSignal = stateSignal("when", {
+  id: "step",
+  oneOf: ["when", "where", "who", "recap", "done"],
+  // the step qualifies THIS visit, not the screen: a link built to the editor
+  // does not inherit the step one happens to be on, and it goes back to the
+  // default when the route stops matching
+  weak: true,
+});
+export const ALERT_EDIT_ROUTE = route("/alerts/:alertId/edit", {
+  searchParams: { step: stepSignal },
+});
+```
 
 ```jsx
-<SlideContainer id="alert_editor" signal={stepSignal} urlParam="step">
+<SlideContainer signal={stepSignal}>
 ```
 
-Two things it does that a `useEffect` calling `history.replaceState` beside the
-container cannot, and they are the reason it lives inside:
-
-- it writes the travels that HAPPENED. A travel a lock refused, or one the caller
-  refused late, never reaches the address — or is written back when it does;
-- it READS the param through the walk rather than jumping to it. The address
-  comes from outside the box (typed, shared, kept from a session that has moved
-  on), so every slide between here and there is asked to let go the way a key
-  going that way would ask it, and the first one that holds is where one stops.
-  `?step=done` cannot open a confirmation screen for something nobody sent — and
-  the address is then rewritten with the area actually shown, so it never says
-  one is somewhere one is not.
+That is the whole wiring, and every half of it is the piece that already
+existed. Worth naming, because each answers a question a wizard actually has:
+
+- **where it opens is the state's own default** — the first argument of
+  `stateSignal`. The container has a `defaultCurrent` for when it owns its
+  position, but a bound container does not own it: one place says where the step
+  starts, and it is the same place a reset goes back to;
+- **the param is absent while the step IS that default** (route.js prunes it), so
+  `/alerts/W-123/edit` is clean on the first step, gains `?step=where` on the
+  second, and loses it again coming back. The address carries what differs from
+  the usual answer and nothing else;
+- **the container walks to the step rather than jumping to it.** The address comes
+  from outside the box (typed, shared, kept from a session that has moved on), so
+  every slide between here and there is asked to let go the way a key going that
+  way would ask it, and the first one that holds is where one stops. `?step=done`
+  cannot open a confirmation screen for something nobody sent. The signal is then
+  written with the area actually shown, so the address never says one is
+  somewhere one is not;
+- **only the travels that HAPPENED are written.** A travel a lock refused, or one
+  `onCurrentChange` refused late, never reaches the signal — or is written back
+  when it does.
 
 A container remembers nothing across a reload, so a step whose `required` the app
 knows is already satisfied says so itself (`required={!alreadyFilled}`); the same
 holds for a hold that a finished job lifts (`preventNavNext={!published}`).
 
-`history: "push"` is the other half, for slides that ARE places one came from — a
-gallery one browses:
+**A start that depends on where one is** — a wizard creating something opens on
+its first question, the same wizard editing something opens on its summary — is
+not a prop on the container either: a `stateSignal` takes a SIGNAL as its default
+and follows it as long as nobody has answered otherwise.
 
-```jsx
-<SlideContainer urlParam={{ name: "photo", history: "push" }}>
+```js
+const stepDefaultSignal = computed(() =>
+  // `matchingSignal`, not `matching`: the plain property is a mirror, the
+  // signal is what a computed can follow
+  ALERT_EDIT_ROUTE.matchingSignal.value ? "recap" : "when",
+);
+const stepSignal = stateSignal(stepDefaultSignal, { id: "step", weak: true });
 ```
 
-Even there, a slide reached by DRAGGING replaces rather than pushes: swiping back
-and forth with a thumb is browsing, not a trail one wants to walk home along.
+The pruning follows it too, so both addresses stay clean on the step they open
+on — `/alerts/create` on "when", `/alerts/W-123/edit` on "recap" — and a step
+someone actually chose survives the default moving under it.
 
-What `urlParam` is not: a route. Nothing is declared, nothing matches, no page
-transition plays — what travels is the box, and the address is a label on where
-the box stands. A position several parts of the app must react to is still a
-route.
+Two containers on one screen are two signals, and that is the whole answer to
+"which one owns the param": the one holding the route's signal. A gallery of
+seven wizards side by side hands each of them a `useSignal` of its own, and
+nothing goes into the address.
+
+### A state whose values ARE places: `history: "push"`
+
+Replacement is the default because most URL-held state qualifies the screen one
+is on. A state whose values are places one came from — the photo being looked at
+in a gallery — says so where the state is declared:
+
+```js
+const photoSignal = stateSignal(undefined, { id: "photo", history: "push" });
+```
+
+Every write of it then stacks an entry, wherever the write comes from. Except
+where the writer knows this particular move is not one: a slide reached by
+DRAGGING replaces even in a container that pushes, because swiping back and forth
+with a thumb is browsing, not a trail one wants to walk home along. That is said
+at the write rather than declared:
+
+```js
+photoSignal.set(nextPhoto, { history: "replace" });
+```
+
+`SlideContainer` already does exactly that for its own drags, so a gallery gets
+it by declaring the state and nothing else.
+
+### What this is not
+
+It is not a route. Nothing is declared for the steps themselves, nothing matches
+on them, and no page transition plays — a transition needs the page to change
+([route_transitions.md](./route_transitions.md)), and a search param moving is
+not one. What travels is the box, and the address is a label on where the box
+stands. A position several parts of the app must react to is still a route.
 
 Demo: [../src/layout/demos/8_slide_container_demo.html](../src/layout/demos/8_slide_container_demo.html).

package/docs/popup_open.md

@@ -97,11 +97,24 @@ This is the same entry point the attributes go through: same target resolution,
 same command proxies, same events. The popup stays uncontrolled, and keeps its
 say over closing.
 
-`event` is the DOM event the decision came from. Pass it whenever there is one:
-it is chained into the request event, and that chain is what lets the popup
-handle focus correctly (which element to give focus back to, whether a
-mousedown's click must be swallowed). Omit it only when nothing user-initiated
-triggered the command.
+`event` is what caused the decision, and it is mandatory — triggering a command
+without one throws. It is chained into the request event, and that chain is what
+lets the popup handle focus correctly (which element to give focus back to,
+whether a mousedown's click must be swallowed) and what the debug panel groups
+the whole sequence under.
+
+Almost always there is a DOM event to hand over, because almost always something
+was done to the page. When there genuinely was not — a timer firing, an action
+settling, a signal changing — say so with a `CustomEvent` named after what
+happened rather than leaving the origin unsaid:
+
+```js
+import { chainEvent, triggerNaviCommand } from "@jsenv/navi";
+
+const expiredEvent = new CustomEvent("session_expired");
+chainEvent(expiredEvent, causeEvent); // when something did precede it
+triggerNaviCommand(dialogRef.current, "--navi-open", expiredEvent);
+```
 
 ## Which element receives the command
 

package/docs/state_binding.md

@@ -0,0 +1,142 @@
+# Bound, not wired
+
+Every piece of state navi shows already has a way in and a way out: the value in
+a control, the area a `SlideContainer` stands on, whether a popup is open, where
+the user is in the application. A callback whose whole body copies that state
+into a variable of your own is a second road beside one that exists — and from
+then on there are two owners for one truth.
+
+- [The three shapes](#the-three-shapes)
+- [The callback that only remembers](#the-callback-that-only-remembers)
+- [Why it is not merely shorter](#why-it-is-not-merely-shorter)
+- [What is left for the callback](#what-is-left-for-the-callback)
+- [What binds itself](#what-binds-itself)
+- [When there is no binding](#when-there-is-no-binding)
+
+## The three shapes
+
+Almost everything an application has to say about a component is one of three
+things, and each has its own prop:
+
+| what the code has to say                      | how it is said                             |
+| --------------------------------------------- | ------------------------------------------ |
+| this state is the app's, both ways            | `signal`                                   |
+| something HAPPENS when it changes             | `action` (`uiAction` for what cannot fail) |
+| a press asks something of a component near it | `command` + `commandFor`                   |
+
+Reaching for a handler that is none of the three — an `onClick`, an
+`onCurrentChange`, a `uiAction` writing a signal — is the sign that one of them
+was missed.
+
+## The callback that only remembers
+
+The same mistake, in four places:
+
+```jsx
+// ✗ the app is told where the slides went, and writes it back down
+<SlideContainer
+  current={step}
+  onCurrentChange={(area) => {
+    stepSignal.value = area;
+  }}
+/>
+// ✓
+<SlideContainer signal={stepSignal} />
+
+// ✗ the control is told what it now holds, and the app writes it back down
+<Picker value={side} uiAction={(value) => (sideSignal.value = value)} />
+// ✓
+<Picker signal={sideSignal} />
+
+// ✗ a button proposing a value to a control, straight into the signal
+<Button onClick={() => (durationSignal.value = ninetyMinutes)}>1h30</Button>
+// ✓
+<Button command="--navi-update" commandFor="duration" value={ninetyMinutes}>
+  1h30
+</Button>
+
+// ✗ the popup is told it opened, and the app writes it back down
+<Dialog
+  open={isOpen}
+  onOpen={() => (openSignal.value = true)}
+  onClose={() => (openSignal.value = false)}
+/>
+// ✓
+<Dialog signal={openSignal} />
+```
+
+In each pair the second line is not a tidier spelling of the first: it is the
+binding the component already implements, and the first is a partial
+re-implementation of it.
+
+## Why it is not merely shorter
+
+A binding is written by **everything that moves the state**, not only by the
+gesture the caller thought of. A `SlideContainer`'s signal is written by a drag,
+by an arrow key, by a `--navi-right` command sent from a chevron outside the
+box, by the address when the signal is a route's own, by a step refusing to be
+left. A control's
+signal is written by the user typing, by a group placing its children, by a
+picker committing on close, by a `--navi-update` from a shortcut button. A
+hand-written callback catches the cases it was written for and silently misses
+the rest — and the drift only shows on the screen where a second gesture was
+added.
+
+It reads in the other direction too, which no callback gives at all: writing the
+signal MOVES the component. The wheels roll, the slides travel, the popup opens.
+That is what replaces the `key` or the `value` prop pushed down to force a
+component into a state.
+
+And it goes through navi's interaction gate. A `command` on a read-only,
+disabled or busy control is refused and says why; an `onClick` doing the same
+write is plain DOM, fires on a greyed-out button and rewrites a value nobody was
+allowed to change.
+
+## What is left for the callback
+
+Binding the state does not remove the callback — it removes one job from it:
+
+- **`onCurrentChange` with a `signal` bound still fires**, and is still worth
+  writing: `cause` says whether the slide was pressed, dragged, or asked for by
+  the address — which is what tells a history push from a replace — and
+  returning `false` REFUSES the travel. Neither of those is state.
+- **`uiAction`** is for what moves with the value without being it: logging,
+  something else on screen following along. Not "remember it".
+- **`action`** is for what can fail or take time — it carries the busy state and
+  the error, which a `uiAction` does not (see
+  [actions.md](./actions.md#action-or-uiaction)).
+- **`onClick`** is for imperative work with nothing to send, nothing to open and
+  nothing to propose.
+
+## What binds itself
+
+| the state                         | how it binds                                                | where it is written up                                                                                               |
+| --------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| a control's value                 | `signal` (every control, every group)                       | [control_value.md](./control_value.md)                                                                               |
+| the area a `SlideContainer` is on | `signal` (a route's search param signal puts it in the URL) | its JSDoc, [navigation.md](./navigation.md#a-slidecontainer-in-the-url-a-position-that-is-not-a-place-one-came-from) |
+| a popup being open                | `signal`, `open`, `navState`                                | [popup_open.md](./popup_open.md)                                                                                     |
+| where the user is                 | route + search-param signals                                | [navigation.md](./navigation.md)                                                                                     |
+| a value proposed to a control     | `command="--navi-update"`                                   | [control_value.md](./control_value.md#a-button-that-proposes-a-value-is---navi-update)                               |
+| the state of an async run         | an `action`, read by `useAsyncData`                         | [actions.md](./actions.md)                                                                                           |
+
+## When there is no binding
+
+Sometimes the state being wired by hand has no prop for it. That is not a
+licence to wire it — it is a finding, and it is one of two:
+
+- the state is already held somewhere and the app is keeping a parallel copy of
+  it (the URL, the control itself, an action's own state) — the fix is to read
+  it where it lives;
+- or navi is genuinely missing a binding, and should gain one.
+
+Say which, rather than leaving a hand-wired callback behind: it is the version
+the next screen copies, and by then it is the app's pattern.
+
+## See also
+
+- [control_value.md](./control_value.md) — who holds a control's value, and what
+  a bound signal holds control by control
+- [actions.md](./actions.md#action-or-uiaction) — `action` or `uiAction`
+- [popup_open.md](./popup_open.md) — who owns the fact that a popup is open
+- [interactions.md](./interactions.md) — a gesture is named, not read by hand:
+  the same rule, one layer down

package/package.json

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