npm - @escape-game-over/atlas - Versions diffs - 0.1.1 - Mend

@escape-game-over/atlas 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (63) hide show

package/README.md +364 -0
package/bin/use-project.mjs +131 -0
package/docs/NOT-BUILT.md +329 -0
package/docs/checks.md +139 -0
package/docs/share-images.md +52 -0
package/docs/toolchain.md +83 -0
package/package.json +51 -0
package/src/analytics/google.ts +351 -0
package/src/analytics/index.ts +102 -0
package/src/analytics/tags.ts +57 -0
package/src/analytics/umami.ts +285 -0
package/src/astro/MetaTags.astro +87 -0
package/src/astro/consent.ts +165 -0
package/src/astro/images.ts +315 -0
package/src/astro/index.ts +44 -0
package/src/astro/public-files.ts +129 -0
package/src/astro/site-routes.ts +307 -0
package/src/config.ts +218 -0
package/src/contact.ts +233 -0
package/src/file.ts +16 -0
package/src/files.ts +39 -0
package/src/hours.ts +312 -0
package/src/i18n/define.ts +217 -0
package/src/i18n/placeholders.ts +94 -0
package/src/i18n/translate.ts +190 -0
package/src/image.ts +29 -0
package/src/index.ts +222 -0
package/src/jsonld/article.ts +165 -0
package/src/jsonld/breadcrumb.ts +34 -0
package/src/jsonld/business.ts +196 -0
package/src/jsonld/ids.ts +106 -0
package/src/jsonld/index.ts +59 -0
package/src/jsonld/node.ts +78 -0
package/src/jsonld/organization.ts +154 -0
package/src/jsonld/place.ts +96 -0
package/src/jsonld/product.ts +172 -0
package/src/jsonld/quantity.ts +55 -0
package/src/jsonld/service.ts +237 -0
package/src/jsonld/video.ts +239 -0
package/src/jsonld/website.ts +58 -0
package/src/llms.ts +160 -0
package/src/meta/content.ts +190 -0
package/src/meta/index.ts +432 -0
package/src/meta/robots.ts +212 -0
package/src/meta/share-image.ts +232 -0
package/src/meta/tag.ts +133 -0
package/src/meta/verification.ts +53 -0
package/src/money.ts +237 -0
package/src/project.ts +249 -0
package/src/redirects.ts +266 -0
package/src/robots.ts +80 -0
package/src/routes/define.ts +412 -0
package/src/routes/family.ts +251 -0
package/src/routes/resolve.ts +266 -0
package/src/site/api.ts +354 -0
package/src/site/create.ts +660 -0
package/src/site/index.ts +32 -0
package/src/site/page.ts +148 -0
package/src/sitemap.ts +257 -0
package/src/types.ts +160 -0
package/src/url.ts +144 -0
package/src/warn.ts +88 -0
package/src/xml.ts +103 -0

package/src/site/page.ts ADDED Viewed

@@ -0,0 +1,148 @@
+import type { MetaContent, MetaTag } from "../meta/index.ts";
+import type { HttpsUrl, UrlPath } from "../url.ts";
+/**
+ * The vocabulary of one page: what a view is handed, and what it hands back.
+ *
+ * Separate from `api.ts`, which describes the site as a whole. Everything here
+ * is about a single document — where it sits, what it says, which slice of a
+ * list it is — and none of it mentions a route registry.
+ */
+export interface LinkOptions {
+    /**
+     * Which page of a paginated list to link to, from 1.
+     *
+     * `1` and `undefined` both give the bare path, because page one *is* the
+     * bare path — so a loop over page numbers needs no special case for the
+     * first, and cannot produce a `/page/1` that was never built.
+     */
+    readonly page?: number;
+    /** Without the leading `#`. */
+    readonly hash?: string;
+    readonly query?: Readonly<Record<string, string>>;
+}
+/**
+ * Props for one generated page.
+ *
+ * A type alias, not an interface: SSG frameworks require props to be assignable
+ * to an index-signature type, which interfaces are not.
+ */
+export type PageProps<L extends string, Id extends string> = {
+    readonly routeId: Id;
+    readonly locale: L;
+    /**
+     * Which page of this route's list to render, from 1.
+     *
+     * Always present, and `1` for a route that does not paginate — a view that
+     * ignores it renders the only page there is, and one that slices a list by
+     * it needs no guard.
+     */
+    readonly page: number;
+};
+/** One `{ params, props }` pair, shaped for a static-site router. */
+export type StaticPath<L extends string, Id extends string> = {
+    readonly params: Readonly<Record<string, string | undefined>>;
+    readonly props: PageProps<L, Id>;
+};
+/** Everything one page's `<html>` and `<head>` need. */
+export interface PageMeta {
+    /** For `<html lang dir>` — this page's locale, not the site default. */
+    readonly lang: string;
+    readonly dir: "ltr" | "rtl";
+    /** Everything for `<head>`, which is nearly everything. */
+    readonly tags: MetaTag[];
+    /**
+     * For immediately after `<body>`, and usually empty.
+     *
+     * Its own list because one thing lib emits genuinely belongs there — Tag
+     * Manager's `<noscript>` iframe, which the head ignores. A layout renders
+     * both, and cannot put either in the other's place.
+     */
+    readonly bodyTags: MetaTag[];
+}
+/**
+ * What a page passes to `metaFor`: its words, its picture, its trail, and which
+ * page of a list it is.
+ *
+ * `MetaContent` is about a *document* — the title, the description, the share
+ * image — and knows nothing of a site around it. The two fields here are what a
+ * document cannot answer alone: where it sits among other pages, and which
+ * slice of a list it shows.
+ *
+ * No longer generic over `RouteId`. It was, while a callback named each step of
+ * the trail and had to be handed ids this project actually builds. The trail
+ * now arrives finished, so nothing here mentions a route.
+ */
+export type PageContent = MetaContent & PageExtras;
+/**
+ * The two things a document cannot answer about itself.
+ *
+ * Split out because `MetaContent` is an intersection with a union — an
+ * interface cannot extend one — and the union is what stops a page being both
+ * an article and something else.
+ */
+interface PageExtras {
+    /**
+     * Which page of a paginated list this is, from 1.
+     *
+     * Pass `Astro.props.page` straight through. It is what makes page 2
+     * canonical to itself rather than to the list — *"don't use the first page
+     * of a paginated sequence as the canonical page"* — and what points its
+     * `hreflang` alternates at page 2 of each other language instead of at
+     * their first.
+     *
+     * Omitted is page one, so an unpaginated view says nothing and is right.
+     */
+    readonly page?: number;
+    /**
+     * The trail, already built — by `breadcrumbFor`, which is what knows a
+     * route's ancestors.
+     *
+     * Handed over rather than derived here from callbacks, because the page
+     * renders this same trail and the two have to be one array. Callbacks meant
+     * two places building it from the same rules: two places to keep in step,
+     * and one of them wrong the moment a rule gained a case. The version this
+     * replaced pointed a paginated list's own crumb at page one, so the
+     * structured data on page three claimed to be page one.
+     *
+     * Omit it and no breadcrumb is emitted.
+     */
+    readonly breadcrumb?: readonly Crumb[];
+}
+/**
+ * One step of a breadcrumb trail: what it is called, and where it goes.
+ *
+ * Both forms of the destination, as `Alternate` carries both, because the two
+ * readers want different ones. A link in the page wants the path — an absolute
+ * one sends a developer from localhost to the production host mid-click — while
+ * structured data requires the absolute URL.
+ */
+export interface Crumb {
+    readonly name: string;
+    /** Root-relative, for an `href`. */
+    readonly path: UrlPath;
+    /** Absolute, for structured data. */
+    readonly url: HttpsUrl;
+}
+export interface Alternate<L extends string> {
+    readonly locale: L;
+    readonly path: UrlPath;
+    readonly url: HttpsUrl;
+}
+/** One entry in a language switcher: where it goes, and how to label it. */
+export interface LocaleLink<L extends string> extends Alternate<L> {
+    /** The language's name, written in that language. */
+    readonly label: string;
+    readonly htmlLang: string;
+    readonly dir: "ltr" | "rtl";
+    readonly isCurrent: boolean;
+}

package/src/sitemap.ts ADDED Viewed

@@ -0,0 +1,257 @@
+import type { ResolvedLocaleMeta } from "./config.ts";
+import type { GeneratedFile } from "./file.ts";
+import type { RouteEntry } from "./routes/resolve.ts";
+import { type HttpsUrl, joinUrl } from "./url.ts";
+import { el, renderXmlDocument, type XmlElement } from "./xml.ts";
+const SITEMAP_NS = "http://www.sitemaps.org/schemas/sitemap/0.9";
+const XHTML_NS = "http://www.w3.org/1999/xhtml";
+const XML_CONTENT_TYPE = "application/xml; charset=utf-8";
+/**
+ * What the sitemaps.org spec allows in one file. A file above it is not a
+ * large sitemap, it is a rejected one.
+ *
+ * A value rather than a sentence in two doc comments, because two things need
+ * it: the default below sits under it, and `checkEntryLimit` refuses anything
+ * over it. Written once, so the number in the error cannot drift from the
+ * number that produced it.
+ */
+const SPEC_MAX_ENTRIES = 50_000;
+/** Under the cap, with headroom — see `SPEC_MAX_ENTRIES`. */
+const DEFAULT_ENTRY_LIMIT = 45_000;
+/** How a site configures its sitemap. Part of `site.config.ts`. */
+export interface SitemapConfig {
+    /** Filename the sitemap is served under. Defaults to `sitemap.xml`. */
+    readonly name?: string;
+    /**
+     * Maximum URLs per file before the sitemap splits into an index plus
+     * numbered parts. Defaults to 45000 (the spec caps a file at 50000).
+     *
+     * A whole number from 1 to 50000, the most the spec allows in one file.
+     * Anything else throws at build rather than being clamped — see
+     * `checkEntryLimit` for why this one is not forgiving, and for what a value
+     * on either side of the range would otherwise do.
+     */
+    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`.
+     *
+     * Always keeps the configured name, so the public URL is stable whether or
+     * not the sitemap ended up split: it is the single sitemap when everything
+     * fits, and the index when it does not.
+     */
+    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> {
+    readonly siteUrl: HttpsUrl;
+    readonly name: string;
+    readonly entryLimit?: number;
+    readonly entries: readonly RouteEntry<L, Id>[];
+    readonly localeMeta: Readonly<Record<L, ResolvedLocaleMeta>>;
+    /**
+     * Alternates for one route, so each URL can advertise its translations.
+     *
+     * Takes the page as well as the id, and must: a paginated route emits an
+     * entry per page, and asking without one would answer for page 1 every
+     * time — so `/news/page/2` would advertise `/news` as its own translation,
+     * never reference itself, and declare the same alternate cluster the list
+     * does. Google discards a cluster whose members disagree rather than
+     * picking a winner, so that is the whole route's `hreflang` lost, not one
+     * URL's.
+     *
+     * Structural rather than `LinkOptions`, which lives in `site/` and imports
+     * this module — the shape is the contract, and naming the type would be a
+     * cycle.
+     */
+    readonly alternatesFor: (
+        id: Id,
+        options?: { readonly page?: number }
+    ) => readonly { readonly locale: L; readonly url: HttpsUrl }[];
+}
+/** `sitemap.xml` -> `sitemap-0.xml`, keeping whatever extension was configured. */
+function partName(name: string, index: number): string {
+    const dot = name.lastIndexOf(".");
+    return dot === -1
+        ? `${name}-${index}`
+        : `${name.slice(0, dot)}-${index}${name.slice(dot)}`;
+}
+/**
+ * The cap a sitemap splits at, checked before anything divides by it.
+ *
+ * Two ways to get it wrong, and both are caught here because both fail
+ * silently in their own way.
+ *
+ * *Too small* — zero or less, or a fraction. Thrown rather than clamped, which
+ * is the opposite of what `pages` on a route wants, and the difference is
+ * whether the wrong value means anything: a route computing `pages: 0` from an
+ * empty list plainly means "one page", so lib normalises it, while "at most
+ * zero URLs per file" describes no sitemap at all. And the consequence is not a
+ * bad file, it is no build — `chunk` advances by this value, so zero or less
+ * loops forever, allocating until the process is killed with nothing said about
+ * why.
+ *
+ * *Too large* — over `SPEC_MAX_ENTRIES`. This one builds perfectly and produces
+ * a file a search engine refuses to read, which is the worse failure of the
+ * two: splitting is the whole point of the field, and a limit above the cap
+ * quietly switches it off.
+ */
+function checkEntryLimit(limit: number): void {
+    if (Number.isInteger(limit) && limit > 0 && limit <= SPEC_MAX_ENTRIES) {
+        return;
+    }
+    throw new Error(
+        `sitemap.entryLimit is ${limit}, which is not a number of URLs one file can hold: it wants a whole number from 1 to ${SPEC_MAX_ENTRIES}, the most the sitemaps.org spec allows in a file.`
+    );
+}
+function chunk<T>(
+    items: readonly T[],
+    size: number
+): readonly (readonly T[])[] {
+    if (items.length <= size) return [items];
+    const chunks: T[][] = [];
+    for (let i = 0; i < items.length; i += size) {
+        chunks.push(items.slice(i, i + size));
+    }
+    return chunks;
+}
+function file(
+    siteUrl: HttpsUrl,
+    name: string,
+    root: XmlElement
+): GeneratedFile {
+    return {
+        name,
+        url: joinUrl(siteUrl, `/${name}`),
+        body: renderXmlDocument(root),
+        contentType: XML_CONTENT_TYPE,
+    };
+}
+/**
+ * Renders the sitemap from the same route entries the pages are built from, so
+ * a retranslated slug or a switched-off page can never drift out of sync with it.
+ *
+ * Each URL carries `xhtml:link` alternates for its other locales, which is how
+ * search engines are told these are translations of one page rather than
+ * duplicates. Astro's own sitemap integration cannot express this: it pairs
+ * locales by matching the path after the locale prefix, which translated slugs
+ * never share.
+ *
+ * Above `entryLimit` URLs the result splits into an index plus numbered parts.
+ */
+export function buildSitemap<L extends string, Id extends string>(
+    input: SitemapInput<L, Id>
+): Sitemap {
+    // Before anything divides by it. A project supplies this as a plain
+    // `number` and nothing else stands between the config and the loop.
+    const entryLimit = input.entryLimit ?? DEFAULT_ENTRY_LIMIT;
+    checkEntryLimit(entryLimit);
+    const included = input.entries.filter((entry) => !entry.sitemap?.exclude);
+    const urlFor = (entry: RouteEntry<L, Id>): XmlElement => {
+        return el("url", [
+            el("loc", joinUrl(input.siteUrl, entry.path)),
+            // This entry's own page, so each URL advertises the same-numbered
+            // page of every other locale. Safe for an unpaginated route:
+            // `pathFor` reads page 1 and the bare path as the same thing, and
+            // every locale of a route shares one `pages` count — so a page that
+            // produced an entry here exists in all of them.
+            ...input
+                .alternatesFor(entry.routeId, { page: entry.page })
+                .map((alternate) =>
+                    el("xhtml:link", {
+                        rel: "alternate",
+                        hreflang: input.localeMeta[alternate.locale].htmlLang,
+                        href: alternate.url,
+                    })
+                ),
+            entry.sitemap?.lastmod !== undefined &&
+                el("lastmod", entry.sitemap.lastmod),
+            entry.sitemap?.changefreq !== undefined &&
+                el("changefreq", entry.sitemap.changefreq),
+            entry.sitemap?.priority !== undefined &&
+                el("priority", entry.sitemap.priority.toFixed(1)),
+        ]);
+    };
+    const urlset = (entries: readonly RouteEntry<L, Id>[]): XmlElement =>
+        el(
+            "urlset",
+            { xmlns: SITEMAP_NS, "xmlns:xhtml": XHTML_NS },
+            entries.map(urlFor)
+        );
+    const chunks = chunk(included, entryLimit);
+    if (chunks.length <= 1) {
+        const only = file(input.siteUrl, input.name, urlset(included));
+        return toSitemap(only, [only]);
+    }
+    const parts = chunks.map((entries, index) =>
+        file(input.siteUrl, partName(input.name, index), urlset(entries))
+    );
+    // The index keeps the configured name, so the submitted URL never changes.
+    const index = file(
+        input.siteUrl,
+        input.name,
+        el(
+            "sitemapindex",
+            { xmlns: SITEMAP_NS },
+            parts.map((part) => el("sitemap", [el("loc", part.url)]))
+        )
+    );
+    return toSitemap(index, [index, ...parts]);
+}

package/src/types.ts ADDED Viewed

@@ -0,0 +1,160 @@
+/**
+ * Small type utilities shared across `lib/`.
+ *
+ * Each one names an idiom that is otherwise easy to misread — or, in the case of
+ * `IsNever` and `NoExcessKeys`, easy to get subtly wrong.
+ */
+/**
+ * The string keys of `T`.
+ *
+ * Plain `keyof T` is `string | number | symbol`, which breaks template literal
+ * types like `` `route.${K}.title` ``. Every key we care about is a string.
+ */
+export type StringKeys<T> = keyof T & string;
+/**
+ * `true` when `T` is exactly `never`.
+ *
+ * The tuple wrappers are load-bearing: a bare `T extends never ? …` is a
+ * *distributive* conditional, and distributing over `never` produces `never` —
+ * so the check silently never runs. Wrapping both sides turns off distribution.
+ */
+export type IsNever<T> = [T] extends [never] ? true : false;
+/**
+ * Rejects any key of `T` that is not in `Allowed`, by demanding those keys hold
+ * `never` — a type no value has.
+ *
+ * Needed because these helpers *infer* `T` from the argument: the object literal
+ * becomes the type rather than being checked against a fixed target, so ordinary
+ * excess-property checking has nothing to compare against. Use it in a
+ * self-referential constraint:
+ *
+ * ```ts
+ * function f<const T extends Shape & NoExcessKeys<T, KnownIds>>(value: T): T
+ * ```
+ */
+export type NoExcessKeys<T, Allowed extends PropertyKey> = Readonly<
+    Record<Exclude<keyof T, Allowed>, never>
+>;
+type Month =
+    | "01"
+    | "02"
+    | "03"
+    | "04"
+    | "05"
+    | "06"
+    | "07"
+    | "08"
+    | "09"
+    | "10"
+    | "11"
+    | "12";
+type Day =
+    | "01"
+    | "02"
+    | "03"
+    | "04"
+    | "05"
+    | "06"
+    | "07"
+    | "08"
+    | "09"
+    | "10"
+    | "11"
+    | "12"
+    | "13"
+    | "14"
+    | "15"
+    | "16"
+    | "17"
+    | "18"
+    | "19"
+    | "20"
+    | "21"
+    | "22"
+    | "23"
+    | "24"
+    | "25"
+    | "26"
+    | "27"
+    | "28"
+    | "29"
+    | "30"
+    | "31";
+export type Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
+/**
+ * One uppercase letter, for the code standards that are spelled in them.
+ *
+ * Beside `Digit` because it is the same kind of thing: a character class the
+ * template-literal types elsewhere are built from, rather than anything about
+ * this library's own subject.
+ */
+export type Letter =
+    | "A"
+    | "B"
+    | "C"
+    | "D"
+    | "E"
+    | "F"
+    | "G"
+    | "H"
+    | "I"
+    | "J"
+    | "K"
+    | "L"
+    | "M"
+    | "N"
+    | "O"
+    | "P"
+    | "Q"
+    | "R"
+    | "S"
+    | "T"
+    | "U"
+    | "V"
+    | "W"
+    | "X"
+    | "Y"
+    | "Z";
+/**
+ * A calendar date, `YYYY-MM-DD`.
+ *
+ * Checked by the type system rather than at build time, so `"2026-3-1"`,
+ * `"01/03/2026"`, `"2026-13-01"` and `"2026-03-01T00:00:00Z"` are all rejected
+ * on the line where they were written — as is a bare `string`, which is the case
+ * a runtime check would have had to exist for.
+ *
+ * Every part is spelled out digit by digit rather than left as a `${number}`
+ * pattern, which would also admit `"1e3-03-01"` and five-digit years. That costs
+ * 100 × 12 × 31 = 37 200 members, comfortably inside what TypeScript will hold;
+ * a full four-digit year would be 10 000 × 372 and far past it. The price is
+ * that this needs one more digit in 2100.
+ */
+export type IsoDate = `20${Digit}${Digit}-${Month}-${Day}`;
+/**
+ * A whole percentage, `0` to `100`.
+ *
+ * Built by counting rather than written out, which is the one place this file
+ * departs from spelling a union in full: a hundred and one literals is not
+ * readable, and the rule producing them is. `Acc["length"]` grows by one per
+ * step until it reaches the target, and every length along the way is a member.
+ *
+ * The ceiling is TypeScript's instantiation depth, and it is lower in practice
+ * than the thousand the limit suggests — measured in this project, `Upto<1000>`
+ * reports "excessively deep" and `Upto<512>` does not. Well above a percentage,
+ * and worth knowing before reaching for a wider range: pick the bound the
+ * domain justifies and check it compiles.
+ */
+type Upto<N extends number, Acc extends number[] = []> = Acc["length"] extends N
+    ? Acc[number]
+    : Upto<N, [...Acc, Acc["length"]]>;
+export type Percentage = Upto<101>;