@jsenv/navi 0.29.443 → 0.29.444

package/docs/AI_INSTRUCTIONS.md

@@ -114,8 +114,8 @@ start when unsure which export solves a problem.
   Before any handler whose body only assigns state.
 - `control_value.md` — who holds a control's value; `--navi-update` for a button
   proposing one; a `defaultValue` follows the record it was read from; empty
-  keeps the shape of the question. Before wiring a value with `value` +
-  `uiAction`.
+  keeps the shape of the question; what a checkbox is worth (`boolean` for a
+  yes/no). Before wiring a value with `value` + `uiAction`.
 - `control_object.md` — one value made of several controls: `ControlGroup` versus
   `Form`, naming, `<Picker type="object">`, a settings sheet, controls that are
   not there (lazy slides, popups, deferred boxes, items outside the render
@@ -226,8 +226,10 @@ start when unsure which export solves a problem.
   `<Input type="checkbox">`/`<Input type="radio">`; there is no `Checkbox`),
   `Select`, `Picker` and the others work with nothing wired: inside a `Form`, the
   form reads them when it sends. When the app needs the value, bind it with
-  `signal`. `action` reacts to a change that can fail or take time; it is not how
-  a control is wired. Never `onChange` + manual state.
+  `signal`. A checkbox is HTML's (`"on"` or its `value`, `undefined` unchecked);
+  a yes/no is `<Input type="checkbox" boolean>`, `true` or `false`. `action`
+  reacts to a change that can fail or take time; it is not how a control is
+  wired. Never `onChange` + manual state.
 - **A gesture is named, not read by hand**: `interactions={{ swipe_right: … }}`
   on any `Box`, so on any component — never a `pointerdown` listener of your own.
 - **Texts**: a user-visible sentence containing a value is one template with

package/docs/actions.md

@@ -313,13 +313,17 @@ the control's value, so the callback receives what the control now holds.
 ```jsx
 // ✓ the box shows it is saving, says so if the save fails, and goes back to
 //   where it was — nothing to write for any of it
-<Input type="checkbox" action={(visibility) => saveMe({ visibility })} />
+<Input type="checkbox" boolean action={(visibility) => saveMe({ visibility })} />
 
 // ✗ same save, and the user learns nothing: no pending state, and a failure
 //   leaves the box showing something the server never accepted
-<Input type="checkbox" uiAction={(visibility) => saveMe({ visibility })} />
+<Input type="checkbox" boolean uiAction={(visibility) => saveMe({ visibility })} />
 ```
 
+`boolean` makes the box a yes/no, `true` or `false`; without it, unchecked is
+`undefined` and the save sends nothing (see
+[control_value.md](./control_value.md#what-a-checkbox-is-worth)).
+
 The give-away is an `async` `uiAction`, or one that calls something that writes:
 `uiAction` never waits for what it starts, so nobody is left holding the result.
 To merely REMEMBER the value rather than send it, neither is the answer: bind a

package/docs/control_value.md

@@ -14,6 +14,7 @@ somewhere else in the app.
 - [Drawing what a control holds](#drawing-what-a-control-holds)
 - [What a signal holds, control by control](#what-a-signal-holds-control-by-control)
 - [Empty keeps the shape of the question](#empty-keeps-the-shape-of-the-question)
+- [What a checkbox is worth](#what-a-checkbox-is-worth)
 - [Which controls take a `signal`](#which-controls-take-a-signal)
 - [The PROP is what controls, not its value](#the-prop-is-what-controls-not-its-value)
 - [A yes/no shown as two rows](#a-yesno-shown-as-two-rows)
@@ -281,18 +282,37 @@ it holds something. A list of days nobody picked is `[]`, not `""`:
 | `Picker type="array"`, `List selectable multiple` | `[]`     |
 | `Picker type="object"`                            | `{}`     |
 | text/number/date `Input`, `Select`                | `""`     |
-| `Input type="checkbox" value={true}`              | `false`  |
-| radio, checkbox holding a value of its own        | absent   |
+| `Input type="checkbox" boolean`                   | `false`  |
+| radio, any other checkbox                         | absent   |
 
 This is what a clear (`--navi-clear`, a row's cross) leaves behind and what the
 object around it carries, so `value.days || []` is not needed.
 
-A checkbox is a member of a set, the way HTML has it: checked it carries its
-`value` (`"on"` when it was given none), unchecked it carries nothing at all —
-which is what lets several checkboxes sharing a name aggregate into an array. A
-checkbox that is a yes/no says so with `value={true}`, and is then `true` or
-`false`. Its bound `signal` holds the boolean either way: what a signal on a
-checkbox is about is whether it is checked.
+## What a checkbox is worth
+
+A checkbox answers the way HTML's does: checked it carries its `value`,
+unchecked it carries nothing. `boolean` makes it a yes/no instead:
+
+| checkbox       | checked  | unchecked   |
+| -------------- | -------- | ----------- |
+| no `value`     | `"on"`   | `undefined` |
+| `value="toto"` | `"toto"` | `undefined` |
+| `value={true}` | `true`   | `undefined` |
+| `boolean`      | `true`   | `false`     |
+
+That is what it hands everywhere: to its own `action` and `uiAction`, and to
+the form or group around it. Only a bound `signal` differs: it holds whether the
+box is checked, a boolean in every row above.
+
+Choose by what the box asks:
+
+- **A yes/no** (a setting, a consent, a favourite) is `boolean`. Unchecked has
+  to say "no", and `undefined` says nothing: `{ favourite: undefined }` is sent
+  as `{}`, the server changes nothing, and the box shows a "no" nobody
+  accepted.
+- **A member of a set** (several checkboxes sharing a `name`, each adding its
+  value) takes its own `value`, or none for `"on"`. Unchecked carries nothing,
+  so the group gathers only the checked ones into an array.
 
 ## Which controls take a `signal`
 

package/package.json

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