@jsenv/navi 0.29.109 → 0.29.111

package/docs/AI_INSTRUCTIONS.md

@@ -88,6 +88,17 @@ consistency across the app, not from any single call site.
   before displaying an error by hand, before writing an error boundary of your
   own, and before concluding that a dev overlay over a page that already shows
   its error is a crash.
+- `docs/field_validation.md` — what a control refuses and who decides it: the
+  split between what only a browser can answer (a blocked keystroke, where the
+  callout lands, when the message appears) and « is this value acceptable »,
+  which is @jsenv/validity's and which a server asks about the same value. The
+  constraint attributes navi ships, the `charGuard`/`maxLengthGuard` props that
+  act before there is a value, how a message key is overridden, and the three
+  places an app's own rule can live — both sides via
+  `constraintFromValidityRule`, the server alone, the browser alone. Read it
+  before writing a constraint of your own: if the sentence would make sense in a
+  server's response, the rule belongs in validity and the constraint is only its
+  browser-side caller.
 - `docs/css_architecture.md` — how Navi's CSS layering works, and the
   supported ways to override component styles (props > CSS variables > direct
   rule overrides, in that preference order).
@@ -203,8 +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`.
-  Read it before writing an overflowing label or a row with a trailing icon.
+  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.
+  Read it before writing an overflowing label or a row with a trailing icon,
+  and before touching a text control's `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

@@ -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,23 @@ 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.
+
+Where such a rule belongs — a navi constraint, a @jsenv/validity rule the
+server runs too, or both — is `docs/field_validation.md`.
+
 ## What a failing action does
 
 It writes the error into `errorSignal`, moves to `FAILED`, and stops.

package/docs/field_validation.md

@@ -0,0 +1,193 @@
+# Field validation
+
+What a control refuses, who decides it, and what is left for a server to say.
+
+## The split
+
+A control refuses a value for two very different kinds of reason, and keeping
+them apart is the whole subject.
+
+**What only a browser can answer.** A keystroke blocked before the value exists,
+a callout placed next to the field, `required` on a radio group, `data-one-of`
+reading an option list out of the document, the moment a message appears
+(typing? blur? submit?).
+This is navi's, and it stays navi's.
+
+**« Is this value acceptable ».** A length, a set of allowed characters, a
+value that renders nothing, a business rule. This is not a DOM question — a
+server asks the same one about the same value — so it lives in
+[@jsenv/validity](../../../tooling/validity/README.md) and navi consumes it.
+
+The consequence that matters when writing an app: **do not write a constraint
+for something a rule already answers**. If the sentence you are about to write
+in a `check()` would make sense in a server's response, the knowledge belongs in
+a validity rule, and the constraint is only its browser-side caller.
+
+## Constraints
+
+A constraint is `{ name, check(field) }`. `check` returns `null` when the value
+passes, or the message to show — a string, or `{ message, target }` when the
+callout belongs on another element than the control itself.
+
+Navi's own constraints are switched on by an attribute on the control —
+standard when the platform has one, `data-*` when it does not.
+
+**They are written as props, in camelCase.** A constraint declares the attribute
+it reads (`data-no-emoji`) and a control accepts the prop that stands for it
+(`noEmoji`), putting it on the control host under the attribute name — the same
+conversion `element.dataset` does. So `singleSpace` is what you write and
+`data-single-space` is what ends up in the DOM (and in the devtools, and in a
+test selector). The attribute form is accepted too, for a control written in
+plain HTML.
+
+| prop                            | attribute                                   | refuses                                                                         |
+| ------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------- |
+| `required`, `pattern`           | same                                        | what the platform's attributes mean                                             |
+| `minLength`, `maxLength`        | same                                        | a string too short or too long                                                  |
+| `min`, `max`, `step`            | same                                        | a number, date, time or duration out of range                                   |
+| `singleSpace`                   | `data-single-space`                         | a leading or trailing space, two in a row                                       |
+| `displayable`                   | `data-displayable`                          | zalgo, a value showing nothing, blank lines in series, a joiner joining nothing |
+| `maxStackedMarks`               | `data-max-stacked-marks`                    | (parameter of `displayable`)                                                    |
+| `noEmoji`                       | `data-no-emoji`                             | an emoji, where a name, an identifier or a title does not want one              |
+| `maxLineBreaks`                 | `data-max-line-breaks`                      | a value holding more line breaks than that                                      |
+| `oneOf`                         | `data-one-of`                               | a value outside the option list its CSS selector points at                      |
+| `sameAs`                        | `data-same-as`                              | a value differing from the field it names                                       |
+| `minDigit`, `minUpperLetter`, … | `data-min-digit`, …                         | a password missing a kind of character                                          |
+| `timeAfter`, `timeMinDuration`  | `data-time-after`, `data-time-min-duration` | a time span that ends before it starts, or is too short                         |
+
+```jsx
+<Input required singleSpace noEmoji maxLength={80} />
+<Textarea displayable singleSpace maxLineBreaks={4} />
+```
+
+A boolean switch (`displayable`, `singleSpace`, `noEmoji`) passed as `false` is
+off, so `noEmoji={settings.strictNames}` says what it looks like it says. The
+others carry a value — a count, a selector — and are off by being absent.
+
+Each constraint has a `<name>Message` prop (and a `data-<name>-message`
+attribute) to replace its sentence for one field. To change it everywhere,
+override the i18n key instead — see below.
+
+Two props sit beside them and belong to the browser alone, because they act
+before there is a value to validate: `charGuard` blocks a keystroke that is not
+in its character class, `maxLengthGuard` blocks the one that would overflow (and
+truncates a paste). Both show what they refused in a callout rather than
+silently swallowing it.
+
+`charGuard` takes a character class or one of validity's preset names, so a
+field can refuse the keystroke with the same knowledge the value is checked
+against: `charGuard="tel"`, `charGuard="slug"`, `charGuard="noEmoji"`. Refusing
+the keystroke and refusing the value are different jobs — the pair
+`maxLengthGuard`/`maxLength` is the same split — and a field usually wants both.
+
+**A guard answers for the gesture, never for what the field already holds.** A
+value can arrive already outside the class or already too long — a
+`defaultValue`, a signal, a value written from elsewhere — and a guard that
+re-judged the whole value would refuse every keystroke over it, blaming the
+person for a character they did not type, and refuse the deletion that would
+have fixed it. So a change is refused only when it makes the value worse. What
+is already there is the constraint's business, and it says so at submit.
+
+## Reading the validity without submitting
+
+`useConstraintValidityState(ref)` gives the control's validity as it stands,
+re-read whenever it changes:
+
+```js
+const state = useConstraintValidityState(inputRef);
+state.valid; // false
+state.single_space.messageString; // the sentence
+state.reported; // "max_length" — the one the callout says
+```
+
+Several constraints fail at once and only one sentence is shown: the one with
+the highest priority — an `error` status first, then `required`, then the
+platform's own constraints, then navi's and the app's, ties going to the first
+registered. `reported` names it, so a summary drawn beside the field says the
+same thing as the callout rather than picking a second one.
+
+`src/control/demos/validation/text_rules_demo.html` is that, one rule per row: a
+value that breaks it, its message read live, and a submit to see the callout.
+
+## Messages
+
+Every sentence navi says is a key in `naviI18n`, and the validation ones are
+`constraint.*`. An app changes one for its whole app by registering over it:
+
+```js
+import { naviI18n } from "@jsenv/navi";
+
+naviI18n.add("constraint.single_space.consecutive", {
+  fr: "Pas deux espaces d'affilée.",
+});
+```
+
+The keys of everything validity owns are validity's own key prefixed with
+`constraint.` — `single_space.start` is `constraint.single_space.start`,
+`char_class.slug` is `constraint.char_class.slug`. That is deliberate: the
+sentence a server returns and the sentence the field shows are looked up under
+one name, so making them agree is registering one key, not maintaining a
+translation table. See `src/control/rules/validity_bridge.js`, and `i18n.md` for
+how the registry itself works.
+
+## An app's own rules
+
+An app puts its rules in the package its server reads too, and then decides, per
+rule, who runs it.
+
+**Both sides.** The rule is a validity rule; navi wears it as a constraint.
+
+```js
+// shared/src/text_rules.js — read by the server and by the front
+export const MAX_WORDS_RULE = {
+  name: "maxWords",
+  applyOn: (maxWords, value) => {
+    if (maxWords === undefined || typeof value !== "string") {
+      return null;
+    }
+    const count = value.trim().split(/\s+/).length;
+    if (count <= maxWords) {
+      return null;
+    }
+    return { key: "max_words", params: { max: maxWords, count } };
+  },
+};
+```
+
+```js
+// front — once, at module level: a constraint rebuilt on every render is a new
+// object on every check
+import { constraintFromValidityRule } from "@jsenv/navi";
+
+const MAX_WORDS_CONSTRAINT = constraintFromValidityRule(MAX_WORDS_RULE, {
+  maxWords: 40,
+});
+
+<Textarea constraints={[MAX_WORDS_CONSTRAINT]} />;
+```
+
+The rule's key is looked up in `naviI18n` under `constraint.max_words`, so
+register it there — or pass `formatMessage` beside the parameters to say it
+through the app's own i18n instead.
+
+**The server alone.** A rule needing the database, another user's data or a
+secret stays in `createValidity({ rules })` and never reaches the front; its
+refusal arrives with the response like any other error.
+
+**The browser alone.** A rule about the gesture rather than the value — what a
+keystroke may insert, a warning shown while typing — is a plain navi constraint,
+written inline and never sent anywhere:
+
+```js
+<Input
+  constraints={[(field) => (field.uiState === "admin" ? "Reserved" : null)]}
+/>
+```
+
+`registerGlobalConstraint(constraint)` is the same thing for every control at
+once, for a rule that genuinely holds everywhere in the app.
+
+The line to hold across all three: **the front may be laxer than the back, never
+stricter**. A value the field accepted and the server refuses is a promise
+broken after the fact — which is exactly what happens when the same rule is
+written twice and the copies drift.

package/docs/popup_open.md

@@ -60,8 +60,15 @@ The available commands: `--navi-open`, `--navi-close`, `--navi-toggle`,
 `--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. `--navi-close:all` closes every popup above the button, nearest
-first — a link leaving from a badge shown over a sheet leaves both; a popup
-that refuses to close keeps the ones above it open too.
+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
@@ -194,6 +215,20 @@ 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.
+
 ## Text that must not move when its style changes
 
 A label that becomes bold when its row is selected reflows everything around it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.109",
+  "version": "0.29.111",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {
@@ -29,9 +29,9 @@
     "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"
+    "@jsenv/validity": "0.4.3"
   },
   "devDependencies": {
     "@jsenv/assert": "4.5.7",