@jsenv/navi 0.29.417 → 0.29.419

package/docs/form_changed.md

@@ -1,10 +1,10 @@
 # What a form sends, and what it measures against
 
 A form answers a question. Asked again with the same answer, it has nothing to
-say — so by default **a `<Form>` sends nothing when nothing changed**. This is
-the whole subject of this file: what "changed" is measured against, what counts
-as an answer the form already holds, and what to do on a screen whose fields are
-filled a request later.
+say — so by default **a `<Form>` sends nothing when nothing changed**. This file
+is about what "changed" is measured against, what counts as an answer the form
+already holds, and what to do on a screen whose fields are filled a request
+later.
 
 - [Sending nothing is the default](#sending-nothing-is-the-default)
 - [What follows a send](#what-follows-a-send)
@@ -21,8 +21,9 @@ hold their defaults, one reopened and left alone — runs **no action**. No
 request, nothing in the network tab.
 
 Everything around the action still happens: the constraints are checked, and
-what follows the send still follows it (the popup closes, the slide moves on).
-The user is done either way; there was simply nothing to send.
+what follows the send still follows it — the popup closes, the slide moves on,
+the page changes. The user is done either way; there was simply nothing to
+send.
 
 `canSendWhileUnchanged` turns that off, for a form where sending the same thing
 twice is the point — a single button firing a notification, an action whose
@@ -35,18 +36,24 @@ duplicates are fine.
 ## What follows a send
 
 The form has answered its question; `command` says what the screen does about
-it — dismiss the popup (`--navi-close`), move on the slide map
-(`--navi-left`…), go to a page (`--navi-nav-to:/games/42`), go back to the one
-the reader came from (`--navi-nav-back:/games`), empty itself and stay where it
-is (`--navi-reset`), stay put as it is (`--navi-void`). Left out, the surface the
-form sits in decides: a popup closes, a slide goes on, a form on a page does
-nothing.
+it — `--navi-close`, `--navi-left`…, `--navi-nav-to:/games/42`,
+`--navi-nav-back:/games` (back to the page the reader came from),
+`--navi-reset` (empty itself and stay), `--navi-void` (stay put as it is). Left
+out, the surface the form sits in decides: a popup closes, a slide goes on, a
+form on a page does nothing. A submit button says its own with `formCommand`,
+which wins over the form's: in a form with two ways out, "save" stays and
+"delete" goes back to the list.
+
+It is a prop, decided before the send, because it runs **whether or not there
+was anything to send**. Nothing runs when the send fails, or when a constraint
+refuses it: the form stays in front of the person, showing what it is waiting
+for.
 
 ### A popup that stays open
 
-A side panel, a dialog or a popover closes once a form inside it is sent. When
-the popup is a place one keeps working in — a panel where a push is sent, two
-fields are fixed, an account is linked — the form says it stays:
+A popup closes once a form inside it is sent. When it is a place one keeps
+working in — a panel where a push is sent, two fields are fixed, an account is
+linked — the form says it stays:
 
 ```jsx
 <SidePanel signal={openUserSignal} value={user.id}>
@@ -56,13 +63,9 @@ fields are fixed, an account is linked — the form says it stays:
 </SidePanel>
 ```
 
-The form says it, not the popup. A popup does not know which of its forms is
-its answer: the same panel can hold a form you edit in over and over and a
-"delete" whose send has to close it. A popup that stays open whatever is sent
-inside it would make every form in it that should close say so again, which
-is the same repetition in the other direction. Nor does a `SidePanel` get a
-different default from a `Dialog`: the same content in either one should
-behave the same, and on a small screen a `SidePanel` often _is_ a dialog.
+The form says it, not the popup: the same panel can hold a form edited in over
+and over and a "delete" whose send has to close it, and the same content should
+behave the same in a `SidePanel` or a `Dialog`.
 
 When the popup's open state is a url param (`signal` bound to a route's search
 param), closing it takes the param out of the url. A form that forgot
@@ -71,28 +74,20 @@ is what a reload would have brought back.
 
 `--navi-reset` is the one to reach for when the form is a place one comes back
 to — an entry created, then the next one: the fields go back to their
-`defaultValue`, ready for the next entry. (What the form is measured against
-stays what was just sent — see below — so the emptied form reads as changed,
-and the fields' own constraints are what keep an empty one from being sent.)
+`defaultValue`. What the form is measured against stays what was just sent (see
+below), so the emptied form reads as changed, and the fields' own constraints
+are what keep an empty one from being sent.
 
 ```jsx
 <Form action={createPlaceGroup} command="--navi-reset">
 ```
 
-It runs **whether or not there was anything to send** — that is the other half
-of the rule above: the person is done either way, and a submit that ran no
-action still closes the popup, still moves on, still navigates. Which is why
-this is a prop, decided before the send: the form has to know where it goes even
-when nothing happened.
-
-Nothing runs when the send fails, or when a constraint refuses it. The form then
-stays in front of the person, showing what it is waiting for.
-
 ### When only the response knows where to go
 
 A creation lands on the page the server just made, and its id comes back with
 the response — too late for a prop. Do it in the action, which is where the
-answer is:
+answer is (a creation always has something to send, so there is no "the press
+did nothing" case for `command` to cover):
 
 ```jsx
 <Form
@@ -103,13 +98,10 @@ answer is:
 >
 ```
 
-Nothing to declare: a creation always has something to send, so there is no
-"the press did nothing" case for `command` to cover.
-
-If you would rather it go through the command machinery all the same (to reuse
-whatever a command does on that surface), the form carries what follows the send
-as `data-after-send`, read once the send has succeeded — so an action can write
-it while it runs:
+To go through the command machinery all the same (to reuse whatever a command
+does on that surface), write it where the form keeps what follows the send,
+`data-after-send`, read once the send has succeeded — an action can write it
+while it runs:
 
 ```js
 formRef.current.setAttribute("data-after-send", `--navi-nav-to:/games/${id}`);
@@ -151,19 +143,17 @@ An age that is usually 18, a duration that is usually 1h30 — the form holds
 nothing there, and confirming the suggestion IS an answer ("yes, 18"), which
 must be sendable. A bound signal falls on whichever side its content puts it: a
 signal restored from the url or set by whoever fills the screen carries an
-answer, even when the signal also declares a default (its default only says
-where a reset goes back to).
-
-The same question is asked of a single control by `isUIStateHeld`
-(`src/control/held_ui_state.js`) — a form asks it once per field.
+answer. A `stateSignal` that declares a default is never empty — the default is
+what it holds until something else is written, and what writing `undefined`
+puts back — so its field counts as held from the start.
 
 ## A screen filled after it opened: `pristineKey`
 
-The baseline is taken as soon as the fields have registered, which is right for
-a form whose values are there on the first render — and wrong for a screen that
-modifies something: the resource arrives a request later and fills the fields,
-so a form measured against what it held BEFORE that opens **already changed**.
-Its submit is live, and pressing it sends back the resource untouched.
+The baseline taken as the fields register is right for a form whose values are
+there on the first render — and wrong for a screen that modifies something: the
+resource arrives a request later and fills the fields, so the form opens
+**already changed**. Its submit is live, and pressing it sends back the resource
+untouched.
 
 `pristineKey` takes the baseline again. Pass whatever says the filling is done:
 
@@ -171,23 +161,19 @@ Its submit is live, and pressing it sends back the resource untouched.
 <Form pristineKey={game && players && places ? "loaded" : undefined}>
 ```
 
-Change it **once**, when the screen is ready. Taken again after someone started
-typing, it would call what they wrote the reference.
-
-No need to delay it by a tick: the reference is taken when the fields have
-settled, and again at the end of that same tick — so a row that arrives in a
-render of its own (a value computed from signals, a memoized row) is part of it
-without the screen having to know which of its fields settle late.
+Change it **once**, when the screen is ready: taken again after someone started
+typing, it would call what they wrote the reference. There is no tick to wait
+for — fields that settle in a render of their own are part of it.
 
 Do not use a `key` on the `<Form>` for this: it remounts every control and every
 popup inside it, and anything half-typed goes with them.
 
 ## A submit that says it is waiting
 
-By default a submit that sends nothing is still accepted — in a dialog or a
-slide it closes / moves on all the same. In a form that goes nowhere on its own,
-the press would visibly do nothing; `readOnlyWhileFormUnchanged` on the button
-holds it back and says what it is waiting for.
+A submit that sends nothing is still accepted — in a dialog or a slide it closes
+or moves on all the same. In a form that goes nowhere on its own, the press
+would visibly do nothing; `readOnlyWhileFormUnchanged` on the button holds it
+back and says what it is waiting for.
 
 ```jsx
 <Button type="submit" readOnlyWhileFormUnchanged>
@@ -208,26 +194,23 @@ something, a list acting on every touch. They say so with `standalone`:
 ```
 
 `standalone` is not a filter, it is the absence of a relationship: the control
-does not register with the group around it. Nothing goes up — its value is not
-collected, and the form stays unchanged whatever it does — and nothing comes
-down either: the form's reset does not reach it, nor does its validation
-cascade.
+does not register with the group around it. Nothing goes up (its value is not
+collected, the form stays unchanged whatever it does) and nothing comes down
+(the form's reset, its validation cascade).
 
 What it does **not** say is "ignore everything around me". `disabled`,
 `readOnly` and `loading` travel on their own contexts and go on reaching it,
-and that is deliberate: a door that carries no value of its own can still
-write into the form through what its popup does, and a read-only form must
-still shut it. An affordance that genuinely writes nowhere says that
-separately, with `whenSelfInteractionsBlocked="ignore"` — as it says whose
-press it is with `selfInteractions`, and a control whose action is meant to be
-left running says THAT separately too, with `actionStandalone`. One question
-each, one prop each (see
+deliberately: a door with no value of its own can still write into the form
+through what its popup does, and a read-only form must still shut it. An
+affordance that genuinely writes nowhere says so separately
+(`whenSelfInteractionsBlocked="ignore"`), as it says whose press it is with
+`selfInteractions`, and a control whose action is meant to be left running
+with `actionStandalone` — one question each, one prop each (see
 [interactions.md](./interactions.md#the-third-question-whose-value-is-it)).
 
-Every control takes the prop, groups included — `<Form standalone>` is the
-same sentence, and so is a `<List standalone>` inside a picker's popup, which
-is what lets a search box or a second list sit beside the one that IS the
-answer (see
+Every control takes the prop, groups included — `<Form standalone>`, or a
+`<List standalone>` sitting beside the one that IS the answer in a picker's
+popup (see
 [control_object.md](./control_object.md#a-picker-whose-value-is-an-object)).
 
 ## See also

package/docs/group.md

@@ -0,0 +1,141 @@
+# Grouping controls (`<Group>`)
+
+What we want: **several controls reading as one object.** A search input and
+its button, a row of segmented buttons, a column of setting rows — when they
+belong together, the eye should see one frame with divisions inside it, not
+three boxes that happen to touch: one border along each seam instead of two side
+by side, and a radius only on the four outer corners.
+
+`<Group>` is what produces that. Reach for it whenever you place controls
+against each other and any of them has a border or a radius — never hand-write
+negative margins, `border-radius: 0` overrides, or a `borderRadius` prop set to
+`0` on the middle members. Those spellings look right on the case you are
+looking at and break on the next one: a member added at the end, a member
+hidden by a condition (the "first" is then the second child), a switch from row
+to column.
+
+```jsx
+<Group>
+  <Input name="search" placeholder="Search…" />
+  <Button>Go</Button>
+</Group>
+```
+
+Stacked, one setting per row:
+
+```jsx
+<Group row>
+  <Picker name="side" ui={…} expandX />
+  <Picker name="level" ui={…} expandX />
+  <Picker name="city" ui={…} expandX />
+</Group>
+```
+
+`row` (or `vertical`, the same prop — each member is a row, so they stack
+vertically and meet along horizontal seams) is the only prop that changes the
+arrangement; everything else is read off the members themselves. Say it rather
+than `flex="y"`: the seams follow `row`, not the layout.
+
+Live examples: `src/control/demos/15_group_demo.html`.
+
+## What Group does to its members
+
+- **Seams**: a member with a member before it is pulled back by one border
+  width, so the two borders along a seam become one line — the member's own
+  `--border-width` when it declares one, else the group's `--group-border-width`
+  (default: `--navi-control-border-width`).
+- **Corners**: a member loses the radius on each side where it faces another
+  member. A single member keeps its own radius — a group of one looks like the
+  control alone.
+- **Members only**: a child out of the group's flow is none of its business. A
+  popup renders inside its opener's subtree, so a `Dialog` or `Popover` written
+  next to the button that opens it is a child of the group, backdrop included; a
+  callout anchored on a `<button>` is mounted in that button's parent. They mark
+  themselves `navi-out-of-flow`, and the group skips them: none takes a corner,
+  none moves anyone else's (a row of one button and the dialog it opens is still
+  a group of one), none is pulled back by a border width.
+- **Overlap order**: the member hovered, the one showing a focus ring (on itself
+  or inside it), and the one holding something open (`aria-expanded="true"`)
+  paint above their neighbours, so their border and ring are not sliced
+  (`--navi-z-index-control-hovered` / `-focused` / `-expanded`, expanded
+  highest). The group is deliberately not isolated — see
+  [z_index.md](./z_index.md#why-a-group-member-is-not-isolated).
+
+Nothing else: a group does not restyle its members, does not impose a size,
+and takes any `Box` prop for its own layout.
+
+## Writing a control that belongs in a group
+
+A group never writes a selector that reaches inside a member — a member's
+subtree holds more than the member (a `Picker` renders its popup inside itself;
+a control carries buttons of its own, like the clear cross in a slot), and a
+rule matching "some descendant" finds all of them. It asks for a square corner
+in two forms instead, and a control answers with whichever fits.
+
+**The property, on the member itself.** A control declares the radius of its
+frame on its own root, and whatever inner element paints that frame takes
+`border-radius: inherit`:
+
+```css
+.navi_thing {
+  /* Declared here even though the box below is what draws it */
+  border-radius: var(--thing-border-radius);
+
+  .navi_thing_box {
+    border: ...;
+    border-radius: inherit;
+  }
+}
+```
+
+**The custom property, which travels.** A member is not always the control that
+carries the frame: a button can arrive wrapped in a tooltip or a link, at any
+depth. So the group also sets `--x-corner-top-left-radius` and its three
+siblings on the member, and a control that can arrive wrapped reads them as an
+override of its own radius. The `--x-` prefix marks navi's internal wiring, not
+a surface an app writes to (an app changes a radius with the `borderRadius`
+prop, which lands in the fallback):
+
+```css
+.navi_thing {
+  border-top-left-radius: var(
+    --x-corner-top-left-radius,
+    var(--thing-border-radius)
+  );
+  /* …and the three others */
+}
+```
+
+**Whoever answers the ask also stops it.** Custom properties inherit all the
+way down, so the control that consumed a corner sets the four back to `initial`
+on the first element inside it — otherwise a button in a slot, or the Save
+button of a form in an open popup, reads a corner meant for the row that opened
+it. `Popover` and `Dialog` stop it at their own root. **A member drawing the
+frame itself stops it too**: a `Box` that paints a background or a border, or
+insets what it holds with padding, is what the outer corner belongs to, and
+marks itself `navi-box-frame` to stop the claims for everything inside. A
+wrapper adding neither — a tooltip, a link, a bare `<Box>` — lets them through
+to the control that really carries the frame.
+
+A control that declares its radius on an inner element instead is invisible to
+`Group`: it keeps round corners in the middle of the row, and no rule in
+`group.jsx` can reach it without naming that private class. Fix the control, not
+the group. The controls shipped by navi all follow this: `Button`, `Input`,
+`Select`, `Picker`, `Spin`, checkbox, range.
+
+## When it is not a Group
+
+- Controls separated by space, each with its own frame — that is a `Box` with
+  `spacing`, they were never one object.
+- A label and its control — that is `Field`.
+- Several controls making ONE value between them (an address out of three
+  fields, a day and two wheels out of one moment) — that is `ControlGroup`,
+  which is about the value and draws nothing. Same word, other subject: see
+  [control_object.md](./control_object.md). Both at once is fine — a `Group`
+  around the members of a `ControlGroup`.
+- Radio buttons or checkboxes sharing a name and a validation — that is
+  `RadioGroup` / `CheckboxGroup`, which is about the value, not the frame. They
+  can be put inside a `Group` if you also want them to share a frame.
+- Controls that are ONE value between them, with a word written inside the frame
+  (the hours and the minutes of "07h30") — that is `SpinGroup`, which drops the
+  members' frames rather than joining them.

package/docs/i18n.md

@@ -9,7 +9,7 @@ Translation is a consequence of doing that, not the reason to do it. An app with
 one language still benefits from one place holding its wording; and once it does,
 adding a second language becomes a data change instead of a refactor.
 
-Three tools, from smallest commitment to largest:
+Four tools, from smallest commitment to largest:
 
 | Tool                    | Gives you                                |
 | ----------------------- | ---------------------------------------- |
@@ -18,6 +18,11 @@ Three tools, from smallest commitment to largest:
 | `createI18n()`          | a registry of the app's texts            |
 | `naviI18n`              | navi's own texts, to override            |
 
+Reach for `interpolateText`/`<Interpolate>` as soon as a sentence has a value in
+it, and for `createI18n` as soon as more than a handful of texts exist — the
+migration from the first to the second is wrapping the string in a call, which
+is why starting with plain interpolation costs nothing.
+
 ## Writing a sentence: `interpolateText` / `<Interpolate>`
 
 Use these the moment a sentence contains a value. They need no i18n instance and
@@ -40,14 +45,9 @@ In JSX, `<Interpolate>` keeps the sentence readable when part of it is styled:
 The point is that the full sentence is visible in one place. The alternative —
 `Data limited to <Text bold>{radius} km</Text> around {zone}.` — reads as
 fragments, and cannot later become a translation key, because there is no
-single string to be the key.
-
-Placeholders are `[name]`. The delimiter is `[]` rather than `{}`/`{{}}` because
-it collides with neither JSX nor template literals nor ordinary punctuation.
-Details worth knowing (all in `interpolateText`'s JSDoc): a value can be a
-dot-path (`[item.label]`), a function (called only if the placeholder is
-present), and a placeholder with no value is left visible as `[name]` rather
-than disappearing.
+single string to be the key. Placeholders are `[name]`; what a value can be (a
+dot-path, a function) and what a missing one does are in `interpolateText`'s
+JSDoc.
 
 ## Centralizing texts: `createI18n`
 
@@ -93,44 +93,13 @@ message needs a stable name that does not move when navi rewords its default
 English. Same reasoning applies to any shared component library — the trade-off
 flips with who owns the text.
 
-Without `keyLang`, every language is explicit, English included:
-
-```js
-const i18n = createI18n();
-i18n.add("greeting", { en: "Hello [name]!", fr: "Bonjour [name] !" });
-```
-
-### Registering
-
-Three ways in, all accumulative — re-registering a key replaces that one key and
-leaves the rest alone:
-
-```js
-i18n.add("Save", { fr: "Enregistrer" }); // one key, many languages
-i18n.addAll({ Save: { fr: "Enregistrer" }, Cancel: { fr: "Annuler" } });
-i18n.addLangKeys("fr", frenchPack); // a whole language, e.g. a fetched JSON file
-```
-
-A regional variant inherits from its parent for every key it does not override,
-resolved at registration time — so register `"fr"` before `"fr-CA"`.
-
-### What comes out
-
-`i18n(key, values, { lang })` returns the translation with placeholders
-replaced. The language is resolved per key: the preferred languages in order
-(`lang`, or the whole `languagesSignal` list by default), then the
-`fallbackLang` given at creation, and the first one translating the key wins. A
-half-translated language therefore shows its own words where it has them and the
-next language's everywhere else.
-
-When none of them translates the key, it comes back as is, so a missing
-translation degrades to readable text rather than blank space or a crash. With
-opaque keys that text is the key's name, which is why an instance with opaque
-keys wants a `fallbackLang` holding every key — `naviI18n` falls back to
-English.
-
-`i18n.has(key)` is the way to tell "no translation" apart from "translation that
-happens to equal the key".
+A key no language translates comes back as is, so a missing translation
+degrades to readable text rather than blank space or a crash — with opaque keys,
+to the key's name. That is why an instance with opaque keys wants a
+`fallbackLang` holding every key (`naviI18n` falls back to English), and
+`i18n.has(key)` is how to tell "no translation" apart from "a translation that
+happens to equal the key". Registering (`add`, `addAll`, `addLangKeys`) and how
+the language is resolved key by key are in `createI18n`'s JSDoc.
 
 ## Which language
 
@@ -153,13 +122,13 @@ languages. With it, that browser lands on the app's best available language for
 all of them.
 
 It decides more than the wording: `<Time>` and the format helpers
-(`formatNumber`, `formatTime`, …) read the same signal, so **a document that never calls it follows the browser,
-dates and numbers included** — `2026-09-01` reads "09/01/2026" on an en-US
-machine and "01/09/2026" on a French one, from the same code and the same data.
-Nothing on screen says which reading is being applied, so this is worth one call
-at startup even in an app with a single language, and worth remembering for a
-second document in the same repo (an admin panel, a demo page), which starts
-from zero.
+(`formatNumber`, `formatTime`, …) read the same signal, so **a document that
+never calls it follows the browser, dates and numbers included** —
+`2026-09-01` reads "09/01/2026" on an en-US machine and "01/09/2026" on a French
+one, from the same code and the same data. Nothing on screen says which reading
+is being applied, so this is worth one call at startup even in an app with a
+single language, and in every document of the repo (an admin panel, a demo
+page), each of which starts from zero.
 
 Because the language is read at lookup time, a component that reads `i18n(...)`
 during render re-renders with the new wording when the language changes — as
@@ -177,28 +146,14 @@ naviI18n.add("list.empty", {
   en: "Nothing here yet.",
   fr: "Rien pour l'instant.",
 });
-naviI18n.addLangKeys("ja", { "button.close": "閉じる" });
 ```
 
-Its JSDoc lists the key namespaces; the exhaustive list of keys and defaults is
-the registration block in `src/text/navi_i18n.js`, which is meant to be read —
-plus `src/i18n/humanize_i18n.js` in `@jsenv/humanize` for the `time.*` wording
-the formatters use. Both register into the one registry `naviI18n` is, so
-overriding either goes through the same call.
+Its JSDoc lists the key namespaces and the unit names `<Quantity>`/`<Unit>`
+look up; the exhaustive list of keys and defaults is the registration block in
+`src/text/navi_i18n.js`, plus the `time.*` wording the formatters use,
+registered by `@jsenv/humanize`. Both go into the one registry `naviI18n` is,
+so overriding either is the same call.
 
-Do not put application texts in `naviI18n`. Key collisions aside, the two have
-different lifecycles: navi's keys come with the package version, the app's come
-with the app.
-
-One convention to know, since it is what `<Quantity>`/`<Unit>` look up: a unit
-name may have `<unit>__plural` and `<unit>__short` variants, both optional
-(missing ones fall back to the singular). An unregistered unit goes to
-`Intl.NumberFormat`, so only units Intl gets wrong or does not know need
-registering at all.
-
-## Choosing, in one line
-
-Reach for `interpolateText`/`<Interpolate>` as soon as a sentence has a value in
-it. Reach for `createI18n` as soon as more than a handful of texts exist — the
-migration from the first to the second is wrapping the string in a call, which
-is why starting with plain interpolation costs nothing.
+**Do not put application texts in `naviI18n`.** Key collisions aside, the two
+have different lifecycles: navi's keys come with the package version, the app's
+come with the app.