@jsenv/navi 0.29.112 → 0.29.115

package/docs/AI_INSTRUCTIONS.md

@@ -214,11 +214,11 @@ consistency across the app, not from any single call site.
   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 —
-  and why an emoji belongs only in free text, rendered with `emojiAsIcon` —
-  except in a control one types in, where there is no markup to wrap a glyph in
-  and the fixed line height is what keeps the rows even.
+  and why every text — controls included — is written on one line height
+  (`--navi-line-height`, 1.25): the number below which an emoji is clipped and
+  above which the rows drift apart.
   Read it before writing an overflowing label or a row with a trailing icon,
-  and before touching a text control's `line-height`.
+  and before touching any `line-height`.
 - `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/actions.md

@@ -97,6 +97,20 @@ it — and why a run settles with its error rather than rejecting — is
 state at once — `{ idle, loading, completed, aborted, error, data, params }` —
 for a component that needs to look at it rather than render it.
 
+**Reading does not run.** `useAsyncData` waits for data someone else asked for
+— for a page, the route, through `routeAction`. A component reading an action
+that nobody ran suspends, and `<Loading>` draws nothing for an idle action (no
+spinner for a request nobody sent): the whole subtree stays blank, for good. The
+obvious fix does not work — a `useEffect` in that same component that would
+`run()` it never fires, because a suspended component has no effects, and the
+run it was about to start is exactly what the suspension waits for. So either
+the action is started **before** anything reads it — bound where the screen is
+decided: a `routeAction`, a `<Button action>`, the `action` of the `<Link>` one
+came in by — or the component owns its request and does not suspend on it: a
+folding panel, a slice a button asks for. That one reads `action.dataSignal` and
+`action.errorSignal` (or `useActionStatus`) directly, `run()`s the action from an
+effect, and draws its own skeleton until the data is there.
+
 `{ onLoad }` is what the screen does with the data **once, when it becomes
 known** — seed the fields someone is about to edit, focus something, remember
 where a list was:

package/docs/create_and_edit.md

@@ -134,7 +134,9 @@ Two things to know or the screen stays empty:
 - **Reading an action does not start it.** `useAsyncData` waits for data
   someone else asked for; what asks is the route (`routeAction`). A component
   reading an action nobody runs suspends forever, and the whole `<Loading>`
-  subtree stays blank.
+  subtree stays blank — and an effect in that component cannot rescue it, a
+  suspended component has no effects. What to do instead is under "Reading an
+  action" in [actions.md](./actions.md#reading-an-action).
 - **Handle the error where it happens**, or hand it to an `<ErrorBoundary>`:
   `useAsyncData(action, { loading: true, error: true })` returns
   `[data, loading, error]`, which is what lets a page draw its own "the server

package/docs/typography.md

@@ -159,75 +159,58 @@ Two things opt out of that flow:
 
 **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, 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.
-
-So, first: **an emoji is only expected in free text a user typed** — a message,
-a comment, a description. It has no business in a title, an identifier, a
-label, and a field holding one of those can refuse it outright rather than
-teaching every row of the app to survive it.
-
-A name is the exception worth stating: people are called what they are called,
-and a whitelist on a name field ends up refusing somebody's real name. An app
-taking that side puts `emojiAsIcon` on everything that renders a name, and
-keeps the name field itself to the rules that are about the layout rather than
-the alphabet — `data-displayable`, which refuses only what cannot be drawn:
-marks stacked into zalgo (the one thing `emojiAsIcon` does not rescue, since it
-draws over the row above), a value that shows nothing at all, blank lines in
-series.
-
-Where it is expected, `emojiAsIcon`:
-
-```jsx
-<Text emojiAsIcon>Salut 👋 on se retrouve au parc 🌳 ?</Text>
-```
-
-Every emoji found in the string children is rendered inside an `Icon`, which
-caps it at `1em` and centers it on the line like any glyph icon — the line keeps
-the height of its text, on one line or several. This is what chat apps do (an
-emoji is a 1em box, never a glyph with its own metrics). `Button` and
-`MessageBox` have it on by default — a label is one line whose height
-everything around it relies on, a message is free text; `Badge` forwards it,
-opt-in.
-
-**It does not go through a component.** Only the strings the `Text` itself
-receives are rewritten, so `<Text emojiAsIcon><UserName /></Text>` does
-nothing at all: the string is inside `UserName`, and that is where
-`renderEmojiAsIcon()` has to be called. Doing it there also spares a `Text`
-that would inject a separator between the name and whatever follows it.
-
-There is no way to turn it on for a whole app, on purpose: most of an app's
-text is its own wording, where an emoji cannot appear, and the ones that do
-carry a typed value are known one by one. An app that renders such a value
-everywhere writes its own component around `Text` — the same place it already
-decides how a name is displayed.
-
-What it does not do, and that is accepted: under `maxLines` the `Text` clips at
-its own box — that is what truncation is — and an emoji drawn a little beyond
-its 1em box can lose a sliver at the top. The line stays aligned, which is the
-part that matters.
-
-**Do not raise `lineHeight` because of emoji.** The default line height keeps
-text compact and, with `emojiAsIcon`, holds up even when nearly every word is
-an emoji (see the dense cases in `text_emoji_demo.html`). 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; that glyph gets `emojiAsIcon`.
-
-**A control one types in is the exception, and there the line height is the
-whole answer.** `emojiAsIcon` rewrites strings into markup, and there is no
-markup inside a `<textarea>` or an `<input>`: the value is raw text the browser
-draws itself, so no glyph in it can be wrapped in anything. Under
-`line-height: normal` a line box takes the height of the tallest font it holds,
-so the one line carrying an emoji stands taller than the ones around it — rows
-of uneven height, and a box sized in `lh` (`minRows`/`maxRows`) that jumps as
-soon as one is typed. `Textarea` therefore fixes its line height, and picks a
-value tall enough to contain an emoji's own box so the glyph is not clipped
-either: a tighter one would keep the rows even and cut the top off the emoji.
-Do not remove it, and do not tighten it — `34_textarea_demo.html` shows the two
-side by side. The rule above still holds everywhere the text is rendered rather
-than typed.
+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.
+
+**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.
+
+**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.
+
+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.
+
+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).
 
 ## Text that must not move when its style changes
 

package/package.json

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