@escape-game-over/atlas 0.1.96 → 0.1.97

package/docs/rich-text.md

@@ -167,6 +167,34 @@ 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 a slot once
+
+A view that renders many messages through one call — a FAQ page reading every
+answer in a loop — cannot pass a slot to some messages and not others: a
+message that declares no slot refuses the argument, and one that does demands
+it. Bind the slots when the `rich()` is made instead:
+
+```ts
+const rich = site.rich(locale, { contact: "contact", rooms: "rooms" });
+
+rich("faq.hours.a"); // "…on our [a:contact]Contact page[/a]." needs nothing more
+rich("faq.age.a"); // no slots, still no argument
+```
+
+Nothing is loosened:
+
+- **A bound destination is checked where it is bound**, against the routes this
+  project builds, as a call's would be.
+- **A slot 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 answers fails to compile if one answer names a slot nobody bound.
+- **A call's own destination wins** over a bound one, should it pass the same
+  slot; the type does not offer a bound slot to the call, so this only matters
+  for a key that arrived as a plain `string`.
+
+Copy still names a slot, never an address. Binding moves where the destination
+is written — to the one place that renders the copy — not into the copy.
+
 ## What the compiler holds in step
 
 Which marks a message uses is checked across locales by the same machinery that
@@ -266,7 +294,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.97",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,

package/src/content/rich.ts

@@ -179,6 +179,12 @@ 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>>;
 }
 
 /** The link slots message `K` declares, e.g. `"venue"` from `[a:venue]`. */
@@ -200,8 +206,11 @@ export type RichParamsOf<
     Catalog,
     K extends StringKeys<Catalog>,
     RouteId extends string,
+    Bound extends string = never,
 > = Readonly<Record<MessageParamsOf<Catalog, K>, string>> &
-    Readonly<Record<LinkNamesOf<Catalog, K>, LinkTarget<RouteId>>>;
+    Readonly<
+        Record<Exclude<LinkNamesOf<Catalog, K>, Bound>, LinkTarget<RouteId>>
+    >;
 
 /**
  * `[key]` for a message that needs nothing, `[key, params]` otherwise.
@@ -214,20 +223,26 @@ export type RichArgsOf<
     Catalog,
     K extends StringKeys<Catalog>,
     RouteId extends string,
-> = [MessageParamsOf<Catalog, K> | LinkNamesOf<Catalog, K>] extends [never]
+    Bound extends string = never,
+> = [
+    MessageParamsOf<Catalog, K> | Exclude<LinkNamesOf<Catalog, K>, Bound>,
+] extends [never]
     ? [key: K]
-    : [key: K, params: RichParamsOf<Catalog, K, RouteId>];
+    : [key: K, params: RichParamsOf<Catalog, K, RouteId, Bound>];
 
 /**
  * `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. `Bound` names the slots 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,
+    Bound extends string = never,
+> = <K extends StringKeys<Catalog>>(
+    ...args: RichArgsOf<Catalog, K, RouteId, Bound>
 ) => RichText;
 
 /** `site.plain()`, keyed and parameterised exactly as `t()` is. */
@@ -252,11 +267,16 @@ export function createRichText<
     Catalog,
     L extends string,
     RouteId extends string = string,
->(options: RichTextOptions<L>): RichTextFor<Catalog, RouteId> {
-    const { catalog, locale, link, origin } = options;
+    Bound extends string = never,
+>(
+    options: RichTextOptions<L> & {
+        readonly links?: Readonly<Record<Bound, LinkTarget<RouteId>>>;
+    }
+): RichTextFor<Catalog, RouteId, Bound> {
+    const { catalog, locale, link, origin, links } = options;
 
     return <K extends StringKeys<Catalog>>(
-        ...args: RichArgsOf<Catalog, K, RouteId>
+        ...args: RichArgsOf<Catalog, K, RouteId, Bound>
     ): RichText => {
         // The conditional tuple cannot be destructured directly; the runtime
         // shape is always `[key]` or `[key, params]`. As in `createTranslate`.
@@ -267,7 +287,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, link, origin)
         );
     };
 }
@@ -276,6 +296,7 @@ function resolve(
     span: ParsedSpan,
     at: string,
     params: Readonly<Record<string, string>> | undefined,
+    links: Readonly<Record<string, string>> | undefined,
     link: LinkResolver,
     origin: HttpsUrl
 ): Span {
@@ -291,7 +312,7 @@ function resolve(
         case "link":
             return resolveLink(
                 text,
-                targetFor(span.name, at, params),
+                targetFor(span.name, at, params, links),
                 at,
                 link,
                 origin
@@ -346,15 +367,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;

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 {
+    LinkTarget,
+    PlainTextFor,
+    RichTextFor,
+} from "../content/index.ts";
 import type { GeneratedFile } from "../file.ts";
 import type { PublicFilePath } from "../files.ts";
 import type { Fonts } from "../fonts.ts";
@@ -174,8 +178,17 @@ 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.
+     *
+     * `links` binds slots once for every message read through it, for a view
+     * that renders many messages through one call: `{ contact: "contact" }`
+     * lets any of them write `[a:contact]` with nothing passed per call. The
+     * targets are checked here, as a call's would be; a slot left unbound is
+     * still required at the call, and still a compile error without it.
      */
-    rich(locale: L): RichTextFor<Catalog, RouteId>;
+    rich<const Bound extends string = never>(
+        locale: L,
+        links?: Readonly<Record<Bound, LinkTarget<RouteId>>>
+    ): RichTextFor<Catalog, RouteId, Bound>;
 
     /**
      * A locale-bound `plain()`: the same catalog, read as words alone.

package/src/site/create.ts

@@ -9,6 +9,7 @@ import {
     createPlainText,
     createRichText,
     type LinkResolver,
+    type LinkTarget,
 } from "../content/index.ts";
 import type { GeneratedFile } from "../file.ts";
 import type { PublicFilePath } from "../files.ts";
@@ -837,12 +838,16 @@ export function createSite<
         routes: enabledRouteIds,
 
         translate: (locale) => translateFactory(catalog, locale),
-        rich: (locale) =>
-            createRichText<Full, L, RouteId>({
+        rich: <const Bound extends string = never>(
+            locale: L,
+            links?: Readonly<Record<Bound, LinkTarget<RouteId>>>
+        ) =>
+            createRichText<Full, L, RouteId, Bound>({
                 catalog,
                 locale,
                 link: richLink(locale),
                 origin: siteUrl,
+                ...(links === undefined ? {} : { links }),
             }),
         plain: (locale) =>
             createPlainText<Full, L>({