@escape-game-over/atlas 0.1.5 → 0.1.7

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

@@ -26,6 +26,7 @@ export {
     CONSENT_UPDATE_GLOBAL,
     type ConsentDefaults,
     type ConsentState,
+    consentRequired,
     type GoogleSettings,
     type UmamiReplay,
     type UmamiSettings,
@@ -45,12 +46,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 +66,19 @@ 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,
@@ -227,7 +246,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/meta/tag.ts

@@ -92,6 +92,15 @@ export function asMetaTag(script: AnalyticsTag): MetaTag {
     if (script.kind === "noscriptFrame") {
         return { kind: "noscriptFrame", src: script.src };
     }
+    if (script.kind === "preconnect") {
+        // A `link` rather than a kind of its own: the head vocabulary already
+        // has the shape, and a preconnect is a link in every sense the renderer
+        // cares about. See `AnalyticsTag` for why no `crossorigin`.
+        return {
+            kind: "link",
+            attrs: { rel: "preconnect", href: script.origin },
+        };
+    }
     const unhandled: never = script;
     throw new Error(`Unhandled analytics tag: ${JSON.stringify(unhandled)}`);
 }

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,

package/src/url.ts

@@ -46,6 +46,26 @@ export function isUrlPath(path: string): path is UrlPath {
     return path.startsWith("/");
 }
 
+/**
+ * A fragment on whatever page is being rendered: `#booking`, `#Scenarios`.
+ *
+ * The one link target lib cannot resolve and does not need to. A route id
+ * becomes a different path in every language and an `https://` URL points
+ * somewhere else entirely; a fragment names an element of the document it is
+ * written in, so it is already the whole answer and passes through untouched.
+ *
+ * Typed as its own shape rather than folded into `UrlPath` because they are not
+ * interchangeable: `/booking` navigates and `#booking` scrolls, and a leading
+ * character is the only thing that distinguishes them. See `LinkTarget`, which
+ * tells the four apart by exactly that.
+ */
+export type Hash = `#${string}`;
+
+/** The runtime half of `Hash`. See `isHttpsUrl`. */
+export function isHash(value: string): value is Hash {
+    return value.startsWith("#");
+}
+
 /**
  * An origin without its trailing slash.
  *