@jsenv/navi 0.29.482 → 0.29.484

package/docs/AI_INSTRUCTIONS.md

@@ -208,8 +208,9 @@ start when unsure which export solves a problem.
   line height for everything; `BadgeList`. Before an overflowing label, and
   before touching a `line-height`.
 - `i18n.md` — `interpolateText`/`<Interpolate>` for one sentence, `createI18n`
-  for the app's texts, `naviI18n` for navi's own. Before writing a user-visible
-  sentence.
+  for the app's texts, `naviI18n` for navi's own, and which helper writes a
+  number, a day or a time. Before writing a user-visible sentence, a number, a
+  date or a time.
 - `testid.md` — role and accessible name first; where `data-testid` lands; what
   not to target. Before a selector in a test.
 

package/docs/actions.md

@@ -84,6 +84,10 @@ const userAction = getUser.bindParams({ id: userIdSignal });
 // and starts it, with useAsyncData(userAction, { run: true })
 ```
 
+The params a signal or a getter hands over may be a fresh object each time:
+params equal to the ones held are the same question, so the binding keeps the
+object it has — nothing is asked again, and its readers do not render again.
+
 `{ debounce }` puts a delay between the signal and the instance, for params that
 move faster than a request should — a search box, a wheel, a slider:
 
@@ -104,6 +108,15 @@ params by hand. It follows where the signal **settles** (`A → B → A` sends
 nothing for `B`). `actionRunEffect`, which takes the action itself and a params
 getter, is for a request that must go out whether or not something draws it.
 
+A request that follows typing — the suggestions under an address field — is
+this binding, never the field's `action`: a field whose action runs is busy,
+and a busy field is read-only, so the person could not go on typing.
+`actionDebounce` delays an action that saves what was typed. Such a request,
+written with a plain `createAction`, has no verb for the network policy to see
+([network_policy.md](./network_policy.md)): offline, its params say there is
+nothing to ask (`undefined`, [below](#nothing-to-ask-and-coming-back)).
+`src/control/demos/integration/0_address_autocomplete_demo.html` is this shape.
+
 ### The answer is kept on the instance that ran
 
 An action's state — `dataSignal`, `errorSignal`, `runningStateSignal` — belongs
@@ -479,6 +492,38 @@ stays on screen while it does, is in [list_refresh.md](./list_refresh.md); a
 scope with reruns of its own, and a rerun after another resource writes, are
 [`withParams()`](./resource.md#withparams-a-scope-with-reruns-of-its-own).
 
+A read that is no row of a resource — a count, a summary — follows writes the
+same way, with `dependencies` on the action:
+
+```js
+const SUMMARY = createAction(fetchSummary, {
+  dependencies: [ORDER, { resource: CART, on: ["POST"] }],
+});
+```
+
+After a listed write, its instances that answered, or are still asking, ask
+again; `on` is read as a resource's is
+([resource.md](./resource.md#dependencies-rerun-after-another-resource-writes)).
+
+What the server moves on its own — an email that may bounce, an account being
+linked in another app — no write announces: its reader asks again on a timer.
+
+```js
+const [delivery] = useAsyncData(DELIVERY.GET.bindParams({ id }), {
+  run: true,
+  poll: {
+    every: 3000,
+    until: (delivery) => delivery.status !== "pending",
+    for: 60_000,
+  },
+});
+```
+
+It ticks only while that reader is mounted and the document visible (once at
+once when it shows again), never while a network policy answers reads from the
+store, and each tick revalidates: the answer stays drawn and `loading` stays
+false. `until`, `for` and a failure end it.
+
 `rerunActions(actionSet)` reruns several at once;
 `updateActions({ prerunSet, runSet, rerunSet, resetSet })` settles the four
 kinds of request in one pass — a route change goes through it.

package/docs/control_value.md

@@ -18,6 +18,7 @@ somewhere else in the app.
 - [Which controls take a `signal`](#which-controls-take-a-signal)
 - [The PROP is what controls, not its value](#the-prop-is-what-controls-not-its-value)
 - [A yes/no shown as two rows](#a-yesno-shown-as-two-rows)
+- [A choice that can be given back](#a-choice-that-can-be-given-back)
 - [Clearing, resetting, and what is shown meanwhile](#clearing-resetting-and-what-is-shown-meanwhile)
 - [`value` and `signal` exclude each other](#value-and-signal-exclude-each-other)
 - [A `stateSignal` brings more than a value](#a-statesignal-brings-more-than-a-value)
@@ -25,12 +26,12 @@ somewhere else in the app.
 
 ## The three answers
 
-| what you pass          | who holds the value | when the user acts                                                                    |
-| ---------------------- | ------------------- | ------------------------------------------------------------------------------------- |
-| nothing                | the control         | it keeps it; `uiAction` tells you                                                     |
-| `defaultValue`         | the control         | same — the default is where it starts, and a new one is taken while nothing is edited |
-| `signal`               | the signal          | the control writes it back, both ways                                                 |
-| `value` (or `checked`) | you                 | nothing moves until you hand a new one down                                           |
+| what you pass          | who holds the value | when the user acts                                                                         |
+| ---------------------- | ------------------- | ------------------------------------------------------------------------------------------ |
+| nothing                | the control         | it keeps it; `uiAction` tells you                                                          |
+| `defaultValue`         | the control         | same — the default is where it starts, and a new one is taken while nothing is edited      |
+| `signal`               | the signal          | the control writes it back, both ways                                                      |
+| `value` (or `checked`) | you                 | it holds what you hand down: the press shows its change, a failed `action` puts yours back |
 
 A control given `value` and nothing to listen to it (`uiAction`, `action`, a
 `signal`, a `command`, a form or group collecting it) is read-only, and says so
@@ -57,6 +58,12 @@ const minutesSignal = useSignal(0);
 minutesSignal.value = 30;
 ```
 
+A control moved by a gesture writes each value the gesture passes through: a
+wheel dragged, flung or turned by the mouse wheel writes every row it crosses,
+and its `action` runs once, on the row it settles on. Whatever reads the signal
+re-renders at that rate, so read it in the smallest component that shows it, or
+through a `computed` of what it needs.
+
 "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. So the signal always says where the
@@ -242,10 +249,22 @@ or taken back (the action failed, the popup was cancelled).
 
 This holds for a control, for a group given a `defaultValue` (a selectable list,
 a `ControlGroup`), and for everything inside a picker's popup, which stays
-mounted while closed. So the record goes in as `defaultValue` and nothing else —
-no `key` to remount the popup when it changes: a key also destroys whatever is
-being typed when the answer to ANOTHER field arrives. A picker's cancel follows
-the same line: it undoes the person's edits
+mounted while closed.
+
+Where the record goes depends on who sends it. A control that saves itself —
+its own `action`, nothing around it to press — takes it as `defaultValue`
+(`defaultChecked`). A picker whose `action` sends what its popup holds takes it
+as its own `value`, the controls in the popup carrying only their `name`: a
+default is a suggestion the picker does not hold, and closing on one untouched
+confirms it ([form_changed.md](./form_changed.md#what-counts-as-already-held)),
+so a popup opened and closed with defaults in it sends the record back. A group
+holding nothing of its own counts as holding an answer as soon as one of its
+controls does. A form editing a record has the same trap, and its own way out
+([create_and_edit.md](./create_and_edit.md#the-edit-screen-opens-before-its-values)).
+
+Either way, no `key` to remount the popup when the record changes: a key also
+destroys whatever is being typed when the answer to ANOTHER field arrives. A
+picker's cancel follows the same line: it undoes the person's edits
 ([popup_open.md](./popup_open.md#what-cancel-actually-undoes)), and what the
 outside moved during the opening stays moved.
 
@@ -296,13 +315,13 @@ no field needs a url of its own — the fields then take nothing but their `name
 What a control is worth when it holds nothing has the type of what it holds when
 it holds something. A list of days nobody picked is `[]`, not `""`:
 
-| control                                           | empty is |
-| ------------------------------------------------- | -------- |
-| `Picker type="array"`, `List selectable multiple` | `[]`     |
-| `Picker type="object"`                            | `{}`     |
-| text/number/date `Input`, `Select`                | `""`     |
-| `Input type="checkbox" boolean`                   | `false`  |
-| radio, any other checkbox                         | absent   |
+| control                                                            | empty is |
+| ------------------------------------------------------------------ | -------- |
+| `Picker type="array"`, `List selectable multiple`, `CheckboxGroup` | `[]`     |
+| `Picker type="object"`                                             | `{}`     |
+| text/number/date `Input`, `Select`                                 | `""`     |
+| `Input type="checkbox" boolean`                                    | `false`  |
+| radio, `List selectable`, any other checkbox                       | absent   |
 
 This is what a clear (`--navi-clear`, a row's cross) leaves behind and what the
 object around it carries, so `value.days || []` is not needed.
@@ -333,6 +352,24 @@ Choose by what the box asks:
   value) takes its own `value`, or none for `"on"`. Unchecked carries nothing,
   so the group gathers only the checked ones into an array.
 
+A button that stays pressed — a mode ("Edit" / "Done"), show/hide, a setting —
+is a checkbox too, drawn as a button: `<Input type="checkbox" variant="button"
+boolean signal={editingSignal}>`, its children its words and its name. A
+`<Button aria-pressed>` whose press writes the signal back is the binding done
+by hand: the state it shows is the app's to keep in step, where the checkbox
+announces it as checked and follows the signal whoever writes it.
+
+```jsx
+// ✗ a button wired to remember a state
+<Button aria-pressed={editing} uiAction={() => (editingSignal.value = !editing)}>
+  {editing ? "Done" : "Edit"}
+</Button>
+// ✓
+<Input type="checkbox" variant="button" boolean signal={editingSignal}>
+  {editingSignal.value ? "Done" : "Edit"}
+</Input>
+```
+
 ## Which controls take a `signal`
 
 All of them: `Input` (every type), `Picker`, `Select`, `Wheel`, `Spin`,
@@ -389,6 +426,25 @@ What cannot be done is give a row `undefined` to mean "no value" — `undefined`
 is what UNCHECKED means, here as in HTML, so such a row can never be ticked.
 "Nothing chosen" is the absence of a row, not a row.
 
+## A choice that can be given back
+
+A single choice that may also be no choice at all — left, right, or neither — is
+`<List selectable deselectable>`: the selected row, pressed again, lets go, and
+the list holds nothing (absent). Without `deselectable` it is a radio group: a
+choice moves to another row but never goes away.
+
+```jsx
+<List selectable deselectable name="side" defaultValue={me.side}>
+  <List.Item value="left">Gauche</List.Item>
+  <List.Item value="right">Droite</List.Item>
+  <List.Item value="both">Les deux</List.Item>
+</List>
+```
+
+An answer that is the others together ("both") is a row of its own, not two
+rows held at once; what it lights in the others hangs off `aria-selected` in
+CSS.
+
 ## Clearing, resetting, and what is shown meanwhile
 
 Three things that look alike and are not:

package/docs/create_and_edit.md

@@ -232,6 +232,24 @@ for a screen 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 screen that stays open after Save
+
+Everything above assumes the screen is left on saving. One edited in place —
+a settings panel, saved, then edited again — has no shape that answers all of
+it yet, and each of the three leaves one thing out:
+
+- `defaultValue={record.x}` follows the record and never undoes an edit, but is
+  not held: an untouched Save sends the record back.
+- `onLoad` + `pristineKey` is held, and stops following: a record moved while
+  the screen is open stays as `onLoad` found it.
+- `useSignalSync(record.x)` ([state_binding.md](./state_binding.md)) is held
+  and follows, but the record moving overwrites what is being typed — and it
+  compares by reference, so a record read again as a new array or object
+  counts as a move even when nothing in it changed.
+
+What not to write: `useSignal(record.x)` with `key={record.updated_at}` on the
+block. The key throws away what is being typed each time the record moves.
+
 ## A field that picks from a list too big to load
 
 A place, a player, a category: the field is a picker whose popup holds **one
@@ -399,7 +417,14 @@ only its mechanisms change.
 | the draft lives in the `searchParams`                 | it lives in the dialog, and dies with it                                                                           |
 | cancelling = leaving the screen, which is thrown away | `mount="while-opened"` (+ a `key` on the form), same effect                                                        |
 | `RouteTravel` between the two screens                 | nothing: a dialog has no neighbour                                                                                 |
-| `onLoad` + `pristineKey`: the resource arrives after  | it is already in hand — the dialog is opened FROM the list                                                         |
+| `onLoad` + `pristineKey`: the resource arrives after  | it is in hand — the dialog is opened FROM the list, or re-reads it as it opens (below)                             |
+
+A list's copy of a record can be minutes old, so a sheet that saves the whole
+record reads it again as it opens, and that answer lands after the popup has
+taken what it holds at open. A `Picker` given the record as its `value` (or its
+signal) counts what the outside writes before the person changes anything as
+what was there at open: a look and a close send nothing, and a cancel goes back
+to the record as it arrived, not to the list's copy.
 
 What does not change:
 

package/docs/css_architecture.md

@@ -50,6 +50,19 @@ along with the code; at module scope, it lands on every page importing the
 module, and nothing can shake it out. Assign at module scope only for a module
 that is a side effect by design — an app's tokens, say.
 
+The same holds for an app's components, and the choice moves the cascade:
+between unlayered sheets the last one adopted wins a tie. Assigned at module
+scope in a module the entry imports, an app's sheet is adopted before any navi
+component renders, and loses every tie with navi's rules, the same way every
+session. Assigned in render, it lands after the navi sheets already adopted and
+before the ones still to come, so a tie goes to whichever came last — which
+depends on what the user opened first. Before moving a sheet from one to the
+other, find its ties (a `.navi_*` class as a rule's subject, an app class on a
+navi component setting what navi's one-class rule sets) and settle each by
+weight, a prop or a variable rather than by order; what other modules use from
+the sheet (a class they wear) goes in a shared sheet, installed by each of them
+as below.
+
 The setter is keyed by module: **two assignments in one module do not add up**,
 the second replaces the first. A stylesheet shared between components is
 therefore a module of its own, exposing an install function its callers run
@@ -258,6 +271,21 @@ A variant (`icon`, `discrete`, `bare`, `border`, `headless`…) describes what
 the caller did not say: it only moves defaults, so a prop given next to it
 always wins.
 
+#### Where a prop lands
+
+A `Button`, a range input and a `CardLayout` paint a frame inside themselves.
+Their visual props — `background*`, `border*`, `borderRadius`, `boxShadow`,
+`outline*`, `opacity`, `filter`, `cursor`, `overflow` — and their padding go to
+that frame; size, position and margins stay on the control. A `style={{…}}` is
+not sorted: all its keys paint the outer element, so a background or a shadow
+written there lands around the frame rather than on it. Write them as props.
+
+What navi's unlayered structure sets — a control's `position: relative` —
+changes with the prop (`<Button absolute inset>`), or with the variable that
+feeds it where there is one (`--nav-width`), never with a class: one class only
+ties with navi's rule, and sheet order decides the tie (see
+[Where CSS lives](#where-css-lives-importmetacss)).
+
 ### 2. CSS variables (for global or theme-level changes)
 
 When the same change applies to many components (e.g. a design token update),
@@ -279,6 +307,32 @@ with `--navi-app-max-width` — never `--dialog-max-width`, a `--component-*`
 token every dialog resets on itself: see
 [safe_area.md](./safe_area.md#an-app-that-is-narrower-than-the-window).
 
+#### The tokens a rule may read
+
+What `:root` declares, and so what an app's own css may read with `var()`:
+
+- spacing: `--navi-xxs` … `--navi-xxl` (`xxs`, `xs`, `s`, `m`, `l`, `xl`,
+  `xxl`), in `em` — the scale the spacing props take, and `borderRadius` too
+  (`borderRadius="s"` is `var(--navi-s)`): there is no radius scale of its own;
+- type: `--navi-typo-xxs` … `--navi-typo-xxl`, the scale `size` takes, and
+  `--navi-line-height` ([typography.md](./typography.md#emoji));
+- the paper: `--navi-surface-color`, `--navi-surface-text-color`,
+  `--navi-chrome-color` (see [below](#two-planes-the-paper-and-the-frame));
+- `--navi-accent-color`; `--navi-error-color`, `--navi-info-color`,
+  `--navi-success-color` and `--navi-warning-color`, each with a `-light` twin;
+- the stacking bands `--navi-z-index-*` ([z_index.md](./z_index.md)) and the
+  screen's `--navi-safe-area-inset-*` ([safe_area.md](./safe_area.md));
+- the themable defaults of controls and surfaces: `--navi-control-*`,
+  `--navi-button-*` (the button grey is `--navi-button-background-color`),
+  `--navi-picker-*`, `--navi-link-*`, `--navi-popup-*`, `--navi-callout-*`,
+  `--navi-focus-outline-*`, `--navi-placeholder-*`.
+
+The color keywords are not read this way: they go through the `color` prop
+([typography.md](./typography.md)). A name found neither here nor in the doc of
+what it belongs to is most likely declared nowhere, and `var()` on it draws its
+fallback without a word — `--navi-radius-s`, `--navi-space-m`, `--navi-font-mono`
+look plausible and are not tokens.
+
 #### `--navi-*` vs `--component-*`: where the override has to go
 
 The two families are **not** interchangeable, and layers have nothing to do
@@ -327,9 +381,16 @@ Scoping to an ancestor is not enough: `.my-sidebar { --link-color-pressed: blue
 fails for the same reason `:root` does. The selector has to reach the link
 element itself.
 
+The rule is about declarations, not about the family. A `--component-*` navi
+only reads with a fallback and declares nowhere — `--button-background`,
+`--button-border`, `--button-padding*` — has nothing on the element to beat, so
+an ancestor's value reaches it like any inherited custom property; one navi
+declares — `--button-color`, `--nav-current-indicator-color` — stops at the
+element.
+
 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-…)`.
+`--navi-<component>-<thing>` in `src/navi_css_vars.js` (in navi's repository)
+and make the component default read `var(--navi-…)`.
 
 #### Two planes: the paper and the frame
 
@@ -414,6 +475,24 @@ and it stops at the surface. Declaring the formulas on `*` to make container
 ratios work is the thing not to do: it would overwrite the pinned keyword on
 each of the card's children, and a paper could no longer say anything.
 
+##### A dark surface inside a light page
+
+`color` on a surface turns what is written against `currentColor` — the four
+keyword formulas, and whatever an app writes the same way. It does not turn the
+colors navi writes as `light-dark()` or as a system color: the paper
+(`--navi-surface-color`) and its ink (`CanvasText`), the control border, the
+button grey, the focus ring, a `Wheel`'s ink, glass and frame. A card saying
+`color: white` and nothing else still holds a near-black wheel.
+
+`color-scheme: dark` on the surface turns those: a `light-dark()` is resolved
+where it is used, so every one below the surface takes its dark side — except a
+token the app pinned to an absolute on `:root`. A dark card says both. A
+component's own color token (`--wheel-color`) still tints it, set on the card
+or any ancestor. `color-scheme` is inherited and no surface takes it back: a
+popup opened from the card is drawn dark too. (A lowered `light-dark()` follows
+`prefers-color-scheme` only: see
+[Browser support](#browser-support-navis-css-and-your-target).)
+
 ### 3. Direct rule override (avoid unless necessary)
 
 Overriding the actual CSS rules (not the variables) is intentionally hard. If
@@ -496,6 +575,7 @@ elements and the boxes before and after.
 | A global design token                                         | `--navi-*` on `:root`                                                                              |
 | The share of ink in `secondary`/`emphasis`/`discrete`/`hint`  | `--navi-color-*-mix` on `:root` — never on a container                                             |
 | A container's own paper (a dark card)                         | `color` on it, plus a keyword pinned if its formula reads wrong; both stop at the next popup       |
+| A dark surface inside a light page                            | `color-scheme: dark` on it, beside its `color` — it turns every `light-dark()` below               |
 | How wide popups may ever get                                  | `--navi-app-max-width` on `:root`                                                                  |
 | A structural layout rule                                      | Expose a new CSS variable (contribute)                                                             |
 | A rule counting children of a container holding navi controls | `:nth-child(… of S)`, `:not([navi-out-of-flow])`, or a class — a popup or a callout is a child too |

package/docs/data_states.md

@@ -38,6 +38,12 @@ the component reads:
 | `error: true`   | suspends                  | `error`, plus `dismissError` |
 | both            | `loading`                 | `error`                      |
 
+A delegated failure is thrown whatever the action still holds: a refresh that
+fails — the rerun when the app comes back to the foreground, a dependency's —
+takes rows that were on screen to the boundary, whose fallback replaces them. A
+reader with something to keep showing asks for `error: true`, and each reader of
+a shared action decides this on its own.
+
 The invariant that makes this worth relying on: **`loading: true` never
 suspends.** Not while the action runs, not while a debounced binding is
 settling, not while it holds params nobody has started yet, not after a failure
@@ -113,7 +119,9 @@ told it shimmers until something runs that action.
 
 navi's own placeholders take that flag rather than inventing it: `<Text loading>`
 shimmers, `<Text skeleton>` is the same bar held still, and
-`<Text skeleton loading={loading}>` is one that tells the truth either way.
+`<Text skeleton loading={loading}>` is one that tells the truth either way. A
+spinner beside a value is `<LoadingIndicator>` — never `<Loading>`, which is the
+boundary a delegated wait suspends into and draws nothing of its own.
 
 **Knowing the count beforehand beats guessing it.** A screen that already knows
 how many rows are coming — a count carried by the parent resource, a total

package/docs/drag_interactions.md

@@ -60,17 +60,33 @@ carry began with, for the release as well (unlike a swipe's), except for
 | `leave`          | `{ id, x, y }`                                                   |
 | `grab`           | `{ pointerType, gestureInfo }`                                   |
 | `release`        | `{ id, x, y, outcome }`                                          |
+| `settle`         | `{ id, outcome, refused }`                                       |
 | `refuse`         | `{ pointerType }`                                                |
 
 Items and places are named by their `id`. **What an outcome returns is waited
 on**: the gesture holds what it carries until that promise settles, and a
 rejection sends it home — a place the application would not accept must not stay
-on screen as if it had. `moving`, `grab`, `release` and `refuse` **report, they
-do not ask**: what they return is not waited on, and preventing their event
-calls nothing off.
+on screen as if it had. `moving`, `grab`, `release`, `settle` and `refuse`
+**report, they do not ask**: what they return is not waited on, and preventing
+their event calls nothing off.
+
+**A refusal says why, on the element, once it is home**: an error callout, the
+way a control says its action failed — a seat taken in the meantime is something
+the person has to read, not guess from a card flying back. What the outcome
+rejected with is read the way an `errorMapping` answer is
+([error_handling.md](./error_handling.md#someone-just-acted--a-controls-action)):
+an error, a string or an element is shown; `{ message, target }` is shown on
+that target; rejecting with nothing (`return Promise.reject()`) refuses without
+a word. An outcome answered by `"request_action"` is said by its control.
 
 **Where the position is kept is the answer's.** Until the release navi carries
-the element with a translate of its own. An element drawn from state
+the element on its `translate` property, added to the translate it already had.
+The element's matrix is `translate`, then `rotate`, then `scale`, then
+`transform`, so the hand's translate applies outside whatever the element is
+drawn with — a shape turned to a bearing, a marker scaled with the zoom, by
+property or inside `transform` — and the element stays under the hand. What it
+is drawn with is left alone, a `var()` included, and a release kept in place
+writes only `translate` back. An element drawn from state
 (`left`/`top` computed from a position the application holds) is redrawn by the
 `move` handler, and its layout owns the position from then on: navi sees it drawn
 elsewhere and drops its translate, or it would land twice as far as the hand
@@ -90,20 +106,22 @@ whatever it is declared on, and a `data-drop-container` (a place outside is only
 reached from outside).
 
 ```jsx
+const startViewTransition = ensureDocumentStartViewTransition();
+
 <List.Item
   id={task.id}
   data-view-transition-name={`task_${task.id}`}
   interactions={{
     reorder: (event) => {
       const { fromId, toId, syncCloneWithDropTarget } = event.detail;
-      return document.startViewTransition(() => {
+      return startViewTransition(() => {
         syncCloneWithDropTarget();
         setOrder(moveBefore(order, fromId, toId));
       }).finished;
     },
     toss: (event) => remove(event.detail.id),
   }}
-/>
+/>;
 ```
 
 Every element declaring `reorder` marks itself, so the set of items IS the set of
@@ -406,6 +424,12 @@ up (a counter of what is in the hand) stays set up with nothing to take it down.
 hand lets go, while still knowing whether something is on its way. Like `grab`,
 it needs a drag to happen in, and a dev warning says so.
 
+`settle` is when the carry is over, after the answer: the copy gone and the
+original shown again (it is hidden, `navi-drag-clone-source`, while the copy
+waits and flies), or the element at rest where it stays. `refused` says the
+answer rejected. A copy taken back in hand on its way home has not settled — that
+carry goes on, and its own end is told.
+
 ### The hand pulls and nothing follows: `refuse`
 
 Something that can be carried is not always free to be: a court whose place on the

package/docs/dynamic_import.md

@@ -214,8 +214,10 @@ failed as failed: a second `import()` of the same address is refused without a
 request, for the life of the document. So a retry has nothing to do —
 `error.action.rerun()` fails again at once, on the same failure — and the one way
 out is a fresh document: **`window.location.reload()`**, which the screen offers
-in words the reader understands. navi does not reload on its own: a document
-reloading itself is a loop waiting to happen.
+in words the reader understands. Not navi's own `reload()`: it asks the route
+actions again inside this same document, and the import fails again at once.
+navi does not reload on its own: a document reloading itself is a loop waiting
+to happen.
 
 The page or the component reading its code says it where it stands, as above. A
 failure left to a boundary reaches it like a failed read does; a boundary that

package/docs/error_handling.md

@@ -92,6 +92,25 @@ the page. Being an element, the message:
 Reference: `src/control/demos/form_error_mapping_jsx/demo.html`, a mapping
 answering with a different component per error kind.
 
+### Someone acted, and no control asked — a gesture, an autosave
+
+A card dropped on a place, a row swiped away, a draft saved as it is typed: the
+person did something and the write runs from a callback, with no control's
+action to draw its failure. The rule does not change — the answer belongs where
+they acted — and what holds the callback says it there:
+
+- **a drag outcome** (`land`, `reorder`, `toss`, `leave`, `move`) is said on the
+  element once it is home, in an error callout, and what the callback rejected
+  with is read like an `errorMapping` answer — rejecting with nothing refuses
+  without a word ([drag_interactions.md](./drag_interactions.md#carrying-something-move-reorder-land-toss-leave));
+- **any other interaction's callback** that rejects is reported like every
+  error nothing displays (below): a swipe whose write failed comes back in
+  place, and the error is not lost with it. Reject with nothing for a refusal
+  that has nothing to say;
+- **a write nobody's gesture is waiting on** (an autosave in an effect) has no
+  place to answer at: the screen reads the action that ran it
+  (`useAsyncData(action, { error: true })`) and says it where the draft is.
+
 ### A screen's data failed — a route action
 
 Nobody clicked; the page simply cannot be drawn. It is the page, or a piece of

package/docs/i18n.md

@@ -69,6 +69,16 @@ import { i18n } from "@/app_i18n.js";
 i18n("Deleting [name]…", { name: file.name });
 ```
 
+A placeholder's value is data — a name, a number, a formatted date — or wording
+the code picks: "tonight", a label from a table. Wording is looked up too, and
+handed over translated; so is a unit word of the app's own, which `<Quantity>`
+shows as given:
+
+```jsx
+i18n("Updated [when]", { when: i18n("tonight") });
+<Quantity unit={[i18n("ticket"), i18n("tickets")]}>{count}</Quantity>;
+```
+
 ### In an app, the text is the key
 
 `keyLang: "en"` means "keys are already written in English". The key doubles as
@@ -101,6 +111,46 @@ to the key's name. That is why an instance with opaque keys wants a
 happens to equal the key". Registering (`add`, `addAll`, `addLangKeys`) and how
 the language is resolved key by key are in `createI18n`'s JSDoc.
 
+## A sentence that depends on a number
+
+A sentence whose words follow a count is one translation with several forms,
+never two keys picked in code with one language's rule baked in (`count > 1 ?
+plural : singular` is wrong in French at 0 and in English at 0, and Polish has
+three forms where English has two). The forms go in place of the string, and
+`count` picks one: an exact number written as a key first, then the form the
+language gives that number (`Intl.PluralRules`), then `other`:
+
+```js
+const seats = {
+  0: "Full",
+  one: "[count] free seat",
+  other: "[count] free seats",
+};
+i18n(seats, { count: place.freeSeats });
+```
+
+The `other` string is the key the other languages register their forms under —
+each language with the forms it has:
+
+```js
+i18n.add("[count] free seats", {
+  fr: {
+    0: "Complet",
+    one: "[count] place libre",
+    other: "[count] places libres",
+  },
+});
+```
+
+With opaque keys, every language registers its forms under the key, and the
+call passes `count`: `naviI18n` does this for its own messages. `<Quantity>`
+picks its unit's form by the same rule, and `pluralCategory(count, { lang })`
+answers it for a choice that is not a sentence.
+
+A list of items read as one phrase is joined by `formatList` — the language's
+"and" or "or" and its commas ("8h–10h, 12h et 18h–20h"), never a hand-written
+`" et "`.
+
 ## Which language
 
 Nothing needs configuring for navi and app texts to agree on a language: both
@@ -134,6 +184,33 @@ Because the language is read at lookup time, a component that reads `i18n(...)`
 during render re-renders with the new wording when the language changes — as
 long as the call happens in render, not in a value captured once outside it.
 
+## Writing a value
+
+A number, a day or a time on screen is wording as much as a sentence is, and
+navi writes it: never `Intl` or `toLocale*` with a locale of the app's own,
+which pins one region beside navi's dates and ignores `setSupportedLanguages`.
+Each helper takes `lang` and otherwise reads the signal above; the component is
+for JSX, the function for a string (a `title`, a notification).
+
+| Value                   | Component                                          | String                                           |
+| ----------------------- | -------------------------------------------------- | ------------------------------------------------ |
+| a number                | `<Quantity>`                                       | `formatNumber`                                   |
+| a day                   | `<Time type="date">`                               | `formatDay`                                      |
+| a month                 | `<Time type="month">`                              | `formatMonth`                                    |
+| a day and its time      | `<Time type="datetime">`                           | `formatDatetime`                                 |
+| a time of day           | `<Time type="time">`                               | `formatTimeOfDay`, or `formatTime` from a `Date` |
+| a clock from a count    | `<Time type="hour"\|"minute" format="timestring">` |                                                  |
+| two times of day        | `<TimeRange>`                                      | `formatTimeRange`                                |
+| a day relative to today | `dayLabel` on `<Time type="date">`, beside the day | `formatDayRelative`                              |
+| an instant, from now    | `<Time type="relative">`                           | `formatTimeRelative`                             |
+| a duration              | `<Time type="duration">`                           | `formatDuration` and its per-unit siblings       |
+| items read as one list  |                                                    | `formatList`                                     |
+
+A spelled day writes its year only when it is not in `now`'s year (`year:
+"auto"`, see `formatDay`): appending the year by hand writes it twice for a
+date in another year. A capital letter at the start of a value is
+`<Text capitalize>`, not a sliced string.
+
 ## Changing what navi says
 
 `naviI18n` holds navi's own texts. Register on it to override a default or to
@@ -156,4 +233,6 @@ so overriding either is the same call.
 
 **Do not put application texts in `naviI18n`.** Key collisions aside, the two
 have different lifecycles: navi's keys come with the package version, the app's
-come with the app.
+come with the app. The unit names it looks up are for rewording a unit navi or
+`Intl` already knows ("hour", "kilometer"); a unit word of the app's own comes
+from the app's registry, translated (see [above](#centralizing-texts-createi18n)).