@jsenv/navi 0.29.148 → 0.29.149

package/docs/AI_INSTRUCTIONS.md

@@ -263,12 +263,14 @@ consistency across the app, not from any single call site.
   of navi's own.
 - `docs/interactions.md` — the `interactions` prop: making a component answer a
   swipe, a held press, a shortcut, and registering a gesture navi does not have.
-  It also holds `ownTarget`, for an affordance an application draws inside a
-  zone that belongs to another control — a chip's cross, an eye, a diskette:
-  the three modes and the question that picks one (does it write to the control
-  it sits in?), the `Box` form that claims the press and nothing more (so an
-  affordance keeps its own drawing instead of becoming a control), and what
-  `ownTarget` does NOT stop (a plain `onClick` on an ancestor).
+  It also holds `selfInteractions`, for an affordance an application draws
+  inside a zone that belongs to another control — a chip's cross, an eye, a
+  diskette: why the claim is a required LIST (a press is not a drag, and what
+  is not named stays the zone's), `whenSelfInteractionsBlocked` and the question
+  that picks one of its three modes (does it write to the control it sits in?),
+  the `Box` form that claims interactions and nothing more (so an affordance
+  keeps its own drawing instead of becoming a control), and what the claim does
+  NOT stop (a plain `onClick` on an ancestor).
   Read it before reading the pointer by hand — who owns a press between nested
   boxes, and what a touch may do, are decided before the first pixel moves and
   cannot be got right from outside navi — and before stopping the propagation of

package/docs/actions.md

@@ -96,7 +96,9 @@ available while a rerun is in flight). Where a failure goes when no screen takes
 it — and why a run settles with its error rather than rejecting — is
 [error_handling.md](./error_handling.md). `useActionStatus(action)` gives the whole
 state at once — `{ idle, loading, completed, aborted, error, data, params }` —
-for a component that needs to look at it rather than render it.
+for a component that needs to look at it rather than render it. It reads that
+very instance: to know what moves when a control is handed the action, see
+[the instance a control runs](#the-instance-a-control-runs).
 
 **Reading does not run.** `useAsyncData` waits for data someone else asked for
 — for a page, the route, through `routeAction`. A component reading an action
@@ -187,6 +189,38 @@ callback:
 </Button>
 ```
 
+## The instance a control runs
+
+A control binds the action it is given to its own UI state and runs the result.
+Which instance that is depends on whether the control carries a value:
+
+- a control with **no value of its own** — a button — contributes no params, so
+  what it runs **is** the instance it was handed. `useActionStatus` on that
+  instance sees the click, the run, the data.
+- a control that **carries a value** — an input, a form — runs the child
+  instance bound to that value. Those params are not the caller's, so neither
+  is the status: the instance the caller holds stays idle while the control's
+  run moves. Read the effect where it lands (the store, for a resource verb),
+  or listen to the run itself, below.
+
+Every control with an `action` reports the run it performs, whichever instance
+that is:
+
+```jsx
+<Button
+  action={shareAction}
+  onActionStart={(e) => {}}
+  onActionEnd={(data, e) => {}}
+  onActionError={(error, e) => {}}
+  onActionAborted={(e) => {}}
+/>
+```
+
+`onActionEnd` receives the data of a run that **completed** — a failure never
+reaches it. A failure goes to `onActionError`, alongside wherever the error is
+displayed (see [error_handling.md](./error_handling.md)); an abort to
+`onActionAborted`.
+
 ## `action` or `uiAction`
 
 Both fire when a control's value changes, and they are not two ways of writing
@@ -257,10 +291,10 @@ once per row. See
 [popup_open.md](./popup_open.md#a-press-that-opens-a-popup-and-acts-on-it).
 
 What is left for an `onClick` is what no value can express — imperative work
-with nothing to open and nothing to send. And one nuance worth knowing: on an
-`ownTarget`, a caller's `onClick` runs inside that control's own interaction
-gate rather than firing from the DOM (see
-[interactions.md](./interactions.md#an-affordance-inside-somebody-elses-box-owntarget)),
+with nothing to open and nothing to send. And one nuance worth knowing: on a
+control with `selfInteractions`, a caller's `onClick` runs inside that control's
+own interaction gate rather than firing from the DOM (see
+[interactions.md](./interactions.md#an-affordance-inside-somebody-elses-box-selfinteractions)),
 so the usual objection — an `onClick` fires on a read-only control — does not
 apply there. Everywhere else it does.
 

package/docs/error_handling.md

@@ -41,6 +41,11 @@ validation message on the **requester** (the submit button, not the form):
   else — `"none"` — means the control displays nothing because something else
   does. `<Details>` uses that: its `<ActionRenderer>` shows the error inside the
   open panel.
+- `onActionError(error, event)` fires alongside whichever display was chosen —
+  it is for reacting to the failure, not for showing it (showing stays claimed
+  by the message or the boundary). Its siblings on every control with an
+  `action` — `onActionStart`, `onActionEnd`, `onActionAborted` — are in
+  [actions.md](./actions.md#the-instance-a-control-runs).
 
 ### A screen's data failed — a route action
 

package/docs/interactions.md

@@ -531,64 +531,94 @@ sideways), while a `move` goes wherever it is put, a `land` wherever the board h
 places and a `toss` wherever it was thrown (`xy`). `data-drag-delay`,
 `data-drag-slop`, `data-drag-threshold` tune when the press becomes a grab.
 
-### An affordance inside somebody else's box: `ownTarget`
+### An affordance inside somebody else's box: `selfInteractions`
 
 A chip's cross inside a carried piece, an eye on a row that travels, a diskette
-on a picker's façade. It is aimed AT, not merely inside, and the press belongs
-to it alone:
+on a picker's façade. It is aimed AT, not merely inside — but aimed at for
+WHAT, which is the whole of the prop:
 
 ```jsx
-<Badge.Button ownTarget onClick={() => remove(id)}>
+<Badge.Button selfInteractions="click" onClick={() => remove(id)}>
   ×
 </Badge.Button>
 ```
 
-No gesture starts under it, no navi control above it answers the mousedown or
-the click, and its `onClick` waits for its own interaction gate instead of
-firing from the DOM.
+The press is now this cross's alone: no navi control above it answers the
+mousedown or the click, and its `onClick` waits for its own interaction gate
+instead of firing from the DOM.
 
-#### Does it write to the control it sits in?
+#### Why it is a list, and why it is required
 
-That question, and nothing else, picks the mode:
+A press is not a drag. A drag announces itself — a few pixels of travel with a
+mouse, a long hold with a finger — and a click is the absence of both, so the
+two can be told apart without anyone guessing at pointerdown. An affordance
+that claimed every gesture at once would be a HOLE in whatever it sits in: a
+badge drawn against the edge of a card is a seventh of that card, and precisely
+the edge one grabs to carry it.
 
-| what it does                                                 | mode                 | on a read-only / disabled / busy zone     |
-| ------------------------------------------------------------ | -------------------- | ----------------------------------------- |
-| writes to it (a cross that removes, a stepper)               | `ownTarget`          | it goes                                   |
-| writes to it, and its presence says there is something there | `ownTarget="refuse"` | it stays and refuses with a callout       |
-| never touches it (a diskette saving into MY address book)    | `ownTarget="always"` | nothing changes: still lit, still pressed |
+So the claim names its interactions, and what it does not name stays the zone's:
+
+| written                        | takes                     | leaves                              |
+| ------------------------------ | ------------------------- | ----------------------------------- |
+| `selfInteractions="click"`     | the press                 | the grab — the card is still carried by it |
+| `selfInteractions="click drag"`| both                      | —                                   |
+| `selfInteractions="*"`         | every gesture, now and later | —                                |
+
+`"*"` is there for the case where it is true, not as a shorthand: it is the one
+value that will silently swallow a gesture navi has not shipped yet.
+
+`data-drag-ignore` says a different thing, to the gesture alone and for all of
+them at once: the press there is none of the gesture's business, and the element
+keeps both its cursor and its text selection.
+
+#### Where the zone blocks: does it write to the control it sits in?
+
+That question, and nothing else, picks `whenSelfInteractionsBlocked` — what
+becomes of the affordance where the zone around it is disabled or read-only.
+The claimed interactions are its subject, and only them: the ones left to the
+zone were never this element's to block.
+
+| what it does                                                 | written                                      | on a blocked zone                         |
+| ------------------------------------------------------------ | -------------------------------------------- | ----------------------------------------- |
+| writes to it (a cross that removes, a stepper)               | nothing — `"hide"` is the default            | it goes                                   |
+| writes to it, and its presence says there is something there | `whenSelfInteractionsBlocked="refuse"`       | it stays and refuses with a callout       |
+| never touches it (a diskette saving into MY address book)    | `whenSelfInteractionsBlocked="ignore"`       | nothing changes: still lit, still pressed |
 
 A greyed cross that still removes is worse than no cross — hence the default.
-`"always"` is the other extreme and the caller owns it: the zone's read-only is
+`"ignore"` is the other extreme and the caller owns it: the zone's read-only is
 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.
 
+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.
+
 #### On something you draw yourself
 
-`ownTarget` is a `Box` prop too, so an affordance does not have to become a
-control to claim its press — a pastille positioned in a card's corner by its own
-class stays exactly what it was drawn as:
+`selfInteractions` is a `Box` prop too, so an affordance does not have to become
+a control to claim its interactions — a pastille positioned in a card's corner
+by its own class stays exactly what it was drawn as:
 
 ```jsx
-<Box as="button" ownTarget className="court_side" onClick={explain}>
+<Box as="button" selfInteractions="click" className="court_side" onClick={explain}>
 ```
 
-On a box the prop does exactly one thing: it writes `data-own-target`. That
-attribute is the claim — it is what the controls above read, and what the
+On a box the prop does exactly one thing: it writes `data-self-interactions`.
+That attribute is the claim — it is what the controls above read, and what the
 gesture readers read (`data-drag-handle`, `data-drag-ignore` and friends are the
-same vocabulary). Writing it by hand on an element navi does not render works
-and is the last resort: a typo there is silent, whereas the prop is spelled
-once.
+same vocabulary), each picking its own word out of it. Writing it by hand on an
+element navi does not render works and is the last resort: a typo there is
+silent, whereas the prop is spelled once and checked.
 
-The modes above are the other half, and they belong to controls: they are about
-a gate, a callout and a control's own read-only, none of which a box has. A box
-claims the press and nothing more; put the affordance on a control when what it
-does about a held zone matters.
+`whenSelfInteractionsBlocked` is the other half, and it belongs to controls: it
+is about a gate, a callout and a control's own read-only, none of which a box
+has. A box claims interactions and nothing more; put the affordance on a control
+when what it does about a held zone matters.
 
 #### When the affordance should sit OUTSIDE instead
 
-`ownTarget` says a façade CAN yield a zone; it does not say it should. What
-decides is whether the affordance stays where the finger left it.
+`selfInteractions` says a façade CAN yield a zone; it does not say it should.
+What decides is whether the affordance stays where the finger left it.
 
 An icon that lives inside its control while that control is showing, and
 becomes a pill of its own once it is not, is a switch that moves when you flip
@@ -598,21 +628,36 @@ which is the whole gesture on a phone. `<ControlSwap>` is that row: two
 controls taking turns in the middle, a fixed cap at each end.
 
 So: an affordance that acts on what it sits in (a chip's cross, a stepper, an
-eye on a row) belongs inside, and takes its press back with `ownTarget`. One
-that swaps what is being shown belongs outside it, where it can stay put.
+eye on a row) belongs inside, and takes its press back with `selfInteractions`.
+One that swaps what is being shown belongs outside it, where it can stay put.
+
+Whichever side of the frame it ends up on, the control must be told, because a
+control draws affordances of its own and will otherwise draw a second one:
+
+- **inside** — a field has slots for it, `Input.UI.LeftSlot`,
+  `Input.UI.RightSlot`, `Input.UI.IconSlot` (an icon sized on the line rather
+  than on a character) and `Input.UI.UnitSlot`. They label the field, so a
+  press lands on it rather than blurring it — except when the field is not
+  focused yet, where the slot may take the focus itself, which is what a clear
+  cross or a reveal-password eye needs.
+- **outside** — the icon the type would have drawn has to go, or it sits two
+  centimetres from yours: `icon={null}`. It is the same prop that replaces it
+  (`icon={<MySvg />}`) and that leaves it alone (left out). A `search` field
+  still swaps that slot for its clear cross once it holds a value, whatever
+  `icon` says — the cross is about the value, not about the decoration.
+
+```jsx
+<Input type="search" icon={null} /> // the row draws the magnifier
+```
 
 #### navi steps back; a plain `onClick` does not
 
-What `ownTarget` stops is navi answering: the controls above it, and the
-gestures. It does **not** stop the event — the propagation is left whole, so
+What the claim stops is navi answering: the controls above it, and the gestures
+it named. It does **not** stop the event — the propagation is left whole, so
 that everything which is not a navi interaction still sees the press it always
 saw. A raw `onClick` on an ancestor is one of those, and still fires; stop it
 there yourself if it must not.
 
-`data-drag-ignore` says a narrower thing, to the gesture alone: the press there
-is none of the gesture's business, and the element keeps both its cursor and its
-text selection.
-
 ### What says a thing can be picked up
 
 Almost nothing, on purpose. A **handle** (`data-drag-handle`) exists only to drag,

package/docs/resource.md

@@ -138,6 +138,13 @@ One verb dispatching on a string gives up everything the store does for you:
 per-operation action state (loading/error per button), per-relation autorerun,
 and a child collection that other components can read.
 
+The same smell wears a second coat: a verb on one relation carrying, in its
+params, an id from a **different** relation — a `group_id` sent to the game ×
+user shares, which the server expands into people. That is two relations
+spelled as one, and the one the gesture is actually about (game × group) is the
+one that ends up with no rows, no action state, and nothing for its row on
+screen to read.
+
 | Situation                                                                                                     | Use                                                                                                                                 |
 | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
 | The child is a first-class entity with its own store, shared across parents (a user referenced by many games) | `.one()` / `.many()`                                                                                                                |
@@ -149,6 +156,18 @@ and a child collection that other components can read.
 Singular vs plural is about the relation, not the verb: `.one`/`.scopedOne` for a
 single sub-object, `.many`/`.scopedMany` for a collection.
 
+And the table has a negative worth naming, because the workaround looks fine in
+a demo: **a write whose effect the response does not carry is a modelling bug,
+not a case for the client to remember.** After the write, some row on screen
+will claim "this happened" — and it must read that from the store, which only
+holds what responses carried. When the relation actually written has no row
+anywhere (the response answered with a different entity than the one the
+gesture was about), whatever the screen memorizes instead lives on the client
+and **dies with the session**: reload, and the row confidently claims the write
+never happened. The fix is on the shape — give that relation its own
+relationship method and a callback returning what was written, even when the
+backend must grow a field for it — never a flag next to the button.
+
 ## Callback return contracts
 
 These are not guessable — each relationship method has its own shape.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.148",
+  "version": "0.29.149",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {
@@ -29,7 +29,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@jsenv/dom": "0.17.35",
+    "@jsenv/dom": "0.17.36",
     "@jsenv/humanize": "1.7.8",
     "@jsenv/validity": "0.4.3"
   },
@@ -40,6 +40,7 @@
     "@jsenv/plugin-preact": "../../related/plugin-preact",
     "@jsenv/snapshot": "../../tooling/snapshot",
     "@jsenv/terminal-table": "../../tooling/terminal-table",
+    "@jsenv/test": "../../related/test",
     "@jsenv/urls": "../../tooling/urls",
     "@preact/signals": "2.11.1",
     "playwright": "1.62.1",