@escape-game-over/atlas 0.1.95 → 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
@@ -253,7 +281,7 @@ per `[v:name]` and one for links — usually in a small wrapper
 ```
 
 A `[tel]` link renders with `dir="ltr"`: a number has no letters to set its
-direction, and on a right-to-left page it would otherwise read "2227 0244 965+".
+direction, and on a right-to-left page it would otherwise read "0100 555 202 1+".
 A number on its own, outside copy, is `@escape-game-over/atlas/astro/phone`.
 
 `attrs` puts attributes on a variant's run, so a script can find it and rewrite
@@ -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.95",
+    "version": "0.1.97",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,

package/src/astro/Phone.astro

@@ -6,8 +6,8 @@
  * <a href={telHref(phone)}><Phone phone={phone} /></a>
  * ```
  *
- * "+965 2227 0244" has no letters to set its direction, so on an Arabic page
- * the browser would lay it out right to left and show "2227 0244 965+". Its own
+ * "+1 202 555 0100" has no letters to set its direction, so on an Arabic page
+ * the browser would lay it out right to left and show "0100 555 202 1+". Its own
  * element with `dir="ltr"` keeps it whole, the way the page expects a number
  * to read, and copies as just the number. An email needs none of this: its
  * letters already make it read left to right.

package/src/astro/RichText.astro

@@ -82,7 +82,7 @@ const variantAttrs = (variant: string) =>
                 </a>
             );
         // A number has no letters to set its direction; on a right-to-left
-        // page it would read "2227 0244 965+". See `Phone.astro`.
+        // page it would read "0100 555 202 1+". See `Phone.astro`.
         case "tel":
             return (
                 <a

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/jsonld/business.ts

@@ -15,8 +15,17 @@ import { geoCoordinates, openingHours, postalAddress } from "./place.ts";
 
 export interface LocalBusinessInput {
     readonly name: string;
-    /** The site's own origin. Also the node's identity, see `@id` below. */
+    /**
+     * The page about it: the site, or one location's page on a site with
+     * several. Its origin carries the node's identity, see `@id` below.
+     */
     readonly url: HttpsUrl;
+    /**
+     * Which of the site's businesses this is, on a site with several: `north`
+     * makes the `@id` `<origin>#business-north`. Point at it with
+     * `businessId(url, location)`.
+     */
+    readonly location?: string;
     readonly address: PostalAddress;
     /**
      * Another name this venue actually goes by.
@@ -162,7 +171,7 @@ export interface LocalBusinessInput {
 export function localBusiness(business: LocalBusinessInput): JsonLdNode {
     return {
         "@type": schemaType(business.type ?? "LocalBusiness"),
-        "@id": businessId(business.url),
+        "@id": businessId(business.url, business.location),
         name: business.name,
         ...alternateName(business.name, business.alternateName),
         url: business.url,

package/src/jsonld/ids.ts

@@ -1,4 +1,4 @@
-import { type HttpsUrl, normalizeOrigin } from "../url.ts";
+import { type HttpsUrl, isHttpsUrl, normalizeOrigin } from "../url.ts";
 
 /**
  * The `@id` each addressable node takes, and the types that keep them apart.
@@ -43,7 +43,9 @@ import { type HttpsUrl, normalizeOrigin } from "../url.ts";
  * -checks, while the mistake this exists to stop — passing a bare URL where a
  * reference belongs — does not.
  */
-export type BusinessId = `${HttpsUrl}#business`;
+export type BusinessId =
+    | `${HttpsUrl}#business`
+    | `${HttpsUrl}#business-${string}`;
 
 /** The identity of a brand node. See `BusinessId`. */
 export type OrganizationId = `${HttpsUrl}#organization`;
@@ -68,15 +70,25 @@ export type WebsiteId = `${HttpsUrl}#website`;
 export type ServiceId = `${HttpsUrl}#service`;
 
 /**
- * The `@id` a business node takes, from the site's origin.
+ * The `@id` a business node takes: on the origin of `url`, whichever page of
+ * the site that is.
  *
  * Exported because a reference has to be built by whoever points at it, and the
  * fragment must match exactly — a node linking to `#local-business` when the
  * business calls itself `#business` is a dangling reference that no validator
  * reports and no crawler resolves. One definition, used by both ends.
+ *
+ * A site with several businesses — one per location — names each:
+ * `businessId(origin, "north")` is `<origin>#business-north`.
+ * Without a name they would all be `#business`, and a crawler merges nodes
+ * that share an id, so the locations would read as one place.
  */
-export function businessId(url: HttpsUrl): BusinessId {
-    return `${normalizeOrigin(url)}#business`;
+export function businessId(url: HttpsUrl, location?: string): BusinessId {
+    const origin = new URL(url).origin;
+    if (!isHttpsUrl(origin)) throw new Error(`"${url}" has no https origin.`);
+    return location === undefined
+        ? `${origin}#business`
+        : `${origin}#business-${location}`;
 }
 
 /** The `@id` a brand node takes. See `businessId`. */

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>({