@jsenv/navi 0.29.418 → 0.29.420

package/docs/state_binding.md

@@ -113,7 +113,8 @@ const styleSignal = useSignalSync(user.share_image_style);
 ```
 
 One write at a time shows nothing: the answer carries the value the signal
-already holds. Two in flight — two notches in quick succession — and every
+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.

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.