@escape-game-over/atlas 0.1.96 → 0.1.98

package/docs/rich-text.md

@@ -167,6 +167,43 @@ A caller that does can build one — `joinUrl(site.urlFor(id, locale), href)`.
 address or number is written once. The number must be in international form —
 `"+30 210 0000000"` — because a local one does not dial from abroad.
 
+## Binding slots and values once
+
+A view that renders many messages through one call — a FAQ page reading every
+answer in a loop, a description per route — cannot pass a slot or a value to
+some messages and not others: a message that declares none refuses the
+argument, and one that does demands it. Bind them when the reader is made:
+
+```ts
+const rich = site.rich(locale, {
+    links: { contact: "contact", rooms: "rooms" },
+    values: { hours: "Mon–Fri 10:00–22:00" },
+});
+
+rich("faq.hours.a"); // "…open {hours}, see [a:contact]Contact[/a]." needs nothing
+rich("faq.age.a"); // no slots or placeholders, still no argument
+```
+
+`site.translate(locale, { values })` and `site.plain(locale, { values })` take
+the same `values`; they have no links to bind.
+
+Nothing is loosened:
+
+- **A bound destination is checked where it is bound**, against the routes this
+  project builds, as a call's would be.
+- **Whatever is left unbound is still required** at the call, and still a
+  compile error without it — for a single key and for a union of keys alike, so
+  a loop over messages fails to compile if one names a slot or placeholder
+  nobody bound.
+- **A bound name is not offered to the call.** Passing it again is a compile
+  error; for a key that arrived as a plain `string`, the call's own wins.
+- **A bound name nothing uses is fine.** A reader binds what its messages may
+  use, not what each one does.
+- **A value is still text.** It cannot open a mark, bound or passed.
+
+Copy still names a slot, never an address. Binding moves where the destination
+or value is written — to the one place that renders the copy — not into it.
+
 ## What the compiler holds in step
 
 Which marks a message uses is checked across locales by the same machinery that
@@ -266,7 +303,8 @@ class nor attrs still renders its words, and warns at build.
 | --------------------------------------------------- | --------------------------------------------------------------------- |
 | A locale dropping `[a:venue]`                       | compile error — the marks must match across a message                 |
 | `[a:venue]` in one locale, `[a:booking]` in another | compile error — the argument is part of the token                     |
-| `rich()` without a slot's target                    | compile error, then a build error naming the slot                     |
+| `rich()` without a slot's target, unbound           | compile error, then a build error naming the slot                     |
+| A slot bound to an unbuilt route                    | compile error where it is bound                                       |
 | A slot filled with an unbuilt route                 | compile error at the call site                                        |
 | `[Mon-Fri]`                                         | build error, listing the marks and the `[[` escape                    |
 | `[b]` never closed, `[/b]` never opened             | build error naming the message and locale                             |

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.96",
+    "version": "0.1.98",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,

package/src/content/index.ts

@@ -32,6 +32,7 @@ export {
     html,
     type LinkResolver,
     type LinkTarget,
+    type MessageBindings,
     type PlainTextFor,
     plain,
     type RichText,

package/src/content/rich.ts

@@ -11,6 +11,7 @@ import {
     lookupTemplate,
     type MergedCatalog,
     render,
+    valueFor,
 } from "../i18n/translate.ts";
 import type { StringKeys } from "../types.ts";
 import {
@@ -179,6 +180,28 @@ export interface RichTextOptions<L extends string> {
      * on a bad one. `joinUrl` already answers it once.
      */
     readonly origin: HttpsUrl;
+    /**
+     * Destinations bound once, for every message this `rich()` reads: a slot
+     * named here is filled without the call passing it. Already checked by
+     * the type that built this; strings by the time they reach the runtime.
+     */
+    readonly links?: Readonly<Record<string, string>>;
+    /** Placeholder values bound the same way. */
+    readonly values?: Readonly<Record<string, string>>;
+}
+
+/**
+ * What a `rich()` binds when it is made: link destinations and placeholder
+ * values that every message read through it may use without the call passing
+ * them. `plain()` and `t()` take the `values` half.
+ */
+export interface MessageBindings<
+    RouteId extends string,
+    Links extends string,
+    Values extends string,
+> {
+    readonly links?: Readonly<Record<Links, LinkTarget<RouteId>>>;
+    readonly values?: Readonly<Record<Values, string>>;
 }
 
 /** The link slots message `K` declares, e.g. `"venue"` from `[a:venue]`. */
@@ -200,8 +223,12 @@ export type RichParamsOf<
     Catalog,
     K extends StringKeys<Catalog>,
     RouteId extends string,
-> = Readonly<Record<MessageParamsOf<Catalog, K>, string>> &
-    Readonly<Record<LinkNamesOf<Catalog, K>, LinkTarget<RouteId>>>;
+    Links extends string = never,
+    Values extends string = never,
+> = Readonly<Record<Exclude<MessageParamsOf<Catalog, K>, Values>, string>> &
+    Readonly<
+        Record<Exclude<LinkNamesOf<Catalog, K>, Links>, LinkTarget<RouteId>>
+    >;
 
 /**
  * `[key]` for a message that needs nothing, `[key, params]` otherwise.
@@ -214,25 +241,36 @@ export type RichArgsOf<
     Catalog,
     K extends StringKeys<Catalog>,
     RouteId extends string,
-> = [MessageParamsOf<Catalog, K> | LinkNamesOf<Catalog, K>] extends [never]
+    Links extends string = never,
+    Values extends string = never,
+> = [
+    | Exclude<MessageParamsOf<Catalog, K>, Values>
+    | Exclude<LinkNamesOf<Catalog, K>, Links>,
+] extends [never]
     ? [key: K]
-    : [key: K, params: RichParamsOf<Catalog, K, RouteId>];
+    : [key: K, params: RichParamsOf<Catalog, K, RouteId, Links, Values>];
 
 /**
  * `rich()`, keyed like `t()` and asking for a little more.
  *
  * Generic over the routes as well as the catalog, which is what lets a link
- * slot be typed. `createSite` supplies both.
+ * slot be typed. `createSite` supplies both. `Links` and `Values` name what
+ * was bound when this `rich()` was made, which a call no longer passes.
  */
-export type RichTextFor<Catalog, RouteId extends string> = <
-    K extends StringKeys<Catalog>,
->(
-    ...args: RichArgsOf<Catalog, K, RouteId>
+export type RichTextFor<
+    Catalog,
+    RouteId extends string,
+    Links extends string = never,
+    Values extends string = never,
+> = <K extends StringKeys<Catalog>>(
+    ...args: RichArgsOf<Catalog, K, RouteId, Links, Values>
 ) => RichText;
 
 /** `site.plain()`, keyed and parameterised exactly as `t()` is. */
-export type PlainTextFor<Catalog> = <K extends StringKeys<Catalog>>(
-    ...args: TranslateArgsOf<Catalog, K>
+export type PlainTextFor<Catalog, Values extends string = never> = <
+    K extends StringKeys<Catalog>,
+>(
+    ...args: TranslateArgsOf<Catalog, K, Values>
 ) => string;
 
 /**
@@ -252,11 +290,15 @@ export function createRichText<
     Catalog,
     L extends string,
     RouteId extends string = string,
->(options: RichTextOptions<L>): RichTextFor<Catalog, RouteId> {
-    const { catalog, locale, link, origin } = options;
+    Links extends string = never,
+    Values extends string = never,
+>(
+    options: RichTextOptions<L> & MessageBindings<RouteId, Links, Values>
+): RichTextFor<Catalog, RouteId, Links, Values> {
+    const { catalog, locale, link, origin, links, values } = options;
 
     return <K extends StringKeys<Catalog>>(
-        ...args: RichArgsOf<Catalog, K, RouteId>
+        ...args: RichArgsOf<Catalog, K, RouteId, Links, Values>
     ): RichText => {
         // The conditional tuple cannot be destructured directly; the runtime
         // shape is always `[key]` or `[key, params]`. As in `createTranslate`.
@@ -267,7 +309,7 @@ export function createRichText<
         const template = lookupTemplate(catalog, locale, String(key));
 
         return parseMarks(template, at).map((span) =>
-            resolve(span, at, params, link, origin)
+            resolve(span, at, params, { links, values }, link, origin)
         );
     };
 }
@@ -276,11 +318,15 @@ function resolve(
     span: ParsedSpan,
     at: string,
     params: Readonly<Record<string, string>> | undefined,
+    bound: {
+        readonly links: Readonly<Record<string, string>> | undefined;
+        readonly values: Readonly<Record<string, string>> | undefined;
+    },
     link: LinkResolver,
     origin: HttpsUrl
 ): Span {
     if (span.kind === "break") return span;
-    const text = fill(span.text, at, params);
+    const text = fill(span.text, at, params, bound.values);
 
     switch (span.kind) {
         case "text":
@@ -291,7 +337,7 @@ function resolve(
         case "link":
             return resolveLink(
                 text,
-                targetFor(span.name, at, params),
+                targetFor(span.name, at, params, bound.links),
                 at,
                 link,
                 origin
@@ -315,17 +361,15 @@ function resolve(
 function fill(
     template: string,
     at: string,
-    params: Readonly<Record<string, string>> | undefined
+    params: Readonly<Record<string, string>> | undefined,
+    values: Readonly<Record<string, string>> | undefined
 ): string {
     return render(template, at, (name, whole) => {
-        // `Object.hasOwn` rather than reading the index straight, for the reason
-        // `createRawTranslate` uses it — see there.
-        const value =
-            params !== undefined && Object.hasOwn(params, name)
-                ? params[name]
-                : undefined;
+        const value = valueFor(name, params, values);
         if (value === undefined) {
-            throw new Error(`${at} is missing a value for "${whole}".`);
+            throw new Error(
+                `${at} is missing a value for "${whole}". Pass it, or bind it: { values: { ${name}: "…" } }.`
+            );
         }
         return value;
     });
@@ -346,15 +390,22 @@ function fill(
 function targetFor(
     name: string,
     at: string,
-    params: Readonly<Record<string, string>> | undefined
+    params: Readonly<Record<string, string>> | undefined,
+    links: Readonly<Record<string, string>> | undefined
 ): string {
-    const target =
-        params !== undefined && Object.hasOwn(params, name)
-            ? params[name]
-            : undefined;
+    // The call's own destination first, then one bound for every message.
+    const target = (() => {
+        if (params !== undefined && Object.hasOwn(params, name)) {
+            return params[name];
+        }
+        if (links !== undefined && Object.hasOwn(links, name)) {
+            return links[name];
+        }
+        return undefined;
+    })();
     if (target === undefined) {
         throw new Error(
-            `${at} has no destination for the link slot "[a:${name}]". Pass one: rich(key, { ${name}: "some-route-id" }).`
+            `${at} has no destination for the link slot "[a:${name}]". Pass one: rich(key, { ${name}: "some-route-id" }), or bind it: site.rich(locale, { ${name}: "some-route-id" }).`
         );
     }
     return target;
@@ -558,13 +609,19 @@ function collapse(parts: readonly string[]): string {
  * `RichArgsOf` is `rich()`'s and `TranslateArgsOf` is this one's: what a caller
  * is asked for follows from what comes out.
  */
-export function createPlainText<Catalog, L extends string>(
-    options: RichTextOptions<L>
-): PlainTextFor<Catalog> {
-    const { catalog, locale } = options;
+export function createPlainText<
+    Catalog,
+    L extends string,
+    Values extends string = never,
+>(
+    options: RichTextOptions<L> & {
+        readonly values?: Readonly<Record<Values, string>>;
+    }
+): PlainTextFor<Catalog, Values> {
+    const { catalog, locale, values } = options;
 
     return <K extends StringKeys<Catalog>>(
-        ...args: TranslateArgsOf<Catalog, K>
+        ...args: TranslateArgsOf<Catalog, K, Values>
     ): string => {
         const [key, params] = args as [K, Readonly<Record<string, string>>?];
         const at = `Message "${String(key)}" (${locale})`;
@@ -572,7 +629,9 @@ export function createPlainText<Catalog, L extends string>(
 
         return collapse(
             parseMarks(template, at).map((span) =>
-                span.kind === "break" ? " " : fill(span.text, at, params)
+                span.kind === "break"
+                    ? " "
+                    : fill(span.text, at, params, values)
             )
         );
     };

package/src/i18n/translate.ts

@@ -87,6 +87,12 @@ export type RawTranslate = (
 export interface RawTranslateOptions<L extends string> {
     readonly catalog: MergedCatalog<L>;
     readonly locale: L;
+    /**
+     * Values bound once, for every message this `t()` reads: a placeholder
+     * named here is filled without the call passing it. Checked by the type
+     * that built this; strings by the time they reach the runtime.
+     */
+    readonly values?: Readonly<Record<string, string>>;
 }
 
 /**
@@ -129,7 +135,7 @@ export function lookupTemplate<L extends string>(
 export function createRawTranslate<L extends string>(
     options: RawTranslateOptions<L>
 ): RawTranslate {
-    const { catalog, locale } = options;
+    const { catalog, locale, values } = options;
 
     return (key, params) => {
         const template = lookupTemplate(catalog, locale, key);
@@ -143,13 +149,10 @@ export function createRawTranslate<L extends string>(
                 // pattern above, so `params["__proto__"]` finds `Object.prototype`
                 // on any plain object, is not `undefined`, and would be substituted
                 // into the page as "[object Object]" instead of throwing.
-                const value =
-                    params !== undefined && Object.hasOwn(params, name)
-                        ? params[name]
-                        : undefined;
+                const value = valueFor(name, params, values);
                 if (value === undefined) {
                     throw new Error(
-                        `Message "${key}" (${locale}) is missing a value for "${whole}".`
+                        `Message "${key}" (${locale}) is missing a value for "${whole}". Pass it, or bind it: site.translate(locale, { values: { ${name}: "…" } }).`
                     );
                 }
                 return value;
@@ -158,6 +161,24 @@ export function createRawTranslate<L extends string>(
     };
 }
 
+/**
+ * A placeholder's value: the call's own first, then one bound for every
+ * message. `undefined` when neither has it, for the caller to report.
+ */
+export function valueFor(
+    name: string,
+    params: Readonly<Record<string, string>> | undefined,
+    values: Readonly<Record<string, string>> | undefined
+): string | undefined {
+    if (params !== undefined && Object.hasOwn(params, name)) {
+        return params[name];
+    }
+    if (values !== undefined && Object.hasOwn(values, name)) {
+        return values[name];
+    }
+    return undefined;
+}
+
 /** The `{placeholders}` message `K` needs from the caller. */
 export type MessageParamsOf<
     Catalog,
@@ -165,19 +186,30 @@ export type MessageParamsOf<
 > = EntryPlaceholders<Catalog[K]>;
 
 /**
- * `[key]` for a message with no placeholders, `[key, params]` otherwise.
+ * `[key]` for a message with nothing left to pass, `[key, params]` otherwise.
+ * `Bound` names the placeholders bound when the `t()` was made, which a call
+ * no longer passes.
  *
  * The tuple wrappers around `MessageParamsOf` stop the conditional from
  * distributing, so a union of keys is answered once rather than per member.
  */
-export type TranslateArgsOf<Catalog, K extends StringKeys<Catalog>> = [
-    MessageParamsOf<Catalog, K>,
-] extends [never]
+export type TranslateArgsOf<
+    Catalog,
+    K extends StringKeys<Catalog>,
+    Bound extends string = never,
+> = [Exclude<MessageParamsOf<Catalog, K>, Bound>] extends [never]
     ? [key: K]
-    : [key: K, params: Readonly<Record<MessageParamsOf<Catalog, K>, string>>];
-
-export type TranslateFor<Catalog> = <K extends StringKeys<Catalog>>(
-    ...args: TranslateArgsOf<Catalog, K>
+    : [
+          key: K,
+          params: Readonly<
+              Record<Exclude<MessageParamsOf<Catalog, K>, Bound>, string>
+          >,
+      ];
+
+export type TranslateFor<Catalog, Bound extends string = never> = <
+    K extends StringKeys<Catalog>,
+>(
+    ...args: TranslateArgsOf<Catalog, K, Bound>
 ) => string;
 
 /**
@@ -190,14 +222,19 @@ export type TranslateFor<Catalog> = <K extends StringKeys<Catalog>>(
  * catalog, which only needs to be indexable by key and locale.
  */
 export function createTranslateFactory<Catalog, L extends string>() {
-    return function createTranslate(
+    return function createTranslate<Bound extends string = never>(
         catalog: MergedCatalog<L>,
-        locale: L
-    ): TranslateFor<Catalog> {
-        const raw = createRawTranslate({ catalog, locale });
+        locale: L,
+        values?: Readonly<Record<Bound, string>>
+    ): TranslateFor<Catalog, Bound> {
+        const raw = createRawTranslate({
+            catalog,
+            locale,
+            ...(values === undefined ? {} : { values }),
+        });
 
         function t<K extends StringKeys<Catalog>>(
-            ...args: TranslateArgsOf<Catalog, K>
+            ...args: TranslateArgsOf<Catalog, K, Bound>
         ): string {
             // The conditional tuple cannot be destructured directly; the runtime
             // shape is always `[key]` or `[key, params]`.

package/src/index.ts

@@ -100,6 +100,7 @@ export {
 export {
     html,
     type LinkTarget,
+    type MessageBindings,
     type PlainTextFor,
     plain,
     type RichText,

package/src/site/api.ts

@@ -1,5 +1,9 @@
 import type { ResolvedLocaleMeta } from "../config.ts";
-import type { PlainTextFor, RichTextFor } from "../content/index.ts";
+import type {
+    MessageBindings,
+    PlainTextFor,
+    RichTextFor,
+} from "../content/index.ts";
 import type { GeneratedFile } from "../file.ts";
 import type { PublicFilePath } from "../files.ts";
 import type { Fonts } from "../fonts.ts";
@@ -160,8 +164,14 @@ export interface Site<
      */
     readonly routes: readonly RouteId[];
 
-    /** A locale-bound `t()`. */
-    translate(locale: L): TranslateFor<Catalog>;
+    /**
+     * A locale-bound `t()`. `bind.values` fills those placeholders for every
+     * message, as `rich()`'s does; the rest are still the call's to pass.
+     */
+    translate<const Values extends string = never>(
+        locale: L,
+        bind?: { readonly values?: Readonly<Record<Values, string>> }
+    ): TranslateFor<Catalog, Values>;
 
     /**
      * A locale-bound `rich()`: the same catalog, read as styled runs.
@@ -174,8 +184,21 @@ export interface Site<
      * Bound to a locale here rather than taking one per call, because a link
      * inside the copy resolves to *this* language's path, and a `rich()` that
      * took the locale late would be a second place to get that wrong.
+     *
+     * `bind` fixes link destinations and placeholder values once, for every
+     * message read through it — for a view that renders many messages through
+     * one call: `{ links: { contact: "contact" }, values: { hours } }` lets any
+     * of them write `[a:contact]` or `{hours}` with nothing passed per call.
+     * Bound targets are checked here, as a call's would be; whatever is left
+     * unbound is still required at the call, and a compile error without it.
      */
-    rich(locale: L): RichTextFor<Catalog, RouteId>;
+    rich<
+        const Links extends string = never,
+        const Values extends string = never,
+    >(
+        locale: L,
+        bind?: MessageBindings<RouteId, Links, Values>
+    ): RichTextFor<Catalog, RouteId, Links, Values>;
 
     /**
      * A locale-bound `plain()`: the same catalog, read as words alone.
@@ -191,7 +214,10 @@ export interface Site<
      * does not break the day someone emphasises a clause in the sentence it
      * quotes.
      */
-    plain(locale: L): PlainTextFor<Catalog>;
+    plain<const Values extends string = never>(
+        locale: L,
+        bind?: { readonly values?: Readonly<Record<Values, string>> }
+    ): PlainTextFor<Catalog, Values>;
 
     /** Absolute path of a route in one locale, e.g. `/el/sxetika-me-emas`. */
     pathFor(id: RouteId, locale: L, options?: LinkOptions): UrlPath;

package/src/site/create.ts

@@ -9,6 +9,7 @@ import {
     createPlainText,
     createRichText,
     type LinkResolver,
+    type MessageBindings,
 } from "../content/index.ts";
 import type { GeneratedFile } from "../file.ts";
 import type { PublicFilePath } from "../files.ts";
@@ -836,20 +837,34 @@ export function createSite<
         fonts,
         routes: enabledRouteIds,
 
-        translate: (locale) => translateFactory(catalog, locale),
-        rich: (locale) =>
-            createRichText<Full, L, RouteId>({
+        translate: <const Values extends string = never>(
+            locale: L,
+            bind?: { readonly values?: Readonly<Record<Values, string>> }
+        ) => translateFactory<Values>(catalog, locale, bind?.values),
+        rich: <
+            const Links extends string = never,
+            const Values extends string = never,
+        >(
+            locale: L,
+            bind?: MessageBindings<RouteId, Links, Values>
+        ) =>
+            createRichText<Full, L, RouteId, Links, Values>({
                 catalog,
                 locale,
                 link: richLink(locale),
                 origin: siteUrl,
+                ...bind,
             }),
-        plain: (locale) =>
-            createPlainText<Full, L>({
+        plain: <const Values extends string = never>(
+            locale: L,
+            bind?: { readonly values?: Readonly<Record<Values, string>> }
+        ) =>
+            createPlainText<Full, L, Values>({
                 catalog,
                 locale,
                 link: richLink(locale),
                 origin: siteUrl,
+                ...bind,
             }),
 
         pathFor,