@jsenv/navi 0.29.170 → 0.29.172

package/docs/AI_INSTRUCTIONS.md

@@ -69,6 +69,13 @@ consistency across the app, not from any single call site.
   collection (searching it is that collection's own `GET_MANY`). Companion
   files: `docs/actions.md`, `docs/resource_with_params.md`,
   `docs/resource_dependencies.md`.
+- `docs/actions.md` — an action and its params: when to call the action versus
+  bind an instance, what a failing run does, the four ways to run one. Read the
+  debounce part before putting a delay on params — a debounced binding follows
+  where its signal SETTLES and never a value it only passed through, settling is
+  a comparison and not a countdown, and the in-between states a gesture writes
+  are real params that `batch()` or a better-shaped question must handle, not
+  the delay.
 - `docs/data_states.md` — what a screen draws while its data is loading,
   missing, stale or failed: the three questions `data`, `loading` and `error`
   answer separately, the four combinations of the first two and what each one
@@ -90,6 +97,19 @@ consistency across the app, not from any single call site.
   Read it before adding verbs to `rerunOn`, hiding a list on `loading`,
   remounting a list with a `key` to refresh it, or reporting that a page
   stopped refreshing since a transition was defined on its pair.
+- `docs/list_action.md` — a list that acts on what it holds, and the one thing
+  that decides how it waits: where the `action` lives. On the `<List>` it is the
+  selection being sent and the whole list waits; on a row's own button it is a
+  call about that row and the other rows stay live. Also who draws the wait and
+  answers a press when a row carries a control (the control, always — the row is
+  the fallback for a row that holds nothing but text), why such a row is
+  `readOnly` and never `loading`, and the one that works by luck: a list held
+  read-only refuses the `--navi-select` its own button fires on success, and
+  whether it lands comes down to a tick — clearing the flag in a `finally` saves
+  it, clearing it a moment later loses the selection silently. Read it before
+  putting `loading` on a row whose button is working, before
+  `<List readOnly={pending}>`, and before writing a second spinner next to the
+  one a control already draws.
 - `docs/error_handling.md` — the two kinds of error and how navi keeps them
   apart: where an error is shown depending on where it came from (a control's
   action shows it on what was clicked, a route action replaces the page, a
@@ -160,8 +180,11 @@ consistency across the app, not from any single call site.
   RESORT for a decision that is not a press — with the rule that decides most
   reviews: the `event` it takes is the gesture you were handed, threaded down to
   the call, never a `new CustomEvent()` built on the spot (that is for a timer,
-  an action settling, a signal changing, and nothing else). Read it before
-  calling `triggerNaviCommand`, before passing `open` to a popup, and before an
+  an action settling, a signal changing, and nothing else). Also the close
+  cross: `<Dialog.Close />` exists, it is the way out and so the one affordance
+  the surrounding read-only/disabled does not reach, and it asks rather than
+  forces. Read it before calling `triggerNaviCommand`, before passing `open` to
+  a popup, before writing a close button by hand, and before an
   `onOpen`/`onClose` writing a signal.
 - `docs/autofocus.md` — who gets the keyboard when a popup opens or a slide
   arrives, and whether a ring shows on it: the ladder navi walks, what

package/docs/actions.md

@@ -102,6 +102,40 @@ is drawing it. During the delay the instance is still the previous one, holding
 the previous answer — `loading` is what says a newer one is coming, don't
 compare params by hand to find out.
 
+### A debounced signal asks where it settles, not where it passed
+
+The delay publishes where the signal **settles**, never a value it only passed
+through on the way. A question that goes `A → B → A` inside the delay is the
+question `A`: no request goes out for `B`, and `loading` never went up. Only a
+signal that is somewhere new once the delay elapses moves the binding.
+
+That is load-bearing rather than a nicety, because settling is a **comparison,
+not a countdown**: `paramsSettlingSignal` is true while the signal and the
+binding differ and false when they agree. Move the binding to a value the signal
+is not on and nothing is left that could make them agree again — the screen is
+told a newer answer is coming, with no delay still running to bring one, and
+only another write to the source frees it. So a value the source never settled
+on does not cost a stale request, it costs a screen stuck on "loading".
+
+### The in-between states of a gesture are real params
+
+The delay decides _when_ a question goes out, never _which_ one is coherent: it
+sees every write, including the ones a gesture only passes through. Moving an
+item from one slot to another by filling the new slot and then emptying the old
+one is two writes, and between them the item is in both — a state nobody meant
+to ask about, and a question the delay would happily send if it landed there.
+
+Make the intermediate not matter, rather than counting on the delay to hide it.
+Two ways, both worth having on their own:
+
+- **`batch()` the writes that belong to one gesture**, so the intermediate state
+  never exists at all — not for the delay, not for a render, not for a
+  validation rule reading the same signals.
+- **Shape the question so states that are equivalent compare equal.** Params are
+  compared deeply, so a list whose order carries nothing asks a new question
+  every time it is rearranged; sent deduplicated and sorted, rearranging stops
+  changing the question — better than asking it late.
+
 ## Running: `run`, `rerun`, `prerun`, `reset`
 
 | Method     | Does                                                                     |

package/docs/interactions.md

@@ -590,6 +590,12 @@ about a value the affordance does not write, so answering "read-only" to a
 gesture that was never going to write anything says nothing true. Use it only
 when that is really the case.
 
+navi's own `<Dialog.Close />` is the second canonical case: a read-only picker
+still opens, and leaving what it opened writes nothing to it — so the cross is
+`"ignore"` and a hand-written one must say the same, or it refuses the press
+aimed at the way out (see
+[popup_open.md](./popup_open.md#the-close-cross)).
+
 Busy is not on the list because busy does not block: it is the read-only a
 running action sets on its way that does.
 

package/docs/list_action.md

@@ -0,0 +1,121 @@
+# A list that acts on what it holds
+
+Two different screens are written with the same components: a list that answers
+one question (which seat, which side, which city) and a list that is a place to
+act, row by row (invite this person, archive that row). They look alike and they
+wait very differently, and what decides it is one thing:
+
+**Where the action lives decides who waits.**
+
+- [On the list: one answer, and the list waits](#on-the-list-one-answer-and-the-list-waits)
+- [On a row's control: that row waits alone](#on-a-rows-control-that-row-waits-alone)
+- [Who draws the wait, and who answers a press](#who-draws-the-wait-and-who-answers-a-press)
+- [Read-only, not loading](#read-only-not-loading)
+- [Hold the rows, not the list](#hold-the-rows-not-the-list)
+
+Live examples: the **Button** section of
+`src/control/demos/13_list_selectable_demo.html` shows both, side by side, over
+a backend answered by hand.
+
+## On the list: one answer, and the list waits
+
+`action` on the `<List>` is the selection being sent. The list holds one value,
+so there is one run, and the whole list is busy until it comes back — every row
+refuses in the meantime, which is what you want when the rows are alternatives.
+
+```jsx
+<List selectable action={(seat) => putSeat(seat)}>
+```
+
+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.
+
+## On a row's control: that row waits alone
+
+`action` on the button inside the row is a call about that row. The list is not
+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.Item
+    selectable
+    value={person}
+    readOnly={pending}
+    selectableArea="manual"
+  >
+    <Text expandX>{person}</Text>
+    <Button
+      action={() => invite(person)}
+      command="--navi-select"
+      commandFor="the_list"
+      command-value={rowId}
+    >
+      Invite
+    </Button>
+  </List.Item>
+</List>
+```
+
+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
+without anything to undo.
+
+`selectableArea="manual"` is what makes the button the interaction surface: the
+row stops claiming presses that land anywhere in it, so the only way in is the
+button.
+
+## Who draws the wait, and who answers a press
+
+**Whatever control is on the row carries the wait and the refusal.** A button,
+a checkbox, a picker — it has a place to draw a spinner and an anchor to hang a
+callout on, and it is what the user pressed. The row itself is the fallback,
+for a row that holds nothing but text: it draws a loading outline, swallows
+presses (its buttons included) and opens the sentence itself.
+
+That is why a selectable row does not answer a press twice. It swallows the
+press so nothing inside it acts, then asks the control it carries to explain —
+one callout, one sentence, the same on the pointer and on the keyboard, and the
+caller's `readOnlyMessage` / `busyMessage` respected either way.
+
+## Read-only, not loading
+
+A row whose button is working is **not loading** — the button is. The row is in
+use, and what says that is `readOnly`:
+
+```jsx
+<List.Item readOnly={pending} readOnlyMessage="Invitation en cours." />
+```
+
+`loading` on a row means the ROW is waiting on something — being added to the
+list, removed from it, saved where it is (see the `loading` values on
+`List.Item`). Putting it there for a control's run draws a second wait next to
+the one the button is already drawing, and says the row is being changed when it
+is only being used.
+
+Give the row a `readOnlyMessage` when it is held for a reason that will pass:
+the default sentence is about availability ("this option is not available"),
+which is the wrong thing to say about a wait.
+
+## Hold the rows, not the list
+
+It is tempting to write `<List readOnly={pending}>` to keep a second row from
+being pressed while one is in flight. It works, and it works by luck: the
+command the button fires on success (`--navi-select`) is aimed at the list, and
+a list still read-only at that moment refuses it — the call goes through and the
+row is never marked, silently.
+
+Whether it lands comes down to one tick. Clearing the flag in a `finally` clears
+it before the command runs, so the selection arrives; clearing it a moment later
+— a transition, a debounce, one more `await` on the way out — loses it. Nothing
+on screen says which of the two you wrote.
+
+Hold the rows instead. `readOnly` on every row is what "one at a time" looks
+like, it says the same thing on screen, and it leaves the list free to take the
+answer whenever the answer comes:
+
+```jsx
+<List.Item readOnly={pending !== null} />   // all of them: one at a time
+<List.Item readOnly={pending.includes(name)} />  // this one: each on its own
+```

package/docs/popup_open.md

@@ -12,6 +12,7 @@ What opens a `Dialog` or a `Popover`, and who owns the fact that it is open.
 - [A press that opens a popup and acts on it](#a-press-that-opens-a-popup-and-acts-on-it)
 - [Reacting to open and close](#reacting-to-open-and-close)
 - [Escape cancels, the other gestures keep](#escape-cancels-the-other-gestures-keep)
+- [The close cross](#the-close-cross)
 - [When the app holds the open state](#when-the-app-holds-the-open-state)
 - [A popup that loads data](#a-popup-that-loads-data)
 - [What the popup holds while it is closed](#what-the-popup-holds-while-it-is-closed)
@@ -423,12 +424,12 @@ that fails does so behind a closed popup**.
 The gestures that close a popup do not all mean the same thing, and that is on
 purpose:
 
-| gesture                         | what it means | who decides                                         |
-| ------------------------------- | ------------- | --------------------------------------------------- |
-| Escape                          | cancel        | `escapeEffect="cancel"` (default)                   |
-| a click outside                 | close, keep   | `pointerInteractionOutsideEffect="close"` (default) |
-| a close button (`--navi-close`) | close, keep   | the button                                          |
-| `--navi-cancel` on a button     | cancel        | the button                                          |
+| gesture                        | what it means | who decides                                         |
+| ------------------------------ | ------------- | --------------------------------------------------- |
+| Escape                         | cancel        | `escapeEffect="cancel"` (default)                   |
+| a click outside                | close, keep   | `pointerInteractionOutsideEffect="close"` (default) |
+| a close cross (`--navi-close`) | close, keep   | [the cross](#the-close-cross)                       |
+| `--navi-cancel` on a button    | cancel        | the button                                          |
 
 Escape says "forget it". It is the one gesture that has meant that everywhere,
 for as long as there have been dialogs, and navi keeps it that way. **A popup
@@ -500,6 +501,69 @@ A dialog picker's cancel also goes back in history, so anything written to the
 url while it was open (a route `stateSignal`, a search param) goes back with it
 — one more reason Escape and the click outside are not interchangeable.
 
+## The close cross
+
+The cross is navi's own: `<Dialog.Close />`, `<Popover.Close />`,
+`<Popup.Close />` — one component under three names, reached from whichever
+popup is being written. The caller places it, and nothing else:
+
+```jsx
+<Dialog id="duration">
+  <Box header flex="x" alignY="center" padding="s">
+    <Box expandX>Durée de la partie</Box>
+    <Dialog.Close />
+  </Box>
+  …
+</Dialog>
+```
+
+It comes with the things a hand-written cross has to remember: the `aria-label`
+in the active language (`label` overrides it), and the padding that turns a
+three-millimetre glyph into a target a thumb can hit.
+
+### It is the way out, so the state around it does not reach it
+
+**A close button written by hand refuses the press inside a read-only control.**
+A read-only `Picker` still opens — what it holds is often a shape only its popup
+draws, and reading it changes nothing — and it hands its popup that same
+read-only so every control in there refuses on its own terms. The cross is not
+one of those controls: closing writes nothing to the picker. `<Dialog.Close />`
+says so (`whenSelfInteractionsBlocked="ignore"`, see
+[interactions.md](./interactions.md)); a `<Button command="--navi-close" />`
+does not, wears the read-only it was handed, and answers a press aimed at the
+way out with "this action is not available right now".
+
+The same holds for a disabled zone, and for a form busy sending: the way out of
+a popup is never held by the state of what the popup belongs to.
+
+If a cross really has to be hand-written — it is drawn into a bigger affordance
+of the app's own, say — it carries the claim itself:
+
+```jsx
+<Button command="--navi-close" icon whenSelfInteractionsBlocked="ignore">
+  …
+</Button>
+```
+
+### It asks, it does not force
+
+Being exempt from the state around it is not being exempt from the popup's
+answer. The cross sends `--navi-close`, which reaches the popup as a close
+REQUEST — the same one Escape and the click outside make — and the popup
+decides:
+
+- a control inside it is mid-action → the close is refused, and that control
+  says why ([above](#the-popup-owns-its-open-state));
+- `onRequestClose` calls `preventDefault()` → the popup stays open;
+- a `Picker` takes the close as an answer, so it validates what its popup holds
+  and runs its action on the way out — and an invalid value keeps it open.
+
+The cross therefore lands exactly where a click outside lands: same request,
+same refusals, same "close, keep". A popup that must not be dismissed at a given
+moment says so in its own `onRequestClose`, where Escape and the backdrop are
+refused too — not by hiding or disabling the cross, which only removes the one
+way out that is visible.
+
 ## When the app holds the open state
 
 A popup whose being-open is a fact about the application rather than about the

package/package.json

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