@jsenv/navi 0.29.172 → 0.29.174

package/docs/AI_INSTRUCTIONS.md

@@ -109,7 +109,9 @@ consistency across the app, not from any single call site.
   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.
+  one a control already draws. Also `parallelGuard` — how many of a list's rows
+  may be acting at once, four by default, `Infinity` to lift it: it counts runs
+  where `maxLengthGuard` counts values.
 - `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

package/docs/list_action.md

@@ -12,6 +12,7 @@ wait very differently, and what decides it is one thing:
 - [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)
+- [How many at once: `parallelGuard`](#how-many-at-once-parallelguard)
 
 Live examples: the **Button** section of
 `src/control/demos/13_list_selectable_demo.html` shows both, side by side, over
@@ -79,6 +80,26 @@ 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.
 
+And it lands **where the press landed**. A row answers for a whole box, and its
+own control is a visually hidden checkbox, so a sentence anchored on that would
+sit in the middle of the row pointing at nothing. Pressed on the button, it
+belongs on the button; pressed on the row's own surface, on the row:
+
+| what was pressed                                | where the sentence appears |
+| ----------------------------------------------- | -------------------------- |
+| the button of a row whose own run is going      | the button                 |
+| the name of that same row                       | the row                    |
+| the button of a row held back by something else | the button                 |
+
+The last one needs nothing special: that row is not blocked, so the press
+reaches the button and the button's own gate answers it.
+
+A row that would rather always take it says so once:
+
+```jsx
+<List.Item data-callout-anchor="item" />
+```
+
 ## Read-only, not loading
 
 A row whose button is working is **not loading** — the button is. The row is in
@@ -119,3 +140,26 @@ answer whenever the answer comes:
 <List.Item readOnly={pending !== null} />   // all of them: one at a time
 <List.Item readOnly={pending.includes(name)} />  // this one: each on its own
 ```
+
+## How many at once: `parallelGuard`
+
+A list is a place where the same gesture is available many times over, and
+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.
+
+```jsx
+<List parallelGuard={2}>      // stricter
+<List parallelGuard={Infinity}>  // lifted, without taking it out of the tree
+```
+
+It counts runs, not values — which is the whole difference from `maxLengthGuard`
+next to it: that one says how many things the selection may HOLD, this one how
+many may be HAPPENING. A list can carry either, or both, and they refuse for
+unrelated reasons.
+
+Only a control that would start a run is held: a row with nothing to run, or a
+button that merely fires a command, never waits its turn.

package/package.json

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