@jsenv/navi 0.29.102 → 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_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

@@ -533,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/package.json

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