@jsenv/navi 0.29.108 → 0.29.110

package/docs/actions.md

@@ -176,6 +176,13 @@ one that asks something of a control near it is a `command` (a value proposed is
 [control_value.md](./control_value.md#a-button-that-proposes-a-value-is---navi-update)).
 Reaching for a plain `onClick` usually means one of those was missed.
 
+On a link — a `Link`, a `<Button href>` or `<Button route>` — the three fire on
+the press, before the navigation, and the navigation waits for none of them: a
+`command="--navi-close"` closes the sheet the link leaves, an `action` that
+writes a draft synchronously is found by the next page, and a request goes on
+its own while the page changes. Work that decides the destination is not a
+link's: it navigates itself, from a `<Button action>`.
+
 The press that looks like a fourth case is the one that opens something and then
 does something with what came of it — "save this guest", pressed on a row,
 replacing the guest once the profile exists. It is not a fourth case and it is

package/docs/control_group.md

@@ -121,6 +121,15 @@ Reference: `.navi_button_content` in `button_ui.jsx` (a button reads then
 stops), `.navi_picker_box`, `.navi_input_slot`, `.navi_popover`,
 `.navi_dialog`.
 
+**A member drawing the frame itself stops it too**, without being a control. A
+row of settings — a `Field`, a `Label`, a `Box` — that paints a background or a
+border, or that insets what it holds with padding, is what the outer corner
+belongs to; the switch at the right end of that row is not on it. `Box` marks
+itself with `navi-box-frame` for exactly those props and stops the claims for
+everything inside. A wrapper adding neither is only an enrobage — a tooltip, a
+link, a bare `<Box>` — and lets them through to the control that really carries
+the frame.
+
 A control that declares its radius on an inner element instead is invisible to
 `Group`: it keeps round corners in the middle of the row, and no rule written
 in `group.jsx` can reach it without naming that private class — which is how a

package/docs/error_handling.md

@@ -94,6 +94,20 @@ Not an error at all, and not to be modelled as one: a value the app or the
 browser refuses is a **status on the control**, carried by navi's constraint
 validation. Never throw to reject a value — see `src/control/rules/`.
 
+An app's own rule joins that set as a constraint — `{ name, check }`, where
+`check(field)` reads `field.uiState` and returns a message or `null`:
+
+```jsx
+<Input constraints={[TEXT_SHAPE_CONSTRAINT]} />; // this control
+registerGlobalConstraint(TEXT_SHAPE_CONSTRAINT); // every control
+```
+
+A constraint is an object, so it carries whatever it needs to decide — there is
+nothing to pass through an attribute. The attributes the shipped constraints
+read (`required`, `data-single-space`, `data-displayable`…) exist because those
+constraints are global and need a per-field switch; a constraint written for
+one call site does not.
+
 ## What a failing action does
 
 It writes the error into `errorSignal`, moves to `FAILED`, and stops.

package/docs/popup_open.md

@@ -59,7 +59,16 @@ The available commands: `--navi-open`, `--navi-close`, `--navi-toggle`,
 `--navi-cancel` (closes, telling the popup the close means "revert"),
 `--navi-confirm` (says yes, then closes). What "revert" does to what is inside
 is [its own section](#escape-cancels-the-other-gestures-keep) — it is also what
-Escape says.
+Escape says. `--navi-close:all` closes every popup above the button, nearest
+first; a popup that refuses to close keeps the ones above it open too. A link
+that leaves is the usual case — a badge shown over a sheet, both left in one
+press:
+
+```jsx
+<Link href={PLAYER_ROUTE.buildUrl({ playerId })} command="--navi-close:all">
+  Profil
+</Link>
+```
 
 ## Something else opens it: `triggerNaviCommand`
 

package/docs/typography.md

@@ -165,9 +165,18 @@ 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 name, a title, an identifier,
-a label. Validate those fields so it never gets in, rather than teaching every
-row of the app to survive it.
+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`:
 
@@ -183,6 +192,18 @@ emoji is a 1em box, never a glyph with its own metrics). `Button` and
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.108",
+  "version": "0.29.110",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {
@@ -29,7 +29,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@jsenv/dom": "0.17.29",
+    "@jsenv/dom": "0.17.30",
     "@jsenv/humanize": "1.7.8",
     "@jsenv/validity": "0.4.2"
   },