@jsenv/navi 0.29.37 → 0.29.39

package/docs/AI_INSTRUCTIONS.md

@@ -78,6 +78,11 @@ consistency across the app, not from any single call site.
   `header`/`body`/`footer` on, `FixedBar` space, `List`'s `scroller`, and
   scroll inside a `Dialog`/`Popover`. Read it before writing CSS to make
   something scroll — navi almost certainly already has the prop.
+- `docs/control_value.md` — who holds a control's value: nobody, a bound
+  `signal` (two-way, in both directions), or you (`value`/`checked`). What
+  `signal` + `defaultValue` says, what a signal holds for each kind of control,
+  and why `value` and `signal` cannot both be passed. Read it before wiring a
+  control's value by hand with `value` + `uiAction`.
 - `docs/control_group.md` — `<Group>`: several controls reading as one framed
   object (one border per seam, radius on the outer corners only). Read it
   before placing bordered controls against each other, and before writing

package/docs/actions.md

@@ -115,3 +115,6 @@ changes do exactly that).
 - [resource_with_params.md](./resource_with_params.md) — `withParams()` and
   isolated rerun scopes
 - [list_refresh.md](./list_refresh.md) — what a write refreshes
+- [popup_open.md](./popup_open.md#closing-when-a-button-also-runs-an-action) —
+  closing a popup from a button that also runs an action (closing from inside
+  the action is refused)

package/docs/control_value.md

@@ -0,0 +1,132 @@
+# Who holds a control's value
+
+Nobody, a signal, or you. Every control answers one of those three, and which
+one it is decides what happens when the value moves — from a gesture, or from
+somewhere else in the app.
+
+- [The three answers](#the-three-answers)
+- [A bound signal works in both directions](#a-bound-signal-works-in-both-directions)
+- [`signal` + `defaultValue`: the answer and where it starts](#signal--defaultvalue-the-answer-and-where-it-starts)
+- [What a signal holds, control by control](#what-a-signal-holds-control-by-control)
+- [Which controls take a `signal`](#which-controls-take-a-signal)
+- [`value` and `signal` exclude each other](#value-and-signal-exclude-each-other)
+- [A `stateSignal` brings more than a value](#a-statesignal-brings-more-than-a-value)
+
+## The three answers
+
+| what you pass          | who holds the value | when the user acts                          |
+| ---------------------- | ------------------- | ------------------------------------------- |
+| nothing                | the control         | it keeps it; `uiAction` tells you           |
+| `defaultValue`         | the control         | same — the default is only where it starts  |
+| `signal`               | the signal          | the control writes it back, both ways       |
+| `value` (or `checked`) | you                 | nothing moves until you hand a new one down |
+
+A control given `value` and nothing to listen to it (`uiAction`, `action`, a
+`signal`, a surrounding form) is read-only, and says so in dev: it is showing
+something nobody can change.
+
+## A bound signal works in both directions
+
+This is the part that does not show in a call site: `signal` is not a seed. The
+control writes every change into it, **and follows it when something else
+writes it**.
+
+```jsx
+const minutesSignal = useSignal(0);
+
+<Wheel type="integer" signal={minutesSignal}>
+  {MINUTES.map((m) => (
+    <Wheel.Item key={m} value={m}>
+      {pad2(m)}
+    </Wheel.Item>
+  ))}
+</Wheel>;
+
+// elsewhere — the wheel rolls to 30, no re-render of your own needed
+minutesSignal.value = 30;
+```
+
+Both halves are worth knowing about, because each replaces a habit:
+
+- the write-back replaces `uiAction={(v) => (mySignal.value = v)}`;
+- the follow replaces the `key` or the `value`/`uiAction` pair used to push an
+  outside change into a control.
+
+## `signal` + `defaultValue`: the answer and where it starts
+
+They are not competing, they answer two different questions:
+
+- the **signal** is the answer, when it holds one;
+- `defaultValue` is where the control starts, and where a reset goes back to.
+
+```jsx
+// "how many players" is what my account usually answers, unless this game says
+// otherwise — no `??` to write, and no first render showing the wrong one
+<List selectable signal={gameLevelsSignal} defaultValue={me.levels}>
+```
+
+An emptied signal (`signal.value = undefined`) puts the control back on its
+default rather than leaving it blank — which is what makes "nothing decided
+here, use the usual answer" expressible at all. Without a `defaultValue`, an
+emptied signal empties the control.
+
+## What a signal holds, control by control
+
+The signal holds what the control is ABOUT, which is not always its `value`
+attribute:
+
+| control                                                       | what the signal holds             |
+| ------------------------------------------------------------- | --------------------------------- |
+| text/number/date `Input`, `Wheel`, `Spin`, `Picker`, `Select` | the value itself                  |
+| checkbox, radio                                               | a boolean — whether it is checked |
+| `List selectable`                                             | the selected value                |
+| `List selectable multiple`, checkbox group                    | the array of selected values      |
+
+A group (a selectable list, a checkbox group) writes its whole selection into
+the signal, not one item's value — its children put it together between them.
+
+## Which controls take a `signal`
+
+All of them: `Input` (every type), `Picker`, `Select`, `Wheel`, `Spin`,
+`List selectable` (single and multiple), and control groups in general. Anything
+that is a navi control goes through the same state controller, and the same
+`signal` prop.
+
+Inside a `List selectable` you can bind the list, or give each `List.Item` its
+own `selected` — but not expect the two to arbitrate. An item that declares
+`selected` is answering for itself, and the list's signal does not reposition
+it.
+
+## `value` and `signal` exclude each other
+
+`value` (or `checked`) says "you hold it", `signal` says "the signal holds it".
+Passing both is a call site to fix: **the signal wins and the other prop is
+ignored** — on a leaf control as on a group (a selectable list, a checkbox
+group) — and navi says so in dev. One owner, whichever half of the binding you
+look at.
+
+Replacing `value` with `signal` also means dropping the `uiAction` that used to
+write the signal by hand — it is exactly what the binding now does. Keep
+`uiAction` only for what is not "remember the value": logging, a side effect,
+something else moving with it.
+
+## A `stateSignal` brings more than a value
+
+A plain signal (`useSignal`, `signal()`) is enough to bind a control. A
+`stateSignal` also carries its own `options`, and a control reads them so it
+does not have to be told twice: `type` (which decides the input type and the
+validation messages), `min`, `max`, `step`, and its **default**, which seeds
+`defaultValue`/`defaultChecked` — so a reset goes back to the signal's original
+default rather than to whatever it happened to hold at the last render.
+
+That is the only difference. A plain signal binds the same way in both
+directions; it just has nothing extra to say.
+
+## See also
+
+- [control_group.md](./control_group.md) — several controls reading as one
+  framed object
+- [actions.md](./actions.md) — `action` vs `uiAction`: what carries loading and
+  error
+- [popup_open.md](./popup_open.md#escape-cancels-the-other-gestures-keep) — what
+  a cancelled popup does to the value inside it

package/docs/popup_open.md

@@ -8,6 +8,7 @@ What opens a `Dialog` or a `Popover`, and who owns the fact that it is open.
 - [Which element receives the command](#which-element-receives-the-command)
 - [The anchor](#the-anchor)
 - [Reacting to open and close](#reacting-to-open-and-close)
+- [Escape cancels, the other gestures keep](#escape-cancels-the-other-gestures-keep)
 - [When `open` is the right answer, and what it costs](#when-open-is-the-right-answer-and-what-it-costs)
 - [What the popup holds while it is closed](#what-the-popup-holds-while-it-is-closed)
 
@@ -51,7 +52,9 @@ the opening?":
 
 The available commands: `--navi-open`, `--navi-close`, `--navi-toggle`,
 `--navi-cancel` (closes, telling the popup the close means "revert"),
-`--navi-confirm` (says yes, then closes).
+`--navi-confirm` (says yes, then closes). What "revert" does to what is inside
+is [its own section](#escape-cancels-the-other-gestures-keep) — it is also what
+Escape says.
 
 ## Something else opens it: `triggerNaviCommand`
 
@@ -139,6 +142,107 @@ useLayoutEffect(() => {
 }, []);
 ```
 
+### Closing when a button also runs an action
+
+Closing from inside the `action` does not close. While the action runs, the
+button that started it is busy, and a busy control is exactly what a popup
+refuses to close over (see the top of this page). The refusal is not silent —
+the busy control raises a callout saying so — but the popup stays open, and the
+first Escape afterwards dismisses that callout rather than the popup, which
+reads as a popup that no longer closes at all.
+
+There are two shapes, and they say different things:
+
+```jsx
+// Closes on the press. The popup does NOT wait for save(): it is already
+// closed when the action starts, and the action finishes behind it.
+<Button command="--navi-close" commandfor="note-dialog" action={save}>
+  Save
+</Button>
+```
+
+`command` next to `action` is the one to reach for when the answer is taken as
+soon as it is given — the popup gets out of the way, the save runs on its own.
+Know what it costs: **a save that fails does so behind a closed popup**, and the
+error callout it raises lands on a button nobody can see any more. Use it where
+the failure is reported somewhere else, or where losing it is acceptable.
+
+```jsx
+// Closes only once save() has resolved, and stays open if it throws.
+<Button
+  action={save}
+  onActionEnd={() => {
+    // NOT synchronously: the button still counts as busy while its own
+    // action-end handlers run, and the popup would refuse the close.
+    queueMicrotask(() => {
+      triggerNaviCommand(dialogRef.current, "--navi-close");
+    });
+  }}
+>
+  Save
+</Button>
+```
+
+`onActionEnd` only fires when the action succeeded, so the popup stays open on
+failure — the answer is then neither committed nor given up, and it is still
+there to be corrected, with the error shown on the button that raised it.
+
+## Escape cancels, the other gestures keep
+
+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                                          |
+
+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
+that must offer a way out that KEEPS what was chosen offers it with a close
+cross, or by letting the click outside close** — not by teaching Escape to say
+something else.
+
+### What "cancel" actually undoes
+
+Cancelling is not itself an undo: it marks the close, and whoever holds a value
+decides what to do with the mark.
+
+- `Dialog` and `Popover` hold nothing, so they undo nothing. The close event
+  carries `detail.isCancel` and `onClose` receives it — reverting is then the
+  caller's own business.
+- `Picker` holds a value, so it puts back **the value it held when it opened**.
+  That is what makes a picker a picker: opening one is trying something on, and
+  Escape is putting it back.
+
+```jsx
+// Escape here puts back the level the picker held at open, and the list's
+// uiAction fires with that restored value — the draft goes back with it.
+<Picker id="level" ui={…}>
+  <List selectable multiple value={draft.levels} uiAction={…}>…</List>
+</Picker>
+```
+
+The trap is the FIRST open. A picker holds what its popup told it, and before
+the popup has ever been open it has been told nothing — so "the value at open"
+is nothing, even when the control inside starts on a `defaultValue` or on a
+value the app passes it. Escape on that first pass goes back to empty, not to
+what was on screen when the popup opened. From the second open onwards it puts
+back what was really there.
+
+### `escapeEffect="close"`, and why it is a last resort
+
+`escapeEffect="close"` makes Escape say what a click outside says. It exists,
+and it is almost never what you want: it takes away the only key that undoes,
+and a popup with no way back is one people stop opening. Reach for a close
+cross first.
+
+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.
+
 ## When `open` is the right answer, and what it costs
 
 `open` is for a popup whose being-open is a fact about the application, not

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.37",
+  "version": "0.29.39",
   "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.12",
+    "@jsenv/dom": "0.17.13",
     "@jsenv/humanize": "1.7.8",
     "@jsenv/validity": "0.4.2"
   },