@jsenv/navi 0.29.110 → 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/error_handling.md

@@ -108,6 +108,9 @@ read (`required`, `data-single-space`, `data-displayable`…) exist because thos
 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/typography.md

@@ -215,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.110",
+  "version": "0.29.111",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {
@@ -31,7 +31,7 @@
   "dependencies": {
     "@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",