@escape-game-over/atlas 0.1.1

package/src/contact.ts

@@ -0,0 +1,233 @@
+import type { Digit, Letter } from "./types.ts";
+import { warn } from "./warn.ts";
+
+/**
+ * The contact details every site puts in a footer, and the links they make.
+ *
+ * Here because the formatting is mechanical and every consuming repo would
+ * otherwise write the same `replace(/\s+/g, "")` in a component — where it looks
+ * like a detail of that component rather than a rule about telephone numbers.
+ *
+ * Plain data and free functions, not objects with methods: these are written in
+ * a project's settings file, and a factory call would turn a page of data into a
+ * page of code. They also have to survive being handed to structured data, which
+ * wants strings.
+ */
+
+/**
+ * A country calling code: one to three digits, and nothing else.
+ *
+ * Spelled out from `Digit` rather than as `` `${number}` ``, which looks right
+ * and checks almost nothing — it accepts `"+39"` and `"3.9"` alike, so the very
+ * mistakes this is meant to reject would pass.
+ */
+export type CallingCode =
+    | `${Digit}`
+    | `${Digit}${Digit}`
+    | `${Digit}${Digit}${Digit}`;
+
+/**
+ * A telephone number, kept as the two facts it actually is.
+ *
+ * The calling code is separate because the national part is written however the
+ * country writes it — `06 0000 0000`, `(020) 7123 4567` — and stripping that
+ * formatting to build a dialable link is only safe once the code is known.
+ * Storing one joined string means every reader guessing where one ends.
+ *
+ * Not locale-varying, unlike a *displayed* address: spacing and the leading `+`
+ * are conventions of the number's country, not of the language it is read in. An
+ * Italian venue prints `+39 06 …` on its Greek pages too.
+ */
+export interface PhoneNumber {
+    /**
+     * Country calling code, digits only: `"39"`, `"30"`, `"1"`.
+     *
+     * Without the `+`, which is not part of the code — Italy's code *is* 39.
+     * The plus is notation for "dial internationally", and both formatters below
+     * add it, so storing it would only be a character every venue has to
+     * remember and every reader has to strip.
+     */
+    readonly code: CallingCode;
+    /**
+     * The **national significant number** — what follows the country code when
+     * dialling from abroad, spaced however the country groups it.
+     *
+     * Not the domestic form, and the difference is one digit that matters. Most
+     * countries put a *trunk prefix* in front for local dialling — a leading `0`
+     * in the UK, Romania, Germany, France — which is not part of the number and
+     * does not belong here: London's `020 7123 4567` is written `20 7123 4567`.
+     * Italy is the standard exception and keeps its zero, because there the `0`
+     * *is* part of the number: Rome's `06 …` stays `06 …`. Greece has no trunk
+     * prefix at all, so its numbers are written as they are said.
+     *
+     * lib does not strip anything, which is what makes both readings possible:
+     * a rule that dropped the leading zero would be right for London and would
+     * leave Rome with no way to spell itself correctly. The cost is that this
+     * field has one right answer per country rather than "however it looks on
+     * the door", and getting it wrong is visible — `formatPhone` and `e164` read
+     * the same digits, so a stray trunk prefix shows up on the page as
+     * `+44 020 …` rather than hiding in a `tel:` nobody inspects.
+     */
+    readonly number: string;
+}
+
+/**
+ * The number as a person reads it: `+39 06 0000 0000`.
+ *
+ * The stored formatting is kept rather than normalised — whoever wrote it knows
+ * how their country groups its digits, and no general rule does.
+ */
+export function formatPhone(phone: PhoneNumber): string {
+    return `+${phone.code} ${phone.number}`;
+}
+
+/**
+ * The number as a phone dials it: `tel:+390600000000`.
+ *
+ * E.164 — a plus, then digits, nothing else. Spaces, brackets and dashes are
+ * presentation, and a `tel:` containing them is at best ignored and at worst
+ * dialled wrongly.
+ *
+ * The digits themselves are whatever `number` holds — see it. Nothing is added
+ * and nothing is removed, so this and `formatPhone` are two renderings of one
+ * value rather than two opinions about it.
+ */
+export function telHref(phone: PhoneNumber): string {
+    return `tel:${e164(phone)}`;
+}
+
+/**
+ * The number in E.164: `+390600000000`.
+ *
+ * The same digits `telHref` dials, without the scheme — which is what
+ * structured data wants, and the only form that identifies a number
+ * unambiguously enough to match a business against a listing.
+ *
+ * **Only punctuation is removed.** This used to strip a leading zero as well,
+ * on the rule that it is always a trunk prefix — true across most of Europe and
+ * false in Italy, where the zero is part of the number, so Rome shipped
+ * `+396…`, which reaches nothing. There was no way to write it correctly: `06`,
+ * `006` and `6` all came out the same.
+ *
+ * A rule here could only be right for one of the two, and lib has no business
+ * knowing which countries keep their zero — that is a list it would carry, get
+ * subtly wrong, and apply silently. So the digits are the project's to state,
+ * and `PhoneNumber.number` says what to state. Checked August 2026.
+ *
+ * `replace(/^0+/, "")` also took *every* leading zero rather than one trunk
+ * digit, so `007…` became `7…`.
+ */
+export function e164(phone: PhoneNumber): string {
+    return `+${phone.code}${phone.number.replace(/\D/g, "")}`;
+}
+
+/** An email address, which is only ever used whole. */
+export type EmailAddress = `${string}@${string}`;
+
+export function mailtoHref(email: EmailAddress): string {
+    return `mailto:${email}`;
+}
+
+/**
+ * An ISO 3166-1 alpha-2 country code: `"IT"`, `"GR"`, `"RO"`.
+ *
+ * Two uppercase letters, which is what `addressCountry` is read as. A name —
+ * `"Italy"`, `"Ιταλία"` — is a translation of a country rather than an
+ * identifier for one, and belongs in the sentence a page prints, not here.
+ */
+export type CountryCode = `${Letter}${Letter}`;
+
+/**
+ * Where a place is, to the precision a map needs.
+ *
+ * Both halves required, and the pair optional as a whole — which is the point
+ * of it being an object. Half a coordinate is not half an answer: a latitude
+ * with no longitude describes a line around the earth, and a type that allowed
+ * it would be describing something no venue means.
+ *
+ * Not a substitute for the postal address, and not derived from one. This is
+ * the door; an address is how the post office finds the building, and for a
+ * venue down a side street the two are not the same point.
+ */
+export interface Coordinates {
+    /** Degrees north, negative for south. */
+    readonly latitude: number;
+    /** Degrees east, negative for west. */
+    readonly longitude: number;
+}
+
+/** Decimal places, for the precision check below. */
+function decimals(value: number): number {
+    return String(value).split(".")[1]?.length ?? 0;
+}
+
+/**
+ * Rejects a coordinate that cannot be a venue, and warns about a coarse one.
+ *
+ * `0,0` throws. It is the Gulf of Guinea, and far more often it is what a
+ * failed lookup returned — a pair of zeroes reaching structured data is a bug
+ * upstream, never a location.
+ *
+ * Throws rather than warns even for a site still being built, because the whole
+ * field is optional: a venue that has not looked its coordinates up yet leaves
+ * them out and nothing is emitted. `0,0` is not the absence of a location, it
+ * is a claim about a specific patch of ocean, and a warning would let that
+ * claim ship.
+ *
+ * Precision only warns, and at four places rather than the five Google asks
+ * for, because a `number` cannot carry the difference. `41.89490` is written
+ * with five and stored as `41.8949`, so counting the decimals of the stored
+ * value would fail one correct coordinate in ten for having a zero at the end —
+ * a build broken by data that was right. What the warning still catches is the
+ * real mistake: a value pasted at two or three places, which is a hundred
+ * metres out and puts the pin on the wrong block.
+ */
+export function assertCoordinates(where: Coordinates, at: string): void {
+    if (where.latitude === 0 && where.longitude === 0) {
+        throw new Error(
+            `${at}: coordinates are 0,0 — the Gulf of Guinea, and what a failed lookup returns. Leave them out entirely until you have real ones: the field is optional, and no location beats a wrong one.`
+        );
+    }
+
+    const coarse = (["latitude", "longitude"] as const).filter(
+        (axis) => decimals(where[axis]) < 4
+    );
+    if (coarse.length > 0) {
+        warn(
+            at,
+            `${coarse.join(" and ")} ${coarse.length === 1 ? "is" : "are"} rounded to fewer than four decimal places, which places the pin to within about a hundred metres rather than on the door. Take the value from a map rather than shortening it.`
+        );
+    }
+}
+
+/**
+ * A postal address, in its parts.
+ *
+ * **Canonical, not displayed.** This is the address as the post office writes
+ * it — `Roma`, not `Rome` or `Ρώμη` — because that is what `PostalAddress` is
+ * read as, and what matches a business against a place. What a *page* shows is a
+ * different thing: translated, written for the reader, and living in the catalog
+ * beside every other line of copy.
+ *
+ * The two look like duplication and are not. One is a record, one is a sentence,
+ * and a Greek page that printed `Roma` would be as wrong as structured data that
+ * claimed the town was called `Ρώμη`.
+ */
+export interface PostalAddress {
+    /** Street and number: `"Via Nazionale 100"`. */
+    readonly street: string;
+    /** Town or city, in its own language: `"Roma"`. */
+    readonly locality: string;
+    /** Postal or ZIP code, as written locally. */
+    readonly postalCode: string;
+    /**
+     * The country, as its two-letter code: `"IT"`, not `"Italy"`.
+     *
+     * A code rather than a name because this field identifies a country to a
+     * machine, and every country has as many names as there are languages. The
+     * name a page prints is a translation, and lives with the rest of the copy.
+     */
+    readonly country: CountryCode;
+    /** State, province or region, where the country uses one. */
+    readonly region?: string;
+}

package/src/file.ts

@@ -0,0 +1,16 @@
+/**
+ * A file the build has to emit but no page renders — a sitemap, a `robots.txt`.
+ *
+ * It lives on its own because more than one feature produces one, and each of
+ * those features would otherwise have to reach into another for the shape.
+ */
+import type { HttpsUrl } from "./url.ts";
+
+export interface GeneratedFile {
+    /** e.g. `"sitemap.xml"` — the filename the route must use. */
+    readonly name: string;
+    /** Absolute URL, for `robots.txt` and search-console submissions. */
+    readonly url: HttpsUrl;
+    readonly body: string;
+    readonly contentType: string;
+}

package/src/files.ts

@@ -0,0 +1,39 @@
+import type { SitePath } from "./redirects.ts";
+
+/**
+ * The hook a project hangs its `public/` directory on.
+ *
+ * Empty here, and filled in by declaration merging — the same trick Vite uses
+ * for `ImportMetaEnv`. It exists because the union can only be known by reading
+ * a directory, which lib cannot do and must not import from a project, while the
+ * types that *use* it — `fileUrl`, a redirect target — live here.
+ *
+ * The `publicFiles()` integration writes the augmentation, so nothing needs
+ * writing by hand:
+ *
+ * ```ts
+ * declare module "@escape-game-over/atlas" {
+ *     interface PublicFileRegistry {
+ *         path: "/reports/annual-report-2026.pdf";
+ *     }
+ * }
+ * ```
+ */
+// Only an interface can be merged into, so this must not become a type alias —
+// it is a hook for a project's augmentation, not a lazy annotation.
+// biome-ignore lint/suspicious/noEmptyInterface: the emptiness is the point.
+export interface PublicFileRegistry {}
+
+/**
+ * A path to a file in `public/`.
+ *
+ * The project's own union once `publicFiles()` has run, so a mistyped or deleted
+ * file is a compile error and an editor offers the real ones. Falls back to any
+ * site path when the integration is not in use — a check nobody has opted into
+ * should not turn every link into an error.
+ */
+export type PublicFilePath = PublicFileRegistry extends {
+    readonly path: infer Path extends string;
+}
+    ? Path
+    : SitePath;

package/src/hours.ts

@@ -0,0 +1,312 @@
+import type { Digit } from "./types.ts";
+
+/**
+ * When a venue is open, as a week rather than a sentence.
+ *
+ * Two readers want this and want it differently: a footer prints "Mon–Thu & Sun
+ * 14:00–23:30", and `openingHoursSpecification` wants a day list with `opens`
+ * and `closes`. Both are views of the same fact, so the fact is stored once —
+ * per day, unambiguously — and each view is derived. A project that wrote the
+ * sentence by hand would eventually have a footer disagreeing with its own
+ * structured data, and only one of them would be visible.
+ */
+
+/** `00`–`23`. Spelled out so `24:00` and `9:00` are both rejected. */
+type Hour = `0${Digit}` | `1${Digit}` | `2${"0" | "1" | "2" | "3"}`;
+
+/** `00`–`59`. */
+type Minute = `${"0" | "1" | "2" | "3" | "4" | "5"}${Digit}`;
+
+/**
+ * A wall-clock time, 24-hour: `"14:00"`, `"00:45"`.
+ *
+ * The full union of valid times rather than `` `${number}:${number}` ``, which
+ * would accept `"25:99"` — the whole point is that a typo in the one field
+ * nobody proofreads is caught by the compiler rather than published.
+ *
+ * No seconds: no venue opens at 14:00:30, and schema.org reads `HH:MM` fine.
+ */
+export type TimeOfDay = `${Hour}:${Minute}`;
+
+const WEEK = [
+    "monday",
+    "tuesday",
+    "wednesday",
+    "thursday",
+    "friday",
+    "saturday",
+    "sunday",
+] as const;
+
+/**
+ * A day of the week, lowercase.
+ *
+ * Derived from `WEEK` so the type and the order cannot drift apart. Lowercase
+ * because these are identifiers — a project translates them for display, and
+ * schema.org's capitalised names are produced when serialising.
+ */
+export type Weekday = (typeof WEEK)[number];
+
+/**
+ * A span of opening, which may run past midnight.
+ *
+ * `closes` earlier than `opens` means the next day: `14:00`–`00:45` is a venue
+ * that shuts at quarter to one in the morning. This is the convention
+ * `openingHoursSpecification` is read with, and it is why a range is stored as
+ * two times rather than a start and a duration.
+ */
+export interface TimeRange {
+    readonly opens: TimeOfDay;
+    readonly closes: TimeOfDay;
+}
+
+/**
+ * One day: shut, or one or more spans.
+ *
+ * `"closed"` rather than an empty array, and the array cannot *be* empty — one
+ * way to say each thing. An empty list reads as an oversight, and a day nobody
+ * filled in should not be indistinguishable from a day off.
+ *
+ * Several spans cover a venue that shuts for the afternoon.
+ */
+export type DayHours = "closed" | readonly [TimeRange, ...TimeRange[]];
+
+/**
+ * The whole week, every day stated.
+ *
+ * A `Record` of all seven rather than a list of spans: forgetting Wednesday is
+ * then a compile error instead of a day quietly missing from a knowledge panel,
+ * and the same day cannot be listed twice with different hours.
+ */
+export type WeeklyHours = Readonly<Record<Weekday, DayHours>>;
+
+/** Days that share the same hours, ready to be printed or serialised. */
+export interface HoursGroup {
+    /** Every day in the group, in week order. */
+    readonly days: readonly [Weekday, ...Weekday[]];
+    /**
+     * The same days as consecutive spans: `[["monday", "thursday"],
+     * ["sunday", "sunday"]]` is what a footer renders as "Mon–Thu & Sun".
+     *
+     * A single-day span has the same day at both ends, so a caller never has to
+     * special-case one — it can compare the two and print one name.
+     */
+    readonly runs: readonly (readonly [Weekday, Weekday])[];
+    readonly hours: DayHours;
+}
+
+/** The week rotated to start where a locale starts it. */
+function weekFrom(start: Weekday): readonly Weekday[] {
+    const index = WEEK.indexOf(start);
+    return [...WEEK.slice(index), ...WEEK.slice(0, index)];
+}
+
+/** Identity of a day's hours, so two days can be compared for sameness. */
+function keyOf(hours: DayHours): string {
+    return hours === "closed"
+        ? "closed"
+        : hours.map((range) => `${range.opens}-${range.closes}`).join(",");
+}
+
+/**
+ * The week collapsed to its distinct sets of hours.
+ *
+ * Groups appear in the order their first day does, and closed days group like
+ * any other — a footer that wants to print "Sunday: closed" has it, and one
+ * that does not can filter.
+ *
+ * `weekStart` changes the answer rather than only the order: with Monday first,
+ * a venue open Sunday through Thursday reads "Mon–Thu & Sun"; with Sunday
+ * first, the same week is one run, "Sun–Thu". Runs do not wrap around the end
+ * of the week, which is what keeps those two different.
+ */
+export function groupHours(
+    hours: WeeklyHours,
+    weekStart: Weekday = "monday"
+): readonly HoursGroup[] {
+    const groups = new Map<
+        string,
+        {
+            days: [Weekday, ...Weekday[]];
+            runs: [Weekday, Weekday][];
+            hours: DayHours;
+        }
+    >();
+
+    let previousKey: string | undefined;
+    for (const day of weekFrom(weekStart)) {
+        const dayHours = hours[day];
+        const key = keyOf(dayHours);
+        const group = groups.get(key);
+
+        // A group is created holding its first day rather than empty, which is
+        // what lets `days` be a non-empty tuple without a cast: there is no
+        // moment at which an empty group exists.
+        if (group === undefined) {
+            groups.set(key, {
+                days: [day],
+                runs: [[day, day]],
+                hours: dayHours,
+            });
+        } else {
+            group.days.push(day);
+            const lastRun = group.runs.at(-1);
+            if (key === previousKey && lastRun !== undefined) {
+                lastRun[1] = day;
+            } else {
+                group.runs.push([day, day]);
+            }
+        }
+        previousKey = key;
+    }
+
+    return [...groups.values()];
+}
+
+/**
+ * The words a printed week needs, which lib does not have.
+ *
+ * Day names and "closed" are copy: they are translated, and lib holds no copy.
+ * Everything else about the line — which days collapse into a span, what order
+ * they come in, where the dashes go — is mechanical and is done here, because
+ * otherwise every project rewrites the same joins in a component.
+ */
+export interface HoursFormat {
+    /** What to call a day. Usually a lookup in the project's catalog. */
+    day(day: Weekday): string;
+    /** The word for a day the venue is shut. */
+    closed: string;
+    /** Between the ends of a span: `Mon–Thu`, `14:00–23:30`. */
+    between?: string;
+    /** Between spans: `Mon–Thu, Sun`. */
+    and?: string;
+    /** Where the week starts, which changes how days collapse. */
+    weekStart?: Weekday;
+}
+
+/** One line of a printed week: which days, and when. */
+export interface FormattedHours {
+    /** `"Mon–Thu, Sun"`. */
+    readonly days: string;
+    /** `"14:00–23:30"`, or the word for closed. */
+    readonly times: string;
+}
+
+/**
+ * The week as lines ready to print.
+ *
+ * Two strings rather than one so a footer can lay them out as a table and have
+ * the times line up; a caller wanting a sentence joins them itself.
+ *
+ * A run of one day prints as one name — `Sun`, not `Sun–Sun` — which is the
+ * special case every hand-written version of this forgets.
+ */
+export function formatHours(
+    hours: WeeklyHours,
+    format: HoursFormat
+): readonly FormattedHours[] {
+    const between = format.between ?? "–";
+    const and = format.and ?? ", ";
+
+    return groupHours(hours, format.weekStart).map((group) => ({
+        days: group.runs
+            .map(([first, last]) =>
+                first === last
+                    ? format.day(first)
+                    : `${format.day(first)}${between}${format.day(last)}`
+            )
+            .join(and),
+        times:
+            group.hours === "closed"
+                ? format.closed
+                : group.hours
+                      .map((range) => `${range.opens}${between}${range.closes}`)
+                      .join(and),
+    }));
+}
+
+/** Minutes since midnight, for comparing two times. */
+function minutes(time: TimeOfDay): number {
+    return Number(time.slice(0, 2)) * 60 + Number(time.slice(3, 5));
+}
+
+/**
+ * Throws on a week that type-checks but cannot be true.
+ *
+ * The type stops a bad *time*; it cannot stop a bad *week*. Overlapping spans
+ * and reversed ones are typos, and hours are the one thing on a page nobody
+ * re-reads once written — a venue does not find out it has been claiming to
+ * open at 23:00 until somebody arrives at a locked door.
+ *
+ * Throws where the share-image checks only warn, because the failures are not
+ * the same kind of thing. An image below its box looks worse than intended; a
+ * wrong opening time is a false statement, published, that sends a real person
+ * to a closed building. There is no version of shipping it that is acceptable,
+ * so it stops the build.
+ *
+ * Every problem in the week is reported at once. Failing on the first would
+ * mean a build, a fix and another build for each typo in the same table.
+ */
+export function assertHours(hours: WeeklyHours, at: string): void {
+    const problems: string[] = [];
+
+    for (const day of WEEK) {
+        const ranges = hours[day];
+        if (ranges === "closed") {
+            continue;
+        }
+
+        let previousEnd: number | undefined;
+        ranges.forEach((range, index) => {
+            const opens = minutes(range.opens);
+            const closes = minutes(range.closes);
+
+            if (opens === closes) {
+                problems.push(
+                    `${day} opens and closes at ${range.opens}, a span of no length. For a day off write "closed"; for around the clock, 00:00 to 23:59.`
+                );
+                return;
+            }
+
+            // A span running past midnight ends the day: anything after it
+            // would belong to the following one.
+            if (closes < opens && index < ranges.length - 1) {
+                problems.push(
+                    `${day} has a span after ${range.opens}–${range.closes}, which already runs into the next day.`
+                );
+            }
+
+            if (previousEnd !== undefined && opens < previousEnd) {
+                problems.push(
+                    `${day} reopens at ${range.opens} before the previous span has closed.`
+                );
+            }
+
+            previousEnd = closes < opens ? 24 * 60 : closes;
+        });
+    }
+
+    if (problems.length > 0) {
+        throw new Error(
+            `${at}: opening hours are impossible as written.\n${problems
+                .map((problem) => `  - ${problem}`)
+                .join("\n")}`
+        );
+    }
+}
+
+/** schema.org spells its days capitalised; this file spells them as ids. */
+const SCHEMA_DAY: Readonly<Record<Weekday, string>> = {
+    monday: "Monday",
+    tuesday: "Tuesday",
+    wednesday: "Wednesday",
+    thursday: "Thursday",
+    friday: "Friday",
+    saturday: "Saturday",
+    sunday: "Sunday",
+};
+
+/** A group's days, as schema.org names them. */
+export function schemaDays(group: HoursGroup): readonly string[] {
+    return group.days.map((day) => SCHEMA_DAY[day]);
+}