@escape-game-over/atlas 0.1.4 → 0.1.6

package/src/countries.ts

@@ -0,0 +1,314 @@
+/**
+ * Every country a form can offer, as ISO 3166-1 alpha-2.
+ *
+ * Codes rather than names, which is the point on a multilingual site:
+ * `countriesFor` turns each one into the reader's own word for it and sorts
+ * them the way that language sorts. A list of English names would put "Czech
+ * Republic" in front of a Romanian reader and file it under C.
+ *
+ * The code is also what a form should submit, so an enquiry from Germany files
+ * the same whether it was picked as "Deutschland" or "Germany".
+ *
+ * Derived from ICU's region list rather than typed out: every two-letter code
+ * it answers to, less the withdrawn and transitional reservations it still
+ * knows (`SU`, `YU`, `DD`, `ZR`, `AN`, `UK`…) and the aggregates that are not
+ * countries (`EU`, `UN`, `QO`…). 250 entries: the 249 ISO assigns, plus `XK`
+ * for Kosovo, which is user-assigned and in common use.
+ *
+ * **This is a list, not a policy.** It says which codes are well-formed, not
+ * which countries a business will trade with — that is a per-project answer and
+ * belongs in the project, by filtering this.
+ */
+export const COUNTRY_CODES = [
+    "AD",
+    "AE",
+    "AF",
+    "AG",
+    "AI",
+    "AL",
+    "AM",
+    "AO",
+    "AQ",
+    "AR",
+    "AS",
+    "AT",
+    "AU",
+    "AW",
+    "AX",
+    "AZ",
+    "BA",
+    "BB",
+    "BD",
+    "BE",
+    "BF",
+    "BG",
+    "BH",
+    "BI",
+    "BJ",
+    "BL",
+    "BM",
+    "BN",
+    "BO",
+    "BQ",
+    "BR",
+    "BS",
+    "BT",
+    "BV",
+    "BW",
+    "BY",
+    "BZ",
+    "CA",
+    "CC",
+    "CD",
+    "CF",
+    "CG",
+    "CH",
+    "CI",
+    "CK",
+    "CL",
+    "CM",
+    "CN",
+    "CO",
+    "CR",
+    "CU",
+    "CV",
+    "CW",
+    "CX",
+    "CY",
+    "CZ",
+    "DE",
+    "DJ",
+    "DK",
+    "DM",
+    "DO",
+    "DZ",
+    "EC",
+    "EE",
+    "EG",
+    "EH",
+    "ER",
+    "ES",
+    "ET",
+    "FI",
+    "FJ",
+    "FK",
+    "FM",
+    "FO",
+    "FR",
+    "GA",
+    "GB",
+    "GD",
+    "GE",
+    "GF",
+    "GG",
+    "GH",
+    "GI",
+    "GL",
+    "GM",
+    "GN",
+    "GP",
+    "GQ",
+    "GR",
+    "GS",
+    "GT",
+    "GU",
+    "GW",
+    "GY",
+    "HK",
+    "HM",
+    "HN",
+    "HR",
+    "HT",
+    "HU",
+    "ID",
+    "IE",
+    "IL",
+    "IM",
+    "IN",
+    "IO",
+    "IQ",
+    "IR",
+    "IS",
+    "IT",
+    "JE",
+    "JM",
+    "JO",
+    "JP",
+    "KE",
+    "KG",
+    "KH",
+    "KI",
+    "KM",
+    "KN",
+    "KP",
+    "KR",
+    "KW",
+    "KY",
+    "KZ",
+    "LA",
+    "LB",
+    "LC",
+    "LI",
+    "LK",
+    "LR",
+    "LS",
+    "LT",
+    "LU",
+    "LV",
+    "LY",
+    "MA",
+    "MC",
+    "MD",
+    "ME",
+    "MF",
+    "MG",
+    "MH",
+    "MK",
+    "ML",
+    "MM",
+    "MN",
+    "MO",
+    "MP",
+    "MQ",
+    "MR",
+    "MS",
+    "MT",
+    "MU",
+    "MV",
+    "MW",
+    "MX",
+    "MY",
+    "MZ",
+    "NA",
+    "NC",
+    "NE",
+    "NF",
+    "NG",
+    "NI",
+    "NL",
+    "NO",
+    "NP",
+    "NR",
+    "NU",
+    "NZ",
+    "OM",
+    "PA",
+    "PE",
+    "PF",
+    "PG",
+    "PH",
+    "PK",
+    "PL",
+    "PM",
+    "PN",
+    "PR",
+    "PS",
+    "PT",
+    "PW",
+    "PY",
+    "QA",
+    "RE",
+    "RO",
+    "RS",
+    "RU",
+    "RW",
+    "SA",
+    "SB",
+    "SC",
+    "SD",
+    "SE",
+    "SG",
+    "SH",
+    "SI",
+    "SJ",
+    "SK",
+    "SL",
+    "SM",
+    "SN",
+    "SO",
+    "SR",
+    "SS",
+    "ST",
+    "SV",
+    "SX",
+    "SY",
+    "SZ",
+    "TC",
+    "TD",
+    "TF",
+    "TG",
+    "TH",
+    "TJ",
+    "TK",
+    "TL",
+    "TM",
+    "TN",
+    "TO",
+    "TR",
+    "TT",
+    "TV",
+    "TW",
+    "TZ",
+    "UA",
+    "UG",
+    "UM",
+    "US",
+    "UY",
+    "UZ",
+    "VA",
+    "VC",
+    "VE",
+    "VG",
+    "VI",
+    "VN",
+    "VU",
+    "WF",
+    "WS",
+    "XK",
+    "YE",
+    "YT",
+    "ZA",
+    "ZM",
+    "ZW",
+] as const;
+
+/**
+ * An ISO 3166-1 alpha-2 country code: `"IT"`, `"GR"`, `"RO"`.
+ *
+ * Read off the list above rather than described as a shape. `${Letter}${Letter}`
+ * admits all 676 two-letter strings, of which some 400 are not countries, so it
+ * accepted `"XX"` and every typo that happened to be two capitals. This accepts
+ * the 250 that exist and nothing else — including refusing the withdrawn codes
+ * (`SU`, `YU`, `AN`), which look plausible and are the ones worth catching.
+ *
+ * A name — `"Italy"`, `"Ιταλία"` — is a translation of a country rather than an
+ * identifier for one, and belongs in the sentence a page prints. `countriesFor`
+ * is what turns one of these into that.
+ */
+export type CountryCode = (typeof COUNTRY_CODES)[number];
+
+/** One country, in one language. */
+export interface NamedCountry {
+    readonly code: CountryCode;
+    readonly name: string;
+}
+
+/**
+ * The list as one locale reads it: each code with its own name, A to Z in that
+ * language.
+ *
+ * Both halves are locale-dependent, so neither can be cached across locales —
+ * "Ägypten" sorts second in German and "Egypt" fifth in English, and a build
+ * that sorted once would ship one language's order to all of them.
+ *
+ * `Intl.DisplayNames` falls back to the code itself for anything it does not
+ * know, which is what keeps this total: an option always has a label.
+ */
+export function countriesFor(locale: string): readonly NamedCountry[] {
+    const names = new Intl.DisplayNames([locale], { type: "region" });
+    const collator = new Intl.Collator(locale);
+    return COUNTRY_CODES.map((code) => ({
+        code,
+        name: names.of(code) ?? code,
+    })).sort((a, b) => collator.compare(a.name, b.name));
+}

package/src/i18n/define.ts

@@ -1,7 +1,7 @@
 import type { LocalesOf, SiteConfigShape } from "../config.ts";
 import type { IsNever, NoExcessKeys, StringKeys } from "../types.ts";
 import type {
-    EntryPlaceholders,
+    EntryTokens,
     MismatchedLocales,
     OverridePlaceholderMismatch,
     PlaceholderMismatch,
@@ -58,13 +58,13 @@ export type LocalesOfCatalog<Catalog> = StringKeys<
     Catalog[StringKeys<Catalog>]
 >;
 
-type SelfConsistent<E, K> = [
-    MismatchedLocales<E, EntryPlaceholders<E>>,
-] extends [never]
+type SelfConsistent<E, K> = [MismatchedLocales<E, EntryTokens<E>>] extends [
+    never,
+]
     ? unknown
     : PlaceholderMismatch<
           K & string,
-          MismatchedLocales<E, EntryPlaceholders<E>> & string
+          MismatchedLocales<E, EntryTokens<E>> & string
       >;
 
 type ValidateBase<T> = { [K in keyof T]: SelfConsistent<T[K], K> };
@@ -88,7 +88,8 @@ type NoExtraLocales<T, L extends string> = {
  *
  * Enforced at compile time:
  *  - every key defines every locale the site ships, and no others;
- *  - every locale of a key uses exactly the same `{placeholders}`.
+ *  - every locale of a key uses exactly the same `{placeholders}` and `[marks]`,
+ *    so a translation cannot drop the link or the emphasis the others carry.
  */
 export function defineMessages<
     const C extends SiteConfigShape,
@@ -124,11 +125,11 @@ export type ValidateOverrideCatalog<
 
 type ValidateOverrides<T, Base> = {
     [K in keyof T]: K extends keyof Base
-        ? [MismatchedLocales<T[K], EntryPlaceholders<Base[K]>>] extends [never]
+        ? [MismatchedLocales<T[K], EntryTokens<Base[K]>>] extends [never]
             ? unknown
             : OverridePlaceholderMismatch<
                   K & string,
-                  MismatchedLocales<T[K], EntryPlaceholders<Base[K]>> & string
+                  MismatchedLocales<T[K], EntryTokens<Base[K]>> & string
               >
         : unknown;
 };
@@ -142,8 +143,8 @@ type ValidateOverrides<T, Base> = {
  * Enforced at compile time:
  *  - the key must exist in the base catalog, so a typo is rejected rather than
  *    silently becoming a string nothing reads;
- *  - the replacement must use exactly the `{placeholders}` of the base message,
- *    so every existing `t()` call site stays correct.
+ *  - the replacement must use exactly the `{placeholders}` and `[marks]` of the
+ *    base message, so every existing `t()` and `rich()` call site stays correct.
  */
 export function defineMessageOverrides<
     const C extends SiteConfigShape,

package/src/i18n/placeholders.ts

@@ -3,6 +3,7 @@
  * data of any kind lives in `lib/`.
  */
 
+import type { MarkTokens } from "../content/marks.ts";
 import type { Digit, Letter, StringKeys } from "../types.ts";
 
 /**
@@ -22,8 +23,15 @@ import type { Digit, Letter, StringKeys } from "../types.ts";
  */
 type NameChar = Letter | Lowercase<Letter> | Digit | "_";
 
-/** Whether every character of `S` may appear in a placeholder name. */
-type IsName<S extends string> = S extends `${infer Head}${infer Tail}`
+/**
+ * Whether every character of `S` may appear in a placeholder name.
+ *
+ * Exported for `LinkNames` in `content/marks.ts`, which asks the same question
+ * about a `[a:slot]`: both become keys the call site writes in one object, so
+ * "what may a name be spelled with" has to have one answer, not two that agree
+ * until someone widens one of them.
+ */
+export type IsName<S extends string> = S extends `${infer Head}${infer Tail}`
     ? Head extends NameChar
         ? Tail extends ""
             ? true
@@ -66,29 +74,48 @@ export type TextOf<E> = Extract<E[keyof E], string>;
 export type EntryPlaceholders<E> = Placeholders<TextOf<E>>;
 
 /**
- * The locales of `E` whose placeholder set differs from `Expected`.
+ * Everything structural in a template: its `{placeholders}` and its `[marks]`.
+ *
+ * The two are one question — what does this message *require*, over and above
+ * its words — and they are checked together because they fail together. A
+ * translation that drops `{name}` renders a literal brace; one that drops
+ * `[a:venue]` renders a sentence with no link in it. Both are a translator
+ * having edited around the structure rather than inside it.
+ *
+ * Only the consistency check reads this. `MessageParamsOf` stays on
+ * `EntryPlaceholders`, because marks are spelled in the copy and are never
+ * arguments a call site passes.
+ */
+export type Tokens<S extends string> = Placeholders<S> | MarkTokens<S>;
+
+/** Every placeholder and mark used by any locale of an entry. */
+export type EntryTokens<E> = Tokens<TextOf<E>>;
+
+/**
+ * The locales of `E` whose placeholders or marks differ from `Expected`.
  *
  * This is what turns a half-updated translation into a compile error instead of
- * a literal `{name}` rendered on a production page.
+ * a literal `{name}` rendered on a production page — or, since marks joined it,
+ * a Greek paragraph that lost the link the English one carries.
  */
 export type MismatchedLocales<E, Expected extends string> = {
     [L in StringKeys<E>]: [
-        | Exclude<Expected, Placeholders<Extract<E[L], string>>>
-        | Exclude<Placeholders<Extract<E[L], string>>, Expected>,
+        | Exclude<Expected, Tokens<Extract<E[L], string>>>
+        | Exclude<Tokens<Extract<E[L], string>>, Expected>,
     ] extends [never]
         ? never
         : L;
 }[StringKeys<E>];
 
-/** Editor-facing error when placeholders drift between locales of one message. */
+/** Editor-facing error when structure drifts between locales of one message. */
 export interface PlaceholderMismatch<Key extends string, L extends string> {
-    readonly __PLACEHOLDER_MISMATCH__: `Message "${Key}" uses different {placeholders} in locale "${L}" than in its other locales`;
+    readonly __PLACEHOLDER_MISMATCH__: `Message "${Key}" uses different {placeholders} or [marks] in locale "${L}" than in its other locales`;
 }
 
-/** Editor-facing error when an override drops or invents a placeholder. */
+/** Editor-facing error when an override drops or invents one. */
 export interface OverridePlaceholderMismatch<
     Key extends string,
     L extends string,
 > {
-    readonly __OVERRIDE_PLACEHOLDER_MISMATCH__: `Override of "${Key}" in locale "${L}" must use exactly the same {placeholders} as the base message`;
+    readonly __OVERRIDE_PLACEHOLDER_MISMATCH__: `Override of "${Key}" in locale "${L}" must use exactly the same {placeholders} and [marks] as the base message`;
 }

package/src/i18n/translate.ts

@@ -1,3 +1,4 @@
+import { assertNoMarks } from "../content/marks.ts";
 import type { StringKeys } from "../types.ts";
 import type { EntryPlaceholders } from "./placeholders.ts";
 
@@ -32,7 +33,7 @@ const NAME = /^[a-zA-Z0-9_]+$/;
  * unmatched closer to be ambiguous about, and rejecting it would fail copy that
  * is merely writing a bracket.
  */
-function render(
+export function render(
     template: string,
     at: string,
     value: (name: string, whole: string) => string
@@ -88,12 +89,42 @@ export interface RawTranslateOptions<L extends string> {
     readonly locale: L;
 }
 
+/**
+ * One message's raw copy, before anything is substituted or parsed.
+ *
+ * Shared with `content/rich.ts`, which needs the template *unrendered* — marks
+ * are parsed out of it first and placeholders filled per run afterwards, so it
+ * cannot go through `t()`. Both failures are stated once here rather than in
+ * each caller, which is what keeps the two error messages identical.
+ */
+export function lookupTemplate<L extends string>(
+    catalog: MergedCatalog<L>,
+    locale: L,
+    key: string
+): string {
+    const entry = catalog[key];
+    if (entry === undefined) {
+        throw new Error(`Unknown message key "${key}".`);
+    }
+    const template = entry[locale];
+    if (typeof template !== "string") {
+        throw new Error(`Message "${key}" has no copy for locale "${locale}".`);
+    }
+    return template;
+}
+
 /**
  * Builds the runtime half of `t()`.
  *
  * Every failure here is a build-time failure by design: a static site should not
  * ship a page with a literal `{name}` in the markup, so a missing message or an
  * unfilled placeholder throws rather than degrading.
+ *
+ * That rule is why a message carrying `[marks]` is refused here too. `t()`
+ * returns a string, so the only thing it could do with them is print them, and
+ * `[v:accent]Game Over[/v]` rendered into a `<title>` is the literal-brace
+ * failure wearing different brackets. `rich()` reads those, and `plain()` gives
+ * back the sentence without them.
  */
 export function createRawTranslate<L extends string>(
     options: RawTranslateOptions<L>
@@ -101,16 +132,8 @@ export function createRawTranslate<L extends string>(
     const { catalog, locale } = options;
 
     return (key, params) => {
-        const entry = catalog[key];
-        if (entry === undefined) {
-            throw new Error(`Unknown message key "${key}".`);
-        }
-        const template = entry[locale];
-        if (typeof template !== "string") {
-            throw new Error(
-                `Message "${key}" has no copy for locale "${locale}".`
-            );
-        }
+        const template = lookupTemplate(catalog, locale, key);
+        assertNoMarks(template, `Message "${key}" (${locale})`);
         return render(
             template,
             `Message "${key}" (${locale})`,

package/src/index.ts

@@ -45,12 +45,17 @@ export {
     type CallingCode,
     type Coordinates,
     type CountryCode,
+    type E164,
     type EmailAddress,
     e164,
+    e164Of,
     formatPhone,
+    isEmailAddress,
+    type MailtoUrl,
     mailtoHref,
     type PhoneNumber,
     type PostalAddress,
+    type TelUrl,
     telHref,
 } from "./contact.ts";
 export {
@@ -60,6 +65,24 @@ export {
     type MailEndpoint,
     sendContactMessage,
 } from "./contact-form.ts";
+// `parseMarks`, `assertNoMarks` and `createRichText` are deliberately not here.
+// They are how lib gets from a message to a `Span[]`, and a consumer holding
+// them has a second `rich()` that is not bound to the site's route table — so
+// a slot filled with a route id resolves against nothing there. `site.rich(locale)` is
+// the only way in, and `Span` is what a renderer switches on.
+export {
+    type LinkTarget,
+    type PlainTextFor,
+    plain,
+    type RichText,
+    type RichTextFor,
+    type Span,
+} from "./content/index.ts";
+export {
+    COUNTRY_CODES,
+    countriesFor,
+    type NamedCountry,
+} from "./countries.ts";
 export type { GeneratedFile } from "./file.ts";
 export type { PublicFilePath, PublicFileRegistry } from "./files.ts";
 export {
@@ -222,7 +245,9 @@ export type { Sitemap, SitemapConfig } from "./sitemap.ts";
 export type { IsoDate, Letter, StringKeys } from "./types.ts";
 export {
     absoluteUrl,
+    type Hash,
     type HttpsUrl,
+    isHash,
     isHttpsUrl,
     isUrlPath,
     joinUrl,

package/src/site/api.ts

@@ -1,4 +1,5 @@
 import type { ResolvedLocaleMeta } from "../config.ts";
+import type { PlainTextFor, RichTextFor } from "../content/index.ts";
 import type { GeneratedFile } from "../file.ts";
 import type { PublicFilePath } from "../files.ts";
 import type { TranslateFor } from "../i18n/translate.ts";
@@ -161,6 +162,36 @@ export interface Site<
     /** A locale-bound `t()`. */
     translate(locale: L): TranslateFor<Catalog>;
 
+    /**
+     * A locale-bound `rich()`: the same catalog, read as styled runs.
+     *
+     * For copy that is one sentence with a bold clause, an accent colour or a
+     * link in the middle of it. The marks live in the message so every language
+     * can move them — see `content/marks.ts`, which is mostly about why they
+     * cannot live in config instead.
+     *
+     * 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.
+     */
+    rich(locale: L): RichTextFor<Catalog, RouteId>;
+
+    /**
+     * A locale-bound `plain()`: the same catalog, read as words alone.
+     *
+     * For everywhere a string is what fits and markup is not — `llms()`'s
+     * `describe`, a page description, a structured-data `description`. Marks are
+     * dropped, a `[br]` becomes a space, and the result is the sentence a reader
+     * would hear.
+     *
+     * The reason it exists next to `translate` rather than being folded into it:
+     * `t()` refuses a message carrying marks, because the only thing it could do
+     * with them is print them. This is the reading that copes, so a description
+     * does not break the day someone emphasises a clause in the sentence it
+     * quotes.
+     */
+    plain(locale: L): PlainTextFor<Catalog>;
+
     /** Absolute path of a route in one locale, e.g. `/el/sxetika-me-emas`. */
     pathFor(id: RouteId, locale: L, options?: LinkOptions): UrlPath;
     /** The same, prefixed with the site origin — for canonicals and sitemaps. */

package/src/site/create.ts

@@ -4,6 +4,11 @@ import {
     mergeLocaleMeta,
     type SiteConfigShape,
 } from "../config.ts";
+import {
+    createPlainText,
+    createRichText,
+    type LinkResolver,
+} from "../content/index.ts";
 import type { GeneratedFile } from "../file.ts";
 import type { PublicFilePath } from "../files.ts";
 import { type BaseCatalog, mergeCatalog } from "../i18n/define.ts";
@@ -729,6 +734,36 @@ export function createSite<
         });
     }
 
+    /**
+     * How a slot filled with a route id becomes this locale's path.
+     *
+     * `pathFor` already refuses an unknown or disabled route, and its message is
+     * right for a call site that named the id — but a mark comes from a
+     * *translation*, so the useful part is which message to open. That is what
+     * this adds; the original is kept as the cause rather than restated, since
+     * "disabled for this project" and "unknown" are different fixes.
+     */
+    function richLink(locale: L): LinkResolver {
+        return (routeId, at, hash) => {
+            try {
+                // Through `pathFor` rather than concatenated on afterwards, so
+                // a fragment lands after the page segment and the query — the
+                // one order that is right — and so `#` is added in exactly one
+                // place in this package.
+                return pathFor(
+                    routeId as RouteId,
+                    locale,
+                    hash === undefined ? undefined : { hash }
+                );
+            } catch (cause) {
+                throw new Error(
+                    `${at} links to "${routeId}", which is not a page this project builds. A link target is a route id — optionally with a fragment, as "about#team" — a "/path", an https:// URL, or a "#fragment" on the page it is rendered on.`,
+                    { cause }
+                );
+            }
+        };
+    }
+
     return {
         locales,
         defaultLocale,
@@ -740,6 +775,20 @@ export function createSite<
         routes: enabledRouteIds,
 
         translate: (locale) => translateFactory(catalog, locale),
+        rich: (locale) =>
+            createRichText<Catalog, L, RouteId>({
+                catalog,
+                locale,
+                link: richLink(locale),
+                origin: siteUrl,
+            }),
+        plain: (locale) =>
+            createPlainText<Catalog, L>({
+                catalog,
+                locale,
+                link: richLink(locale),
+                origin: siteUrl,
+            }),
 
         pathFor,
         urlFor,