@escape-game-over/atlas 0.1.90 → 0.1.91

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.90",
+    "version": "0.1.91",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,

package/src/i18n/define.ts

@@ -1,6 +1,7 @@
 import type { LocalesOf, SiteConfigShape } from "../config.ts";
 import type { IsNever, NoExcessKeys, StringKeys } from "../types.ts";
 import type {
+    AddedMessageExists,
     EntryTokens,
     MismatchedLocales,
     OverridePlaceholderMismatch,
@@ -137,10 +138,32 @@ export type MessageOverrides<Catalog, L extends string> = {
     readonly [K in StringKeys<Catalog>]?: Readonly<Partial<Record<L, string>>>;
 };
 
-/** Merges a project's override catalog over the base catalog, locale by locale. */
+/**
+ * What `defineProject` checks an `addMessages` against: each key new to the
+ * base catalog, written for exactly the locales the project publishes, with
+ * the same `{placeholders}` and `[marks]` in each.
+ *
+ * New only, because a key the base already has is copy every project shares,
+ * and rewording it is what `overrideMessages` is for — with its own check that
+ * the placeholders survive. An addition shadowing a base key would get round
+ * that check, and two fields could then say different things about one key.
+ */
+export type ValidateAdditions<T, Base, Published extends string> = {
+    [K in keyof T]: K extends keyof Base
+        ? AddedMessageExists<K & string>
+        : NoExcessKeys<T[K], Published> &
+              Readonly<Record<Published, string>> &
+              SelfConsistent<T[K], K>;
+};
+
+/**
+ * Merges a project's override catalog over the base catalog, locale by locale,
+ * then adds the project's own messages.
+ */
 export function mergeCatalog<L extends string>(
     base: BaseCatalog<L>,
-    overrides: OverrideCatalog<L>
+    overrides: OverrideCatalog<L>,
+    additions: OverrideCatalog<L> = {}
 ): Readonly<Record<string, Readonly<Record<L, string>>>> {
     const merged: Record<string, Record<string, string>> = {};
     for (const [key, entry] of Object.entries(base)) {
@@ -154,5 +177,15 @@ export function mergeCatalog<L extends string>(
             if (typeof text === "string") target[locale] = text;
         }
     }
+    for (const [key, entry] of Object.entries(additions)) {
+        // Unreachable via the typed API, which refuses a base key here; an
+        // Astro config is evaluated before the type check, so say it plainly.
+        if (key in merged) {
+            throw new Error(
+                `addMessages: "${key}" is already in the default catalog. Reword it in overrideMessages instead.`
+            );
+        }
+        merged[key] = { ...entry } as Record<string, string>;
+    }
     return merged as Readonly<Record<string, Readonly<Record<L, string>>>>;
 }

package/src/i18n/placeholders.ts

@@ -112,6 +112,11 @@ export interface PlaceholderMismatch<Key extends string, L extends string> {
     readonly __PLACEHOLDER_MISMATCH__: `Message "${Key}" uses different {placeholders} or [marks] in locale "${L}" than in its other locales`;
 }
 
+/** Editor-facing error when a project adds a message the base already has. */
+export interface AddedMessageExists<Key extends string> {
+    readonly __ADDED_MESSAGE_EXISTS__: `Message "${Key}" is already in the default catalog: reword it in overrideMessages instead of adding it`;
+}
+
 /** Editor-facing error when an override drops or invents one. */
 export interface OverridePlaceholderMismatch<
     Key extends string,

package/src/index.ts

@@ -230,6 +230,7 @@ export {
     tierRange,
 } from "./money.ts";
 export type {
+    AddedCatalog,
     DefinedProject,
     ProjectInput,
     ProjectRouteId,

package/src/project.ts

@@ -10,6 +10,7 @@ import type { Fonts } from "./fonts.ts";
 import type {
     BaseCatalog,
     OverrideCatalog,
+    ValidateAdditions,
     ValidateOverrideCatalog,
 } from "./i18n/define.ts";
 import type { ImageAsset } from "./image.ts";
@@ -139,6 +140,20 @@ export interface ProjectInput<L extends string, Routes> {
      * than the argument.
      */
     readonly overrideMessages: OverrideCatalog<L>;
+    /**
+     * Copy only this project has: keys the default catalog does not declare,
+     * each written for every locale the project publishes and no others.
+     *
+     * For what one deployment says and no other does — a venue's own FAQ, a
+     * house rule — so it goes through `translate` and `rich` like any message,
+     * marks and placeholders included, without the shared catalog carrying it
+     * in languages the venue never publishes. A key the default catalog
+     * already has is refused: reword it in `overrideMessages`.
+     *
+     * Optional, unlike `overrideMessages`: nothing downstream is computed from
+     * it except the catalog's keys, which an absent field leaves as they are.
+     */
+    readonly addMessages?: OverrideCatalog<L>;
     /** Slug retranslations and page on/off switches. See `overrideMessages`. */
     readonly overrideRoutes: RouteOverrides<Routes, L>;
 }
@@ -289,7 +304,20 @@ export type ProjectOverrideChecks<
         Routes,
         T["overrideRoutes"]
     >;
-};
+} & (T extends { readonly addMessages: infer A }
+    ? {
+          readonly addMessages: ValidateAdditions<
+              A,
+              Catalog,
+              T["enabledLocales"][number]
+          >;
+      }
+    : unknown);
+
+/** A project's own messages, as a catalog: none when it adds none. */
+export type AddedCatalog<P> = P extends { readonly addMessages: infer A }
+    ? A
+    : Record<never, never>;
 
 export function defineProject<
     const C extends SiteConfigShape,
@@ -324,5 +352,22 @@ export function defineProject<
             );
         }
     }
+    // The same two rules the type states, for the same reason: the config is
+    // evaluated before the type check runs.
+    for (const [key, entry] of Object.entries(project.addMessages ?? {})) {
+        if (key in _messages) {
+            throw new Error(
+                `Project "${project.siteName}": addMessages "${key}" is already in the default catalog. Reword it in overrideMessages instead.`
+            );
+        }
+        const missing = project.enabledLocales.filter(
+            (locale) => typeof entry[locale] !== "string"
+        );
+        if (missing.length > 0) {
+            throw new Error(
+                `Project "${project.siteName}": addMessages "${key}" has no ${missing.join(", ")}. A message a project adds is written for every locale it publishes.`
+            );
+        }
+    }
     return project;
 }

package/src/site/create.ts

@@ -22,7 +22,7 @@ import {
     buildNotFoundMeta,
     resolveShareImage,
 } from "../meta/index.ts";
-import type { ProjectInput, ProjectRouteId } from "../project.ts";
+import type { AddedCatalog, ProjectInput, ProjectRouteId } from "../project.ts";
 import {
     buildRedirects,
     type RedirectRule,
@@ -102,7 +102,7 @@ export function createSite<
     project: P & { readonly enabledLocales: readonly Published[] }
 ): Site<
     Published,
-    Catalog,
+    Catalog & AddedCatalog<P>,
     ProjectRouteId<Routes, P>,
     SectionPrefixOf<Routes, P["overrideRoutes"]>,
     OrphanSectionPrefixOf<Routes, P["overrideRoutes"]>
@@ -179,8 +179,15 @@ export function createSite<
     const llmsUrl: HttpsUrl | undefined =
         config_.llms === false ? undefined : joinUrl(siteUrl, `/${llmsName}`);
 
-    const catalog = mergeCatalog<L>(messages, project.overrideMessages);
-    const translateFactory = createTranslateFactory<Catalog, L>();
+    // The project's own messages join the catalog here, typed and resolved like
+    // any other: `Full` is what every reader below knows the keys by.
+    type Full = Catalog & AddedCatalog<P>;
+    const catalog = mergeCatalog<L>(
+        messages,
+        project.overrideMessages,
+        project.addMessages
+    );
+    const translateFactory = createTranslateFactory<Full, L>();
 
     const resolved = mergeRoutes<L, Routes>(routes, project.overrideRoutes);
 
@@ -831,14 +838,14 @@ export function createSite<
 
         translate: (locale) => translateFactory(catalog, locale),
         rich: (locale) =>
-            createRichText<Catalog, L, RouteId>({
+            createRichText<Full, L, RouteId>({
                 catalog,
                 locale,
                 link: richLink(locale),
                 origin: siteUrl,
             }),
         plain: (locale) =>
-            createPlainText<Catalog, L>({
+            createPlainText<Full, L>({
                 catalog,
                 locale,
                 link: richLink(locale),