@jsenv/navi 0.29.151 → 0.29.153

package/docs/AI_INSTRUCTIONS.md

@@ -138,6 +138,17 @@ consistency across the app, not from any single call site.
   `smallTouchScreenSignal` in an app to change a dialog's size, before passing
   `expandX={false}` to stop a dialog sprawling, and before writing CSS to make a
   dialog fit the screen.
+- `docs/popup_open.md` — what opens a `Dialog`/`Popover` and who owns the fact
+  that it is open: why a popup with no `open` prop is the default (it refuses to
+  close while a control inside it is mid-action), the attributes that open one
+  (`command` + `commandfor`, `value` saying what it is opened ON, reaching
+  `onOpen` before the content is built), and `triggerNaviCommand` as the LAST
+  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
+  `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
   `autoFocus` means on a surface (`true` = the surface takes it, for a popup

package/docs/error_handling.md

@@ -30,7 +30,15 @@ validation message on the **requester** (the submit button, not the form):
 
 - `errorMapping(error)` turns the raw error into what to show: a string, an
   `Error`, an element, or `{ message, target }` to point the message at another
-  element.
+  element. Two returns matter as much as those:
+  - **`return error` — the error untouched — is how a mapping says "not mine"**.
+    It is then shown exactly as if there were no mapping at all, so a mapping
+    only has to know about the cases it dresses.
+  - **returning nothing displays nothing**, on purpose: that is how one
+    particular error is swallowed, per error, where `actionErrorEffect="none"`
+    says it once for the whole control. Beware of it as a default — a mapping
+    whose last branch falls off the end swallows everything it did not
+    recognize, and the person sees the button return to idle with no message.
 - The message is a constraint on the control (`navi_action_error`) rather than a
   render of its own, and it **auto-resets on the next action**: hitting submit
   again clears it and re-submits, instead of the form being stuck invalid.
@@ -47,6 +55,49 @@ validation message on the **requester** (the submit button, not the form):
   `action` — `onActionStart`, `onActionEnd`, `onActionAborted` — are in
   [actions.md](./actions.md#the-instance-a-control-runs).
 
+#### A refusal that carries a link
+
+The callout is not limited to a sentence. When the refusal has somewhere to go —
+"this slot is already taken by that game" — the mapping returns an element and
+the callout holds it, link included:
+
+```jsx
+<Form
+  action={GAME.POST.bindParams(values)}
+  errorMapping={(error) => {
+    const conflict = error.conflict;
+    if (!conflict) return error; // not mine: shown as-is
+    return (
+      <>
+        Ce créneau est déjà pris par{" "}
+        <Link route={GAME_ROUTE} routeParams={{ id: conflict.game_id }}>
+          cette partie
+        </Link>
+      </>
+    );
+  }}
+>
+```
+
+That is the whole thing: the message arrives on the button that was pressed, it
+survives whatever ran before it (a `command` waits for its own action), and it
+clears itself on the next submit. A refusal with a destination does **not** need
+a render of its own in the page.
+
+Two consequences of the message being an element:
+
+- it is rendered as a **preact tree of its own** into the callout, not as part
+  of the app tree, so it receives no context from the app. Anything reading
+  global signals — a navi `<Link route>`, a store — works; anything expecting an
+  app `Context.Provider` above it does not, and has to be given what it needs
+  through props;
+- it has no one-line form, so nothing derives a `title` from it — the callout is
+  the only place it is shown. A string or an `Error` message still writes the
+  control's `title` when the control has none of its own.
+
+[form_error_mapping_jsx demo](../src/control/demos/form_error_mapping_jsx/demo.html)
+shows a mapping answering with a different component per error kind.
+
 ### 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/popup_open.md

@@ -5,6 +5,7 @@ What opens a `Dialog` or a `Popover`, and who owns the fact that it is open.
 - [The popup owns its open state](#the-popup-owns-its-open-state)
 - [A button opens it: the attributes](#a-button-opens-it-the-attributes)
 - [Something else opens it: `triggerNaviCommand`](#something-else-opens-it-triggernavicommand)
+  - [The event is forwarded, not invented](#the-event-is-forwarded-not-invented)
 - [Which element receives the command](#which-element-receives-the-command)
 - [The anchor](#the-anchor)
 - [Opening it ON something](#opening-it-on-something)
@@ -75,10 +76,15 @@ press:
 
 ## Something else opens it: `triggerNaviCommand`
 
-The attributes fire on every click of the element that carries them. As soon as
-the opening is a decision rather than a click — a long press, the end of a drag,
-a double-click, a keyboard shortcut, a server answer, an `IntersectionObserver` —
-the decision has to be made in JS, and the command triggered from there:
+The attributes fire on every click of the element that carries them, and they
+cover more than "this button opens that dialog": `commandfor` says to whom,
+`value` says what it is about, `--navi-x:argument` says how. Before writing any
+JS here, check none of those is the answer — `triggerNaviCommand` is the last
+resort, not the general way to run a command.
+
+What it is for is a decision rather than a click — a long press, the end of a
+drag, a double-click, a keyboard shortcut, a server answer, an
+`IntersectionObserver`:
 
 ```jsx
 import { triggerNaviCommand } from "@jsenv/navi";
@@ -100,16 +106,41 @@ This is the same entry point the attributes go through: same target resolution,
 same command proxies, same events. The popup stays uncontrolled, and keeps its
 say over closing.
 
+### The event is forwarded, not invented
+
 `event` is what caused the decision, and it is mandatory — triggering a command
 without one throws. It is chained into the request event, and that chain is what
 lets the popup handle focus correctly (which element to give focus back to,
 whether a mousedown's click must be swallowed) and what the debug panel groups
 the whole sequence under.
 
-Almost always there is a DOM event to hand over, because almost always something
-was done to the page. When there genuinely was not — a timer firing, an action
-settling, a signal changing — say so with a `CustomEvent` named after what
-happened rather than leaving the origin unsaid:
+So the event to pass is **the one that is already there**, threaded down through
+every function between the handler and the call. A `CustomEvent` built on the
+spot satisfies the signature and defeats its purpose: the origin is a name
+instead of a gesture, and everything read off the real event is gone.
+
+```js
+// ✗ the handler drops the event, the command is told a story instead
+const openMenu = () => {
+  const openEvent = new CustomEvent("open");
+  triggerNaviCommand(popoverRef.current, "--navi-open", openEvent);
+};
+
+// ✓ the handler passes on what it was given
+const openMenu = (event) => {
+  triggerNaviCommand(popoverRef.current, "--navi-open", event);
+};
+```
+
+A helper several presses share takes the event as a parameter like any other;
+the same holds one layer deeper, when the decision is taken by something navi
+handed an event to — an `interactions` detector, an `onOpen`, an action's
+callback. Follow it back: there is a gesture at the start of nearly every
+sequence.
+
+The exception is the sequence that genuinely started on its own — a timer
+firing, an action settling, a signal changing. Then say what happened with a
+`CustomEvent` named after it, rather than leaving the origin unsaid:
 
 ```js
 import { chainEvent, triggerNaviCommand } from "@jsenv/navi";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.151",
+  "version": "0.29.153",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {
@@ -49,6 +49,7 @@
     "access": "public"
   },
   "sideEffects": [
+    "./src/navi_instance.js",
     "./src/navi_css_vars.js",
     "./src/navi_z_indexes.js",
     "./src/control/interaction/*.js",