@escape-game-over/atlas 0.1.4 → 0.1.6

package/src/content/marks.ts

@@ -0,0 +1,408 @@
+/**
+ * The parser that turns one message into styled runs.
+ *
+ * The whole reason this file exists rather than a `ContentItem[]` in config:
+ * **a sentence is one message**. The shape this replaces authored a paragraph
+ * as an array of translation keys — `hero.subtitle_text_1` through `_7` — and
+ * concatenated them in the order the array was written. That fixes two things
+ * copy is not allowed to fix. Word order, which differs per language, and the
+ * *number of runs*, which differs more: a clause English spends four fragments
+ * on is one word in Greek, and there is no way to write that in an array whose
+ * length was decided by whoever typed the English. The missing fragments get
+ * padded with empty strings or the spare ones get dropped, and either way the
+ * translator is editing around a data structure instead of writing a sentence.
+ *
+ * So the marks live *in the copy*, where the translator can move them:
+ *
+ * ```ts
+ * "about.intro": {
+ *     "en-US": "Book [v:accent]up to six players[/v] at [a:venue]our venue[/a].",
+ *     "el-GR": "Κλείσε [a:venue]στον χώρο μας[/a] [v:accent]έως έξι παίκτες[/v].",
+ * }
+ *
+ * rich("about.intro", { venue: "contact" })   // the destination, stated once
+ * ```
+ *
+ * One key, one sentence, and each language orders and splits it however it
+ * needs to. What cannot drift is *which* marks a message uses: the same
+ * machinery that holds `{placeholders}` in step across locales sees these too,
+ * so a translation that loses the link fails the build rather than the page.
+ *
+ * This is deliberately a parser and not a `replace` over a pattern, for the
+ * reason `render` in `i18n/translate.ts` is one: a `[` that opens nothing is a
+ * mistake, not an escape hatch, and it is refused here rather than shipped to
+ * a page as literal text. `[[` and `]]` are the escapes, matching `{{` and `}}`
+ * one file over.
+ */
+
+import type { IsName } from "../i18n/placeholders.ts";
+
+/**
+ * One run of a message, still holding its `{placeholders}`.
+ *
+ * The unresolved half of `Span`: a link knows the *name* of the slot it fills
+ * and nothing about where that goes, because copy does not hold addresses —
+ * see `[a:]` below. `rich.ts` finishes the job.
+ */
+export type ParsedSpan =
+    | { readonly kind: "text"; readonly text: string }
+    | { readonly kind: "bold"; readonly text: string }
+    | {
+          readonly kind: "styled";
+          readonly text: string;
+          readonly variant: string;
+      }
+    | {
+          readonly kind: "link";
+          readonly text: string;
+          /** The slot to fill, e.g. `venue` in `[a:venue]`. Never a URL. */
+          readonly name: string;
+      }
+    | { readonly kind: "email"; readonly text: string }
+    | { readonly kind: "phone"; readonly text: string }
+    | { readonly kind: "break" };
+
+/**
+ * The marks, and what each produces.
+ *
+ * Short names because a translator reads past them to the words, and every
+ * character between `[` and `]` is noise in a sentence they are trying to keep
+ * natural. Long enough to guess at from context, which `[b]` and `[a]` are and
+ * `[x]` would not be.
+ *
+ * `bold` is the one presentational mark lib names outright, because it is not
+ * presentational: it is `<strong>`, it survives into plain text as emphasis a
+ * screen reader announces, and 952 of the runs in the data this replaced were
+ * exactly it. Everything else that was a *style* — a colour, a size — is `[v:]`
+ * and carries a name the project's renderer maps. See `Span.variant`.
+ */
+const MARKS = {
+    b: "bold",
+    v: "styled",
+    a: "link",
+    mail: "email",
+    tel: "phone",
+} as const;
+
+type MarkName = keyof typeof MARKS;
+
+/** The marks whose meaning is incomplete without an argument. */
+const NEEDS_ARGUMENT: ReadonlySet<string> = new Set<MarkName>(["v", "a"]);
+
+/** Written `[br]`, closed by nothing, and the only mark that wraps no words. */
+const VOID_MARK = "br";
+
+/**
+ * The type-level half of `MARKS`, kept beside it rather than a file away.
+ *
+ * **Change one and change the other**, exactly as `NAME` and `NameChar` say to
+ * — and deliberately not the way they are arranged. Those two decide the same
+ * thing from opposite ends of the package and drifted apart once, which is the
+ * mistake this avoids by keeping the pair in view of each other. The runtime
+ * table is above; the union is here.
+ */
+type OpenMark = "b" | "br" | "mail" | "tel" | `v:${string}` | `a:${string}`;
+
+type CloseMark = "/b" | "/v" | "/a" | "/mail" | "/tel";
+
+/**
+ * Every mark a template uses, as a union of the literal tokens it spells.
+ *
+ * The counterpart of `Placeholders` in `i18n/placeholders.ts`, and there for
+ * exactly the same failure: a message whose translation quietly lost something
+ * structural. That file's whole subject is a `{name}` dropped from one locale
+ * and rendered as a literal brace; this is a translator dropping `[a:venue]`
+ * and the Greek page losing the link altogether — worse, because nothing is
+ * left on the page to notice.
+ *
+ * **The argument is part of the token, on purpose.** `[a:venue]` and
+ * `[a:booking]` are different tokens, so a translation cannot fill a different
+ * slot from the one the other locales fill, and `[v:accent]` cannot become
+ * `[v:inverse]` in one language. Those are decisions the copy makes once, not
+ * per locale.
+ *
+ * An escaped `[[b]]` asks for nothing, and falls out rather than needing a case:
+ * the candidate inferred from it is `"[b"`, which is not a member of either
+ * union. Same trick `Placeholders` plays on `{{name}}`.
+ *
+ * Multiplicity is not carried — two `[b]` runs and one look alike here — which
+ * is the limit `Placeholders` has with two `{name}`s and is worth the same
+ * trade.
+ */
+export type MarkTokens<S extends string> =
+    S extends `${string}[${infer Token}]${infer Rest}`
+        ?
+              | (Token extends OpenMark | CloseMark ? `[${Token}]` : never)
+              | MarkTokens<Rest>
+        : never;
+
+/** Distributes over the token union, which `MarkTokens<S>` would not do inline. */
+type SlotOfToken<T> = T extends `[a:${infer Name}]`
+    ? IsName<Name> extends true
+        ? Name
+        : never
+    : never;
+
+/**
+ * The link slots a message declares, as a union of their names.
+ *
+ * What `rich()` turns into required arguments: `"See [a:venue]us[/a]"` asks the
+ * call site for `{ venue: … }`, and the type of that value is a `LinkTarget`
+ * over the routes this project actually builds. **That is the whole reason
+ * copy names a slot rather than a destination.** A route id written into a
+ * translation is a string until the day that message renders; written at the
+ * call site it is checked against the route table like every other link in the
+ * package, it is stated once instead of once per language, and an external URL
+ * stays out of the copy a translator is editing.
+ *
+ * Read off `MarkTokens` rather than scanning the template again, which is not a
+ * shortcut: the scan is where an escaped `[[a:x]]` gets correctly ignored, and a
+ * second pattern that skipped straight to `[a:` would find the `x` inside it and
+ * demand an argument for a link that does not exist.
+ */
+export type LinkNames<S extends string> = SlotOfToken<MarkTokens<S>>;
+
+/**
+ * The names a `[a:name]` slot may be spelled with.
+ *
+ * Exactly `NAME` in `i18n/translate.ts`, because a slot name is the same kind
+ * of thing a `{placeholder}` name is: a key the *call site* writes, in
+ * `rich(key, { venue: "contact" })`. A hyphen there forces quoting and reads as
+ * a mistake, so it is not allowed, and `LinkNames` below reuses `IsName` rather
+ * than restating the rule — the two cannot drift because there is one of them.
+ *
+ * A character class rather than a hand-rolled check, for the reason `NAME` is
+ * one. Speed is not the argument either way: both run at build time on a word.
+ */
+const SLOT = /^[a-zA-Z0-9_]+$/;
+
+/**
+ * What may be spelled in a `[v:name]` variant.
+ *
+ * **`SLOT` plus the hyphen, and the difference is the point.** A variant is
+ * never written in TypeScript at all — copy spells it and the renderer looks it
+ * up — and what it usually mirrors is a CSS custom property or a design token,
+ * which are kebab by convention. `[v:on-dark]` is the natural spelling and
+ * `[v:on_dark]` is the one that would have to be explained. A slot name is a
+ * call-site key and a variant is not, so they answer the hyphen differently.
+ */
+const VARIANT = /^[a-zA-Z0-9_-]+$/;
+
+/** The offending mark, quoted, so the error points at something findable. */
+function describeMark(template: string, open: number, close: number): string {
+    const end = close === -1 ? Math.min(open + 20, template.length) : close + 1;
+    return `"${template.slice(open, end)}"`;
+}
+
+/**
+ * Splits a message into runs, and refuses anything malformed.
+ *
+ * `at` names the message and locale, exactly as `render` is given it, so a
+ * failure says which string to go and fix rather than only that one is wrong.
+ *
+ * Marks do not nest. `[b]bold [v:accent]and red[/v][/b]` is refused rather than
+ * flattened, because the resolved span is a single kind and there is nowhere
+ * for the second one to go — a run is bold *or* it carries a variant. The shape
+ * this replaced had the same limit and answered it by inventing a `boldUnderline`
+ * kind, which was used once in fifty-four deployments; a renderer that wants the
+ * combination should give a variant both properties and name it once.
+ */
+export function parseMarks(
+    template: string,
+    at: string
+): readonly ParsedSpan[] {
+    const spans: ParsedSpan[] = [];
+    let text = "";
+    let open:
+        | { readonly name: MarkName; readonly argument: string }
+        | undefined;
+    let openedAt = 0;
+    let index = 0;
+
+    /**
+     * Emits whatever has accumulated, as plain text or as the open mark's run.
+     *
+     * Empty runs are dropped rather than emitted: `[b][/b]` is copy someone
+     * half-deleted, and a span with no words renders an empty element that
+     * still takes up a renderer's `switch`.
+     */
+    function flush(): void {
+        if (text === "") return;
+        spans.push(
+            open === undefined ? { kind: "text", text } : run(open, text)
+        );
+        text = "";
+    }
+
+    function run(
+        mark: { readonly name: MarkName; readonly argument: string },
+        content: string
+    ): ParsedSpan {
+        switch (MARKS[mark.name]) {
+            case "bold":
+                return { kind: "bold", text: content };
+            case "styled":
+                return {
+                    kind: "styled",
+                    text: content,
+                    variant: mark.argument,
+                };
+            case "link":
+                return {
+                    kind: "link",
+                    text: content,
+                    name: mark.argument,
+                };
+            case "email":
+                return { kind: "email", text: content };
+            case "phone":
+                return { kind: "phone", text: content };
+        }
+    }
+
+    while (index < template.length) {
+        const char = template[index] as string;
+
+        if (char === "[" && template[index + 1] === "[") {
+            text += "[";
+            index += 2;
+            continue;
+        }
+        if (char === "]" && template[index + 1] === "]") {
+            text += "]";
+            index += 2;
+            continue;
+        }
+        // A lone `]` stays text, for the reason a lone `}` does in `render`:
+        // only `[` opens anything, so there is nothing an unmatched closer
+        // could be ambiguous about, and refusing it would fail copy that is
+        // merely writing a bracket.
+        if (char !== "[") {
+            text += char;
+            index += 1;
+            continue;
+        }
+
+        const close = template.indexOf("]", index + 1);
+        if (close === -1) {
+            throw new Error(
+                `${at} has a "[" that is never closed: ${describeMark(template, index, close)}. To write a literal bracket, double it: "[[".`
+            );
+        }
+        const inner = template.slice(index + 1, close);
+
+        if (inner.startsWith("/")) {
+            const name = inner.slice(1);
+            if (open === undefined) {
+                throw new Error(
+                    `${at} closes [${name}] without opening it: ${describeMark(template, index, close)}.`
+                );
+            }
+            if (name !== open.name) {
+                throw new Error(
+                    `${at} opens [${open.name}] and closes [${name}]: ${describeMark(template, index, close)}. Marks do not nest, so the one that opens is the one that must close.`
+                );
+            }
+            flush();
+            open = undefined;
+            index = close + 1;
+            continue;
+        }
+
+        if (inner === VOID_MARK) {
+            flush();
+            spans.push({ kind: "break" });
+            index = close + 1;
+            continue;
+        }
+
+        const separator = inner.indexOf(":");
+        const name = separator === -1 ? inner : inner.slice(0, separator);
+        const argument = separator === -1 ? "" : inner.slice(separator + 1);
+
+        if (!Object.hasOwn(MARKS, name)) {
+            throw new Error(
+                `${at} has a "[" that opens neither a mark nor an escape: ${describeMark(template, index, close)}. The marks are ${markList()}. To write a literal bracket, double it: "[[".`
+            );
+        }
+        const mark = name as MarkName;
+
+        if (open !== undefined) {
+            throw new Error(
+                `${at} opens [${mark}] inside [${open.name}]: ${describeMark(template, index, close)}. Marks do not nest — close the first, or give one variant both properties and name it once.`
+            );
+        }
+        if (NEEDS_ARGUMENT.has(mark)) {
+            if (argument === "") {
+                throw new Error(
+                    `${at} has ${describeMark(template, index, close)} with nothing after the colon. ${argumentHint(mark)}`
+                );
+            }
+            if (mark === "v" && !VARIANT.test(argument)) {
+                throw new Error(
+                    `${at} has a variant that is not a name: ${describeMark(template, index, close)}. A variant is letters, digits, hyphens and underscores — it is looked up by the renderer, not printed.`
+                );
+            }
+            // Catches the shape this used to *require*: a route id, a path or a
+            // URL written straight into the copy. Naming it here rather than
+            // letting it through as an odd slot name, because a translation
+            // carried over from the old form fails on the address itself.
+            if (mark === "a" && !SLOT.test(argument)) {
+                throw new Error(
+                    `${at} has a link slot that is not a name: ${describeMark(template, index, close)}. ${argumentHint(mark)}`
+                );
+            }
+        } else if (separator !== -1) {
+            throw new Error(
+                `${at} passes an argument to a mark that takes none: ${describeMark(template, index, close)}. Write "[${mark}]".`
+            );
+        }
+
+        flush();
+        open = { name: mark, argument };
+        openedAt = index;
+        index = close + 1;
+    }
+
+    if (open !== undefined) {
+        throw new Error(
+            `${at} opens [${open.name}] and never closes it: ${describeMark(template, openedAt, template.indexOf("]", openedAt))}. Close it with "[/${open.name}]".`
+        );
+    }
+    flush();
+    return spans;
+}
+
+function markList(): string {
+    return `${Object.keys(MARKS)
+        .map((name) => `[${name}]`)
+        .join(", ")} and [${VOID_MARK}]`;
+}
+
+function argumentHint(mark: MarkName): string {
+    return mark === "a"
+        ? `A link names a slot the call site fills, not an address: write "[a:venue]" and pass rich(key, { venue: "contact" }). Copy holds no route ids or URLs — they belong where the route table can check them, and where they are written once rather than once per language.`
+        : `A variant names a style the renderer knows, e.g. "[v:accent]".`;
+}
+
+/**
+ * Refuses a message that carries marks, for the callers that can only print it.
+ *
+ * The parser runs rather than a pattern, so a malformed mark fails here with
+ * the same error it would fail with anywhere else — `"[b]bold"` is a mistake
+ * whichever function reads it, and swallowing that to answer a yes-or-no
+ * question would leave `t()` printing the bracket it was written to refuse.
+ *
+ * `"Open [Mon-Fri]"` passes: that is a bracket nobody meant as a mark, `Mon-Fri`
+ * is not one of the five, and the parser has already said so.
+ */
+export function assertNoMarks(template: string, at: string): void {
+    const marked = parseMarks(template, at).some(
+        (span) => span.kind !== "text"
+    );
+    if (marked) {
+        throw new Error(
+            `${at} carries marks, and t() can only print them. Read it with rich(), or with plain(rich(…)) for the words alone.`
+        );
+    }
+}