@escape-game-over/atlas 0.1.23 → 0.1.25

package/src/site/create.ts

@@ -13,12 +13,12 @@ import type { GeneratedFile } from "../file.ts";
 import type { PublicFilePath } from "../files.ts";
 import { type BaseCatalog, mergeCatalog } from "../i18n/define.ts";
 import { createTranslateFactory } from "../i18n/translate.ts";
+import type { ImageAsset } from "../image.ts";
 import { buildLlms, type LlmsItem, type LlmsSection } from "../llms.ts";
 import {
     buildMeta,
     buildNotFoundMeta,
     resolveShareImage,
-    type SiteIcon,
 } from "../meta/index.ts";
 import type { ProjectInput } from "../project.ts";
 import {
@@ -171,9 +171,6 @@ export function createSite<
             | undefined,
     };
 
-    // Declared config, not a call to `llms()`: the head is built page by page
-    // and cannot know whether some other module generated the file, whereas
-    // stating `llms` in the site config is a promise that one is published.
     const llmsName =
         (config_.llms === false ? undefined : config_.llms?.name) ?? "llms.txt";
     // Annotated, not inferred: a template expression widens to `string` unless
@@ -291,15 +288,16 @@ export function createSite<
         entries.map((entry) => entry.path)
     );
 
-    function staticPaths(param: string): StaticPath<L, RouteId>[] {
+    function getStaticPaths(): StaticPath<L, RouteId>[] {
         const paths: StaticPath<L, RouteId>[] = entries.map((entry) => ({
             params: {
-                [param]: entry.path === "/" ? undefined : entry.path.slice(1),
+                route: entry.path === "/" ? undefined : entry.path.slice(1),
             },
             props: {
                 routeId: entry.routeId,
                 locale: entry.locale,
                 page: entry.page,
+                pages: resolved[entry.routeId]?.pages ?? 1,
             },
         }));
 
@@ -362,7 +360,7 @@ export function createSite<
      * a bad icon still fails the build, at the first page that renders.
      */
     let iconChecked = false;
-    function checkedIcon(): SiteIcon {
+    function checkedIcon(): ImageAsset {
         if (iconChecked) return project.icon;
         if (project.icon.width !== project.icon.height) {
             throw new Error(
@@ -795,10 +793,8 @@ export function createSite<
         fileUrl,
         breadcrumbFor,
         orphanSegments,
-        alternatesFor,
         localeLinksFor,
-        entries,
-        staticPaths,
+        getStaticPaths,
         sitemap,
         robots,
         llms,

package/src/site/define.ts

@@ -0,0 +1,120 @@
+import {
+    defineSiteConfig,
+    type LocalesOf,
+    type SiteConfigChecks,
+    type SiteConfigShape,
+} from "../config.ts";
+import {
+    type BaseCatalog,
+    defineMessages,
+    type NoExtraLocales,
+    type ValidateBase,
+} from "../i18n/define.ts";
+import {
+    defineProject,
+    type ProjectChecks,
+    type ProjectInput,
+    type ProjectOverrideChecks,
+} from "../project.ts";
+import {
+    defineRoutes,
+    type RouteRegistry,
+    type ValidateSlugDepth,
+} from "../routes/define.ts";
+import {
+    type FamilyMemberInput,
+    type FamilyOptions,
+    routeFamily,
+} from "../routes/family.ts";
+import { createSite } from "./create.ts";
+
+/**
+ * A site: which languages exist and how URLs are shaped, and everything built
+ * on that, as methods — so no other file restates the config.
+ *
+ * ```ts
+ * // config/site.config.ts
+ * export const atlas = defineSite({ locales: {…}, defaultRouting: {…} });
+ *
+ * // config/routes.ts, messages.ts, projects/<name>/project.ts, site.ts
+ * const rooms = atlas.family("rooms", ROOMS, { enabled: true });
+ * export const defaultRoutes = atlas.routes({ ...rooms, home: {…} });
+ * export const defaultMessages = atlas.messages({…});
+ * export default atlas.project(defaultMessages, defaultRoutes, {…});
+ * export const site = atlas.site(defaultMessages, defaultRoutes, project);
+ * ```
+ *
+ * Every check each step makes is the same one it makes as a function: a typo'd
+ * key, a dropped placeholder or a slug at the wrong depth is an error on the
+ * line that is wrong.
+ */
+export function defineSite<
+    const C extends SiteConfigShape & SiteConfigChecks<C>,
+>(input: C) {
+    const config = defineSiteConfig(input as never) as C;
+    type L = LocalesOf<C>;
+
+    return {
+        config,
+
+        /** A route per member, under one prefix: `rooms/red-room` for `rooms`. */
+        family<
+            const Prefix extends string,
+            const Members extends readonly FamilyMemberInput<L>[],
+            const Options extends FamilyOptions<L> = Record<string, never>,
+        >(
+            prefix: Prefix,
+            members: Members,
+            options?: Options
+        ): ReturnType<typeof routeFamily<C, Prefix, Members, Options>> {
+            return routeFamily(config, prefix, members, options);
+        },
+
+        /** The route table every project starts from. */
+        routes<const T extends RouteRegistry<L>>(
+            routes: T & ValidateSlugDepth<T>
+        ): T {
+            return defineRoutes(config, routes as never) as T;
+        },
+
+        /** The copy every project starts from, in every locale. */
+        messages<const T extends BaseCatalog<L>>(
+            catalog: T & ValidateBase<T> & NoExtraLocales<T, L>
+        ): T {
+            return defineMessages(config, catalog as never) as T;
+        },
+
+        /** One deployment: what differs from the defaults. */
+        project<
+            const Catalog extends BaseCatalog<L>,
+            const Routes extends RouteRegistry<L>,
+            const T extends ProjectInput<L, Routes> &
+                ProjectChecks<L, Catalog, Routes, T>,
+        >(
+            messages: Catalog,
+            routes: Routes,
+            project: T & ProjectOverrideChecks<L, Catalog, Routes, T>
+        ): T {
+            return defineProject(
+                config,
+                messages,
+                routes,
+                project as never
+            ) as T;
+        },
+
+        /** The API every page reads, wired for one project. */
+        site<
+            const Catalog extends BaseCatalog<L>,
+            const Routes extends RouteRegistry<L>,
+            const Published extends L,
+            const P extends ProjectInput<L, Routes>,
+        >(
+            messages: Catalog,
+            routes: Routes,
+            project: P & { readonly enabledLocales: readonly Published[] }
+        ): ReturnType<typeof createSite<C, Catalog, Routes, Published, P>> {
+            return createSite(config, messages, routes, project);
+        },
+    };
+}

package/src/site/index.ts

@@ -3,8 +3,8 @@
  *
  * Three files, along the seam between what the API *is* and what builds it:
  *
- * - `api.ts` — the `Site` interface, and the types read back off it
- *   (`RouteIdOf`, `PerRoute`, `WhenEnabled`). The half worth reading.
+ * - `api.ts` — the `Site` interface, and `PerRoute`, read back off it. The
+ *   half worth reading.
  * - `page.ts` — one page's vocabulary: what a view is handed and what it
  *   returns. Nothing here mentions a route registry.
  * - `create.ts` — `createSite`, the closure that satisfies the interface. Its
@@ -15,11 +15,8 @@
 export type {
     LlmsOptions,
     PerRoute,
-    RouteIdOf,
     Site,
-    WhenEnabled,
 } from "./api.ts";
-export { createSite } from "./create.ts";
 export type {
     Alternate,
     Crumb,

package/src/site/page.ts

@@ -40,11 +40,13 @@ export type PageProps<L extends string, Id extends string> = {
      * it needs no guard.
      */
     readonly page: number;
+    /** How many pages this route's list runs to; `1` for a route that does not paginate. */
+    readonly pages: number;
 };
 
-/** One `{ params, props }` pair, shaped for a static-site router. */
+/** One `{ params, props }` pair for `[...route].astro`. */
 export type StaticPath<L extends string, Id extends string> = {
-    readonly params: Readonly<Record<string, string | undefined>>;
+    readonly params: { readonly route: string | undefined };
     readonly props: PageProps<L, Id>;
 };
 

package/src/sitemap.ts

@@ -38,12 +38,6 @@ export interface SitemapConfig {
     readonly entryLimit?: number;
 }
 
-/** One `{ params, props }` pair for a sitemap file, shaped for a static router. */
-export type SitemapStaticPath = {
-    readonly params: Readonly<Record<string, string>>;
-    readonly props: { readonly file: GeneratedFile };
-};
-
 export interface Sitemap {
     /**
      * The file to submit and to reference from `robots.txt`.
@@ -55,33 +49,6 @@ export interface Sitemap {
     readonly entry: GeneratedFile;
     /** Every file that must be served, `entry` included. */
     readonly files: readonly GeneratedFile[];
-
-    /**
-     * Every file to generate, as `{ params, props }` for a dynamic route.
-     *
-     * `param` is the name of the parameter in the router's filename, e.g.
-     * `"sitemap"` for `[sitemap].ts`. One route therefore serves the single
-     * sitemap or the index plus its parts, without the caller knowing which
-     * case it is in.
-     *
-     * Returns a fresh mutable array, because SSG routers typically demand one.
-     */
-    staticPaths(param: string): SitemapStaticPath[];
-}
-
-function toSitemap(
-    entry: GeneratedFile,
-    files: readonly GeneratedFile[]
-): Sitemap {
-    return {
-        entry,
-        files,
-        staticPaths: (param) =>
-            files.map((file) => ({
-                params: { [param]: file.name },
-                props: { file },
-            })),
-    };
 }
 
 export interface SitemapInput<L extends string, Id extends string> {
@@ -235,7 +202,7 @@ export function buildSitemap<L extends string, Id extends string>(
 
     if (chunks.length <= 1) {
         const only = file(input.siteUrl, input.name, urlset(included));
-        return toSitemap(only, [only]);
+        return { entry: only, files: [only] };
     }
 
     const parts = chunks.map((entries, index) =>
@@ -253,5 +220,5 @@ export function buildSitemap<L extends string, Id extends string>(
         )
     );
 
-    return toSitemap(index, [index, ...parts]);
+    return { entry: index, files: [index, ...parts] };
 }

package/src/warn.ts

@@ -2,22 +2,16 @@
  * The one place lib writes to a console.
  *
  * Everything here is a *warning* by definition: a fact about a file or a string
- * that no type can see, worth saying out loud but never worth failing a build
- * over. Errors throw instead, and say so at the point they are wrong.
+ * that no type can see. Errors throw instead, and say so at the point they are
+ * wrong. `ATLAS_STRICT=1` makes every warning throw too, for CI.
  *
- * Shared so the colouring and the `[lib]` prefix are decided once — a warning
+ * Shared so the colouring and the `[atlas]` prefix are decided once — a warning
  * that looks different depending on which module raised it reads like two
  * different tools.
  */
 
-/**
- * What every line lib writes is labelled with.
- *
- * A constant rather than a literal at each call site: grep for it to find every
- * warning the library can raise, and change it once if this folder is ever
- * published under its real name.
- */
-const PREFIX = "lib";
+/** What every line lib writes is labelled with. */
+const PREFIX = "atlas";
 
 /**
  * The escape character, named rather than embedded. 27 is its code point.
@@ -49,12 +43,16 @@ const RESET = `${ESC}[0m`;
  * `process` and simply gets colour, which is what a browser console renders
  * anyway.
  */
-const colour =
-    (
-        globalThis as {
-            process?: { env?: Readonly<Record<string, string | undefined>> };
-        }
-    ).process?.env?.NO_COLOR === undefined;
+const env = (
+    globalThis as {
+        process?: { env?: Readonly<Record<string, string | undefined>> };
+    }
+).process?.env;
+
+const colour = env?.NO_COLOR === undefined;
+
+/** Read per call rather than once, so a test can switch it. */
+const strict = (): boolean => env?.ATLAS_STRICT === "1";
 
 const paint = (code: string, text: string): string =>
     colour ? `${code}${text}${RESET}` : text;
@@ -66,6 +64,7 @@ const paint = (code: string, text: string): string =>
  * always printed, because a warning nobody can locate is one nobody acts on.
  */
 export function warn(at: string, message: string): void {
+    if (strict()) throw new Error(`${shorten(at)}: ${message}`);
     console.warn(
         `${paint(YELLOW, `[${PREFIX}] [WARN]`)} ${paint(DIM, shorten(at))}\n  ${message}`
     );

package/src/astro/dom.ts

@@ -1,35 +0,0 @@
-/**
- * Scoped element lookups, typed.
- *
- * ```ts
- * const { one, all } = within(root);
- * const dots = all<HTMLButtonElement>("[data-carousel-dot]");
- * ```
- *
- * The root is bound once, so a script cannot reach a second copy of itself
- * elsewhere on the page. `document` belongs in one place per script: finding
- * the roots.
- *
- * **A selector with a combinator still matches against the whole document.**
- * `within(form).one("form p")` can match a `<p>` under a different form; only
- * the final filter is scoped. Use `:scope` if a combinator is needed.
- */
-
-export interface Within {
-    /** The first match inside the root, or `null`. */
-    one<T extends Element = HTMLElement>(selector: string): T | null;
-    /** Every match inside the root, as an array rather than a `NodeList`. */
-    all<T extends Element = HTMLElement>(selector: string): T[];
-}
-
-// `HTMLElement` by default because `hidden`, `dataset` and `focus` live there;
-// the bound stays `Element` so inline `<svg>` lookups are not refused.
-export function within(root: ParentNode): Within {
-    return {
-        one: <T extends Element = HTMLElement>(selector: string) =>
-            root.querySelector<T>(selector),
-        all: <T extends Element = HTMLElement>(selector: string) => [
-            ...root.querySelectorAll<T>(selector),
-        ],
-    };
-}