@jsenv/navi 0.29.146 → 0.29.147

package/docs/AI_INSTRUCTIONS.md

@@ -139,13 +139,18 @@ consistency across the app, not from any single call site.
   `expandX={false}` to stop a dialog sprawling, and before writing CSS to make a
   dialog fit the screen.
 - `docs/autofocus.md` — who gets the keyboard when a popup opens or a slide
-  arrives: the ladder navi walks, what `autoFocus` means on a surface (`true`
-  = the surface takes it, for a popup that is READ before it is filled) versus
-  on a field, why a docked dialog keeps the keyboard down on a phone, and what
-  happens when the opening finds nothing to focus. Read it before wondering
-  where the focus went when a popup opened, and before removing `autoFocus`
-  from fields to stop a virtual keyboard rising — the surface is what decides,
-  not the absence of a field asking.
+  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
+  that is READ before it is filled) versus on a field, why a docked dialog
+  keeps the keyboard down on a phone, what happens when the opening finds
+  nothing to focus, and the rule deciding the focus ring — the modality of what
+  asked for the transfer, an editable target ringing whatever asked. Read it
+  before wondering where the focus went when a popup opened, before removing
+  `autoFocus` from fields to stop a virtual keyboard rising (the surface is
+  what decides, not the absence of a field asking), and before calling
+  `element.focus()` anywhere — `moveFocusTo(element)` is the exported helper
+  that applies both decisions, and a bare `focus()` leaves the ring to the
+  browser.
 - `docs/scroll.md` — where scrolling happens: what turns `Box`
   `header`/`body`/`footer` on, `FixedBar` space, `List`'s `scroller`, scroll
   inside a `Dialog`/`Popover`, and what a scroll does to hover

package/docs/actions.md

@@ -123,6 +123,10 @@ in one would be waiting for itself. Everything else is unchanged — `loading` a
 when asked for — and running an action twice costs nothing, so nothing has to
 be guarded.
 
+Where that wait is caught is the caller's business, and a popup is no exception
+— see [popup_open.md](./popup_open.md#a-popup-that-loads-data) for what that
+costs when it is forgotten.
+
 **`{ run: true }` is the fallback, not the shape to reach for.** A route action
 is asked for when the ADDRESS changes, with everything else that address needs;
 this one cannot start before the component that draws it exists, which is a

package/docs/autofocus.md

@@ -1,8 +1,10 @@
-# Where the keyboard goes when something opens
+# Where the keyboard goes, and when a ring shows
 
 A dialog, a popover, a slide arriving: one of them opens and something inside
 has to hold the keyboard. `autoFocus` is how each element takes part in that
-decision.
+decision. Handing the focus over answers a second question at the same time —
+whether what receives it shows a focus ring — and navi answers that one too,
+at the end of this page.
 
 - [What we want](#what-we-want)
 - [The ladder](#the-ladder)
@@ -12,6 +14,8 @@ decision.
   - [Opting a field back in](#opting-a-field-back-in)
 - [What a field says about itself](#what-a-field-says-about-itself)
 - [When the opening places nothing](#when-the-opening-places-nothing)
+- [The ring is decided too](#the-ring-is-decided-too)
+- [Moving the focus yourself](#moving-the-focus-yourself)
 
 ## What we want
 
@@ -162,3 +166,65 @@ That debt is settled two ways, whichever comes first:
 Without this, the same popup would land the focus in a different place — or
 nowhere — depending on whether it was opened by a click or by the page loading,
 which is the same popup behaving differently for no reason the user can see.
+
+## The ring is decided too
+
+Handing the focus over answers a second question: does what receives it show a
+focus ring? The browser's own answer is unusable here — it reads the last thing
+that touched the DOM, and a focus that came from code touched it last. So navi
+answers instead, and the answer is the **modality of what asked**:
+
+- the user was on the keyboard when this was asked for — a Tab, an Enter, an
+  arrow key: a ring;
+- a finger or a mouse asked: no ring, whatever the code did in between;
+- the element receiving it is **editable** — a text input, a textarea, a
+  contenteditable: a ring anyway. Someone about to type has to see where.
+
+That last one is why opening a search field with a mouse click still rings: the
+field is where you are about to type, not somewhere you merely landed.
+
+Nothing to pass, and nothing to opt into: it is how every navi component moves
+the focus.
+
+### In your CSS
+
+`:focus-visible` and `[data-focus-visible]` — the standard selectors, nothing
+navi-specific. navi implements them with a wider meaning than the browser's: an
+element also counts as focused while a **proxy** holds the focus (a read-only
+range delegating to a sibling) or while an element **controlling** it does (a
+combobox input with `aria-controls` on its listbox — the listbox reads as
+focused while the input is). Style the standard name and you get that for free.
+
+```css
+.my_row:focus-visible {
+  outline: 2px solid var(--navi-focus-outline-color);
+}
+```
+
+## Moving the focus yourself
+
+Prefer saying where the focus belongs over moving it: `autoFocus` on the field
+or the surface (the ladder above), and navi places it at the right moment, with
+the right ring, without scrolling anything.
+
+When you really do have to move it — a control of your own handing over to
+another — use `moveFocusTo` rather than `element.focus()`:
+
+```js
+import { moveFocusTo } from "@jsenv/navi";
+
+moveFocusTo(searchInputElement);
+```
+
+That is the whole call. It applies the two decisions above for you: no
+scroll-into-view, and a ring only where the user is on the keyboard (an
+editable target ringing anyway). A bare `element.focus()` answers "who" and
+leaves "is this visible" to the browser, and the browser reads the last thing
+that touched the DOM — which was your own call.
+
+Pass `focusVisible` when you know better than the last interaction does, and
+`preventScroll: false` when the element really has to be brought into view:
+
+```js
+moveFocusTo(element, { focusVisible: true });
+```

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/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.146",
+  "version": "0.29.147",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {