@escape-game-over/atlas 0.1.4 → 0.1.6

package/src/content/rich.ts

@@ -0,0 +1,550 @@
+import {
+    e164Of,
+    isEmailAddress,
+    type MailtoUrl,
+    mailtoHref,
+    type TelUrl,
+} from "../contact.ts";
+import type { TextOf } from "../i18n/placeholders.ts";
+import type { MessageParamsOf, TranslateArgsOf } from "../i18n/translate.ts";
+import {
+    lookupTemplate,
+    type MergedCatalog,
+    render,
+} from "../i18n/translate.ts";
+import type { StringKeys } from "../types.ts";
+import {
+    type Hash,
+    type HttpsUrl,
+    isHash,
+    isHttpsUrl,
+    isUrlPath,
+    joinUrl,
+    type UrlPath,
+} from "../url.ts";
+import { type LinkNames, type ParsedSpan, parseMarks } from "./marks.ts";
+
+/**
+ * Copy resolved into styled runs: what a renderer is handed, and the only shape
+ * it ever sees.
+ *
+ * Every string here is finished — translated, placeholders filled — and every
+ * link is a URL rather than something that still needs a route table. That is
+ * the seam: lib owns which runs exist and what they say, the project owns what
+ * they look like. A renderer is a `switch` over `kind` and nothing else, so
+ * adding a run type is a compile error at every renderer rather than a silent
+ * gap. The shape this replaces answered an unknown kind with a runtime `throw`
+ * and a `default: return null`, which is the same mistake made twice.
+ */
+export type Span =
+    | { readonly kind: "text"; readonly text: string }
+    /** `<strong>`. Emphasis a screen reader announces, not a font weight. */
+    | { readonly kind: "bold"; readonly text: string }
+    /**
+     * A run the project styles, named by the copy and mapped by the renderer.
+     *
+     * The escape hatch that keeps presentation out of lib, and out of content.
+     * The data this replaced wrote a CSS value into every run — 419 copies of
+     * one brand variable, 144 of `white`, and a dozen stragglers spelling the
+     * same red four different ways. Those are two *roles* wearing a colour's
+     * clothes, and a role is what a variant names: `accent`, `inverse`, `small`.
+     * The renderer holds one map from those to classes, so restyling is one
+     * edit rather than a sweep through fifty-four deployments' copy.
+     */
+    | {
+          readonly kind: "styled";
+          readonly text: string;
+          readonly variant: string;
+      }
+    /**
+     * A link, in the three shapes a destination actually comes in.
+     *
+     * **A union rather than an optional `url` and an `external` flag**, for the
+     * reason `PageKind` is one: those two fields could disagree, and `external:
+     * true` with no absolute URL is a state that means nothing and would still
+     * type-check. Here the discriminant *is* the answer — a consumer that needs
+     * an absolute URL narrows on `to` and gets one, or is told plainly that this
+     * destination has none and why.
+     *
+     * Both forms are carried where both exist, for the reason `Crumb` carries
+     * both: a link in the page wants the path, because an absolute one sends a
+     * developer from localhost to the production host mid-click, while
+     * structured data and anything else without a document around it requires
+     * the absolute URL.
+     */
+    | {
+          readonly kind: "link";
+          readonly text: string;
+          /** A page on this site. Root-relative, and absolute alongside it. */
+          readonly to: "internal";
+          readonly href: UrlPath;
+          readonly url: HttpsUrl;
+      }
+    | {
+          readonly kind: "link";
+          readonly text: string;
+          /** Somewhere else. Already absolute, so both forms are one string. */
+          readonly to: "external";
+          readonly href: HttpsUrl;
+          readonly url: HttpsUrl;
+      }
+    | {
+          readonly kind: "link";
+          readonly text: string;
+          /**
+           * An element of whatever page this is rendered on.
+           *
+           * **No `url`, and that is not a gap.** `rich()` is given a locale, not
+           * a route, so it does not know the page a fragment belongs to — and an
+           * absolute URL invented here would point somewhere real and wrong. A
+           * caller that has the page can build one: `joinUrl(site.urlFor(id,
+           * locale), href)`.
+           */
+          readonly to: "anchor";
+          readonly href: Hash;
+      }
+    | {
+          readonly kind: "email";
+          readonly text: string;
+          readonly href: MailtoUrl;
+      }
+    | {
+          readonly kind: "phone";
+          readonly text: string;
+          readonly href: TelUrl;
+      }
+    | { readonly kind: "break" };
+
+/** A paragraph, as runs. */
+export type RichText = readonly Span[];
+
+/**
+ * What a `[a:slot]` may be filled with, told apart by its first character.
+ *
+ * Four things, one field, because they are already distinguishable and a tagged
+ * object would make the call site state twice what it says once. `#` scrolls,
+ * `/` is a path on this origin, `https://` leaves the site, and anything else is
+ * a route id — which is the form to prefer, because only that one survives a
+ * slug being retranslated or a page moving. Same rule as `redirects()`: a target
+ * names a route, not a URL.
+ *
+ * **This is why the destination is an argument and not part of the copy.**
+ * `RouteId` here is the caller's union of routes the project actually builds, so
+ * `{ venue: "contct" }` is a compile error on the line that wrote it — and a
+ * route the project has switched off is refused just as flatly. Spelled into a
+ * translation instead, it was an unchecked string until the day that message
+ * rendered, repeated once per language, and sitting in a file whose reviewers
+ * are translators rather than developers.
+ */
+export type LinkTarget<RouteId extends string> =
+    | RouteId
+    /**
+     * A route id and a fragment on it: `"challenges#booking"`.
+     *
+     * Here because a bare `#booking` means *this* page, so without it there was
+     * no way to point at a section of another one without dropping to a raw
+     * path — and a raw path is the one form the route table cannot check. The
+     * fragment is appended by `pathFor`, the same way `LinkOptions.hash` is
+     * everywhere else, so it lands after the page number and the query rather
+     * than being concatenated on by this module.
+     */
+    | `${RouteId}#${string}`
+    | UrlPath
+    | HttpsUrl
+    | Hash;
+
+/**
+ * Resolves a route id, and any fragment on it, to this locale's path.
+ *
+ * Supplied by `createSite`. `hash` comes without its `#`, matching
+ * `LinkOptions.hash`, which is what ultimately consumes it.
+ */
+export type LinkResolver = (
+    routeId: string,
+    at: string,
+    hash?: string
+) => UrlPath;
+
+export interface RichTextOptions<L extends string> {
+    readonly catalog: MergedCatalog<L>;
+    readonly locale: L;
+    readonly link: LinkResolver;
+    /**
+     * This deployment's origin, for the absolute half of a link.
+     *
+     * Taken here rather than left to each consumer to prepend, because a
+     * consumer that joins an origin to a path by hand is the one that produces
+     * `https://example.com/about` on a good day and `https://example.com//about`
+     * on a bad one. `joinUrl` already answers it once.
+     */
+    readonly origin: HttpsUrl;
+}
+
+/** The link slots message `K` declares, e.g. `"venue"` from `[a:venue]`. */
+export type LinkNamesOf<Catalog, K extends keyof Catalog> = LinkNames<
+    TextOf<Catalog[K]>
+>;
+
+/**
+ * What `rich()` asks for: a string per `{placeholder}`, a destination per
+ * `[a:slot]`.
+ *
+ * One object with two kinds of value in it, rather than two parameters, because
+ * a call site does not think of them differently — both are things the sentence
+ * needs and the catalog cannot know. The types differ where it matters:
+ * a placeholder takes any string, and a slot takes a `LinkTarget`, so a route
+ * this project does not build is a compile error at the line that wrote it.
+ */
+export type RichParamsOf<
+    Catalog,
+    K extends StringKeys<Catalog>,
+    RouteId extends string,
+> = Readonly<Record<MessageParamsOf<Catalog, K>, string>> &
+    Readonly<Record<LinkNamesOf<Catalog, K>, LinkTarget<RouteId>>>;
+
+/**
+ * `[key]` for a message that needs nothing, `[key, params]` otherwise.
+ *
+ * The mirror of `TranslateArgsOf`, extended with the slots — and the tuple
+ * wrappers do the same job there: they stop the conditional distributing, so a
+ * union of keys is answered once rather than per member.
+ */
+export type RichArgsOf<
+    Catalog,
+    K extends StringKeys<Catalog>,
+    RouteId extends string,
+> = [MessageParamsOf<Catalog, K> | LinkNamesOf<Catalog, K>] extends [never]
+    ? [key: K]
+    : [key: K, params: RichParamsOf<Catalog, K, RouteId>];
+
+/**
+ * `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.
+ */
+export type RichTextFor<Catalog, RouteId extends string> = <
+    K extends StringKeys<Catalog>,
+>(
+    ...args: RichArgsOf<Catalog, K, RouteId>
+) => RichText;
+
+/** `plain()`, keyed and parameterised exactly as `t()` is. */
+export type PlainTextFor<Catalog> = <K extends StringKeys<Catalog>>(
+    ...args: TranslateArgsOf<Catalog, K>
+) => string;
+
+/**
+ * Builds the runtime half of `rich()`.
+ *
+ * **Marks are parsed before placeholders are substituted, and that order is
+ * load-bearing.** A value arriving from config — a venue name, a price, a phone
+ * number — is data, not copy, and data that could open a mark would be a
+ * project injecting styling into its own sentences by accident. Parsing first
+ * means `{phone}` can hold anything at all and still lands as text.
+ *
+ * It also means a mark can wrap a placeholder, which is the case that motivated
+ * it: `"Call us on [tel]{phone}[/tel]"` keeps the number in config where it
+ * belongs and still gets a `tel:` link, without copy ever spelling the digits.
+ */
+export function createRichText<
+    Catalog,
+    L extends string,
+    RouteId extends string = string,
+>(options: RichTextOptions<L>): RichTextFor<Catalog, RouteId> {
+    const { catalog, locale, link, origin } = options;
+
+    return <K extends StringKeys<Catalog>>(
+        ...args: RichArgsOf<Catalog, K, RouteId>
+    ): RichText => {
+        // The conditional tuple cannot be destructured directly; the runtime
+        // shape is always `[key]` or `[key, params]`. As in `createTranslate`.
+        // Placeholder values and link targets are both strings once here — the
+        // distinction they are worth making is entirely a compile-time one.
+        const [key, params] = args as [K, Readonly<Record<string, string>>?];
+        const at = `Message "${String(key)}" (${locale})`;
+        const template = lookupTemplate(catalog, locale, String(key));
+
+        return parseMarks(template, at).map((span) =>
+            resolve(span, at, params, link, origin)
+        );
+    };
+}
+
+function resolve(
+    span: ParsedSpan,
+    at: string,
+    params: Readonly<Record<string, string>> | undefined,
+    link: LinkResolver,
+    origin: HttpsUrl
+): Span {
+    if (span.kind === "break") return span;
+    const text = fill(span.text, at, params);
+
+    switch (span.kind) {
+        case "text":
+        case "bold":
+            return { kind: span.kind, text };
+        case "styled":
+            return { kind: "styled", text, variant: span.variant };
+        case "link":
+            return resolveLink(
+                text,
+                targetFor(span.name, at, params),
+                at,
+                link,
+                origin
+            );
+        case "email":
+            return { kind: "email", text, href: mailto(text, at) };
+        case "phone":
+            return { kind: "phone", text, href: tel(text, at) };
+    }
+}
+
+/**
+ * Substitutes `{placeholders}` into one run's text.
+ *
+ * Per run rather than over the whole template, which is what makes a mark able
+ * to wrap a placeholder: the marks are already gone by the time this sees the
+ * text, so a value can hold anything at all — including a `[` — and still lands
+ * as words. Shared by `rich()` and `plain()` so both fill a message the same
+ * way, and both refuse an unfilled brace rather than shipping it to a page.
+ */
+function fill(
+    template: string,
+    at: string,
+    params: 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;
+        if (value === undefined) {
+            throw new Error(`${at} is missing a value for "${whole}".`);
+        }
+        return value;
+    });
+}
+
+/**
+ * The destination a slot was filled with.
+ *
+ * `Object.hasOwn` rather than reading the index straight, for the reason
+ * `createRawTranslate` uses it: `__proto__` is a legal slot name by `SLOT`, so
+ * a plain object would answer with `Object.prototype` — not `undefined`, and so
+ * not caught below.
+ *
+ * The type already demands this, and it is checked anyway for the case the type
+ * cannot see: a key that arrived as a plain `string`. Same division of labour
+ * as an unfilled `{placeholder}`.
+ */
+function targetFor(
+    name: string,
+    at: string,
+    params: Readonly<Record<string, string>> | undefined
+): string {
+    const target =
+        params !== undefined && Object.hasOwn(params, name)
+            ? params[name]
+            : 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" }).`
+        );
+    }
+    return target;
+}
+
+function resolveLink(
+    text: string,
+    target: string,
+    at: string,
+    link: LinkResolver,
+    origin: HttpsUrl
+): Span {
+    if (isHash(target)) {
+        return { kind: "link", text, to: "anchor", href: target };
+    }
+    // `external` by the shape it was written in rather than by comparing hosts:
+    // a project may well link to a sibling deployment on its own domain, and
+    // that is still leaving this site — a different build, a different bundle,
+    // and a `target`/`rel` decision the renderer should get to make.
+    if (isHttpsUrl(target)) {
+        return {
+            kind: "link",
+            text,
+            to: "external",
+            href: target,
+            url: target,
+        };
+    }
+    // Refused rather than passed through, for the reason `absoluteUrl` refuses
+    // it: an `http://` link is a downgrade browsers increasingly decline to
+    // follow, and it looks exactly like a working one until someone clicks.
+    if (target.startsWith("http://")) {
+        throw new Error(
+            `${at} links to "${target}". An http:// link is a downgrade — write it as https://.`
+        );
+    }
+    // A raw path is taken as written, fragment and all — it is the escape hatch
+    // for a URL this project does not own a route for, and lib has nothing to
+    // check it against.
+    if (isUrlPath(target)) {
+        return {
+            kind: "link",
+            text,
+            to: "internal",
+            href: target,
+            url: joinUrl(origin, target),
+        };
+    }
+
+    // Everything left is a route id, optionally with a fragment on it. Split at
+    // the first `#`: a fragment cannot contain one, so anything after the second
+    // would be part of the fragment rather than a second cut.
+    const cut = target.indexOf("#");
+    const routeId = cut === -1 ? target : target.slice(0, cut);
+    const hash = cut === -1 ? undefined : target.slice(cut + 1);
+
+    // `"contact#"` is a link to the top of a page written as though it were a
+    // link to something on it. Refused rather than resolved to a bare `#`,
+    // which is what the copy would have got and not what it asked for.
+    if (hash === "") {
+        throw new Error(
+            `${at} links to "${target}", which names a fragment and then does not say which. Drop the "#" to link to the page.`
+        );
+    }
+
+    const path = link(routeId, at, hash);
+    return {
+        kind: "link",
+        text,
+        to: "internal",
+        href: path,
+        url: joinUrl(origin, path),
+    };
+}
+
+/**
+ * The `mailto:` for an address written in copy.
+ *
+ * `isEmailAddress` and `mailtoHref` rather than a check and a template here:
+ * what counts as an address, and what scheme it gets, are already decided in
+ * `contact.ts` — and a second opinion about either is a second opinion that
+ * eventually differs. The guard is what lets `mailtoHref` be called at all: an
+ * address arriving out of a message is a `string`, and casting past that would
+ * assert exactly the thing worth testing.
+ *
+ * The failure it catches is the one nobody notices, because the link still
+ * works: a `mailto:` with nothing in the To: field opens a mail client, and the
+ * message goes nowhere.
+ */
+function mailto(text: string, at: string): MailtoUrl {
+    if (!isEmailAddress(text)) {
+        throw new Error(
+            `${at} marks "${text}" as an email address, and it has no "@".`
+        );
+    }
+    return mailtoHref(text);
+}
+
+/**
+ * The `tel:` for a number written in copy.
+ *
+ * `e164Of` holds the rule — only punctuation goes, no leading zero is touched —
+ * beside `e164`, which answers the same question for a structured
+ * `PhoneNumber`. See it for why that zero is not lib's to strip.
+ *
+ * What stays here is the wording of the failure, because only this side knows
+ * the number came out of a *message* and can say which one to go and fix.
+ */
+function tel(text: string, at: string): TelUrl {
+    const dialled = e164Of(text);
+    if (dialled === undefined) {
+        throw new Error(
+            `${at} marks "${text}" as a phone number, and it is not in international form. Write it with a country code, e.g. "+30 210 0000000" — a local number does not dial from abroad.`
+        );
+    }
+    return `tel:${dialled}`;
+}
+
+/**
+ * The words alone, for everywhere that takes a string rather than markup.
+ *
+ * The reason this whole module sits in lib rather than in each project. A meta
+ * description, an `llms.txt` summary and a structured-data `description` all
+ * want the same sentence the page renders, and every one of them takes a plain
+ * string — so without this each project flattens the runs by hand, and they
+ * drift. The implementation this replaces did exactly that: a chain of `if`s
+ * per kind, `return ""` for the ones it could not render, and a `throw` on
+ * anything it had not been taught.
+ *
+ * A `[br]` becomes a space, because that is what it is once the markup is gone,
+ * and runs of whitespace collapse — copy split across a line break otherwise
+ * arrives with a double space in the middle of a `<meta>` tag.
+ */
+export function plain(rich: RichText): string {
+    return collapse(
+        rich.map((span) => (span.kind === "break" ? " " : span.text))
+    );
+}
+
+/**
+ * Runs of whitespace become one, and the ends are trimmed.
+ *
+ * Copy split across a `[br]` otherwise arrives with a double space in the
+ * middle of a `<meta>` tag, which is the sort of thing nobody notices until it
+ * is quoted back in a search result.
+ */
+function collapse(parts: readonly string[]): string {
+    return parts.join("").replace(/\s+/g, " ").trim();
+}
+
+/**
+ * The same, straight from a message key — `plain(rich(…))` without the nesting.
+ *
+ * Which sounds like sugar and is mostly about where it gets used. The callers
+ * that want words rather than runs are the ones furthest from a renderer:
+ * `llms()`'s `describe`, a `<meta name="description">`, a structured-data
+ * `description`. Those are already assembling several strings at once, and
+ * `plain(rich("about.intro", { company }))` reads as two operations there when
+ * it is one question — what does this message say.
+ *
+ * It also answers that question for a message with no marks at all, which `t()`
+ * would too. That overlap is deliberate: a description built this way keeps
+ * working on the day someone adds emphasis to the sentence, where `t()` would
+ * start throwing. Reach for `t()` when the copy is structurally plain and
+ * should stay that way — a button label, an `aria-label` — and for this when
+ * the answer is prose.
+ *
+ * **It asks for `{placeholders}` and not for link destinations**, which is why
+ * it resolves the message itself rather than calling `rich()` and flattening.
+ * A `tel:` this discards is not worth building, and a route id it discards is
+ * not worth demanding — `llms.txt` would otherwise have to name a destination
+ * for every link in every description in order to throw them all away. So
+ * `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;
+
+    return <K extends StringKeys<Catalog>>(
+        ...args: TranslateArgsOf<Catalog, K>
+    ): string => {
+        const [key, params] = args as [K, Readonly<Record<string, string>>?];
+        const at = `Message "${String(key)}" (${locale})`;
+        const template = lookupTemplate(catalog, locale, String(key));
+
+        return collapse(
+            parseMarks(template, at).map((span) =>
+                span.kind === "break" ? " " : fill(span.text, at, params)
+            )
+        );
+    };
+}