@jsenv/navi 0.29.44 → 0.29.46

package/docs/control_value.md

@@ -102,6 +102,12 @@ attribute:
 A group (a selectable list, a checkbox group) writes its whole selection into
 the signal, not one item's value — its children put it together between them.
 
+A `<Form>` (or a `<ControlGroup>`) takes one the same way, holding the whole
+object: its named children are filled from it, they move when something else
+writes it, and what they change is written back into it. One signal for a screen
+whose values arrive together — see
+[create_and_edit.md](./create_and_edit.md#two-screens-two-states).
+
 ## Which controls take a `signal`
 
 All of them: `Input` (every type), `Picker`, `Select`, `Wheel`, `Spin`,

package/docs/create_and_edit.md

@@ -0,0 +1,468 @@
+# Creating a resource, then editing it
+
+The loop almost every application has: a screen that creates something, the page
+of the thing just created, and a screen that edits it. It is worth a page of its
+own because what makes it hard is not the form — it is that **the two screens
+look like the same form and are not the same thing at all**: one holds a draft
+the person is writing, the other holds a resource the server owns.
+
+Working example:
+[../src/control/demos/integration/create_then_edit/create_then_edit.html](../src/control/demos/integration/create_then_edit/create_then_edit.html)
+— the whole loop, with a backend on the page answering by hand so the loading
+and the failures can be looked at.
+
+- [What the loop owes the person](#what-the-loop-owes-the-person)
+- [The routes](#the-routes)
+- [The resource](#the-resource)
+- [Two screens, two states](#two-screens-two-states)
+- [The edit screen opens before its values](#the-edit-screen-opens-before-its-values)
+- [A field that picks from a list too big to load](#a-field-that-picks-from-a-list-too-big-to-load)
+- [Where each screen goes next](#where-each-screen-goes-next)
+- [After a write: what goes back to the network](#after-a-write-what-goes-back-to-the-network)
+- [Movement between them](#movement-between-them)
+
+## What the loop owes the person
+
+The rules below are what the rest of this page is for. Each one is a decision
+about what the person is owed, not about navi.
+
+- **Creating lands on what was created.** Going back to the list after a
+  creation asks the person to find their own thing to be sure it exists; the
+  thing itself is the proof, and it is also where they were heading.
+- **A draft is theirs until it is sent, and not a minute longer.** Half a form
+  filled must survive a reload (it is in the url), and must be gone the next
+  time "create" is opened — a create screen showing the last thing created is a
+  screen nobody trusts.
+- **Saving goes back to the thing, and so does a press that had nothing to
+  send.** The person is done either way; refusing to move because "nothing
+  changed" makes them press again to find out why.
+- **Cancelling puts back what the server says**, not what was typed and
+  abandoned. What leaving with unsaved changes does is a decision each screen
+  takes: dropping them is right when they are a few fields the person chose to
+  leave (that is what the shape below does, for free — the screen is thrown
+  away), and worth a confirmation when they are half an hour of work.
+- **What was written shows up everywhere at once.** A name changed on one screen
+  and stale on the list two seconds later reads as data loss. Some of that is
+  free (the store), some of it is a request the backend has to answer (a list
+  after a creation) — see [after a write](#after-a-write-what-goes-back-to-the-network).
+- **A failure is shown where the thing was asked for**, with what was typed
+  still there: an error on a form that emptied itself is worse than the failure.
+- **Every screen is a url.** Reload, back, a link sent to someone — the screens
+  of this loop are places, and the movement between them says how they are
+  related.
+
+Each of them has a mechanism below, and each mechanism is a line of code, not a
+framework.
+
+## The routes
+
+Four places, and each of them is a url someone can open, reload or share:
+
+```js
+const HOME_ROUTE = route("/");
+const NEW_GAME_ROUTE = route("/games/new", {
+  searchParams: {
+    name: nameSignal,
+    level: levelSignal,
+    players: playersSignal,
+  },
+});
+const GAME_ROUTE = route("/games/:gameId");
+const EDIT_GAME_ROUTE = route("/games/:gameId/edit");
+setupRoutes([HOME_ROUTE, NEW_GAME_ROUTE, GAME_ROUTE, EDIT_GAME_ROUTE]);
+```
+
+The create screen declares its fields as **search params**: a draft that
+survives a reload and travels in a link. The edit screen declares none — its
+values belong to the resource, not to the position.
+
+Two facts about matching decide the rest, and both surprise:
+
+- **Several routes match at once.** A route matches by prefix, so `/` is still
+  matching on `/games/2/edit`, and `/games/new` is also a `/games/:gameId`.
+  That is what keeps a section active while one is inside it.
+- **The first that matches wins**, in the order it is written — the `<Route>`
+  children, and the pages of a travel row alike. So they go from the most
+  precise to the widest:
+
+```jsx
+<Route>
+  <Route route={EDIT_GAME_ROUTE} element={EditGamePage} />
+  <Route route={NEW_GAME_ROUTE} element={NewGamePage} />
+  <Route route={GAME_ROUTE} element={GamePage} />
+  <Route route={HOME_ROUTE} element={HomePage} />
+</Route>
+```
+
+Same thing for what a route LOADS: the loader of `/games/:gameId` must step
+aside on `/games/new`, which is a page and not a game.
+
+```js
+const GAME_OF_ROUTE = routeAction(
+  [GAME_ROUTE, EDIT_GAME_ROUTE],
+  GAME.GET,
+  () => {
+    if (NEW_GAME_ROUTE.matchingSignal.value) {
+      return null; // "new" is not an id
+    }
+    const gameId =
+      GAME_ROUTE.paramsSignal.value.gameId ||
+      EDIT_GAME_ROUTE.paramsSignal.value.gameId;
+    return gameId ? { id: gameId } : null;
+  },
+);
+```
+
+## The resource
+
+Declare the REST callbacks once ([resource.md](./resource.md)) and the store
+does the rest — this is what makes the detail page show the new name **the
+moment the PUT answers**, with nobody reloading anything:
+
+```js
+const GAME = resource("game", {
+  GET: ({ id }) => api.readGame(id),
+  GET_MANY: () => api.readGames(),
+  POST: (values) => api.createGame(values),
+  PUT: ({ id, ...values }) => api.updateGame(id, values),
+});
+```
+
+Two things to know or the screen stays empty:
+
+- **Reading an action does not start it.** `useAsyncData` waits for data
+  someone else asked for; what asks is the route (`routeAction`). A component
+  reading an action nobody runs suspends forever, and the whole `<Loading>`
+  subtree stays blank.
+- **Handle the error where it happens**, or hand it to an `<ErrorBoundary>`:
+  `useAsyncData(action, { loading: true, error: true })` returns
+  `[data, loading, error]`, which is what lets a page draw its own "the server
+  refused" with a "try again" that calls `action.rerun()`.
+
+## Two screens, two states
+
+The same three fields, and two different things behind them:
+
+- the **create** screen holds a **draft** — nobody else's, not saved anywhere,
+  worth keeping while it is being written. It belongs in the url
+  (`searchParams`), which is what makes it survive a reload and travel in a
+  link;
+- the **edit** screen holds **what the server has**, loaded, and proposes
+  changes to it. It is the screen's own state, alive as long as the screen is.
+
+So the fields are written once, and know nothing about which screen they are in:
+
+```jsx
+const GameFormFields = ({
+  nameSignal,
+  levelSignal,
+  playersSignal,
+  loading,
+}) => (
+  <>
+    <Input name="name" signal={nameSignal} loading={loading} required />
+    <Select name="level" signal={levelSignal} loading={loading}>
+      …
+    </Select>
+  </>
+);
+```
+
+Each screen hands it its own:
+
+```jsx
+// créer: le brouillon, qui vit dans l'url
+<GameFormFields
+  nameSignal={draftNameSignal}
+  levelSignal={draftLevelSignal}
+  playersSignal={draftPlayersSignal}
+/>;
+
+// modifier: ceux de cet écran-ci, remplis quand la partie arrive
+const nameSignal = useSignal(undefined);
+```
+
+**Do not let the two share one set of signals.** It is the mistake this shape
+exists to prevent, and it does not look like one: bind both screens to the same
+`nameSignal`, edit a game, then press "create" — the game you just edited is
+sitting in the create form, and in the url. A draft and a resource are not the
+same state; one is on the screen, the other is at the backend.
+
+The draft's other half is the end of its life:
+
+```jsx
+action={async (values) => {
+  const game = await GAME.POST.bindParams(values).rerun();
+  GAME_ROUTE.navTo({ gameId: game.id });
+  draftNameSignal.value = undefined; // il a servi
+  draftLevelSignal.value = undefined;
+}}
+```
+
+`undefined`, not `""`: a state signal put back to undefined returns to its
+default and leaves the url — see [control_value.md](./control_value.md).
+
+**Clear after navigating, not before.** Those signals are read by things on the
+screen being left — the list of places is asked for with the place the draft
+holds — so emptying them while that screen is still up asks for the list again,
+for a screen nobody is looking at any more. Navigate first and the clearing is
+what it should be: tidying up behind oneself.
+
+> One signal for the whole form works too: `<Form signal={gameSignal}>` fills
+> its named children from the object, follows it when something else writes it,
+> and writes back the whole object as the fields change. Reach for it when the
+> values arrive as one object and no field needs a url of its own — the fields
+> then take nothing but their `name`.
+
+## The edit screen opens before its values
+
+The resource arrives a request after the screen. Two shapes, and both are
+right — the question is what the person should be looking at meanwhile:
+
+**The screen waits, showing the form.** The fields are there, empty and busy
+(`loading` on a control marks it `aria-busy` and shows it), and they fill in
+when the resource lands. Nothing blinks in and out, and a long screen does not
+collapse to a spinner. What it costs is one thing to say — **when the filling is
+done**:
+
+```jsx
+const [game, loading, error] = useAsyncData(GAME_OF_ROUTE, {
+  loading: true,
+  error: true,
+  onLoad: (game) => {
+    nameSignal.value = game.name;
+    levelSignal.value = game.level;
+  },
+});
+
+<Form pristineKey={game?.id}>;
+```
+
+`onLoad` is what the screen does with the data **once, when it becomes known**,
+and the two hard parts are already answered by it:
+
+- **How often.** Not every time the data arrives — a successful PUT, a list
+  reloading, a poll all hand the same game back, and copying it again would
+  overwrite what the person is in the middle of writing. It fires once per set
+  of params, which is the action's own answer to "is this another thing, or the
+  same one again". Written by hand this is a `useEffect` keyed on `game?.id`,
+  and `[game]` is the natural, wrong, thing to write.
+- **When.** From a layout effect, so what it writes belongs to the same tick as
+  the render that got the data. That is what lets `pristineKey` be the id
+  itself: the form takes its reference again at the end of that tick, and by
+  then the fields are filled. A copy written in a passive effect (after the
+  paint) would be too late — the screen would open **already changed**, and Save
+  would send the resource back to the server untouched.
+
+The rest of `pristineKey` is in [form_changed.md](./form_changed.md).
+
+**Or the screen waits, showing nothing of the form**: render a skeleton until
+the resource is there, then the form with its values already in the fields.
+Nothing to announce then — the form holds them from its first render — but the
+screen has to be one that can be blanked without the person losing their place.
+
+Either way, cancelling is a link away: the screen is thrown away with what was
+typed in it, and coming back re-reads the resource. There is nothing to restore.
+
+## A field that picks from a list too big to load
+
+A place, a player, a category: the field is a picker, and its popup holds a list
+the backend answers with. The list is **one page** — the nearest, the most
+recent, whatever a `LIMIT` returned. And the screen is pre-filled from the url:
+
+```
+/games/new?place=halle-des-sports
+```
+
+That is what pre-filling is: a link from a place's page, a back button, a
+reload, a shared invitation. The signal is the selection, and the url is its
+memory. But the url carries an **identifier and nothing else** — no name — so
+the screen looks for it in the list it has:
+
+```js
+const selected = places.find((place) => place.id === placeId);
+```
+
+Nothing guarantees that `find`. The place may be far down the ranking, created
+by someone else a minute ago, or named in a link built elsewhere. Nothing is
+broken — the screen falls back on the identifier — but it then shows
+`halle-des-sports` where it promised "Halle des sports", which is the opposite
+of what pre-filling was for. Rare, never seen in development, and always at
+someone else's.
+
+Two ways out, and only one of them keeps the feature:
+
+- **Clear the signals when the screen opens.** No selection, no selection to
+  display. This throws away pre-filling, which is the reason those params exist:
+  removing a feature is not fixing its edge case.
+- **Ask for the list SAYING what you already hold.** What the screen holds
+  travels with the request, and the backend guarantees that item is in the
+  answer — on top of its page, whatever its rank.
+
+```js
+const PLACES_OF_SCREEN = routeAction(
+  [NEW_GAME_ROUTE, EDIT_GAME_ROUTE],
+  PLACE.GET_MANY,
+  // pas `() => true`: ce que l'écran tient déjà doit voyager avec la demande
+  () => {
+    // en création: l'url, connue tout de suite
+    if (NEW_GAME_ROUTE.matchingSignal.value) {
+      return { include: draftPlaceSignal.value };
+    }
+    // en modification: elle arrive avec la ressource
+    const game = GAME_OF_ROUTE.dataSignal.value;
+    return game ? { include: game.placeId } : null;
+  },
+);
+```
+
+Reading the selection in the params is also what makes the list **reload when
+the selection changes** — the action reruns on its own. Which is why the edit
+screen returns `null` until the resource is there: asking for the list before
+knowing what it must contain is asking for it twice, and the first answer is the
+one that cannot show the name.
+
+What `include` is, on the backend side, is the whole subject:
+
+- **an addition, not a filter.** The page stays the page; the asked-for item is
+  in it as well if it was not already, and once if it was;
+- **it takes what a url can hold** — a slug as much as an id;
+- **an `include` that designates nothing is not an error.** The answer is simply
+  the page, and the screen falls back on its "not found" case — which then says
+  something true (that place is gone) instead of being an artefact of
+  pagination;
+- it takes **several** values when several fields are pre-filled:
+  `GET /users?include=42,57`.
+
+> If a url signal designates an item of a paginated list, the identifier it
+> carries must travel with the list request, and the backend must guarantee its
+> presence in the answer. A paginated list is not "the first N", it is "the first
+> N **plus what the caller already holds**".
+
+The other half of the same problem is answered by the resource rather than by
+the list: **what comes back with a resource carries its own label**. The game's
+own page shows "Lieu: Halle des sports" with no list at all, because the GET
+answers with the name next to the id. Only the url is reduced to an identifier,
+and that is exactly where `include` earns its place.
+
+## Where each screen goes next
+
+The two screens navigate for opposite reasons, and that is why they say it in
+two different places:
+
+- **Create**: the page to land on is the one the server just made, and its id
+  comes back with the response. Nothing can be declared before the send, so the
+  action navigates:
+
+  ```jsx
+  <Form
+    action={async (values) => {
+      const game = await GAME.POST.bindParams(values).rerun();
+      GAME_ROUTE.navTo({ gameId: game.id });
+    }}
+  >
+  ```
+
+- **Edit**: the destination is known before the send — and it has to be, because
+  a press with **nothing to send** must leave too. That is `command`, which runs
+  whether or not there was an action to run:
+
+  ```jsx
+  <Form
+    command={`--navi-nav-to:${GAME_ROUTE.buildUrl({ gameId: game.id })}`}
+    action={(values) => GAME.PUT.bindParams({ id: game.id, ...values }).rerun()}
+  >
+  ```
+
+  Do not hold that submit back with `readOnlyWhileFormUnchanged`: the press
+  still does something — it leaves. Holding it back is for a form that goes
+  nowhere, where the press would visibly do nothing at all.
+
+## After a write: what goes back to the network
+
+Creating one game, measured on the demo:
+
+```
+POST /games     la création
+GET  /games     la liste se relit
+GET  /games/2   la page de ce qui vient d'être créé
+```
+
+Each of the two GETs is a decision, and neither is an accident:
+
+- **The list re-reads itself** because whether a new item belongs to a list
+  depends on filters, pagination and sort — the backend knows, the client does
+  not (`rerunOn.GET_MANY: ["POST"]`, and the whole table of defaults is in
+  [list_refresh.md](./list_refresh.md)). A `PUT` does **not** re-read it: the
+  store carries the new values into every list already holding that item, which
+  is why the name changed on the game's page shows up on the list without a
+  request.
+- **The detail GET is not saved by the store.** The action for that id had never
+  run, and the store holding the item is not the same thing as an action having
+  its data. It is also often not redundant: a detail representation is richer
+  than what a write answers — here the GET adds the place's name, the POST does
+  not, and a screen trusting the POST would show "Lieu: —". Skipping it could
+  only ever be a per-resource decision ("my POST answers the same shape as my
+  GET").
+
+Coming back to that page later in the same session costs **nothing**: an action
+that has completed is not run again for the same params. That, and not any
+cache, is what makes a screen already visited open instantly — and what a
+`rerun()` is for when something must genuinely be read again.
+
+## Movement between them
+
+The screens are places, so the movement between them is `RouteTravel` — not
+`SlideContainer`, which is for positions with no url (see
+[navigation.md](./navigation.md#tabs-with-no-url)).
+
+A row says two things at once, and they are said apart. Its `<Route>` children
+are ordered by matching precision (above); `routes` is the order of the
+**journey** — what "one step that way" means:
+
+```jsx
+<RouteTravel routes={[NEW_GAME_ROUTE, GAME_ROUTE]}>
+```
+
+Creating sits to the left of the game, so arriving on what was just created goes
+right ("here is what I just made"). **A page left out of `routes` does not
+travel at all**: the list is not a step along this row — one opens the create
+screen from it, one does not slide there — so it is absent, and that move has no
+animation. Leaving a page out is how a movement is refused; there is no "no
+transition" to ask for.
+
+A pair with a movement of its own gets a row of its own, on its own axis. The
+game and its edit screen are the same thing seen two ways, so they travel
+vertically inside the position the outer row holds for them:
+
+```jsx
+const GameArea = () => (
+  <RouteTravel axis="y" routes={[EDIT_GAME_ROUTE, GAME_ROUTE]}>
+    <Route>
+      <Route route={EDIT_GAME_ROUTE} element={EditGamePage} />
+      <Route route={GAME_ROUTE} element={GamePage} />
+    </Route>
+  </RouteTravel>
+);
+```
+
+Editing sits above the game on that column, so it comes down over it and saving
+sends it back up. The outer row does not move for it: both urls are the same position
+there, which is what makes the two rows independent —
+
+```jsx
+<Route route={EDIT_GAME_ROUTE} element={GameArea} />
+<Route route={GAME_ROUTE} element={GameArea} />
+```
+
+— the same element on both branches, so the inner row stays mounted across the
+two and has something to travel between.
+
+The gesture, the back button and a link pressed all move the same way.
+
+## See also
+
+- [form_changed.md](./form_changed.md) — what a form sends, what follows a send
+- [navigation.md](./navigation.md) — routes, links, travelling
+- [resource.md](./resource.md) — the store behind GET/POST/PUT
+- [control_value.md](./control_value.md) — binding fields to signals

package/docs/css_architecture.md

@@ -120,6 +120,71 @@ Note that scoping to an ancestor is not enough: `.my-sidebar { --link-color-pres
 
 When a component default deserves to be themed globally, promote it: declare a `--navi-<component>-<thing>` in [navi_css_vars.js](../src/navi_css_vars.js) and make the component default read `var(--navi-…)`.
 
+#### An app narrower than the screen
+
+An app that never spans the whole window — a phone-shaped column centered in a
+wide one, bands on the sides — has one problem with popups: a dialog lives in
+the browser's top layer, so it is calibrated on the _viewport_, and would paint
+1500px of modal over a 600px app. The top bar and the bottom nav have the same
+problem and solve it by repeating the app width by hand; popups must not need
+that, because the app would then have to know which components exist.
+
+So the app states its own screen once, and never names a component:
+
+```css
+:root {
+  --navi-app-max-width: 600px;
+  /* --navi-app-max-height too, for an app that also caps its height */
+}
+```
+
+In pixels: popup placement reads this value back from CSS to compute its own
+margins, and a custom property computes to a token stream rather than to a
+length, so `40rem` would arrive there as the string `"40rem"`. A non-px value
+still caps the popup's size (that part is pure CSS) but leaves the margins
+viewport-sized, and says so in the console.
+
+Every popup follows: `Dialog`, `Popover`, and everything built on them
+(`Picker`, `Select`…). It is a ceiling and nothing more — on a screen narrower
+than the app it never binds, and each popup still subtracts its own
+`marginWithContainer` from it, so the gap with the edges is kept either way.
+That gap is itself a share of the app's screen, not of the window (`"3appw"`,
+navi's own unit alongside `vvw`/`vvh`) — otherwise a 3% margin measured on a
+1500px window would eat 90px out of a 600px app.
+
+Do **not** try to get this by setting `--dialog-max-width` on `.navi_dialog`
+from the app. Two reasons:
+
+- it is a `--component-*` token, declared on the element (see the table above),
+  so components that write it themselves outrank an app rule of lower
+  specificity — `.navi_picker[aria-haspopup="dialog"] .navi_dialog` does exactly
+  that, and the app's cap silently disappears for every picker;
+- it is the knob a single popup uses to ask for a specific size, not a ceiling.
+  `--navi-app-max-width` feeds `--dialog-maxmax-width`, the hard ceiling _under_
+  that knob, so a popup that genuinely needs its own `maxWidth` can still say so
+  without any of them escaping the app's screen.
+
+##### Current limitations
+
+`--navi-app-max-width` caps how big a popup may get; it does not move where one
+is placed. Placement is still computed against the real viewport
+(`pickPositionRelativeTo`, in `@jsenv/dom`). That is invisible for anything
+centered on its cross axis — `center`, `bottom`, `top`, which is what a dialog
+does nearly always — but shows for anything anchored to an edge: a
+`positionArea` like `bottom-start`, a `SidePanel`, a fixed bar. Those sit
+against the window's edge rather than the app column's, so they stay on the real
+viewport for now (`side_panel.jsx` restates `--dialog-maxmax-width` as the full
+viewport on purpose).
+
+Making them follow the app column too means narrowing the container rect
+placement is computed against, inside `pickPositionRelativeTo` — worth doing the
+day a side panel or a fixed bar has to live inside a simulated screen.
+
+Note that an app can already get all of it, placement included, by rendering
+itself in an iframe of the target width: the viewport then genuinely _is_ the
+app's screen and no token is needed at all. `--navi-app-max-width` is the answer
+for an app that does not want to pay that price.
+
 ### 3. Direct rule override (avoid unless necessary)
 
 Overriding the actual CSS rules (not the variables) is intentionally hard — that is by design. If you find yourself needing to do this, it usually means a CSS variable should be exposed for that property. Open an issue or add the variable yourself and contribute it back.
@@ -133,4 +198,5 @@ Overriding the actual CSS rules (not the variables) is intentionally hard — th
 | One component instance       | Component prop or `style` attribute                                        |
 | All instances of a component | `--component-*` in unlayered app CSS, on a selector matching the component |
 | A global design token        | `--navi-*` on `:root`                                                      |
+| How wide popups may ever get | `--navi-app-max-width` on `:root`                                          |
 | A structural layout rule     | Expose a new CSS variable (contribute)                                     |

package/docs/form_changed.md

@@ -7,6 +7,7 @@ as an answer the form already holds, and what to do on a screen whose fields are
 filled a request later.
 
 - [Sending nothing is the default](#sending-nothing-is-the-default)
+- [What follows a send](#what-follows-a-send)
 - [What the form is measured against](#what-the-form-is-measured-against)
 - [What counts as already held](#what-counts-as-already-held)
 - [A screen filled after it opened: `pristineKey`](#a-screen-filled-after-it-opened-pristinekey)
@@ -31,6 +32,50 @@ duplicates are fine.
 <Form action={notify} canSendWhileUnchanged>
 ```
 
+## What follows a send
+
+The form has answered its question; `command` says what the screen does about
+it — dismiss the popup (`--navi-close`), move on the slide map
+(`--navi-left`…), go to a page (`--navi-nav-to:/games/42`), stay put
+(`--navi-void`). Left out, the surface the form sits in decides: a popup closes,
+a slide goes on, a form on a page does nothing.
+
+It runs **whether or not there was anything to send** — that is the other half
+of the rule above: the person is done either way, and a submit that ran no
+action still closes the popup, still moves on, still navigates. Which is why
+this is a prop, decided before the send: the form has to know where it goes even
+when nothing happened.
+
+Nothing runs when the send fails, or when a constraint refuses it. The form then
+stays in front of the person, showing what it is waiting for.
+
+### When only the response knows where to go
+
+A creation lands on the page the server just made, and its id comes back with
+the response — too late for a prop. Do it in the action, which is where the
+answer is:
+
+```jsx
+<Form
+  action={async (value) => {
+    const game = await createGame(value);
+    navTo(`/games/${game.id}`);
+  }}
+>
+```
+
+Nothing to declare: a creation always has something to send, so there is no
+"the press did nothing" case for `command` to cover.
+
+If you would rather it go through the command machinery all the same (to reuse
+whatever a command does on that surface), the form carries what follows the send
+as `data-after-send`, read once the send has succeeded — so an action can write
+it while it runs:
+
+```js
+formRef.current.setAttribute("data-after-send", `--navi-nav-to:/games/${id}`);
+```
+
 ## What the form is measured against
 
 One value, called the baseline here: **what the form held the last time it had
@@ -90,6 +135,11 @@ Its submit is live, and pressing it sends back the resource untouched.
 Change it **once**, when the screen is ready. Taken again after someone started
 typing, it would call what they wrote the reference.
 
+No need to delay it by a tick: the reference is taken when the fields have
+settled, and again at the end of that same tick — so a row that arrives in a
+render of its own (a value computed from signals, a memoized row) is part of it
+without the screen having to know which of its fields settle late.
+
 Do not use a `key` on the `<Form>` for this: it remounts every control and every
 popup inside it, and anything half-typed goes with them.
 
@@ -126,4 +176,6 @@ It is then neither collected nor complained about.
   nothing, a bound `signal`, or you
 - [control_object.md](./control_object.md) — one value made of several
   controls: `ControlGroup`, `Form`, and a picker whose value is an object
+- [create_and_edit.md](./create_and_edit.md) — the create/edit loop this is
+  half of: routes, the resource, and where each screen goes next
 - [actions.md](./actions.md) — what an action does around the send itself

package/docs/navigation.md

@@ -248,6 +248,13 @@ read from the children in the order they are written. Pass `routes` only to say
 another order, or when the pages are not children of the box. An entry is a route,
 or `{ route, params }` when the tabs are params of one route.
 
+The row is on the **first** of its pages that matches, the way a `<Route>` shows
+its first matching branch — several routes match at once when one is a case of
+another. A page left out of the row does not travel: reaching it is a change of
+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.
@@ -260,6 +267,14 @@ Demo: [../src/nav/demos/route_travel/route_travel.html](../src/nav/demos/route_t
 and [../src/nav/demos/tabs/tabs.html](../src/nav/demos/tabs/tabs.html). The full
 spec of the gesture is [drag_to_travel.md](./drag_to_travel.md).
 
+## Creating something, then editing it
+
+The create screen, the page of what was created, the edit screen — three routes,
+one form, and a movement between them. It is assembled in
+[create_and_edit.md](./create_and_edit.md), which is also where the two matching
+rules that decide the shape of the `<Route>` tree are spelled out (several routes
+match at once; the first matching branch wins).
+
 ## Tabs with no URL
 
 `SlideContainer` holds slides that replace one another in one box, with the same