@jsenv/navi 0.29.101 → 0.29.103

package/docs/AI_INSTRUCTIONS.md

@@ -123,11 +123,24 @@ consistency across the app, not from any single call site.
   inside a `Dialog`/`Popover`, and what a scroll does to hover
   (`hoverWhileScrolling`, `isScrolling()`). Read it before writing CSS to make
   something scroll — navi almost certainly already has the prop.
+- `docs/badge_list.md` — what a `BadgeList` does per prop (plain, `max`,
+  `shrinkWrap`, `maxLines`) and how it counts its badges (a `Badge` inside one
+  renders nothing and hands itself to the list — so badges must be direct
+  children). How `maxLines` reaches a list drawn inside a `Picker`
+  (`MaxLinesContext`, the picker's own clamp turned off), and why a list in a
+  picker needs a `fallback` — the placeholder text, as plain text: a picker
+  given a `ui` draws no placeholder of its own. Read it before putting a
+  `BadgeList` in a picker's `ui`, before wrapping its fallback in a `Badge`,
+  and before setting `maxLines` on the list rather than on the picker.
 - `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`.
+  and why `value` and `signal` cannot both be passed. It also holds the answer
+  to "a shortcut button beside a control" — `--navi-update`, gated like every
+  interaction, against an `onClick` writing the signal, which is not and fires
+  on a read-only control. Read it before wiring a
+  control's value by hand with `value` + `uiAction`, and before writing a button
+  that proposes a value.
 - `docs/create_and_edit.md` — the loop almost every app has: a screen that
   creates a resource, the page of what was created, a screen that edits it. The
   routes and why several match at once, one form for two modes, filling the edit
@@ -203,9 +216,12 @@ consistency across the app, not from any single call site.
   of navi's own.
 - `docs/interactions.md` — the `interactions` prop: making a component answer a
   swipe, a held press, a shortcut, and registering a gesture navi does not have.
+  It also holds `ownTarget`, for an affordance an application draws inside a
+  zone that belongs to another control — a chip's cross, an eye, a diskette.
   Read it before reading the pointer by hand — who owns a press between nested
   boxes, and what a touch may do, are decided before the first pixel moves and
-  cannot be got right from outside navi.
+  cannot be got right from outside navi — and before stopping the propagation of
+  a pointerdown/mousedown/click to keep a popup from opening.
 - `docs/drag_to_travel.md` — a pointer pushing a whole screen aside
   (`SlideContainer`, `RouteTravel`) and a popup pushed back towards its edge:
   what the gesture is, and above all who owns a press several boxes want — a

package/docs/badge_list.md

@@ -0,0 +1,80 @@
+# BadgeList
+
+A row of badges that wraps. What it does at runtime depends on what it is asked
+for, and nothing is set up for a case that cannot happen:
+
+- **plain** — no `max`, no `maxLines`, no `fallback`, no `shrinkWrap`: one
+  element holding its children as-is. No registry, no effect, no measurement.
+- **`max` / `fallback`** — the badges are counted (see below), nothing is
+  measured, no DOM is watched.
+- **`shrinkWrap`** — a hidden clone of the list is laid out to find the widest
+  wrapped row, and the list is narrowed to it so the last row isn't ragged.
+  Opt-in outside a `Picker` (a picker draws a border around the list, so the
+  ragged edge shows; elsewhere the work would often go unseen), and skipped
+  whenever `maxLines` is in play.
+- **`maxLines`** — every badge is laid out once, hidden; where the rows fell is
+  read; the list is rendered again with the badges that fit and a `+N more`
+  badge for the rest. Both renders land in the same frame. A width change of
+  the room around the list triggers another measure — not a change of the
+  list's own width, which is what it produces, not what it is given.
+
+## How badges are counted
+
+A `Badge` inside a `BadgeList` does not render itself: it hands its props to
+the list through `BadgeListContext` and renders nothing. Badges register in
+tree order, so by the time the list gets to its own content it holds them all
+and knows how many there are before deciding what to show — without walking
+children vnodes, and without rendering a badge it then has to take back.
+
+Two consequences:
+
+- a `Badge` must be a **direct** child of the list — its rendering is moved
+  into the list, so `<div><Badge /></div>` takes the badge out of its wrapper;
+- a badge's own `key` goes to the registering vnode and not to the badge the
+  list draws, which is keyed by position. Reordering recreates the nodes rather
+  than moving them.
+
+## `maxLines` in a Picker
+
+A picker clamps its value with `maxLines`, which is CSS line-clamp — it counts
+line boxes of inline text and never sees a wrapped flex row. So a `BadgeList`
+rendered as a picker's `ui` reads the number from `MaxLinesContext` instead
+(the picker provides it, default 1) and caps its own rows to it, and the picker
+turns its own clamp off (`.navi_picker_value:has(.navi_badge_list)`). Nothing
+to set on the list; `maxLines` on the picker is enough, and a `maxLines` on the
+list itself is a local override.
+
+`max` is a different cap: a number of badges, whatever the rows. The two
+compose — the `+N` badge takes one of the `max` slots.
+
+## The `fallback`
+
+Without a `fallback`, an empty list renders **nothing**. Inside a picker there
+is one more thing to know: a picker given a `ui` draws that and only that, its
+own `placeholder` is **not** drawn next to it. An empty `BadgeList` in a picker
+is a blank picker — so the list's `fallback` is the placeholder, and the
+placeholder text is what to pass:
+
+```jsx
+<BadgeList fallback="Select skills…">
+  {selected.map((skill) => (
+    <Badge key={skill}>{skill}</Badge>
+  ))}
+</BadgeList>
+```
+
+Plain text is the right shape for it. It reads at the picker's own size, in the
+placeholder color — the picker colors its value slot that way while it holds
+nothing — and the picker box stays the same height empty and filled: the box is
+held one line tall by the picker's own line (the right slot is `1lh`), whatever
+the slot inside holds. That slot is a fraction of a pixel taller with a line of
+text than with a row of badges (0.89px at the default font size — a line is set
+by the picker's font and line-height, a badge by its own padding and smaller
+font), which nothing shows.
+
+A transparent `Badge` as fallback matches the slot to the pixel instead, but its
+text is badge-sized — smaller than the picker's — and reads as a badge with
+nothing in it. Only worth it where the slot itself is what something else is
+sized on. Section 4 of `src/control/demos/picker/2_select_multiple_demo.html`
+measures the three cases (no fallback, plain text, transparent badge), box and
+slot side by side.

package/docs/control_group.md

@@ -47,14 +47,19 @@ Live examples: `src/control/demos/15_group_demo.html`.
   last one loses it on the other side, and any member in between loses all
   four. A single member keeps its own radius — a group of one looks like the
   control alone. The ask is made twice, in two forms — see below.
-- **Overlap order**: the member under the pointer, and the member showing a
-  focus ring, paint above their neighbours (`position: relative` plus
-  `--navi-z-index-control-hovered` / `-focused`). Without it the border color
-  change and the focus ring of the active member would be sliced by whichever
-  neighbour is painted after it. The focused member is matched whether it wears
-  `data-focus-visible` itself or merely contains it — a control that wraps a
-  real input (`Picker`, `Spin`) draws the ring on its own frame while the
-  keyboard is held inside. There is deliberately no `isolation: isolate` — see
+- **Overlap order**: the member under the pointer, the member showing a focus
+  ring, and the member holding something open (`aria-expanded="true"`) paint
+  above their neighbours (`position: relative` plus
+  `--navi-z-index-control-hovered` / `-focused` / `-expanded`). Without it the
+  border color change and the focus ring of the active member would be sliced
+  by whichever neighbour is painted after it. The focused member is matched
+  whether it wears `data-focus-visible` itself or merely contains it — a
+  control that wraps a real input (`Picker`, `Spin`) draws the ring on its own
+  frame while the keyboard is held inside; the expanded member is matched the
+  same way, since it can be wrapped in an enrobage. Expanded ranks highest: a
+  `Picker` opened by a click shows no focus ring, hands the focus to its popup
+  and lets the pointer travel to a neighbour, yet its border keeps saying it is
+  the one open. There is deliberately no `isolation: isolate` — see
   [z_index.md](./z_index.md).
 
 Nothing else: a group does not restyle its members, does not impose a size,
@@ -113,7 +118,7 @@ opened it. `Popover` and `Dialog` stop it too, at their own root: nothing a
 popup holds is at a seam.
 
 Reference: `.navi_button_content` in `button_ui.jsx` (a button reads then
-stops), `.navi_picker_right_slot`, `.navi_input_slot`, `.navi_popover`,
+stops), `.navi_picker_box`, `.navi_input_slot`, `.navi_popover`,
 `.navi_dialog`.
 
 A control that declares its radius on an inner element instead is invisible to

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 button that proposes a value is `--navi-update`](#a-button-that-proposes-a-value-is---navi-update)
 - [`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)
 - [Empty keeps the shape of the question](#empty-keeps-the-shape-of-the-question)
@@ -68,20 +69,64 @@ Both halves are worth knowing about, because each replaces a habit:
 The follow goes all the way up: a bound control that lives inside a group — two
 wheels in a `WheelGroup`, a field in a `ControlGroup` — makes that group
 re-aggregate when its signal is written, and the form above sees the new value.
-A shortcut that pushes the controls from the outside is an answer like any
-other: the wheels roll, and the submit lights up.
+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 button that proposes a value is `--navi-update`
+
+A shortcut beside a control — "Tous niveaux" / "Aucun niveau" next to a list of
+levels, "1h / 1h30 / 2h" next to a pair of wheels, a suggestion under a field —
+is a value being offered to that control. It is not an action, and it is not a
+signal to write by hand:
 
 ```jsx
+<ControlGroup id="duration">
+  <TimeWheel name="duration" signal={durationSignal} />
+</ControlGroup>
+
+<Button
+  command="--navi-update"
+  commandFor="duration"
+  value={{ hours: 1, minutes: 30 }}
+>
+  1h30
+</Button>
+```
+
+- the **value** is the button's own `value`, whatever shape it has — a string, an
+  array of levels, an object of two wheels;
+- the **target** is `commandFor`, naming the control's id — left out, the nearest
+  control around the button is used, which is what a button placed inside the
+  control it proposes to wants;
+- and the press goes through the same gate as every other interaction, so a
+  read-only, disabled or busy control **refuses it and says why**.
+
+That last point is the whole reason, and the counter-example is what everybody
+writes first:
+
+```jsx
+// ✗ not gated — plain DOM. On a read-only sheet the button greys out and fires
+//   all the same, rewriting a value nobody is allowed to change.
 <Button
   onClick={() => {
-    hoursSignal.value = 2;
-    minutesSignal.value = 0;
+    durationSignal.value = { hours: 1, minutes: 30 };
   }}
 >
-  2h
+  1h30
 </Button>
 ```
 
+Writing a signal from an `onClick` is only right where nothing is being proposed
+to a control: moving something else on screen, seeding state before anything is
+drawn.
+
+The id goes **on the control**, and a group is one — `ControlGroup`, `Form`,
+`WheelGroup`, `List selectable`. Put it on a layout box around the control and
+the command finds an element that holds no value; navi says so in dev rather
+than letting the press do nothing at all. An id that matches nothing is a dev
+warning too, naming the id it looked for.
+
 ## `signal` + `defaultValue`: the answer and where it starts
 
 They are not competing, they answer two different questions:

package/docs/interactions.md

@@ -105,6 +105,20 @@ interaction happened, and nothing runs. A `Box` with no control anywhere near it
 still answers a callback; only `"request_action"` has nothing to ask, and says so
 in dev.
 
+The one thing the gate weighs besides the control's state is what the
+interaction would do to it. Everything writes unless it says otherwise; an
+interaction that only shows what is already there declares `intent: "read"`, and
+a control held read-only lets that one through. That is how a read-only
+`<Picker>` still opens: the popup is where its answer is really drawn, so it
+opens and everything inside it is held read-only in turn. Disabled and busy go
+on refusing either way — one is out of service, the other is mid-operation, and
+neither has anything to show.
+
+Which controls let a read through is theirs to say, not the caller's: a picker
+with no popup of its own opens the browser's, which cannot be held read-only, so
+that one refuses. `openWhileReadOnly={false}` is how a caller says the popup is
+a form with nothing to read.
+
 ## What a swipe draws, and what it leaves to you
 
 navi makes the element follow the finger — there is nothing to decide about
@@ -519,12 +533,23 @@ places and a `toss` wherever it was thrown (`xy`). `data-drag-delay`,
 
 ### A control inside something draggable
 
-`data-drag-ignore` says the press there is none of the gesture's business: the
-element under it never starts a drag, and keeps both its cursor and its text
-selection. That is what a button living inside a carried piece needs — a cross
-that removes it, a menu — otherwise the piece is picked up from the button like
-from anywhere else. A click of its own usually has to stop there too, or the
-piece reads it as its own click.
+`ownTarget` on the control says it: a chip's cross inside a carried piece, an
+eye on a row that travels, a diskette on a picker's façade. The press belongs to
+that control alone — no gesture starts under it, and nothing above it answers
+the mousedown or the click. It also follows the interactivity of the zone around
+it: read-only, disabled or busy, the affordance goes rather than greys (pass
+`ownTarget="refuse"` for one whose presence is information in itself), and its
+`onClick` waits for its own gate instead of firing from the DOM.
+
+```jsx
+<Badge.Button ownTarget onClick={() => remove(id)}>
+  ×
+</Badge.Button>
+```
+
+`data-drag-ignore` says the same thing to the gesture alone, for something that
+is not a control: the press there is none of the gesture's business, and the
+element keeps both its cursor and its text selection.
 
 ### What says a thing can be picked up
 

package/docs/z_index.md

@@ -74,14 +74,14 @@ file is the overview, this table is its summary. Bands are a decade apart so
 one can grow without reaching the next, and so a value seen in devtools says
 which band it came from.
 
-| Band                                                                                                                                | Token                                                              | Value                        |
-| ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ---------------------------- |
-| Top layer (`Dialog`/`Popover` with `layer="top"`)                                                                                   | —                                                                  | above everything             |
-| `Dialog`/`Popover` with `layer="local"`, their backdrop, callouts                                                                   | `--navi-z-index-popup`, `--navi-z-index-callout`                   | 1000 `+ stack order`         |
-| `FixedBar`                                                                                                                          | `--navi-z-index-bar`                                               | 100                          |
-| Sticky while something scrolls under: `List` header/footer/group labels, `SidePanel` head/foot, `Box` header/footer, `<Box sticky>` | `--navi-z-index-sticky`                                            | 10                           |
-| A `Group` member under the pointer, then the one holding focus                                                                      | `--navi-z-index-control-hovered`, `--navi-z-index-control-focused` | 1, 2                         |
-| `Table` sticky cells, drag, resize                                                                                                  | `src/control/table/z_indexes.js`                                   | 1–7, derived from each other |
+| Band                                                                                                                                | Token                                                                                                 | Value                        |
+| ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ---------------------------- |
+| Top layer (`Dialog`/`Popover` with `layer="top"`)                                                                                   | —                                                                                                     | above everything             |
+| `Dialog`/`Popover` with `layer="local"`, their backdrop, callouts                                                                   | `--navi-z-index-popup`, `--navi-z-index-callout`                                                      | 1000 `+ stack order`         |
+| `FixedBar`                                                                                                                          | `--navi-z-index-bar`                                                                                  | 100                          |
+| Sticky while something scrolls under: `List` header/footer/group labels, `SidePanel` head/foot, `Box` header/footer, `<Box sticky>` | `--navi-z-index-sticky`                                                                               | 10                           |
+| A `Group` member under the pointer, then the one holding focus, then the one holding a popup open                                   | `--navi-z-index-control-hovered`, `--navi-z-index-control-focused`, `--navi-z-index-control-expanded` | 1, 2, 3                      |
+| `Table` sticky cells, drag, resize                                                                                                  | `src/control/table/z_indexes.js`                                                                      | 1–7, derived from each other |
 
 What to read from it:
 

package/package.json

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