@jsenv/navi 0.29.145 → 0.29.147

package/docs/control_value.md

@@ -6,6 +6,7 @@ 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)
+- [A picker fills its popup: the control inside already knows](#a-picker-fills-its-popup-the-control-inside-already-knows)
 - [A button that proposes a value is `--navi-update`](#a-button-that-proposes-a-value-is---navi-update)
   - [`--navi-update:smooth`: the control is seen answering](#--navi-updatesmooth-the-control-is-seen-answering)
 - [`signal` + `defaultValue`: the answer and where it starts](#signal--defaultvalue-the-answer-and-where-it-starts)
@@ -74,6 +75,37 @@ A value pushed in from anywhere is an answer like any other: the wheels roll,
 and the submit lights up. Which is why a **button** offering such a value is not
 a hand-written signal write — see the next section.
 
+## A picker fills its popup: the control inside already knows
+
+A picker mirrors the control in its popup, both ways
+([popup_open.md](./popup_open.md#composing-a-value-or-doing-work)) — and the
+first half of that mirroring happens **at open**: the picker fills the control
+with the value it holds, before anything is shown.
+
+```jsx
+// the row matching the picker's value is already selected, painted and
+// announced — nothing here says which one it is
+<Picker id="channel" signal={channelSignal}>
+  <List selectable>
+    {CHANNELS.map((channel) => (
+      <List.Item key={channel.id} value={channel.id}>
+        {channel.label}
+      </List.Item>
+    ))}
+  </List>
+</Picker>
+```
+
+So a `current`, a `selected` per row, or a `value` computed from what the picker
+holds is not "being explicit": it is a second answer to a question already
+answered, and it is the one that goes stale — the picker's value moves on a
+cancel, on a `--navi-update`, on a signal written elsewhere, and none of those
+pass through the prop the app is computing.
+
+What is left for the app is what to make of the selection, not what it is:
+a row is marked (`aria-selected`) and painted by the list itself, so anything
+extra hangs off that marker in CSS rather than off a prop.
+
 ## A button that proposes a value is `--navi-update`
 
 A shortcut beside a control — "Tous niveaux" / "Aucun niveau" next to a list of

package/docs/css_architecture.md

@@ -217,14 +217,33 @@ before splitting. In navi, `popup_css.js` and `surface_text_css.js` overlap
 `.navi_dialog` and `.navi_popover` with dialog's and popover's own css, which is
 why they are still concatenated.
 
-### The build target has to match the css
-
-The css is transpiled for the runtimes the build targets, so a target older than
-what the css uses is silently lowered. `light-dark()` under a target below Chrome
-123 becomes `var(--lightningcss-light, …) var(--lightningcss-dark, …)`, an
-invalid declaration — the color is simply not applied. navi's own build targets
-Chrome 123 because navi's css uses `light-dark()`; an app targeting older
-browsers must not use css newer than its target.
+### Browser support: navi's css and your target
+
+**navi does not require recent browsers.** Its css is written with modern
+features — css nesting, `light-dark()`, `color-mix()` — and it ships that way:
+navi's own build targets a runtime where all of it is native, so what lands in
+`dist/` is what was authored, unrewritten.
+
+The runtime that decides is **yours**. An app's build reads navi's stylesheets
+out of `node_modules` like any other css and lowers them to the target the app
+declares. Targeting Chrome 89, everything above comes out as nesting-free rules
+and a pair of custom properties standing in for `light-dark()`; targeting the
+default, nothing is touched.
+
+Which is the part worth knowing: **jsenv's default target is recent**, and by
+default it assumes the modern form is fine. An app that must support older
+browsers says so, once, and both its dev server and its build follow — the
+declaration and what each step down costs are in
+[jsenv's browser support](https://github.com/jsenv/core/blob/main/docs/users/c_build/c_build.md#21-browser-support).
+Nothing in the app's own css has to change either: it is lowered by the same
+pass.
+
+One thing is NOT lowered, and it is the trap the section above already names: a
+stylesheet the build cannot parse. A `${}` outside a value position makes the
+whole template opaque, and an opaque template is shipped verbatim — nesting
+included, `light-dark()` included, whatever the target. Such a stylesheet
+silently requires the browsers its own css requires, and no declaration can
+lower it. That is the strongest reason not to write one.
 
 ---
 

package/docs/popup_open.md

@@ -552,6 +552,24 @@ const GroupMembers = () => {
 };
 ```
 
+**A popup that waits holds its own `<Loading>`**, like every other part of a
+screen that can wait — it is not built into `Dialog`/`Popover`, because only the
+code inside knows whether anything in there loads at all:
+
+```jsx
+<Dialog signal={groupSheetOpenSignal}>
+  <Loading fallback={<GroupMembersSkeleton />}>
+    <GroupMembers />
+  </Loading>
+</Dialog>
+```
+
+Without it the nearest boundary is the one at the root of the app, and a
+suspension there empties the whole page — taking with it the popup element the
+browser is in the middle of animating. The alternative is the component drawing
+its own wait (`useAsyncData(action, { loading: true })`), which needs no
+boundary; what is not an option is neither of the two.
+
 What the popup gains is everything a page has:
 
 - the request leaves **with the screen**, in parallel with the rest of what the

package/docs/state_binding.md

@@ -11,6 +11,7 @@ then on there are two owners for one truth.
 - [Why it is not merely shorter](#why-it-is-not-merely-shorter)
 - [What is left for the callback](#what-is-left-for-the-callback)
 - [What binds itself](#what-binds-itself)
+- [A control that shows part of a bigger answer](#a-control-that-shows-part-of-a-bigger-answer)
 - [When there is no binding](#when-there-is-no-binding)
 
 ## The three shapes
@@ -119,6 +120,39 @@ Binding the state does not remove the callback — it removes one job from it:
 | a value proposed to a control     | `command="--navi-update"`                                   | [control_value.md](./control_value.md#a-button-that-proposes-a-value-is---navi-update)                               |
 | the state of an async run         | an `action`, read by `useAsyncData`                         | [actions.md](./actions.md)                                                                                           |
 
+## A control that shows part of a bigger answer
+
+"Who writes the score" has three answers — a player of the game, the organizer
+alone, nobody — and only two of them are rows: "nobody" is a switch under the
+list. So the state holds a value the list cannot show, and binding the list to
+that state leaves it showing nothing whenever the switch is on.
+
+The reflex is to fall back on `value` + `uiAction` and remember the row by hand.
+The finding is elsewhere: **the list is not asking that question**. It asks
+"which of these two", the switch asks "anybody at all", and the answer the
+screen sends is made of both:
+
+```jsx
+const scorerSignal = signal("player"); // what the list asks: one of ITS rows
+const nobodySignal = signal(false); // what the switch asks
+// what the screen answers, made of the two
+const whoWritesSignal = computed(() =>
+  nobodySignal.value ? "nobody" : scorerSignal.value,
+);
+
+<List selectable signal={scorerSignal}>…</List>
+<Input type="checkbox" signal={nobodySignal} />
+```
+
+Each control binds the state it is about, and the value that spans them is
+computed from those — never held a second time. It also gives back for free what
+the hand-written version had to arrange: the row chosen before the switch went
+on is still chosen when it goes off, because nothing ever cleared it.
+
+The rule underneath: a control shows values, so the state it binds is the one
+whose values it can show. A state holding more than that is more than one
+question.
+
 ## When there is no binding
 
 Sometimes the state being wired by hand has no prop for it. That is not a

package/package.json

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