@escape-game-over/atlas 0.1.108 → 0.1.109

package/README.md

@@ -72,6 +72,7 @@ export const { project, redirects } = atlas.project(
 
         enabledLocales: ["el-GR", "en-US"],
         overrideRouting: { defaultLocale: "el-GR", prefixDefaultLocale: true },
+        clock: { "el-GR": "h23", "en-US": "h12" }, // how each language prints times
 
         overrideMessages: {
             // Greek only — the English copy still falls through to the default catalog.
@@ -243,6 +244,8 @@ regression-tested by an `@ts-expect-error` suite.
 | A `robots` directive that is not a real one                                     | error — the vocabulary is a union            |
 | A project `url` that is not `https://`, or ends in a slash                      | error                                        |
 | `defaultLocale` not among the project's `enabledLocales`                        | error                                        |
+| A `clock` leaving out a published locale, or naming an unpublished one          | error                                        |
+| `site.clockFor` on a project that declares no clock                             | throws, naming the project                   |
 | An unknown field in a project declaration                                       | error — a typo cannot sit there unread       |
 | Two routes resolving to the same URL                                            | build throws, naming both                    |
 | A site icon that is not square, a multiple of 48px, and PNG                     | build throws                                 |

package/docs/checks.md

@@ -42,6 +42,7 @@ sees.
 | unknown message key, or an override dropping a `{placeholder}`                            | two routes resolving to the same URL                                    |
 | a message the project declared mandatory and never wrote (`CatalogCovers`)                |                                                                         |
 | copy or a locale label written for a locale outside `enabledLocales`                      |                                                                         |
+| a `clock` leaving out a published locale, or naming one outside `enabledLocales`          | the same, for a project that was not type-checked first                 |
 | a slug whose translation sits at a different depth, in the registry or across the overlay | the same, when a slug is not a literal (computed, or from an env var)   |
 | unknown route id, or a locale the site does not ship                                      | a locale published twice                                                |
 | a malformed language tag (`en_US`, `en-us`, `EN-US`, bare `en`)                           | an icon that is not square, a multiple of 48, and PNG                   |

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.108",
+    "version": "0.1.109",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,
@@ -63,10 +63,10 @@
         "vite": ">= 8"
     },
     "devDependencies": {
-        "@biomejs/biome": "2.6.6",
+        "@biomejs/biome": "2.6.7",
         "@types/node": "26.6.6",
         "@vitest/coverage-istanbul": "5.1.0",
-        "astro": "7.4.10",
+        "astro": "7.4.11",
         "typescript": "6.0.3",
         "vitest": "5.1.0"
     }

package/src/project.ts

@@ -7,6 +7,7 @@ import type {
     SiteConfigShape,
 } from "./config.ts";
 import type { Fonts } from "./fonts.ts";
+import type { HourCycle } from "./hours.ts";
 import type {
     BaseCatalog,
     OverrideCatalog,
@@ -105,6 +106,21 @@ export interface ProjectInput<L extends string, Routes> {
      * declare is a compile error.
      */
     readonly enabledLocales: readonly L[];
+    /**
+     * The clock each published language prints times on: `"h23"` for 18:00,
+     * `"h12"` for 6:00 PM. Read back with `site.clockFor(locale)`.
+     *
+     * One entry for every locale in `enabledLocales`, and none for any other,
+     * so what each page prints is written down beside the languages that print
+     * it: a bilingual Canadian site reads `{ "en-CA": "h12", "fr-CA": "h23" }`.
+     * Not taken from the locale's own default (`Intl`'s) on purpose: a site may
+     * print a 24-hour clock where its language's default is 12-hour, and that
+     * choice is the site's to state.
+     *
+     * Optional: a project that prints no times declares none, and
+     * `clockFor` refuses to answer for it.
+     */
+    readonly clock?: Readonly<Partial<Record<L, HourCycle>>>;
     /**
      * Replaces parts of the site's `defaultRouting` for this project.
      *
@@ -286,6 +302,17 @@ export type ProjectChecks<
             ? NoExcessKeys<T["overrideLocaleMeta"][K], keyof LocaleMetaOverride>
             : LocaleNotEnabled<K>;
     };
+    // The locales written must be ones this project publishes, as for
+    // `overrideLocaleMeta` above. That every one it publishes is there is
+    // checked in `ProjectOverrideChecks`: a conditional on `T` here would make
+    // the constraint circular.
+    readonly clock?: {
+        readonly [K in StringKeys<
+            T["clock"]
+        >]: K extends T["enabledLocales"][number]
+            ? HourCycle
+            : LocaleNotEnabled<K>;
+    };
 };
 
 /** The same checks that map the whole override objects, in parameter position. */
@@ -312,7 +339,16 @@ export type ProjectOverrideChecks<
               T["enabledLocales"][number]
           >;
       }
-    : unknown);
+    : unknown) &
+    (T extends { readonly clock: object }
+        ? {
+              // A clock, once declared, is declared for every page: a locale
+              // left out would have no clock to print its times on.
+              readonly clock: {
+                  readonly [K in T["enabledLocales"][number]]: HourCycle;
+              };
+          }
+        : unknown);
 
 /** A project's own messages, as a catalog: none when it adds none. */
 export type AddedCatalog<P> = P extends { readonly addMessages: infer A }
@@ -369,5 +405,25 @@ export function defineProject<
             );
         }
     }
+    // The clock's rule, for the same reason.
+    if (project.clock !== undefined) {
+        const published: readonly string[] = project.enabledLocales;
+        const missing = published.filter(
+            (locale) => !(locale in (project.clock ?? {}))
+        );
+        if (missing.length > 0) {
+            throw new Error(
+                `Project "${project.siteName}": clock has no ${missing.join(", ")}. A project that declares a clock gives one for every locale it publishes.`
+            );
+        }
+        const extra = Object.keys(project.clock).filter(
+            (locale) => !published.includes(locale)
+        );
+        if (extra.length > 0) {
+            throw new Error(
+                `Project "${project.siteName}": clock names ${extra.join(", ")}, which this project does not publish.`
+            );
+        }
+    }
     return project;
 }

package/src/site/api.ts

@@ -7,6 +7,7 @@ import type {
 import type { GeneratedFile } from "../file.ts";
 import type { PublicFilePath } from "../files.ts";
 import type { Fonts } from "../fonts.ts";
+import type { HourCycle } from "../hours.ts";
 import type { TranslateFor } from "../i18n/translate.ts";
 import type { LlmsSection } from "../llms.ts";
 import type { ThemeColor } from "../meta/index.ts";
@@ -219,6 +220,15 @@ export interface Site<
         bind?: { readonly values?: Readonly<Record<Values, string>> }
     ): PlainTextFor<Catalog, Values>;
 
+    /**
+     * The clock a locale's pages print times on, as the project's `clock`
+     * states it: hand it to `formatHours`, or to anything formatting a time.
+     *
+     * Throws for a project that declares no clock: one that prints times has
+     * to say how.
+     */
+    clockFor(locale: L): HourCycle;
+
     /** 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

@@ -14,6 +14,7 @@ import {
 import type { GeneratedFile } from "../file.ts";
 import type { PublicFilePath } from "../files.ts";
 import { mergeFonts } from "../fonts.ts";
+import type { HourCycle } from "../hours.ts";
 import { type BaseCatalog, mergeCatalog } from "../i18n/define.ts";
 import { createTranslateFactory } from "../i18n/translate.ts";
 import type { ImageAsset } from "../image.ts";
@@ -192,6 +193,18 @@ export function createSite<
 
     const resolved = mergeRoutes<L, Routes>(routes, project.overrideRoutes);
 
+    function clockFor(locale: L): HourCycle {
+        const cycle = project.clock?.[locale];
+        if (cycle === undefined) {
+            throw new Error(
+                project.clock === undefined
+                    ? `Project "${project.siteName}" declares no clock, so it cannot print a time. Add \`clock\`, with an hour cycle for each locale it publishes.`
+                    : `Project "${project.siteName}": clock has no ${locale}.`
+            );
+        }
+        return cycle;
+    }
+
     function pathFor(id: RouteId, locale: L, options?: LinkOptions): UrlPath {
         const route = resolved[id];
         if (route === undefined) {
@@ -867,6 +880,7 @@ export function createSite<
                 ...bind,
             }),
 
+        clockFor,
         pathFor,
         urlFor,
         fileUrl,