@jsenv/navi 0.29.80 → 0.29.82

package/docs/AI_INSTRUCTIONS.md

@@ -156,6 +156,12 @@ consistency across the app, not from any single call site.
 - `docs/z_index.md` (and its tokens in `src/navi_z_indexes.js`) — stacking: why DOM order is the first tool, what a
   `z-index` without `isolation: isolate` actually competes against, and the
   values navi's own popups/bars/tables use. Read it before writing a `z-index`.
+- `docs/typography.md` — text as a component: why every string goes through
+  `Text`, `maxLines` as the one way to truncate (and why `lineClamp={1}` is
+  not it), what makes truncation actually happen in a flex row, and the two
+  opposite shapes of "icon | text | icon" — the end icon kept outside the
+  truncating text, or `attachLastChild` so it never lands alone on a line.
+  Read it before writing an overflowing label or a row with a trailing icon.
 - `docs/i18n.md` — where the texts an app displays live: `interpolateText` /
   `<Interpolate>` for one sentence, `createI18n` for the app's registry,
   `naviI18n` for navi's own texts. Read it before writing a user-visible

package/docs/autofocus.md

@@ -8,7 +8,8 @@ decision.
 - [The ladder](#the-ladder)
 - [A popup that is read before it is filled](#a-popup-that-is-read-before-it-is-filled)
 - [The most precise wins](#the-most-precise-wins)
-- [Docked on a small touch screen: fields are withdrawn](#docked-on-a-small-touch-screen-fields-are-withdrawn)
+- [On a touch device: the surface is what one arrives on](#on-a-touch-device-the-surface-is-what-one-arrives-on)
+  - [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)
 
@@ -34,7 +35,8 @@ Whoever hands out the focus — a popup opening, a slide arriving — tries thes
 in order, and stops at the first that leads somewhere focusable:
 
 1. the element that held the focus when this container was last closed;
-2. the first `autoFocus` — "put it here";
+2. the first `autoFocus` — "put it here". The container's own comes last here,
+   so a field naming itself wins over the surface around it;
 3. the first focusable element — what one came to do;
 4. the deepest `autoFocus="last-resort"`, the container itself included;
 5. nothing, and the caller decides what that means.
@@ -65,10 +67,11 @@ the opposite: "anything in here before me".
 
 ## The most precise wins
 
-`autoFocus` on a field beats `autoFocus` on the surface around it (step 2 above
-comes before step 4). The two can be stated together without a conflict to
-resolve: the surface says where the focus goes by default, a field that really
-is what the user came for says so itself.
+`autoFocus` on a field beats `autoFocus` on the surface around it: both are step
+2 of the ladder, and the container's own mark is tried last there. The two can
+be stated together without a conflict to resolve — the surface says where the
+focus goes by default, a field that really is what the user came for says so
+itself.
 
 ```jsx
 <Dialog autoFocus>
@@ -77,22 +80,54 @@ is what the user came for says so itself.
 </Dialog>
 ```
 
-## Docked on a small touch screen: fields are withdrawn
+## On a touch device: the surface is what one arrives on
 
-A `Dialog` with `dockedOnSmallTouchScreen` becomes a bottom sheet on a phone —
-the one shape the keyboard hurts most, since the sheet starts at the very edge
-the keyboard covers. There, step 3 of the ladder does not consider fields at
-all: rather than the first text input it finds, the opening falls through to
-what remains, usually the surface itself.
+Where the keyboard is a virtual one — anything answering `pointer: coarse` — a
+popup opening drops step 3 of the ladder entirely: the focus goes where
+something ASKED for it, and otherwise to the surface itself.
 
-Nothing to pass, and nothing to remember per call site. A field that wants the
-keyboard on a phone still says so with its own `autoFocus`, which is where that
-decision belongs.
+The condition is the device, not the popup's shape and not the gesture that
+opened it. A virtual keyboard is a fact about the screen: it costs a third of
+the height whichever popup raised it, and a popup opened by the page loading —
+no pointer in it at all — is exactly the one that must not be answered "no
+keyboard here". Docking only makes the cost more visible (a bottom sheet is
+short, so there is less room to lose before the title goes), it is not what
+creates it.
+
+Withdrawing only the FIELDS would not be enough either. The first focusable is
+wherever the content happens to put it — and in a popup that explains before it
+asks, what comes first is the explanation, so the first focusable is far down:
+the terms checkbox, the submit button. Landing there scrolls the popup to it and
+the title is above the top edge again, keyboard or no keyboard. The cause
+changes, the user sees the same thing.
+
+Nothing to pass, and nothing to remember per call site.
+
+### Opting a field back in
+
+Some popups really are opened to type in: one comment box, one rename field.
+There, the field says so itself, and that beats the device — step 2 of the
+ladder comes before step 3 was ever skipped.
+
+```jsx
+<Dialog>
+  <Heading>Leave a comment</Heading>
+  <Textarea name="comment" autoFocus />
+</Dialog>
+```
+
+Worth saying out loud before writing it: a popup holding one field is not
+necessarily a popup opened to fill it — it is often opened to READ what the
+field holds, and raising the keyboard over it then costs the reading for nothing.
+The default answers that case; `autoFocus` on the field answers the other, and
+saying which is which is the caller's to make because nothing about the markup
+can tell them apart.
 
 ## What a field says about itself
 
-- `autoFocus` — "I am what the user came for". A picker's search box on a
-  desktop, the one field of a one-field popup.
+- `autoFocus` — "I am what the user came for". A picker's search box, the field
+  of a popup opened to type in it. It holds on a touch device too: it is how a
+  field opts back into a keyboard the surface would otherwise keep down.
 - `autoFocus="restore"` — "never on a fresh open, but bring me back". A field
   the user was typing in when a popup over it closed: reopening returns to it,
   opening for the first time does not raise a keyboard on it.
@@ -107,9 +142,15 @@ A popup can open on content that holds nothing focusable yet — content still
 being built, a screen not yet interactive. The ladder then comes back empty and
 the opening places no focus at all.
 
-What arrives a moment later is allowed to take it: an opening that placed
-nothing owes the focus to whatever appears next, and an `autoFocus` in that
-content is honored rather than deferring to a transfer that never happened.
+That debt is settled two ways, whichever comes first:
+
+- what arrives a moment later takes it — an `autoFocus` in content built during
+  the opening is honored, rather than deferring to a transfer that never
+  happened;
+- failing that, the ladder is walked once more, one microtask later, still
+  before the browser paints and long before the user can do anything. A surface
+  that says `autoFocus` about itself is placed by that second try.
+
 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.

package/docs/typography.md

@@ -0,0 +1,176 @@
+# Typography (`<Text>` and friends)
+
+What we want: **text is a component, not a tag.** Every string an app displays
+goes through `Text` (or something built on it — `Title`, `Paragraph`,
+`Caption`, `Code`, `Badge`, `Link`, a control's label). The reason is not
+styling: it is that a line of text is rarely only text. It carries an icon, a
+count, a unit, a loading state, a truncation, an anchor to click. Each of those
+has exactly one correct spelling, and `Text` is where that spelling lives — so
+that a screen written by one person and a screen written six months later break
+lines, space icons and truncate the same way.
+
+The corollary: when a piece of text does something the raw tag cannot express,
+the answer is a `Text` prop, not CSS written beside it. If the prop does not
+exist, it is missing from `Text` — that is where to add it.
+
+```jsx
+<Text>Hello</Text>                      // a span
+<Text as="p">A paragraph</Text>         // any tag
+<Title>A heading</Title>                // h1..h6, bold, spaced
+<Caption>A discreet note</Caption>      // small, dimmed
+```
+
+`Text` accepts every `Box` prop (`color`, `size`, `padding`, `expandX`, …), so
+there is never a `<div style>` wrapped around it just to place or color it.
+`size` takes the typography tokens `xxs | xs | s | m | l | xl | xxl` (or any CSS
+length); the spacing props take the spacing tokens of the same name. Two scales,
+same names — `size="l"` is a font size, `padding="l"` is a gap.
+
+Live examples: `src/text/demos/*_demo.html` — one page per concern
+(`text_overflow_demo.html`, `text_spacing_demo.html`, `text_loading_demo.html`,
+`text_attach_last_child_demo.html`, `icon_demo.html`).
+
+## Truncating: `maxLines`, and nothing else
+
+**`maxLines` is the only prop to reach for when text must not exceed a given
+height.** One prop covers both truncations, because from the call site they are
+one decision — "how many lines am I allowed" — even though the browser
+implements them with two unrelated mechanisms:
+
+```jsx
+<Text maxLines={1}>Truncated on one line, with an ellipsis…</Text>
+<Text maxLines={3}>Up to three lines, then an ellipsis…</Text>
+```
+
+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 keeps `white-space`
+sensible for the tag it renders (a `<p>` keeps its line breaks). On a `Text`,
+`maxLines` is always the right answer.
+
+### 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">
+  <Box flex expandX minWidth="0">   {/* without minWidth the row just grows */}
+    <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.
+
+## A row: icon, text, icon
+
+Two rows that look alike on screen and are built the opposite way. Which one you
+want is decided by a single question: **when there is not enough room, does the
+text truncate or does it wrap?**
+
+### The text truncates — the end icon stays visible
+
+Anything that must survive truncation lives **outside** the truncating `Text`,
+as a sibling in a flex row. Inside, it would be eaten by the ellipsis like any
+other character.
+
+```jsx
+<Box flex spacing="s" alignY="center" width="300">
+  <Icon shrink={false}>
+    <StarSvg />
+  </Icon>
+  <Text maxLines={1} expandX>
+    A label long enough that it has to be cut before the trailing icon goes
+  </Text>
+  <Icon shrink={false}>
+    <ChevronSvg />
+  </Icon>
+</Box>
+```
+
+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.
+
+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.
+
+### 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
+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.
+
+```jsx
+<Text attachLastChild>
+  A title long enough to wrap onto several lines
+  <Icon>
+    <ExternalSvg />
+  </Icon>
+</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`.
+
+## 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.
+
+## 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.
+
+## 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.

package/package.json

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