@jsenv/navi 0.29.417 → 0.29.419

package/docs/state_binding.md

@@ -32,8 +32,6 @@ was missed.
 
 ## The callback that only remembers
 
-The same mistake, in four places:
-
 ```jsx
 // ✗ the app is told where the slides went, and writes it back down
 <SlideContainer
@@ -45,18 +43,6 @@ The same mistake, in four places:
 // ✓
 <SlideContainer signal={stepSignal} />
 
-// ✗ the control is told what it now holds, and the app writes it back down
-<Picker value={side} uiAction={(value) => (sideSignal.value = value)} />
-// ✓
-<Picker signal={sideSignal} />
-
-// ✗ a button proposing a value to a control, straight into the signal
-<Button onClick={() => (durationSignal.value = ninetyMinutes)}>1h30</Button>
-// ✓
-<Button command="--navi-update" commandFor="duration" value={ninetyMinutes}>
-  1h30
-</Button>
-
 // ✗ the popup is told it opened, and the app writes it back down
 <Dialog
   open={isOpen}
@@ -69,7 +55,8 @@ The same mistake, in four places:
 
 In each pair the second line is not a tidier spelling of the first: it is the
 binding the component already implements, and the first is a partial
-re-implementation of it.
+re-implementation of it. The same pair for a control's value, and for a button
+proposing one, is in [control_value.md](./control_value.md).
 
 ## Why it is not merely shorter
 
@@ -77,22 +64,20 @@ A binding is written by **everything that moves the state**, not only by the
 gesture the caller thought of. A `SlideContainer`'s signal is written by a drag,
 by an arrow key, by a `--navi-right` command sent from a chevron outside the
 box, by the address when the signal is a route's own, by a step refusing to be
-left. A control's
-signal is written by the user typing, by a group placing its children, by a
-picker committing on close, by a `--navi-update` from a shortcut button. A
-hand-written callback catches the cases it was written for and silently misses
-the rest — and the drift only shows on the screen where a second gesture was
-added.
+left. A control's signal is written by the user typing, by a group placing its
+children, by a picker filling its popup or putting back what it held on Escape,
+by a `--navi-update` from a shortcut button. A hand-written callback catches the
+cases it was written for and silently misses the rest — and the drift only shows
+on the screen where a second gesture was added.
 
 It reads in the other direction too, which no callback gives at all: writing the
 signal MOVES the component. The wheels roll, the slides travel, the popup opens.
 That is what replaces the `key` or the `value` prop pushed down to force a
 component into a state.
 
-And it goes through navi's interaction gate. A `command` on a read-only,
-disabled or busy control is refused and says why; an `onClick` doing the same
-write is plain DOM, fires on a greyed-out button and rewrites a value nobody was
-allowed to change.
+And a `command` goes through navi's interaction gate, which an `onClick` writing
+the same state does not (see
+[control_value.md](./control_value.md#a-button-that-proposes-a-value-is---navi-update)).
 
 ## What is left for the callback
 
@@ -113,13 +98,10 @@ Binding the state does not remove the callback — it removes one job from it:
 ## The callback also fires for the state's own changes
 
 A bound container walks to whatever its signal holds, and tells the callback
-about that walk — `cause: "state"`, `event: null`. It is the only piece that
-knows the change was not a press, and saying so is its job.
-
-The trap is on the other side. A callback that writes somewhere whose answer
-flows back INTO the signal — a server whose response is upserted into the store,
-a `useSignalSync` on the row that re-renders from it — makes every answer a
-change, and every change a write:
+about that walk — `cause: "state"`, `event: null`. The trap is a callback that
+writes somewhere whose answer flows back INTO the signal — a server whose
+response is upserted into the store, a `useSignalSync` on the row that
+re-renders from it:
 
 ```jsx
 // ✗ the answer of the write feeds the signal the write came from
@@ -130,49 +112,30 @@ const styleSignal = useSignalSync(user.share_image_style);
 />;
 ```
 
-With one write at a time nothing shows: the answer carries the value the signal
-already holds, so the model does not change. It takes two writes in flight — two
-notches 200ms apart, a 300ms round trip:
-
-```
-t=0    notch → B   signal=B   PUT B ──────────────┐
-t=200  notch → A   signal=A   PUT A ────────────┐ │
-t=300  B answers, store=B, signal=B, the box     │ │
-       walks to B, onCurrentChange(B, "state"),  │ │
-       save(B) → PUT B ───────────────────────┐  │ │
-t=500  A answers … save(A) → PUT A            │  │ │
-t=600  B answers … save(B) → PUT B            │  │ │
-…
-```
-
-Nothing was reordered — it is enough that an answer lands after a newer write
-was sent. Every answer is then the answer to a request the user has already
-moved past, the container obeys the model, the callback saves what it was just
-told, and that write's answer starts the next turn.
+One write at a time shows nothing: the answer carries the value the signal
+already holds. Two in flight — two notches in quick succession, nothing
+reordered, only an answer landing after a newer write was sent — and every
+answer is to a request the user has already moved past: the container walks to
+it, the callback saves it, and that write's answer starts the next turn. The
+loop never closes.
 
 Decide what the signal IS:
 
 - **The signal is the choice, the server only confirms it.** Seed it once with
-  `useSignal(model)` and never sync it. A late answer changes the store, not the
-  picture. The cost: a write that fails is not undone on screen unless the
-  callback undoes it. Right for a setting saved on the gesture, with no "Save"
-  button.
+  `useSignal(model)` and never sync it: a late answer changes the store, not the
+  picture, and a write that fails is not undone on screen unless the callback
+  undoes it. Right for a setting saved on the gesture, with no "Save" button.
+  That is a `SlideContainer`'s shape; a control says it with
+  `defaultValue={model}` and an `action` (see
+  [control_value.md](./control_value.md#a-defaultvalue-follows-what-it-was-read-from)).
 - **The model is the truth, the control only proposes.** Keep `useSignalSync`
-  and ignore `cause: "state"` in the callback — a change the state asked for is
-  not a choice to save. The cost: a late answer still pulls the picture back for
-  one round trip. Right when another client or a background refresh may change
-  the row while the control is on screen.
+  and ignore `cause: "state"` — a change the state asked for is not a choice to
+  save. A late answer still pulls the picture back for one round trip. Right
+  when another client or a background refresh may change the row while it is on
+  screen.
 - **Never two writes in flight for one field.** Debounce the write, or cancel
-  the one before it (`createRequestCanceller`), so no answer can be older than
-  the latest intent. Right when the write is the expensive part.
-
-Measured on the same screen, the same two notches, a 300ms round trip:
-
-| what the signal is                        | writes sent     | slide changes |
-| ----------------------------------------- | --------------- | ------------- |
-| `useSignalSync` + save every change       | 39, still going | 39            |
-| `useSignal`, seeded once                  | 2               | 2             |
-| `useSignalSync` + ignore `cause: "state"` | 2               | 4             |
+  the one before it (`createRequestCanceller`), so no answer is older than the
+  latest intent. Right when the write is the expensive part.
 
 ## What binds itself
 
@@ -189,13 +152,10 @@ Measured on the same screen, the same two notches, a 300ms round trip:
 
 "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:
+list. Bound to the state holding all three, the list shows nothing whenever the
+switch is on. The fix is not `value` + `uiAction`: **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
@@ -210,13 +170,10 @@ const whoWritesSignal = computed(() =>
 ```
 
 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.
+computed from those — never held a second time (the row chosen before the switch
+went on is still chosen when it goes off: nothing cleared it). A control binds
+the state whose values it can show; a state holding more than that is more than
+one question.
 
 ## When there is no binding
 
@@ -235,7 +192,6 @@ the next screen copies, and by then it is the app's pattern.
 
 - [control_value.md](./control_value.md) — who holds a control's value, and what
   a bound signal holds control by control
-- [actions.md](./actions.md#action-or-uiaction) — `action` or `uiAction`
 - [popup_open.md](./popup_open.md) — who owns the fact that a popup is open
 - [interactions.md](./interactions.md) — a gesture is named, not read by hand:
   the same rule, one layer down

package/docs/testid.md

@@ -71,12 +71,10 @@ on. A testid on the wrapper would answer a click with a hit on the padding.
 </span>
 ```
 
-This routing is what `CONTROL_ATTRIBUTE_SET` in
-`src/control/control_context.js` lists: the props navi hands to the host rather
-than to the box around it (`id`, `name`, `type`, `value`, `tabIndex`,
-`data-testid`, …). Any prop navi does not know lands on the root box instead —
-so a `data-test-id` or a `data-qa` of your own would name the wrapper, which is
-the second reason to keep the standard spelling.
+Navi hands the host the props it knows belong there (`id`, `name`, `type`,
+`value`, `tabIndex`, `data-testid`, …); any prop it does not know lands on the
+root box instead — so a `data-test-id` or a `data-qa` of your own would name
+the wrapper, which is the second reason to keep the standard spelling.
 
 `aria-label` and `aria-labelledby` take the same road, and for the reason the
 section above gives: the name has to be where the role is. The root box has no
@@ -124,16 +122,16 @@ error message, a section, a row — put the testid on the surrounding component
 (`<Field data-testid="email-field">`, `<Box data-testid="cart-row">`); anything
 built on `Box` forwards it to its own element.
 
-A selectable `List.Item` is a control too, and the rule holds there with a
-consequence worth knowing: its host is the real checkbox or radio the row
-selects with, an input navi draws invisible (`navi-visually-hidden`) and lays
-under the row's content. A `data-testid` on the item names that input — what
-`toBeChecked()` reads, not what the eye sees. A test that presses the row, or
-waits for it to show, targets what the row draws: a testid on its content.
+A selectable `List.Item` is a control too, and the rule holds there: its host is
+the real checkbox or radio the row selects with, an input navi draws invisible
+and lays under the row's content. A `data-testid` on the item names that input —
+what `toBeChecked()` reads, not what the eye sees. A test that presses the row,
+or waits for it to show, targets what the row draws: a testid on its content.
 
-A picker's popup is the one element the application does not render itself:
-`<Picker>` builds it, so a `data-testid` on the picker names the trigger and
-nothing names the popup. `popupTestId` does:
+What navi builds itself is named through props. A `data-testid` on a `<Picker>`
+names the trigger; `popupTestId` names the popup it builds (the callout, under
+`mode="callout"`), and `confirmTestId` / `cancelTestId` the yes and no buttons
+of a `type="confirm"` picker's default body:
 
 ```jsx
 <Picker data-testid="tie-break" popupTestId="tie-break-sheet">
@@ -141,13 +139,11 @@ nothing names the popup. `popupTestId` does:
 </Picker>
 ```
 
-Most tests do not need it — a testid on what the popup holds (`<Box
+Most tests do not need `popupTestId`: a testid on what the popup holds (`<Box
 data-testid="place-pick">` among the children) names the screen, not the frame,
 and is the better name for a test that reads or clicks the content. Reach for
-`popupTestId` when the frame IS what the test looks at: a screenshot of the
-popup's surface, its position, its size, its backdrop. It names the popup in
-every mode, including `mode="callout"`, where the frame is a callout rather
-than a sheet.
+it when the frame IS what the test looks at — a screenshot of the popup's
+surface, its position, its size, its backdrop.
 
 ## A callout is a role first
 
@@ -168,9 +164,8 @@ for it is what a live region is for, and the role is what makes a screen reader
 read it out. A test targeting it asserts that.
 
 When the role is not enough — two callouts up at once, a screenshot of one
-particular surface — `openCallout` takes a `testId`, and a picker's
-`popupTestId` covers the one it opens. Waiting on `.navi_callout` is the thing
-to replace: it is a navi class like any other.
+particular surface — `openCallout` takes a `testId`. Waiting on `.navi_callout`
+is the thing to replace: it is a navi class like any other.
 
 `<ControlSwap.Side>` answers the same situation the other way: the cap at the
 end of the row is drawn by navi, and every prop the side does not use for

package/docs/typography.md

@@ -38,11 +38,11 @@ same names — `size="l"` is a font size, `padding="l"` is a gap.
 
 Four of the five are formulas on `currentColor`, so they follow whatever ink
 their container writes in — a dark card sets `color` and nothing else. Never
-write the `--navi-color-*` variable behind a keyword by hand: the keyword is the
-name, and an invented one (`var(--navi-text-color-discrete)`) resolves to
-nothing and silently inherits. What the ratios are, how a theme changes them and
-why a surface re-declares them:
-[css_architecture.md](./css_architecture.md#ink-ratio-paper-the-color-keywords).
+read the `--navi-color-*` variable behind a keyword with `var()`: the keyword is
+the name, and an invented one (`var(--navi-text-color-discrete)`) resolves to
+nothing and silently inherits. Declare one only to pin a container's paper —
+what the ratios are, how a theme changes them and why a surface re-declares
+them: [css_architecture.md](./css_architecture.md#ink-ratio-paper-the-color-keywords).
 
 Live examples: `src/text/demos/*_demo.html` — one page per concern
 (`text_overflow_demo.html`, `text_spacing_demo.html`, `text_loading_demo.html`,
@@ -61,59 +61,19 @@ implements them with two unrelated mechanisms:
 ```
 
 Do **not** write `lineClamp={1}`. `lineClamp` and `overflowEllipsis` are raw
-`Box` style props: they map to `-webkit-line-clamp` and to
-`overflow/text-overflow` one-to-one, and are there for the case where an element
-is not a `Text` (or deliberately opts out of it) and still needs that CSS. They
-know nothing about each other, so `lineClamp={1}` gives a single-line webkit box
-without the single-line handling `maxLines={1}` brings — `maxLines` switches the
-element to a block, sets `min-width: 0` on itself, and states the `white-space`
-its line count needs: one line does not wrap, n lines may (a `<p>` keeps its
-line breaks in both cases). That last part is what makes it hold anywhere:
-`white-space` is inherited, and a raw clamp put under a single-line ancestor — a
-`Picker`'s value, a `Time` — inherits `nowrap`, gets one line to cut, and lets
-the text run past its box instead. On a `Text`, `maxLines` is always the right
-answer, and an explicit `noWrap`/`pre`/`preLine` beside it still wins.
-
-### Who takes `maxLines`
-
-The prop is the same everywhere: a number of lines, cut with an ellipsis.
-
-- **`Text`** and everything built on it — `Title`, `Paragraph`, `Caption`,
-  `Link`, `Time`, `Quantity`… — the prop flows through. `Badge` is `maxLines={1}`
-  by construction.
-- **`Picker`** — its value, `maxLines={1}` by default; `variant="text"` and
-  `variant="bare"` draw the caller's own thing and are not clamped, a `Text` in
-  their `ui` cuts itself with its own `maxLines`.
-- **`Spin`** (`DaySpin`, `NumberSpin`…) — its value; left out, a long value
-  wraps and the box grows.
-- **`Binder`** — its tab labels, `maxLines={1}` by default, `false` lets them
-  wrap; overridable per item.
-- **`BadgeList`** — its rows, measured (a wrapped flex row is not a line box):
-  the badges that fit and a "+N" badge for the rest. Inside a `Picker` it
-  inherits the picker's count, see [badge_list.md](./badge_list.md).
-
-On a plain `Box`, `maxLines` is the raw CSS mapping described above: it clamps
-whatever the box holds, and states nothing else.
-
-### Truncation only happens if something says "you may shrink"
-
-A flex or grid item refuses to become narrower than its content unless it is
-told it may. `maxLines` sets `min-width: 0` on the `Text` itself, so the leaf is
-covered — but **every `Box` between it and the element that actually has a
-width must say it too**, or the whole chain grows instead of truncating:
-
-```jsx
-<Box flex width="300" spacing="s">
-  {/* without minWidth the row just grows */}
-  <Box flex expandX minWidth="0">
-    <Text maxLines={1}>…</Text>
-  </Box>
-</Box>
-```
-
-Symmetrically, whatever must keep its full size says so with `shrink={false}`.
-A row where the text gives way and nothing else does is the normal shape — see
-the recipes below.
+`Box` style props, mapped one-to-one to CSS for an element that is not a `Text`.
+`maxLines` also states the `white-space` its line count needs — one line does
+not wrap, n lines may — and that is what makes it hold anywhere: `white-space`
+is inherited, and a raw clamp put under a single-line ancestor — a `Picker`'s
+value, a `Time` — inherits `nowrap`, gets one line to cut, and lets the text run
+past its box instead. An explicit `noWrap`/`pre`/`preLine` beside `maxLines`
+still wins.
+
+The prop is the same wherever it is taken — a `Picker`'s value (1 by default),
+a `Spin`'s value, `Binder`'s tab labels, a `BadgeList`'s rows (see
+[BadgeList](#badgelist)); `Badge` is `maxLines={1}` by construction. On a plain
+`Box`, `maxLines` is the raw CSS mapping: it clamps whatever the box holds, and
+states nothing else.
 
 ## A row: icon, text, icon
 
@@ -145,22 +105,34 @@ The three parts of it, and each is load-bearing: `shrink={false}` on the icons
 (they are the fixed part), `expandX` on the text (it is the part that gives),
 `maxLines={1}` (what giving way means for text). Drop any one and the row fails
 in a different way — icons squashed, ellipsis never appearing, or the row
-overflowing its container.
+overflowing its container. Same shape for a count, a badge or a status kept to
+the right of the ellipsis: a sibling with `shrink={false}`.
+
+A flex or grid item refuses to become narrower than its content unless it is
+told it may. `maxLines` sets `min-width: 0` on the `Text` itself, but **every
+`Box` between it and the element that actually has a width must say it too**,
+or the whole chain grows instead of truncating:
 
-Same shape for a count, a badge or a status kept to the right of the ellipsis:
-it is a sibling with `shrink={false}`, not a child of the truncating text.
+```jsx
+<Box flex width="300" spacing="s">
+  {/* without minWidth the row just grows */}
+  <Box flex expandX minWidth="0">
+    <Text maxLines={1}>…</Text>
+  </Box>
+</Box>
+```
 
 ### The text wraps — the end icon must not be left alone
 
 No truncation here: the text is allowed to take several lines. The trap is the
 last child. An icon (or a unit, or an arrow) is an atomic inline, so the browser
-is free to break the line right before it — and no character can prevent that; a
-word joiner does not suppress a break before an atomic inline. On the wrong
+is free to break the line right before it — and no character can prevent that;
+a word joiner does not suppress a break before an atomic inline. On the wrong
 container width, the icon ends up alone on a line under the label.
 
 `attachLastChild` fixes it: the last child and the **last word** before it are
-put in one `white-space: nowrap` box, the classic widow fix applied to the one
-place where breaking is always wrong.
+put in one `white-space: nowrap` box — only the last word, since wrapping the
+whole preceding text would stop a long label from wrapping at all.
 
 ```jsx
 <Text attachLastChild>
@@ -171,114 +143,112 @@ place where breaking is always wrong.
 </Text>
 ```
 
-Only the last word travels with the child — wrapping the whole preceding text
-would stop a long label from wrapping at all.
-
 `Link` does this on its own whenever it renders an end icon (`endIcon`,
-`anchorIcon`, the external-target one), which is why a document's table of
-contents never drops an arrow on a line of its own. Write `attachLastChild`
-yourself when you build such a pair outside `Link`.
+`anchorIcon`, the external-target one). Write `attachLastChild` yourself when
+you build such a pair outside `Link`.
 
 ## Spacing between children
 
 `Text` injects a separator between its children whenever at least one side is an
-element — so an icon and a label are spaced without a manual `{" "}`, and two
-plain strings are left alone. `spacing` changes it: a size token (`"s"`, `"m"`,
-…), a CSS length, a number (px), a string used verbatim, or `"pre"` / `0` to
-inject nothing.
-
-Two things opt out of that flow:
-
-- `markAsOutsideTextFlow(Component)` — for something rendered inside a `Text`
-  that takes no room in the line (an absolutely positioned indicator, an
-  overlay). Without it, a separator is injected next to something invisible and
-  leaves a stray gap.
-- `preventSpaceUnderlines` — inside an `<a>`, browsers draw the underline under
-  the space characters too. This replaces them with padding-based spaces, so the
-  underline stops at the text. `Link` sets it.
+element — an icon and a label are spaced without a manual `{" "}` — and
+`spacing` changes it. Two things opt out of that flow:
+`markAsOutsideTextFlow(Component)`, for something rendered inside a `Text` that
+takes no room in the line (an absolutely positioned indicator, an overlay),
+where a separator would leave a stray gap next to something invisible; and
+`preventSpaceUnderlines`, which `Link` sets, so an underline stops at the text
+instead of running under the spaces.
 
 ## Emoji
 
 **An emoji is not a character the layout can absorb.** The system emoji fonts
-(Apple Color Emoji, Segoe UI Emoji, Noto Color Emoji) have a taller
-ascent/descent than any text font, and under `line-height: normal` a line box
-takes the height of the tallest font it holds. So the moment an emoji sits in a
-line, that line is taller than the ones around it: a row shifts down next to its
-neighbours, a paragraph's lines are unevenly spaced, a truncated label no longer
-lines up with its siblings. Tighten the line to get the rows even again and the
-glyph is clipped instead — its box is taller than a letter's, and what sticks
-out is simply cut.
+have a taller ascent/descent than any text font, and under `line-height: normal`
+a line box takes the height of the tallest font it holds. So the moment an emoji
+sits in a line, that line is taller than the ones around it: a row shifts down
+next to its neighbours, a paragraph's lines are unevenly spaced. Tighten the
+line to get the rows even again and the glyph is clipped instead.
 
 **One number answers both: `--navi-line-height`, 1.25.** Tall enough to contain
 an emoji's own box, so nothing is clipped; tight enough that a line carrying one
 is exactly as tall as a line of plain text, so nothing moves. 1 cuts the top off
 the glyph, 1.5 spaces the rows out more than reading them asks for. **An app
 that displays what people typed cannot go below 1.25** — that is the floor this
-token encodes, and the reason it is a token rather than a number repeated in
-every component.
+token encodes.
 
 **Everything is written on that line, controls included.** The document sets it
-on `:root`, and the components that would otherwise come with a line of their
-own from the browser — `Button`, `Input`, `Textarea`, `Select` — are handed it
-by name: a form control inherits nothing from the page on its own, and what it
-starts from is `normal`, the one value the emoji breaks. `Picker` and the items
-of a selectable `List` take it too, though they are drawn by hand: they stand
-in a row with those, sized in `lh` like them, and have to be the same number
-of pixels tall. That is what makes a
-value keep its line, and its emoji its size, as it passes from the field it was
-typed in to whatever displays it afterwards — an emoji typed in an input is not
-clipped, and the same emoji displayed in a row, a bubble or a button does not
-push anything around. `text_emoji_demo.html` shows it by swapping the field and
-the rendering in place.
+on `:root`, and the controls that would otherwise start from the browser's
+`normal` — the one value the emoji breaks — are handed it by name: `Button`,
+`Input`, `Textarea`, `Select`, and `Picker` and selectable `List` items, which
+stand in a row with them. A form control inherits nothing from the page on its
+own. So a value keeps its line, and its emoji its size, from the field it was
+typed in to whatever displays it afterwards (`text_emoji_demo.html`).
 
 A control takes it snapped to the pixel (`--navi-control-line-height`,
-`round(1.25em, 1px)`). The browser lays a line out at its exact height but
-paints the glyph on a pixel row, and at the default control size (13.333px)
-the line is 16.666px: the two-thirds that do not fit go entirely under the
-glyph, which then sits a pixel above the middle of its field — the placeholder
-looks too high. A whole number of pixels has no remainder to put anywhere, and
-a `Textarea` sized in `lh` lands on the same grid as the placeholder it
-measures. The page's text keeps the plain number: a length would stop
-following the font size the moment it is inherited.
+`round(calc(var(--navi-line-height) * 1em), 1px)`): a fractional line puts its
+remainder under the glyph, which then sits a pixel above the middle of its
+field. The page's text keeps the plain number, which follows the font size when
+inherited.
 
 Change it on `:root` for a whole app. Do not unset it on a component, do not let
 one fall back to `normal`, and do not raise a local `lineHeight` because of an
 emoji: a `lineHeight` is a typographic choice for the text itself — a paragraph
 that wants air — never a workaround for a glyph that grew too tall.
 
-**Where an emoji belongs is a separate question, and it is not a layout one.**
-A field can still refuse emoji outright (`noEmoji`) where the value is an
-identifier rather than free text. A name is the case worth stating: people are
-called what they are called, and a whitelist on a name field ends up refusing
-somebody's real name — a name field keeps to the rules that are about what can
-be drawn at all (`data-displayable`: marks stacked into zalgo, a value that
-shows nothing, blank lines in series).
+Where an emoji belongs is a separate question, and not a layout one: a field
+refuses one with `noEmoji`, and a name field — people are called what they are
+called — keeps to what can be drawn at all (`displayable`) rather than a
+whitelist. See [field_validation.md](./field_validation.md#constraints).
 
 ## Text that must not move when its style changes
 
 A label that becomes bold when its row is selected reflows everything around it.
-Two answers, and the one to pick depends on whether the text wraps:
-
-- `holdSpaceForStyle={{ fontWeight: "bold" }}` — an invisible copy rendered in
-  the target style reserves the space; the visible text is layered on top. Handles
-  any style change (weight, size), single-line only. Best with `noWrap`.
-- `boldStable` — paints normal-weight text over a bold background clipped to the
-  glyphs. Works on several lines, handles weight only.
-
-And `shrinkWrap` for the reverse problem: an element whose box is wider than the
-longest line it actually renders (a wrapped paragraph inside a flex or grid
-container). It measures and pins the width to that longest line.
+`holdSpaceForStyle={{ fontWeight: "bold" }}` reserves the space with an
+invisible copy in the target style — any style change, single-line only (best
+with `noWrap`); `boldStable` handles weight only, on several lines. And
+`shrinkWrap` for the reverse problem: an element wider than the longest line it
+renders (a wrapped paragraph inside a flex or grid container) is pinned to that
+line.
 
 ## Loading
 
 `loading` renders a shimmering skeleton in place of the content; `skeleton` is
 the same bar without the animation. The children stay in the DOM (hidden), so
-the block keeps the size the real text will have — pass the eventual text, not a
-placeholder, whenever it is known.
-
-The bar stands in for text and is painted with the text's own ink, so it is seen
-on whatever paper it lands on — a pale card, a filled one where the ink flips —
-without being told what that paper is. Where the surrounding ink is the wrong
-cue, `--skeleton-color` and `--skeleton-shimmer-color` (the moving band) take it
-over; navi declares neither, so both can be set on the element or on any
+the block keeps the size the real text will have — **pass the eventual text,
+not a placeholder**, whenever it is known.
+
+The bar is painted with the text's own ink, so it is seen on whatever paper it
+lands on without being told what that paper is. Where the surrounding ink is the
+wrong cue, `--skeleton-color` and `--skeleton-shimmer-color` (the moving band)
+take it over; navi declares neither, so both can be set on the element or on any
 container above it.
+
+## BadgeList
+
+A row of badges that wraps. A plain one costs nothing — one element holding its
+children as they are; only `max`, `fallback`, `maxLines` and `shrinkWrap` count
+or measure. Once the list has something to decide (`max`, `fallback`,
+`maxLines`), a `Badge` inside it does not render itself: it hands its props to
+the list, which draws it. Two consequences:
+
+- a `Badge` must be a **direct** child of the list — `<div><Badge /></div>`
+  takes the badge out of its wrapper;
+- a badge's own `key` does not reach the badge the list draws, which is keyed
+  by position: reordering recreates the nodes rather than moving them.
+
+Inside a `Picker`, the rows are capped by the picker's `maxLines` (the picker
+turns its own clamp off: line-clamp never sees a wrapped flex row), and `max`
+composes with it — the `+N` badge takes one of the `max` slots. A picker given
+a `ui` draws that and only that, never its `placeholder`, so an empty
+`BadgeList` there is a blank picker: pass the placeholder text as the list's
+`fallback`.
+
+```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, and the
+box stays the same height empty and filled. It is drawn in the normal text
+color, not the placeholder's — a caller's `ui` is never greyed as a placeholder.