@jsenv/navi 0.29.26 → 0.29.28

package/docs/AI_INSTRUCTIONS.md

@@ -47,6 +47,10 @@ consistency across the app, not from any single call site.
 - `docs/z_index.md` — 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/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
+  sentence, and before overriding a navi message.
 - `docs/MOBILE_LAYOUT_PITFALLS.md` — mobile-specific layout gotchas (viewport
   units, virtual keyboard, safe areas).
 - `docs/navigation.md` — how to build navigation: declaring routes
@@ -80,6 +84,12 @@ consistency across the app, not from any single call site.
 - **Field components** (`Input`, `Select`, `Checkbox`, etc.) take an `action`
   prop to respond to interaction — this is the standard wiring, not
   `onChange` + manual state.
+- **Texts**: a user-visible sentence containing a value is written as one
+  template with `[placeholder]`s (`interpolateText` / `<Interpolate>`), not cut
+  into JSX fragments or concatenations. Beyond a handful of texts, an app
+  declares them in its own `createI18n()` instance — using the English text
+  itself as the key, whereas navi's `naviI18n` uses opaque keys. Application
+  texts never go into `naviI18n`. See `docs/i18n.md`.
 - **View transitions**: navi components animate their own changes
   (`itemTransition` on `List`, `RouteTravel` for routes) and never decide for
   the whole document. Two things are the application's call, not navi's:

package/docs/i18n.md

@@ -0,0 +1,183 @@
+# Texts and i18n
+
+Every text an app displays is a value it owns, like any other. The goal here is
+that those values live somewhere findable and are written as whole sentences —
+not cut into JSX fragments, not concatenated at the call site, not scattered so
+widely that changing the tone of the app means grepping for punctuation.
+
+Translation is a consequence of doing that, not the reason to do it. An app with
+one language still benefits from one place holding its wording; and once it does,
+adding a second language becomes a data change instead of a refactor.
+
+Three tools, from smallest commitment to largest:
+
+| Tool                    | Gives you                                |
+| ----------------------- | ---------------------------------------- |
+| `interpolateText(t, v)` | one readable sentence with values in it  |
+| `<Interpolate>`         | the same, with JSX allowed in the values |
+| `createI18n()`          | a registry of the app's texts            |
+| `naviI18n`              | navi's own texts, to override            |
+
+## Writing a sentence: `interpolateText` / `<Interpolate>`
+
+Use these the moment a sentence contains a value. They need no i18n instance and
+no setup, so there is no reason to avoid them in a single-language app.
+
+```js
+import { interpolateText } from "@jsenv/navi";
+
+interpolateText("Deleting [name]…", { name: file.name });
+```
+
+In JSX, `<Interpolate>` keeps the sentence readable when part of it is styled:
+
+```jsx
+<Interpolate radiusKm={<Text bold>{radius} km</Text>} zoneName={zone}>
+  Data limited to [radiusKm] around [zoneName].
+</Interpolate>
+```
+
+The point is that the full sentence is visible in one place. The alternative —
+`Data limited to <Text bold>{radius} km</Text> around {zone}.` — reads as
+fragments, and cannot later become a translation key, because there is no
+single string to be the key.
+
+Placeholders are `[name]`. The delimiter is `[]` rather than `{}`/`{{}}` because
+it collides with neither JSX nor template literals nor ordinary punctuation.
+Details worth knowing (all in `interpolateText`'s JSDoc): a value can be a
+dot-path (`[item.label]`), a function (called only if the placeholder is
+present), and a placeholder with no value is left visible as `[name]` rather
+than disappearing.
+
+## Centralizing texts: `createI18n`
+
+Once several components display text, give the app a registry. One instance for
+the whole app, exported from one module:
+
+```js
+// src/app_i18n.js
+import { createI18n } from "@jsenv/navi";
+
+export const i18n = createI18n({ keyLang: "en" });
+```
+
+Then call it wherever a text is needed. It is callable directly:
+
+```js
+import { i18n } from "@/app_i18n.js";
+
+i18n("Deleting [name]…", { name: file.name });
+```
+
+### In an app, the text is the key
+
+`keyLang: "en"` means "keys are already written in English". The key doubles as
+its own English template, so a single-language app registers nothing at all and
+still gets readable output, and adding French later touches only the registry:
+
+```js
+i18n.add("Deleting [name]…", { fr: "Suppression de [name]…" });
+```
+
+This is the recommended style for applications, because it keeps the call site
+readable. `i18n("Deleting [name]…")` says what appears on screen;
+`i18n("file.delete.progress")` requires a lookup to know. The cost — changing
+the English wording changes the key, so its translations must be updated
+alongside — is the smaller problem in practice, and it is a mechanical one.
+
+### In navi, the key is opaque
+
+`naviI18n` uses opaque keys (`"list.empty"`, `"constraint.required.email"`)
+because a library's texts are addressed from the outside: an app overriding a
+message needs a stable name that does not move when navi rewords its default
+English. Same reasoning applies to any shared component library — the trade-off
+flips with who owns the text.
+
+Without `keyLang`, every language is explicit, English included:
+
+```js
+const i18n = createI18n();
+i18n.add("greeting", { en: "Hello [name]!", fr: "Bonjour [name] !" });
+```
+
+### Registering
+
+Three ways in, all accumulative — re-registering a key replaces that one key and
+leaves the rest alone:
+
+```js
+i18n.add("Save", { fr: "Enregistrer" }); // one key, many languages
+i18n.addAll({ Save: { fr: "Enregistrer" }, Cancel: { fr: "Annuler" } });
+i18n.addLangKeys("fr", frenchPack); // a whole language, e.g. a fetched JSON file
+```
+
+A regional variant inherits from its parent for every key it does not override,
+resolved at registration time — so register `"fr"` before `"fr-CA"`.
+
+### What comes out
+
+`i18n(key, values, { lang })` returns the translation with placeholders
+replaced. When nothing matches it returns the key itself, so a missing
+translation degrades to readable text rather than blank space or a crash. Pass
+`fallbackLang` at creation to fall through to another language first, per key —
+a half-translated language stays usable.
+
+`i18n.has(key)` is the way to tell "no translation" apart from "translation that
+happens to equal the key".
+
+## Which language
+
+Nothing needs configuring for navi and app texts to agree on a language: both
+default to `languagesSignal`, which is read live on every lookup — the browser's
+`navigator.languages`, plus two app-level overrides.
+
+```js
+import { setSupportedLanguages, setPreferredLanguage } from "@jsenv/navi";
+
+setSupportedLanguages(["en", "fr"]); // what the app offers, at startup
+setPreferredLanguage("fr"); // what this user picked, from a language picker
+```
+
+`setSupportedLanguages` matters more than it looks: without it, a browser
+preferring German resolves to German, and every key missing in German falls back
+to its key. With it, that browser lands on the app's best available language
+instead.
+
+Because the language is read at lookup time, a component that reads `i18n(...)`
+during render re-renders with the new wording when the language changes — as
+long as the call happens in render, not in a value captured once outside it.
+
+## Changing what navi says
+
+`naviI18n` holds navi's own texts. Register on it to override a default or to
+add a language navi does not ship:
+
+```js
+import { naviI18n } from "@jsenv/navi";
+
+naviI18n.add("list.empty", {
+  en: "Nothing here yet.",
+  fr: "Rien pour l'instant.",
+});
+naviI18n.addLangKeys("ja", { "button.close": "閉じる" });
+```
+
+Its JSDoc lists the key namespaces; the exhaustive list of keys and defaults is
+the registration block in `src/text/navi_i18n.js`, which is meant to be read.
+
+Do not put application texts in `naviI18n`. Key collisions aside, the two have
+different lifecycles: navi's keys come with the package version, the app's come
+with the app.
+
+One convention to know, since it is what `<Quantity>`/`<Unit>` look up: a unit
+name may have `<unit>__plural` and `<unit>__short` variants, both optional
+(missing ones fall back to the singular). An unregistered unit goes to
+`Intl.NumberFormat`, so only units Intl gets wrong or does not know need
+registering at all.
+
+## Choosing, in one line
+
+Reach for `interpolateText`/`<Interpolate>` as soon as a sentence has a value in
+it. Reach for `createI18n` as soon as more than a handful of texts exist — the
+migration from the first to the second is wrapping the string in a call, which
+is why starting with plain interpolation costs nothing.

package/docs/navigation.md

@@ -98,6 +98,47 @@ const sectionSignal = stateSignal("to_come", {
 export const GAMES_SECTION_ROUTE = route(`/games/:section=${sectionSignal}`);
 ```
 
+#### Declaring the sections is what makes them places
+
+Both forms can be written together, and they say different things — which is
+why declaring the literals is not decoration:
+
+```js
+export const MY_GAMES_ROUTE = route(`/games/me/:section=${sectionSignal}`);
+export const MY_GAMES_TO_COME_ROUTE = route("/games/me"); // the default: no segment
+export const MY_GAMES_CANDIDATE_ROUTE = route("/games/me/candidate");
+export const MY_GAMES_DONE_ROUTE = route("/games/me/done");
+```
+
+Standing on `/games/me/done`:
+
+- `MY_GAMES_ROUTE.buildUrl()` → `/games/me/done`. The parameterized route reads
+  its signal, so a link to "my games" from the bottom bar **reopens the section
+  you were looking at**. That is what the signal is for, and `persists` makes it
+  survive the night;
+- `MY_GAMES_TO_COME_ROUTE.buildUrl()` → `/games/me`, always. A tab must point at
+  its own section, never at the one already open — a tab pointing at the current
+  page is a tab that cannot be clicked.
+
+The default section is the delicate one: it has no segment of its own, so its
+literal route is the **parent** of the parameterized one. It still means the
+default section and does not inherit the param.
+
+What tells navi these values name pages rather than qualify one is precisely
+that the literal routes exist. Where no literal is declared, the value stays a
+qualifier and an ancestor url keeps it:
+
+```js
+const tabSignal = stateSignal("general", { id: "settings_tab" });
+export const ADMIN_ROUTE = route(`/admin/:section=${sectionSignal}/`);
+export const ADMIN_SETTINGS_ROUTE = route(`/admin/settings/:tab=${tabSignal}`);
+// nobody declared /admin/settings/advanced, so on tab "advanced":
+// ADMIN_ROUTE.buildUrl() → /admin/settings/advanced — "admin, where you left it"
+```
+
+So the rule is the one you would want: name a section and it becomes a place;
+leave it unnamed and it stays a setting carried along.
+
 ### Search params
 
 A param that qualifies a page rather than naming it — a zoom level, a sort, a

package/docs/resource.md

@@ -25,7 +25,7 @@ Each callback returns the data to upsert into the store:
 | GET / POST / PUT / PATCH | the full item object, `{ id, … }` |
 | DELETE                   | the id, or `{ id }`               |
 | GET_MANY / POST_MANY / … | an array of item objects          |
-| GET_PAGE                 | `{ items, start, count }` (below) |
+| GET_RANGE                | `{ items, start, count }` (below) |
 
 Actions are read in components through the action system (`useAsyncData`,
 `<Button action>`, …) — see [actions.md](./actions.md).
@@ -48,18 +48,18 @@ it yourself is the point:
   else to land (see [When the backend answers a sub-route with the whole
   parent](#when-the-backend-answers-a-sub-route-with-the-whole-parent)).
 
-A list that loads its rows page by page is **not** one of those cases — that is
-`GET_PAGE`, right below.
+A list that loads its rows a slice at a time is **not** one of those cases — that is
+`GET_RANGE`, right below.
 
-## `GET_PAGE`: feeding a list that loads as it scrolls
+## `GET_RANGE`: feeding a list that loads as it scrolls
 
 A `<List.Items>` asks for the rows it is about to draw and keeps what it gets.
-`GET_PAGE` is the resource's answer to that question — one slice at a time:
+`GET_RANGE` is the resource's answer to that question — one slice at a time:
 
 ```js
 const GAME = resource("game", {
   GET: ({ id }) => fetchJson(`/games/${id}`),
-  GET_PAGE: ({ radar, start, limit }) =>
+  GET_RANGE: ({ radar, start, limit }) =>
     fetchJson(`/radars/${radar.id}/games?start=${start}&limit=${limit}`),
   // { items: [{ id, … }, …], start: 20, count: 137 }
 });
@@ -68,7 +68,7 @@ const GAME = resource("game", {
 ```jsx
 <List.Items
   count={radar.match_count}
-  itemsAction={GAME.GET_PAGE.bindParams({ radar })}
+  itemsAction={GAME.GET_RANGE.bindParams({ radar })}
   renderItem={(game) => <GameCard game={game} />}
 />
 ```
@@ -76,7 +76,7 @@ const GAME = resource("game", {
 The callback receives the bound params merged with the range the list asks for
 (`start`, `end`, `limit`, `before`, `after`, `around`, `count`), and a `signal`
 as second argument — aborted when the list stops wanting those rows. It returns
-a page the way a `Content-Range` does: **`{ items, start, count }`** — these
+a range the way a `Content-Range` does: **`{ items, start, count }`** — these
 rows, at this place, out of that many. `start` may be omitted when the list
 asked for a positive one; `count` defaults to `start + items.length` (a source
 that does not know its total). The items are upserted on their way in, so the
@@ -98,12 +98,12 @@ makes a change detectable), so the one the list is holding is the one it was
 given. Relations are not concerned: they are keyed by owner, and a row reading
 `game.candidates` reads the shared collection whatever object carries it.
 
-`GET_PAGE` is a **reader, not an action**. It keeps no value and takes no place
+`GET_RANGE` is a **reader, not an action**. It keeps no value and takes no place
 in the rerun graph, which is what makes it usable per slice:
 
-- the list already holds the pages it received and glues them back together —
+- the list already holds the slices it received and glues them back together —
   a second memory holding one of them would fight it;
-- a `POST` invalidating "the collection" would otherwise send every page ever
+- a `POST` invalidating "the collection" would otherwise send every slice ever
   loaded back to the network at once.
 
 What it does not give is membership: an item that leaves the collection stays on

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.26",
+  "version": "0.29.28",
   "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.8",
+    "@jsenv/dom": "0.17.9",
     "@jsenv/humanize": "1.7.8",
     "@jsenv/validity": "0.4.2"
   },