@jsenv/navi 0.29.387 → 0.29.388

package/docs/drag_interactions.md

@@ -6,6 +6,8 @@ An element picked up and carried, and what letting go means. It is one gesture
 the gate they go through and how a control learns which of them asked are in
 [interactions.md](./interactions.md); who owns a press when the carried thing
 stands in a box that travels is in [drag_to_travel.md](./drag_to_travel.md).
+Whatever the moment, `event.detail.event` is the `pointerdown` the carry began
+with — for the release as well, unlike a swipe's.
 
 - [Carrying something: `move`, `reorder`, `land`, `toss`, `leave`](#carrying-something-move-reorder-land-toss-leave)
   - [While it is being moved: `moving`](#while-it-is-being-moved-moving)
@@ -29,11 +31,12 @@ differs is the release. One detector reads them all, because it is one press.
 `toss` and `leave` each **combine** with `reorder` and with `land`: dropped on
 another item the element changes places, thrown far and fast it is gotten rid of,
 let go of away from every place it leaves. `leave` combines with `move` as well.
-`toss` does **not** combine with `move`, and neither do `reorder` and `land` with
-each other — one release cannot mean two of those. Declared together, the
-copy-carrying one wins and `move` is never answered — the element itself never
-travels, and a release that is not the other outcome means nothing at all (a dev
-warning says so).
+`move` does **not** combine with any of the three that carry a copy (`reorder`,
+`land`, `toss`), and neither do `reorder` and `land` with each other — one
+release cannot mean two of those. Declared together, the copy-carrying one wins
+and `move` is never answered — the element itself never travels, and a release
+that is not the other outcome means nothing at all; of `reorder` and `land`,
+`land` wins. A dev warning says so in each case.
 
 `move` carries the element ITSELF and leaves it where it was put; the others
 carry a copy and put the original back. That is the same difference said in layout
@@ -50,9 +53,10 @@ place taken by the list.
 ```
 
 `data-drag-free` on the element or a container lets it leave; by default a `move`
-stays inside what one can SEE of its container — which requires that container to
-be a scroll container at all (`overflow` anything but `visible`), since there is
-nothing else for "inside" to mean. A `move` whose answer rejects travels back, because a
+stays inside what one can SEE of its scroll container — the nearest ancestor whose
+`overflow` is `auto` or `scroll`, the page's viewport when there is none — so a
+board that only cuts its content (`hidden`, `clip`) does not hold what moves on
+it. A `move` whose answer rejects travels back, because a
 place the application would not accept must not stay on screen as if it had.
 
 **Where the position is kept is the answer's.** An element drawn from state —
@@ -202,8 +206,9 @@ back, not a row deleted — a list declares `toss`, a surface declares `leave`.
 ```
 
 `leave` combines with every other outcome. Beside `land` or `reorder`, "outside" is
-away from every place. Beside `move` — the element itself travels, and nothing is a
-place — it is outside the surface the element stands in: the nearest
+away from every place. Where nothing is a place — beside `move`, which carries the
+element itself, beside `toss`, or alone — it is outside the surface the element
+stands in: the nearest
 `data-droppable` ancestor, or, without one, what can be seen of the scroll
 container (a dev warning says which). Either way it is judged on the element's
 box no longer overlapping it, not on the pointer, which is still well inside the
@@ -220,8 +225,8 @@ frame when a small marker has just left it.
 </Plan>
 ```
 
-Its detail is `toss`'s — `{ id, x, y }`, the distance travelled being what an exit
-is animated with. Picked up and put straight back down stays a cancel: it has to
+Its detail is `toss`'s without the speed — `{ id, x, y }`, the distance travelled
+being what an exit is animated with. Picked up and put straight back down stays a cancel: it has to
 have gone somewhere to be away from anything.
 
 What the thing does while the answer is asked follows what was carried. A copy
@@ -283,8 +288,8 @@ place, swap the two, refuse.
 />
 ```
 
-`toId` is an element and **never null**: a copy over nothing is a release that
-meant nothing, and the interaction does not happen at all.
+`toId` always names an element and is **never null**: a copy over nothing is a
+release that meant nothing, and the interaction does not happen at all.
 
 **Which elements are places: those marked `data-droppable`, and only those.**
 Declaring `land` says an element can be CARRIED, which on a board is a different
@@ -487,9 +492,11 @@ vibration above, a state kept elsewhere, a counter.
 
 `grab` **reports, it does not ask**: what it returns is not waited on, and
 preventing its event does not call the gesture off. And it is not an interaction on
-its own — declared without one of the five above there is no gesture for it to be
-the beginning of, and a dev warning says so. Its detail carries `pointerType` and
-the `gestureInfo`.
+its own — declared without one of the five above (or `moving`) there is no
+gesture for it to be the beginning of, and a dev warning says so, unless the
+element declares `pan` or `zoom`, whose moments they then are
+([pan_zoom.md](./pan_zoom.md)). Its detail carries `pointerType` and the
+`gestureInfo`.
 
 A `longpress` needs none of this: it already happens at the moment the hold is
 acquired, not at the release.
@@ -574,7 +581,7 @@ prevented.
 One outcome refusing refuses the whole gesture — the five answer one carry, and
 something that must not be carried has none of them. Like `grab` and `release`,
 `refuse` **reports, it does not ask**, and it is not an interaction on its own.
-Its detail is `{ pointerType }` and nothing more: there is no `gestureInfo`
+Its detail is `{ pointerType }` beside the press (`event`), and no `gestureInfo`
 because there was no gesture, and what feedback wants to know is which hand asked
 — a vibration for a finger, nothing extra for a mouse whose cursor has already
 said it.
@@ -587,11 +594,11 @@ usually gets its own from the list around it, which the copy has left. So the
 clone's look is the page's to declare, through the attributes the gesture puts on
 it:
 
-| Attribute                 | On                                                     |
-| ------------------------- | ------------------------------------------------------ |
-| `navi-drag-clone`         | the copy being carried                                 |
-| `navi-drag-clone-wrapper` | what positions it (already shadowed, in the top layer) |
-| `navi-drag-clone-source`  | the original, still in place (already hidden)          |
+| Attribute                 | On                                                   |
+| ------------------------- | ---------------------------------------------------- |
+| `navi-drag-clone`         | the copy being carried (already shadowed and scaled) |
+| `navi-drag-clone-wrapper` | what positions it, in the top layer                  |
+| `navi-drag-clone-source`  | the original, still in place (already hidden)        |
 
 ```css
 .task[navi-drag-clone] {
@@ -603,19 +610,19 @@ it:
 Reusing the item's own class is the point: the copy is that item, so it is styled
 as that item plus whatever being carried changes.
 
-**Which is also the trap, for anything positioned on a board.** The copy is the
-same element re-parented into a carrier box, so a geometry written in the style
-attribute follows it there — `width: calc(50% - 2 * var(--gap))` then means half
-of the copy instead of half of the board, and the piece is carried at the wrong
-size. Put what a piece LOOKS like in a class and leave only which place it is
-inline (two custom properties will do), then let it fill its carrier:
+**Which is also the trap, for anything positioned on a board.** The copy is a
+deep clone of the element put in a carrier box, so a geometry written in the style
+attribute comes with it. navi takes back where it stands (`position`, `inset`,
+`margin` and `translate` are reset on the copy) but not its size —
+`width: calc(50% - 2 * var(--gap))` then means half of the carrier instead of
+half of the board, and the piece is carried at the wrong size. Put what a piece
+LOOKS like in a class and leave only which place it is inline (two custom
+properties will do), then let it fill its carrier:
 
 ```css
 [navi-drag-clone-wrapper] .piece {
-  position: static;
   width: 100%;
   height: 100%;
-  translate: none;
 }
 ```
 
@@ -654,8 +661,8 @@ from for as long as the question is open — and if the answer refuses, the copy
 back to it.
 
 `data-drag-axis` says which axes the drag walks, and its default is not the same
-for every outcome: `reorder` alone walks the list (`y`, or `x` for a list that runs
-sideways), while a `move` goes wherever it is put, a `land` wherever the board has
+for every outcome: `reorder` alone walks the list (`y`; a list that runs sideways
+says `data-drag-axis="x"`), while a `move` goes wherever it is put, a `land` wherever the board has
 places, a `toss` wherever it was thrown and a `leave` out by whichever edge (`xy`).
 `data-drag-delay`,
 `data-drag-slop`, `data-drag-threshold` tune when the press becomes a grab.
@@ -728,6 +735,9 @@ leaves the paint alone:
 import { createDragGestureController, dragAfterIntent } from "@jsenv/navi";
 
 const onPointerDown = (pointerDownEvent) => {
+  // Read now: the callback below runs once the intent shows, after dispatch,
+  // when `currentTarget` is null.
+  const element = pointerDownEvent.currentTarget;
   dragAfterIntent(pointerDownEvent, () => {
     const controller = createDragGestureController({
       onDrag: (gestureInfo) => {
@@ -741,9 +751,7 @@ const onPointerDown = (pointerDownEvent) => {
         COURT.PUT.run({ angle: angleSignal.peek() });
       },
     });
-    return controller.grabViaPointer(pointerDownEvent, {
-      element: pointerDownEvent.currentTarget,
-    });
+    return controller.grabViaPointer(pointerDownEvent, { element });
   });
 };
 ```

package/docs/drag_to_travel.md

@@ -192,12 +192,13 @@ laptop a horizontal two-finger swipe IS the back-navigation gesture, and a
 region that neither takes it nor lets it go is the worst of the three — the page
 rocks and nothing happens.
 
-Not the same thing as the drag gesture it sits beside
-([drag_gesture.js](../../dom/src/interaction/drag/drag_gesture.js)): that one is
-for **carrying an object** across the page — it lays a backdrop over the
-document, makes everything else `inert`, takes the focus and blocks the scroll
-keys. Here nothing is picked up and the page must keep its focus and its
-scrolling while a screen slides. Same word, other gesture.
+Not the same thing as **carrying an object** across the page, although both read
+the pointer through the same loop
+([drag_gesture.js](../../dom/src/interaction/drag/drag_gesture.js)): a carry has
+it lay a backdrop over the document, make everything else `inert`, take the
+focus and block the scroll keys. Here nothing is picked up and the page must keep
+its focus and its scrolling while a screen slides, so the travel asks it for none
+of that (`documentInteractions: "manual"`). Same loop, other gesture.
 
 ## Who owns a gesture
 
@@ -333,8 +334,9 @@ the browser for what those two properties do not cover.
 
 ### What is contained, and what still leaks
 
-Containing is only ever read on a **scroll container** — an element that clips,
-in the browser's sense, whether or not it has anything to scroll. Three places
+Containing is only ever read on a **scroll container** — an element whose
+`overflow` is `hidden`, `auto` or `scroll`, whether or not it has anything to
+scroll (`clip` cuts without making one). Three places
 could carry it: the travelling box, everything inside it, or the scrollers
 themselves. Which of the three works is an engine question, and the answer
 splits in two:
@@ -365,12 +367,14 @@ them is that an empty `textarea` is contained too — a browser cannot be asked
 "only if it scrolls" — so on Blink a wheel over one moves nothing rather than
 the list around it.
 
-On Blink this leaves the boxes that **do not clip**, since those are never
-asked. Of navi's own: `SlideContainer` clips (`overflow: hidden`) and a
-`SidePanel` is a `Dialog`, which scrolls (`overflow: auto`) — both are asked. A
-`RouteTravel` box does not clip and must not be made to: a scroll container
-there would become the nearest one for every `position: sticky` inside the pages
-it holds. A row marked swipeable by `interactions` does not clip either.
+On Blink this leaves the boxes that are **not scroll containers**, since those
+are never asked. Of navi's own: a `SidePanel` is a `Dialog`, which scrolls
+(`overflow: auto`), and is asked. A `SlideContainer` cuts with `overflow: clip`,
+which is not a scroll container (`hidden` would be one, and would let the slides
+off stage be scrolled to), so it is not asked. A `RouteTravel` box does not clip
+at all and must not be made a scroll container: one there would become the
+nearest one for every `position: sticky` inside the pages it holds. A row marked
+swipeable by `interactions` is not one either.
 
 Which is why navi contains what it KNOWS scrolls, in `box.jsx`:
 
@@ -386,7 +390,8 @@ does, and it puts the containment exactly where every engine reads it. A list, a
 dialog body, a scrolling panel inside a travelling page are covered on Blink
 again.
 
-What still leaks, and only on Blink, and only under a box that does not clip: a
+What still leaks, and only on Blink, and only under a box that is not a scroll
+container: a
 scroller **nobody declared and no tag names** — a bare
 `<div style="overflow: auto">`, a widget from elsewhere. Its leftovers reach the
 page, which is the old symptom in a much smaller corner. Two ways out, per case:
@@ -447,10 +452,10 @@ The two ends cost differently, and it is worth knowing which one is being felt:
   and there is no gap at all.
 
 What the browser will not turn around with it is everything ELSE the
-transition carries — see "One gesture that bar cannot follow" at the end of
-this file.
+transition carries — see [One gesture that bar cannot
+follow](#one-gesture-that-bar-cannot-follow).
 
-Two things a travel in hand must never lose:
+What a travel in hand must never lose:
 
 - **a travel being undone is not up for grabs.** Its end is already decided;
   held again mid-revert, its animations never finish, the wait for them never
@@ -546,13 +551,13 @@ travel had started finishes without anyone. It is invisible with a mouse, which
 is why it survives a whole session of desktop testing.
 
 So a travel that has become ours refuses the `touchmove` (`preventDefault`), and
-only then — a finger that means to scroll must still scroll. Two details make it
-hold:
+only then — a finger that means to scroll must still scroll. Three details make
+it hold:
 
-- the listener sits on the element the touch LANDED on as well as on the box: a
+- the listener sits on the element the touch LANDED on as well as on the window: a
   touch keeps being dispatched at the node it started on, and a travel may
   replace the DOM under the finger (a page that travels navigates), after which
-  that node no longer passes through the box on its way up;
+  that node no longer passes through the window on its way anywhere;
 - the pointer is captured on the BOX rather than on what the finger landed on,
   for the same reason: what the caller does may take that target away, and a
   capture whose element leaves the document is a capture the browser drops;
@@ -659,7 +664,8 @@ aimed decides what that costs:
     at half of its time a travel has covered ~80% of its distance, and rewound
     at `-1` the visible way home collapses into the steep end of the curve — a
     snap, not a return. The pictures walk home over how far they visibly are
-    from home, at the travel's own pace (`revertWalkTime`);
+    from home, at the travel's own pace (`walkPicturesHome` in
+    `src/transition/view_transition_revert.js`);
   - both of the above run straight into the compositor traps: the distance is
     computed from the clock through the easing curve (the pseudo-elements'
     animated position cannot be read), and the rate is handed over with

package/docs/dynamic_import.md

@@ -126,9 +126,9 @@ what asks, not to the render.**
 
    It starts one render late, and per instance: a component fetched this way
    in three places asks three times (the browser fetches the module once), and
-   coming back to it suspends for the microtask the import takes to answer
-   from the module map. Reach for it when there is genuinely no state to read
-   the request off — not to save declaring one.
+   coming back to it draws its wait again for the microtask the import takes to
+   answer from the module map. Reach for it when there is genuinely no state to
+   read the request off — not to save declaring one.
 
 Delegating instead (the hook without `loading: true`, under a `<Loading>`
 around the frame) follows the rule for data: **the `<Loading>` goes where the
@@ -210,8 +210,10 @@ The page or the component reading its code says it where it stands, as
 above. A failure left to a boundary — a page reading its code without
 `error: true` — reaches it like a failed read does; a boundary that shows only
 what came from the network and rethrows the rest as a bug recognises an import
-by its action — `error.action` is the route action the app declared for the
-code — rather than by the browser's message.
+by its action rather than by the browser's message. `error.action` is the
+instance that ran, not the route action itself (a route action hands out the
+instance for its params), and every instance bound from one action carries its
+`callback`: `error.action.callback === GAME_PAGE_CODE.callback`.
 
 ## Preact's `lazy()` is not this
 

package/docs/error_handling.md

@@ -184,12 +184,16 @@ report — window `error`, the jsenv overlay in dev — and that is the right an
 for it: nothing had to guess whether someone was waiting.
 
 **Some runs have nobody to reject at**, and they say so where they start: one
-started from a signal effect because its params changed, one whose failure the
-control that started it already draws, a routing whose result every caller drops.
+started from a signal effect because its params changed, one started by the
+render that reads it (`{ run: true }`), one whose failure the control that
+started it already draws, a routing whose result every caller drops.
 They pass through [`runUnwatched()`](../src/action/run_unwatched.js), which takes
-the rejection without hiding the error — it stays in `errorSignal`. That is the
-whole list of places navi swallows one, and taking it is what obliges that place
-to ask the next question: did anything display this error? (below).
+the rejection without hiding the error — it stays in `errorSignal`. That is
+every place navi swallows one but the prefetch on intent, dropped without a
+word since nothing on screen asked for it and the arrival runs the action again
+([dynamic_import.md](./dynamic_import.md#ahead-of-the-render-intent)). Taking
+it is what obliges that place to ask the next question: did anything display
+this error? (below).
 
 Two things must never become a rejection, and do not. **A navigation**: the
 routing's promise is what the browser calls the navigation itself, and rejecting
@@ -212,24 +216,19 @@ Whatever displays the error sets `error.__handled_by__` (via
 one thing and only one: **this error is on screen somewhere.**
 
 It is the same mark the jsenv supervisor reads to keep its dev overlay out of
-the way. It has to exist because `preact/debug` re-throws, in a `setTimeout`,
-**every error a boundary handled** — deliberately, so that React-style dev
-overlays keep working:
-
-```js
-// when an error was handled by an ErrorBoundary we will nonetheless emit an error
-// event on the window object. This is to make up for react compatibility in dev mode
-// and thus make the Next.js dev overlay work.
-```
-
-Without the mark, an app calmly displaying "you are offline" gets a crash
-overlay thrown over it.
+the way: a window `error` or `unhandledrejection` carrying it is not shown. An
+error on screen can still reach window another way — a run started by hand and
+never awaited — and without the mark an app calmly displaying "you are offline"
+gets a crash overlay thrown over it. navi's own report reads the same mark
+(below).
 
 Everything navi ships already marks: `<ErrorBoundary>` when it renders its
-fallback, `<ActionRenderer>` / `<Button action>` when they render their error
-branch, `useAsyncData({ error: true })`
-when it hands the error to the component, and a run given an `onError` — asking
-for the error is taking it.
+fallback, `<ActionRenderer>` when it renders its error branch,
+`useAsyncData({ error: true })` when it hands the error to the component, and a
+run given an `onError` — asking for the error is taking it. Every control with
+an `action` runs it that way, so the control claims the failure whatever it
+then shows: a callout, a boundary (`actionErrorEffect="throw"`), or nothing
+(`"none"`, a mapping returning nothing).
 
 ## Taken by nobody: the report
 
@@ -240,10 +239,9 @@ code that produced it.
 **Being read is enough to call the report off**, displayed or not. Once a render
 has the error, everything that can happen next is already covered without this
 module: it is displayed (and marked), or it is thrown — and a thrown error either
-finds a boundary that displays it, or reaches window on its own, since
-`preact/debug` re-throws what a boundary caught and an unbounded throw aborts the
-render loudly. Reporting it here too would be a second voice, and the wrong one:
-this module cannot see which of those happened.
+finds a boundary that displays it, or reaches window on its own, since preact
+re-throws what no boundary handled. Reporting it here too would be a second
+voice, and the wrong one: this module cannot see which of those happened.
 
 **And a render stopped in the middle read nothing after it.** `useAsyncData`
 delegates a failure by throwing it out of the render — that is how the error
@@ -287,8 +285,9 @@ easy to miss when writing another one:
 
 - **Mark only what you actually render.** Marking on catch, before knowing
   whether anything is displayed, turns a boundary into a bug swallower: a
-  `TypeError` in a component becomes a blank page AND a silent one, since the
-  mark muted the overlay that would have pointed at it. navi's boundary marks
+  `TypeError` it then re-throws reaches window marked as on screen, so the
+  overlay that would have pointed at it stays out of the way — a blank page AND
+  a silent one. navi's boundary marks
   just before rendering its fallback, and re-throws untouched when it has no
   fallback — nothing to display means nothing handled.
 - **Reset on the document URL, not only on the rerun.** Re-running the failed

package/docs/field_validation.md

@@ -25,7 +25,8 @@ a validity rule, and the constraint is only its browser-side caller.
 
 ## Constraints
 
-A constraint is `{ name, check(field) }`. `check` returns `null` when the value
+A constraint is `{ name, check(field) }` — a bare `check` function is accepted
+too. `check` returns `null` when the value
 passes, or the message to show — a string, or `{ message, target }` when the
 callout belongs on another element than the control itself.
 
@@ -44,7 +45,7 @@ plain HTML.
 | ------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------- |
 | `required`, `pattern`           | same                                        | what the platform's attributes mean                                             |
 | `minLength`, `maxLength`        | same                                        | a string too short or too long                                                  |
-| `min`, `max`, `step`            | same                                        | a number, date, time or duration out of range                                   |
+| `min`, `max`, `step`            | same                                        | a number, date, time or duration out of range, or off its step                  |
 | `singleSpace`                   | `data-single-space`                         | a leading or trailing space, two in a row                                       |
 | `displayable`                   | `data-displayable`                          | zalgo, a value showing nothing, blank lines in series, a joiner joining nothing |
 | `maxStackedMarks`               | `data-max-stacked-marks`                    | (parameter of `displayable`)                                                    |
@@ -64,9 +65,34 @@ A boolean switch (`displayable`, `singleSpace`, `noEmoji`) passed as `false` is
 off, so `noEmoji={settings.strictNames}` says what it looks like it says. The
 others carry a value — a count, a selector — and are off by being absent.
 
-Each constraint has a `<name>Message` prop (and a `data-<name>-message`
-attribute) to replace its sentence for one field. To change it everywhere,
-override the i18n key instead — see below.
+**`singleSpace="autoFix"` corrects the value instead of refusing it.** A text
+field ends with a space more often than anyone means it to — a pause after a
+word, a mobile keyboard after a suggestion, a paste — and a refusal then asks
+the person to find and delete a character they cannot see. With `"autoFix"`,
+the leading and trailing spaces are removed and a run of spaces becomes one:
+
+```jsx
+<Input name="title" singleSpace="autoFix" />
+```
+
+- **At commit, never while typing.** The correction runs when the field is
+  left, and before an action reads the value. Correcting on each keystroke would
+  eat the space the person is about to follow with a word, so an action run
+  from typing (a search, debounced or not) reads the value as typed.
+- **Nothing to say.** The correction is validity's own `SINGLE_SPACE_RULE`, so
+  the value always passes the rule: no callout, and a server re-checking with
+  `singleSpace: true` accepts what it receives.
+- **It lands everywhere the value lives**: the field, its ui state, the bound
+  `signal`. A `disabled` or `readOnly` field is left alone, since its value is
+  the app's and not the person's.
+- **`singleSpace` is the only constraint that offers it.** A correction is worth
+  it only where it cannot change what the person meant; a `maxLength` silently
+  cutting a text would.
+
+Most constraints take a `<name>Message` prop to replace their sentence for one
+field (`requiredMessage`, `singleSpaceMessage`, `oneOfMessage`…; `step` and the
+time span constraints have none). To change it everywhere, override the i18n
+key instead — see below.
 
 Two props sit beside them and belong to the browser alone, because they act
 before there is a value to validate: `charGuard` blocks a keystroke that is not
@@ -78,7 +104,10 @@ silently swallowing it.
 field can refuse the keystroke with the same knowledge the value is checked
 against: `charGuard="tel"`, `charGuard="slug"`, `charGuard="noEmoji"`. Refusing
 the keystroke and refusing the value are different jobs — the pair
-`maxLengthGuard`/`maxLength` is the same split — and a field usually wants both.
+`maxLengthGuard`/`maxLength` is the same split — and a guard brings the value
+check along: `maxLengthGuard` is checked at submit as `maxLength`, `charGuard`
+sets an `Input`'s `pattern` from its class unless one is given. `maxLength`
+alone is the submit-only half.
 
 **A guard answers for the gesture, never for what the field already holds.** A
 value can arrive already outside the class or already too long — a

package/docs/interactions.md

@@ -104,20 +104,21 @@ which the carrying interactions answer with).
 Two holds on one press — a `longpress` declared on something inside an
 element that declares one too — are answered by the nearer one, the way a
 click is the innermost target's: the inner hold fires, the outer wait is given
-up. Delays being equal; an outer hold made shorter than the inner one fires
-first. A press that lands on something carried inside the element (`move`,
-`moving`, `reorder`…) is that thing's the same way: the outer hold does not
-wait on it, whether the source drags by holding or by distance — except a
-source that says `"refuse"` for this press, which carries nothing.
+up. That is with equal delays; an outer hold made shorter than the inner one
+fires first. navi says so in dev, once per element, the first time it happens:
+the outer hold is a declaration that can never fire, and a picker opened by
+`openOn="longpress"` around a card that already holds one is exactly where it
+happens. One hold has one meaning — two things on one card want two gestures
+(a hold and a click), not two holds. A press that lands on something carried
+inside the element (`move`, `moving`, `reorder`…) is that thing's the same
+way: the outer hold does not wait on it, whether the source drags by holding
+or by distance — except a source that says `"refuse"` for this press, which
+carries nothing.
 
 There is no `dblclick` in that table, on purpose: the browser fires it for a
 mouse and never for a finger, so an element declaring it would answer half the
 hands that reach it. `double_click` is the same gesture counted from the
-pointer — see [Twice, whichever hand it is](#twice-whichever-hand-it-is). navi says so in dev, once per element, the first time it happens: the
-outer hold is a declaration that can never fire, and a picker opened by
-`openOn="longpress"` around a card that already holds one is exactly where it
-happens. One hold has one meaning — two things on one card want two gestures
-(a hold and a click), not two holds.
+pointer — see [Twice, whichever hand it is](#twice-whichever-hand-it-is).
 
 A name nothing knows how to detect produces a dev warning naming the detectors
 that exist. The carrying family and the two surface streams each have a file of
@@ -148,8 +149,9 @@ ancestor can also listen for one, and `preventDefault()` on it means "not this
 time".
 
 The lower-level event the interaction was read from is reachable too:
-`interactionEvent.detail.event` is the `pointerdown` a swipe or a hold was made
-of — which is how a menu is opened at the point the press happened.
+`interactionEvent.detail.event` is the `pointerdown` a hold or a drag was made
+of (a drag's release included), and the `pointerup` that ended a swipe or a tap
+— which is how a menu is opened at the point the press happened.
 
 ## Reaching the control
 
@@ -157,8 +159,8 @@ Everything goes through the interaction gate of the **nearest control** — itse
 an ancestor, or the one control it wraps, in that order. So a disabled, read-only
 or busy control answers a swipe the way it answers a click: it says why, where the
 interaction happened, and nothing runs. A `Box` with no control anywhere near it
-still answers a callback; only `"request_action"` has nothing to ask, and says so
-in dev.
+still answers a callback; only the two requests (`"request_action"`,
+`"request_ui_action"`) have nothing to ask, and say so in dev.
 
 A `Box` that lays out **several** controls — a row of badges, a toolbar — belongs
 to none of them: its interactions are its own, answered with no gate, exactly as
@@ -544,10 +546,11 @@ returns how to undo whatever it did. Listeners, attributes, anything: it is a
 plain setup and teardown, so a detector counts what it needs in its own closure
 and nothing has to hold state on its behalf.
 
-`claims` takes a **set** of names rather than one, because interactions sharing an
-input have to be arbitrated together — a swipe, a hold and a click dispute the
-same press, and read apart they walk over each other. `types` (third argument) is
-which of them were actually declared here.
+`claims` is asked one name at a time, and a detector claims a **set** of them
+rather than one, because interactions sharing an input have to be arbitrated
+together — a swipe, a hold and a click dispute the same press, and read apart
+they walk over each other. `types` (third argument) is which of them were
+actually declared here.
 
 `trigger(type, originalEvent, detail)` says the interaction happened. Called with
 a single event — `trigger(event)` — the type is the detector's own, which only
@@ -577,17 +580,18 @@ container above it does not take the gesture:
   under the same finger reads it before answering: a list reordered vertically
   inside a row of slides swiped sideways leaves the sideways gesture alone, and a
   piece carried both ways inside a bottom sheet takes the press whole. Nothing to
-  wire — see `docs/drag_to_travel.md`. A `Dialog` docked to the bottom edge goes
+  wire — see `docs/drag_to_travel.md`. A `Dialog` docked to an edge goes
   further and reads the press only on its header (plus anything carrying
   `data-swipe-grip`), so its body is free whatever is in it.
 - **A hold does not take the context menu.** Declaring `longpress` says what a
   held finger does; a right click comes from the other button and keeps opening
   the browser's menu. Declare `contextmenu` beside it to make the right click do
   the same thing. (A held _finger_ is the system's own context-menu gesture, and
-  that one is refused while the wait runs.)
+  that one is refused for the length of the press, not just of the wait.)
 - **Where the press already means something, text is not selected.** An element
-  declaring `longpress` or a swipe, and a drag source standing in a
-  `data-drag-on-contact` place, keep their text unselectable: the browser answers
+  declaring `longpress`, a swipe or a counted tap (`double_click`,
+  `single_click`), and a drag source standing in a `data-drag-on-contact`
+  place, keep their text unselectable: the browser answers
   that same press with a selection of its own — the word under the thumb, blue,
   with handles — and nothing takes it back once the press is over. For every
   pointer, mouse included, which cannot finish a selection begun where the press
@@ -621,6 +625,7 @@ container above it does not take the gesture:
 - `src/control/interaction/interaction_press.js` — swipes, holds and the two
   taps, and what a swipe writes on the element.
 - `src/control/interaction/interaction_keyboard.js`,
-  `interaction_native.js` — the other two detectors.
+  `interaction_native.js` — shortcuts, and the browser's own events. The
+  carrying and surface detectors are referenced from their own docs.
 - `src/control/demos/38_interactions_demo.html` — every case above, plus a
   mailbox, a board, a surface, and a custom gesture registered from the page.

package/docs/list_action.md

@@ -29,7 +29,8 @@ refuses in the meantime, which is what you want when the rows are alternatives.
 ```
 
 A press on another row while it runs is refused and says so, in the selection's
-own words ("la sélection est en cours d'enregistrement") rather than in a row's.
+own words ("le choix est en cours d'enregistrement", "la sélection…" in a
+`multiple` list) rather than in a row's.
 
 ## On a row's control: that row waits alone
 
@@ -38,8 +39,9 @@ part of it: it holds no action, nothing about it is busy, and the other rows
 stay live. Two rows can be in flight at once.
 
 ```jsx
-<List selectable multiple>
+<List id="the_list" selectable multiple>
   <List.Item
+    id={rowId}
     selectable
     value={person}
     readOnly={pending}
@@ -60,7 +62,7 @@ stay live. Two rows can be in flight at once.
 
 The command is what marks the row, and it runs **only if the action succeeded**
 — a button given both runs its action first and lets its command follow (see
-[actions.md](./actions.md)). So a refused invitation leaves the row unmarked
+[actions.md](./actions.md#a-press-that-opens-something-and-waits-for-the-answer)). So a refused invitation leaves the row unmarked
 without anything to undo.
 
 `selectableArea="manual"` is about the row's own surface, not about the button:
@@ -149,8 +151,9 @@ nothing about a row's own action stops someone from starting one on every row it
 draws — a dozen requests in flight because the list happened to be long.
 
 So a list allows **four runs at once by default**. While that many are out,
-every row that is not running goes read-only and says how many it is waiting on;
-the next press is possible again the moment one comes back.
+every control in it that would start another run goes read-only and says how
+many it is waiting on; the next press is possible again the moment one comes
+back.
 
 ```jsx
 <List parallelGuard={2}>      // stricter