@shaferllc/keel 0.66.0 → 0.74.0

package/docs/i18n.md

@@ -0,0 +1,302 @@
+# Internationalization
+
+Translations with ICU message formatting, plus the `Intl` formatters that go with
+them.
+
+```ts
+import { setTranslations, t } from "@shaferllc/keel/core";
+
+setTranslations({
+  en: { "cart.items": "{count, plural, =0 {Your cart is empty} one {# item} other {# items}}" },
+  fr: { "cart.items": "{count, plural, =0 {Panier vide} one {# article} other {# articles}}" },
+});
+
+t("cart.items", { count: 3 }); // "3 items" — in the request's locale
+```
+
+There is **no dependency here, and there doesn't need to be.** `Intl` ships with
+every modern runtime — Node and Cloudflare Workers both carry the full ICU data —
+so plurals, currencies, dates, and relative times are the platform's job. What Keel
+adds is the message parser on top, which is the part `Intl` doesn't do.
+
+## Setting it up
+
+Register translations once (in a service provider), and add the middleware that
+works out each request's locale:
+
+```ts
+import { setI18n, I18nManager, setTranslations, detectLocale, HttpKernel } from "@shaferllc/keel/core";
+
+export class I18nServiceProvider extends ServiceProvider {
+  boot(): void {
+    setI18n(new I18nManager({ defaultLocale: "en" }));
+
+    setTranslations({
+      en: await import("../resources/lang/en.json", { with: { type: "json" } }).then((m) => m.default),
+      fr: await import("../resources/lang/fr.json", { with: { type: "json" } }).then((m) => m.default),
+    });
+
+    this.app.make(HttpKernel).use(detectLocale());
+  }
+}
+```
+
+Now `t()` works anywhere in the request — a controller, a view, a transformer —
+without threading a locale through every call.
+
+## Translation files
+
+Nested objects and flat dot-keys are the same thing, and you can mix them:
+
+```json
+{
+  "cart": {
+    "items": "{count, plural, one {# item} other {# items}}",
+    "empty": "Your cart is empty"
+  },
+  "checkout.title": "Checkout"
+}
+```
+
+Both `t("cart.items")` and `t("checkout.title")` resolve.
+
+## The message format
+
+The supported ICU subset is the part people actually use.
+
+### Interpolation
+
+```
+Hello {name}!
+```
+
+### Plurals
+
+```
+{count, plural, =0 {Your cart is empty} one {# item} other {# items}}
+```
+
+`#` becomes the count, formatted for the locale (`1,234 items`). An exact `=N`
+branch beats the plural category — which is the whole point of `=0`, because "Your
+cart is empty" reads better than "0 items".
+
+**Categories are the locale's, not English's.** French treats 0 and 1 as singular;
+Polish has `one`/`few`/`many`/`other`. That's exactly why you write a message rather
+than `count === 1 ? "item" : "items"` — that ternary is a bug in most of the world.
+
+### Ordinals
+
+```
+{n, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}
+```
+
+→ 1st, 2nd, 3rd, 4th, 11th.
+
+### Select
+
+```
+{gender, select, male {He} female {She} other {They}} replied
+```
+
+An unmatched value (or a missing one) takes the `other` branch.
+
+### Numbers, dates, times
+
+```
+{n, number}                 1,234.5
+{n, number, percent}        25%
+{n, number, integer}        4
+{n, number, ::currency/USD} $9.50
+{d, date, medium}           Jul 11, 2026
+{d, time, short}            3:30 PM
+```
+
+### Nesting
+
+Branches are themselves messages, so they nest as deep as you need:
+
+```
+{count, plural,
+  =0 {No messages for {name}}
+  one {{name} has # message}
+  other {{name} has # messages}}
+```
+
+### Literal braces
+
+`'{'` and `'}'` render as literal braces.
+
+## Formatters
+
+`Intl`, bound to the request's locale:
+
+```ts
+const l = i18n();
+
+l.formatNumber(1234.5); // "1,234.5"      (de-DE: "1.234,5")
+l.formatCurrency(9.5, "USD"); // "$9.50"
+l.formatDate(order.createdAt); // "Jul 11, 2026"
+l.formatTime(order.createdAt); // "3:30:00 PM"
+l.formatRelativeTime(post.publishedAt); // "3 days ago"
+l.formatList(["a", "b", "c"]); // "a, b, and c"
+l.formatList(names, { type: "disjunction" }); // "a, b, or c"
+l.formatPlural(5); // "other"
+l.formatDisplayName("fr"); // "French"
+```
+
+`formatRelativeTime` picks a sensible unit from the distance on its own — seconds,
+hours, days — or takes one: `formatRelativeTime(date, "hour")`.
+
+These are worth using even in a **single-locale** app: they're the correct way to
+render money and dates, and they cost nothing.
+
+## Locale detection
+
+`detectLocale()` works out the request's locale and stashes it, in this order:
+
+1. a custom `resolve(c)` you supply
+2. a query param — `detectLocale({ query: "lang" })` → `?lang=fr`
+3. a cookie — `detectLocale({ cookie: "locale" })`
+4. the `Accept-Language` header (turn it off with `header: false`)
+5. the default locale
+
+**Only supported locales are honored**, so `?lang=xx` can't push the app into a
+locale you have no translations for — it falls through to the next source.
+
+`negotiateLocale()` is the header parser on its own, if you want it:
+
+```ts
+negotiateLocale("fr-CA,fr;q=0.9,en;q=0.8", ["en", "fr"], "en"); // "fr"
+```
+
+It honors `q` weights and matches `fr-CA` against a supported `fr`.
+
+## Fallbacks
+
+A key with no translation in the active locale falls back — down a chain, not off
+a cliff:
+
+1. the locale itself (`es-MX`)
+2. its configured fallback (`fallbackLocales: { "es-MX": "es" }`)
+3. its **base language** (`es`)
+4. the default locale (`en`)
+
+So you can ship `es` fully and `es-MX` as a handful of regional overrides, and
+everything else still resolves:
+
+```ts
+setTranslations({
+  es: { greeting: "Hola", chair: "silla" },
+  "es-MX": { chair: "banca" }, // just the override
+});
+
+i18n("es-MX").t("chair"); // "banca"
+i18n("es-MX").t("greeting"); // "Hola" — from `es`
+```
+
+## Missing keys
+
+A missing key **does not throw**. It renders as the key itself (`cart.items`), so
+the page still works and the gap is obvious rather than blank. It also fires an
+`i18n.missing` event, which is how you find them in production:
+
+```ts
+listen("i18n.missing", ({ key, locale }) => {
+  logger().warn("missing translation", { key, locale });
+});
+```
+
+Override what's rendered with the `missing` option:
+
+```ts
+new I18nManager({ missing: (key, locale) => `[${locale}:${key}]` });
+```
+
+---
+
+## API reference
+
+### `t(key, data?)`
+
+`t(key: string, data?: Record<string, unknown>): string`
+
+Translate a key in the **current request's** locale (or the default, outside a
+request), formatting its ICU message with `data`.
+
+### `i18n(locale?)`
+
+`i18n(locale?: string): I18n`
+
+An `I18n` for a locale — or, with no argument, the current request's.
+
+### `I18n`
+
+| Method | Signature |
+|--------|-----------|
+| `t` | `(key, data?) => string` |
+| `has` | `(key) => boolean` |
+| `formatNumber` | `(value, options?: Intl.NumberFormatOptions) => string` |
+| `formatCurrency` | `(value, currency, options?) => string` |
+| `formatDate` | `(value, options?: Intl.DateTimeFormatOptions) => string` |
+| `formatTime` | `(value, options?) => string` |
+| `formatRelativeTime` | `(value, unit?, options?) => string` |
+| `formatList` | `(items, options?: Intl.ListFormatOptions) => string` |
+| `formatPlural` | `(count, options?) => Intl.LDMLPluralRule` |
+| `formatDisplayName` | `(code, type?) => string` |
+| `locale` | the locale code |
+
+### `I18nManager`
+
+| Method | Signature |
+|--------|-----------|
+| `add` | `(data: TranslationsByLocale) => this` |
+| `load` | `(...loaders: TranslationLoader[]) => Promise<this>` |
+| `locale` | `(code?) => I18n` |
+| `supported` | `() => string[]` |
+| `defaultLocale` | the default locale code |
+
+`new I18nManager(options)` — see `I18nOptions`.
+
+### `setI18n(manager)` / `getI18n()` / `setTranslations(data)`
+
+Replace the active manager, read it, or add translations to it.
+
+### `detectLocale(options?)`
+
+`detectLocale(options?: DetectLocaleOptions): MiddlewareHandler`
+
+Work out the request's locale and stash it for `t()` / `i18n()`.
+
+### `negotiateLocale(header, supported, defaultLocale)`
+
+`negotiateLocale(header: string | null | undefined, supported: string[], defaultLocale: string): string`
+
+The `Accept-Language` parser, standalone.
+
+### `formatMessage(message, data?, locale?)`
+
+`formatMessage(message: string, data?: Record<string, unknown>, locale?: string): string`
+
+Format an ICU message directly, without a translation lookup.
+
+### `objectLoader(data)`
+
+`objectLoader(data: TranslationsByLocale): TranslationLoader` — the simplest loader.
+
+### Interfaces & types
+
+#### `I18nOptions`
+
+`{ defaultLocale?, supportedLocales?, fallbackLocales?, missing? }`.
+
+#### `DetectLocaleOptions`
+
+`{ query?, cookie?, header?, resolve? }`.
+
+#### `Translations` / `TranslationsByLocale`
+
+A locale's messages (nested or flat), and those keyed by locale.
+
+#### `TranslationLoader`
+
+`{ load(): Promise<TranslationsByLocale> | TranslationsByLocale }`.

package/docs/inertia.md

@@ -0,0 +1,241 @@
+# Inertia
+
+Keel ships a server-side [Inertia.js](https://inertiajs.com) adapter. Pair Keel's
+routing with an Inertia client (React, Vue, or Svelte) and render page components
+from the server without building an API — `inertia("Page", props)` returns the
+right response automatically.
+
+## Configure it
+
+Bind an `Inertia` instance in a service provider. You supply the **root view**
+(the HTML shell that embeds the page data and loads your client bundle) and an
+optional asset **version**:
+
+```ts
+import { ServiceProvider, singleton, Inertia, inertiaPageAttr } from "@shaferllc/keel/core";
+
+export class InertiaServiceProvider extends ServiceProvider {
+  register(): void {
+    singleton(
+      Inertia,
+      () =>
+        new Inertia({
+          version: "1",
+          rootView: (page) =>
+            `<!DOCTYPE html><html><head><meta charset="utf-8"></head>` +
+            `<body><div id="app" data-page="${inertiaPageAttr(page)}"></div>` +
+            `<script src="/assets/app.js"></script></body></html>`,
+        }),
+    );
+  }
+}
+```
+
+`inertiaPageAttr(page)` serializes and HTML-escapes the page object for the
+`data-page` attribute.
+
+> **The version defaults to `"1"`.** Omit it and every deploy reports the same
+> asset version — fine until you ship new assets, at which point stale clients
+> won't be told to hard-reload. Bump it (a build hash, a timestamp) whenever your
+> bundle changes so the adapter can force a full reload on mismatch.
+
+## Render a page
+
+From a controller, or straight from a route:
+
+```ts
+import { inertia } from "@shaferllc/keel/core";
+
+// controller
+show() {
+  return inertia("Users/Show", { user: getUser(param("id")) });
+}
+
+// brisk route
+router.on("/dashboard").renderInertia("Dashboard", { title: "Welcome" });
+```
+
+`inertia()` looks up the bound `Inertia` instance and delegates to its `render`.
+The component name is the client-side path Inertia resolves (e.g. `Users/Show`
+maps to your `Pages/Users/Show` component); `props` is any JSON-serializable
+object.
+
+> **Configure the adapter before you render.** `inertia()` throws
+> `Inertia is not configured…` if no `Inertia` instance is bound in the
+> container. Register the provider (above) during boot, before any route runs.
+
+## What the adapter does
+
+It implements the Inertia protocol for you. Every branch below is decided from
+the incoming request headers — you call `inertia("Page", props)` once and the
+adapter picks the response:
+
+| Situation | Response |
+|-----------|----------|
+| First visit (no `X-Inertia` header) | The full HTML document from your `rootView` (a `string`) |
+| Inertia navigation (`X-Inertia: true`) | `{ component, props, url, version }` JSON + `X-Inertia: true` and `Vary: X-Inertia` headers |
+| Asset version changed (GET) | `409` + `X-Inertia-Location` so the client hard-reloads |
+| Partial reload (`X-Inertia-Partial-Data`) | Only the requested props, for the matching component |
+
+The `url` embedded in the page object is the request's `pathname + search` —
+Inertia uses it to keep the browser history in sync.
+
+### Version mismatches
+
+The version check only fires on a **GET** Inertia request whose
+`X-Inertia-Version` header differs from the adapter's configured version. On a
+mismatch the adapter returns an empty `409` with `X-Inertia-Location` set to the
+current URL; the Inertia client sees the `409` and does a full page reload to
+pull fresh assets. Non-GET requests (a form POST, say) skip the check and render
+normally.
+
+### Partial reloads
+
+When the client asks for a partial reload it sends two headers:
+`X-Inertia-Partial-Component` (the component it already has mounted) and
+`X-Inertia-Partial-Data` (a comma-separated list of prop keys it wants). The
+adapter only trims props when the partial component **matches** the component
+you're rendering — so a partial reload of `Users/Index` won't accidentally
+strip props when you render `Users/Show`. Matching props are filtered down to
+the requested keys; everything else is dropped from the payload.
+
+```ts
+// Client requests only `notifications` for the already-mounted Dashboard.
+// The adapter sends { component: "Dashboard", props: { notifications }, ... }.
+inertia("Dashboard", { stats, notifications, activity });
+```
+
+> Partial reloads are an **allow-list** (the `only` mechanism). The adapter does
+> not implement Inertia's `except` variant — every listed key is kept, all others
+> are dropped.
+
+## The client
+
+The adapter is the server half. On the client, set up Inertia as usual
+(`@inertiajs/react` / `-vue` / `-svelte`) pointing at `#app`, and build your
+`app.js` bundle referenced by the root view. See
+[inertiajs.com](https://inertiajs.com) for the client setup.
+
+## Related
+
+`inertia()` resolves the `Inertia` instance from the [container](./container.md),
+so it's bound like any other [service provider](./providers.md) singleton. The
+`renderInertia` brisk-route helper lives on the [router](./routing.md).
+
+---
+
+## API reference
+
+### `inertia(component, props?)`
+
+`inertia(component: string, props?: Record<string, unknown>): Response | string`
+
+Renders an Inertia response for the current request using the `Inertia` instance
+bound in the container.
+
+```ts
+import { inertia } from "@shaferllc/keel/core";
+
+return inertia("Users/Show", { user });
+```
+
+**Notes:** `props` defaults to `{}`. Throws `Inertia is not configured…` if no
+`Inertia` instance is bound — bind one in a provider first. Returns a `string`
+(the `rootView` HTML) on a first load and a `Response` (JSON, or a `409`) on an
+Inertia navigation, so it fits anywhere a route handler can return either.
+
+### `inertiaPageAttr(page)`
+
+`inertiaPageAttr(page: InertiaPage): string`
+
+HTML-escapes a JSON-serialized page object for embedding in the `data-page`
+attribute of your root element.
+
+```ts
+`<div id="app" data-page="${inertiaPageAttr(page)}"></div>`;
+```
+
+**Notes:** escapes `&`, `"`, `'`, `<`, and `>` (in that order, so `&` isn't
+double-escaped). Use it only inside a double-quoted attribute in your `rootView`
+— it is the escaping counterpart the Inertia client reads back off `#app`.
+
+### `Inertia`
+
+The adapter itself. Construct one and bind it as a container singleton; the
+`inertia()` helper resolves it per request. You rarely call its methods directly
+— `inertia()` and `renderInertia()` do.
+
+#### `new Inertia(options)`
+
+`new Inertia(options: InertiaOptions)`
+
+Creates an adapter with a root view and an optional asset version.
+
+```ts
+new Inertia({
+  version: "1",
+  rootView: (page) => `<div id="app" data-page="${inertiaPageAttr(page)}"></div>`,
+});
+```
+
+**Notes:** `options.version` defaults to `"1"` when omitted; `options.rootView`
+is required.
+
+#### `render(component, props?)`
+
+`render(component: string, props?: Record<string, unknown>): Response | string`
+
+Produces the correct response for the current request: the full HTML document on
+a first visit, the page JSON on an Inertia navigation, a `409` on a version
+mismatch, or a trimmed payload for a partial reload.
+
+```ts
+const html = new Inertia({ rootView }).render("Dashboard", { title: "Welcome" });
+```
+
+**Notes:** reads the active request from `ctx()`, so call it inside a request
+(the `inertia()` helper does this for you). `props` defaults to `{}`. The JSON
+branch sets `X-Inertia: true` and `Vary: X-Inertia`; the `409` branch sets
+`X-Inertia-Location`.
+
+### Interfaces & types
+
+#### `InertiaOptions`
+
+```ts
+interface InertiaOptions {
+  version?: string;
+  rootView: (page: InertiaPage) => string;
+}
+```
+
+The constructor argument. `version` is the asset version (default `"1"`); a
+mismatch against the client's `X-Inertia-Version` forces a full reload.
+`rootView` renders the HTML shell for a first, non-XHR load — it receives the
+`InertiaPage` and must embed it (typically via `inertiaPageAttr`) so the client
+can boot.
+
+```ts
+const options: InertiaOptions = {
+  version: "abc123",
+  rootView: (page) =>
+    `<div id="app" data-page="${inertiaPageAttr(page)}"></div>`,
+};
+```
+
+#### `InertiaPage`
+
+```ts
+interface InertiaPage {
+  component: string;
+  props: Record<string, unknown>;
+  url: string;
+  version: string;
+}
+```
+
+The Inertia page object — the payload both the JSON response and the `rootView`
+receive. `component` is the page name, `props` its (possibly partial-reload
+filtered) data, `url` the request's `pathname + search`, and `version` the
+adapter's asset version. You consume it inside `rootView`; you don't build it
+yourself.