@escape-game-over/atlas 0.1.24 → 0.1.26

package/src/astro/ref.ts

@@ -0,0 +1,46 @@
+/**
+ * Finding the elements a script works on, by a selector the template wrote as
+ * a plain attribute — `[data-faq-search]` — so what the script asks for is what
+ * devtools shows.
+ */
+
+/** Names the root in an error, for a selector that matched nothing. */
+const where = (root: ParentNode): string =>
+    "localName" in root && typeof root.localName === "string"
+        ? `<${root.localName}>`
+        : "the document";
+
+/**
+ * The first match under `root`, or a thrown error naming the selector. Inside
+ * `element`'s `connect`, that error lands in the dev panel.
+ */
+export function ref<T extends Element = HTMLElement>(
+    root: ParentNode,
+    selector: string
+): T {
+    const found = root.querySelector<T>(selector);
+    if (found === null) {
+        throw new Error(`${where(root)} has nothing matching ${selector}`);
+    }
+    return found;
+}
+
+/**
+ * An element's `data-<name>` value, or a thrown error naming the element and
+ * the attribute. For an optional one, read `dataset` directly.
+ */
+export function data(element: Element, name: string): string {
+    const value = element.getAttribute(`data-${name}`);
+    if (value === null) {
+        throw new Error(`<${element.localName}> has no data-${name}`);
+    }
+    return value;
+}
+
+/** Every match under `root`. None is an answer here, not an error. */
+export function refs<T extends Element = HTMLElement>(
+    root: ParentNode,
+    selector: string
+): T[] {
+    return [...root.querySelectorAll<T>(selector)];
+}

package/src/astro/site-routes.ts

@@ -67,16 +67,10 @@ export interface SiteRoutesOptions {
      *
      * The finished file rather than a flag, because this is the one output whose
      * words lib does not have: page names and summaries live in a catalog under
-     * a key convention it cannot guess. Omitting it does not turn the file off —
-     * `site.llms()` still writes one, listing every page by route id with no
-     * summaries. That is a worse file and a real one; switching it off is a
-     * decision, made with `llms: false` in the site config.
+     * a key convention it cannot guess. Omitted, `site.llms()` writes one listing
+     * every page by route id with no summaries.
      */
     readonly llms?: GeneratedFile;
-    /** Write the sitemap. Defaults to true. */
-    readonly sitemap?: boolean;
-    /** Write `robots.txt`. Defaults to true. */
-    readonly robots?: boolean;
 }
 
 /**
@@ -98,7 +92,7 @@ export interface SiteRoutesOptions {
  * again for the reason above.
  */
 export function siteRoutes(options: SiteRoutesOptions): AstroIntegration {
-    const { site, redirects, llms, sitemap = true, robots = true } = options;
+    const { site, redirects, llms } = options;
 
     /** `llms.txt (4.2 kB)` — the name and what it actually weighs. */
     const describe = (file: GeneratedFile): string =>
@@ -115,12 +109,9 @@ export function siteRoutes(options: SiteRoutesOptions): AstroIntegration {
     // it and leaves the same string in `llms.txt` untouched. A build is always
     // right, since it evaluates the config in a fresh process.
     const generate = (): GeneratedFile[] => {
-        const files: GeneratedFile[] = [];
-        if (sitemap) files.push(...site.sitemap().files);
-        if (robots) files.push(site.robots());
-        // `llmsUrl` is what every page's head links to, so a file must exist at
-        // it: the described one when given, a bare listing otherwise. Undefined
-        // means the config turned both off.
+        const files: GeneratedFile[] = [...site.sitemap().files, site.robots()];
+        // Every page's head links to it, so one is written unless the config
+        // turned it off.
         if (site.llmsUrl !== undefined) files.push(llms ?? site.llms());
         // Length rather than presence: a site with no rules gets no file, not an
         // empty one.
@@ -349,6 +340,9 @@ export function siteRoutes(options: SiteRoutesOptions): AstroIntegration {
                     // every locale is prefixed, which is the first URL anyone
                     // opens. Serving them here makes dev answer as production
                     // will, rather than as a place where the rules do not exist.
+                    // Not Astro's `redirects`: it serves every redirect to a
+                    // non-route (an external URL, a public file) as 301,
+                    // whatever status it was given.
                     // Matched with and without a trailing slash, because a host
                     // either normalises one away before its rules run or treats
                     // the two as the same URL. Dev should not be the only place

package/src/config.ts

@@ -99,18 +99,7 @@ export interface SiteConfigShape {
     readonly defaultRouting: RoutingConfig<string>;
     readonly sitemap?: SitemapConfig;
     readonly robots?: RobotsConfig;
-    /**
-     * `false` to publish no `llms.txt`. Omitted, one is published under the
-     * default name.
-     *
-     * Opt-out like the two above, even though lib cannot write this one
-     * unaided — it needs a name and a summary per page, which only the consumer
-     * has. Forgetting to supply them is a build error rather than a reason to
-     * make the file opt-in: this key is also what puts `<link rel="describedby">`
-     * in every head, and a page cannot tell whether `site.llms()` was called
-     * somewhere, so the declaration stands in for it and `siteRoutes` checks
-     * that it was kept.
-     */
+    /** `false` publishes no `llms.txt`, and no page links to one. */
     readonly llms?: LlmsConfig | false;
     // No share image here on purpose: an image belongs to the page it
     // represents, so the page passes its own to `metaFor`.
@@ -135,25 +124,28 @@ export type LocalesOf<C> = C extends { readonly locales: infer M }
  * `string`, and the config reports a cascade of malformed-tag errors on lines
  * that were fine.
  */
-export function defineSiteConfig<
-    const T extends SiteConfigShape & {
-        readonly defaultRouting: {
-            readonly defaultLocale: StringKeys<T["locales"]>;
-            // Mapped over the keys actually written, not declared as a
-            // `Partial<Record<…>>`: a constraint is checked by assignability,
-            // and an extra key is assignable to a type whose properties are all
-            // optional. Demanding an impossible value for a bad key is what
-            // makes the error land on that line.
-            readonly pageSegmentByLocale?: {
-                readonly [K in StringKeys<
-                    T["defaultRouting"]["pageSegmentByLocale"]
-                >]: K extends StringKeys<T["locales"]>
-                    ? string
-                    : LocaleNotDeclared<K>;
-            };
+/** Everything a site config must satisfy; see `defineSite`. */
+export type SiteConfigChecks<T extends SiteConfigShape> = SiteConfigShape & {
+    readonly defaultRouting: {
+        readonly defaultLocale: StringKeys<T["locales"]>;
+        // Mapped over the keys actually written, not declared as a
+        // `Partial<Record<…>>`: a constraint is checked by assignability,
+        // and an extra key is assignable to a type whose properties are all
+        // optional. Demanding an impossible value for a bad key is what
+        // makes the error land on that line.
+        readonly pageSegmentByLocale?: {
+            readonly [K in StringKeys<
+                T["defaultRouting"]["pageSegmentByLocale"]
+            >]: K extends StringKeys<T["locales"]>
+                ? string
+                : LocaleNotDeclared<K>;
         };
-        readonly locales: ValidateLocales<T["locales"]>;
-    },
+    };
+    readonly locales: ValidateLocales<T["locales"]>;
+};
+
+export function defineSiteConfig<
+    const T extends SiteConfigShape & SiteConfigChecks<T>,
 >(config: T): T {
     return config;
 }
@@ -179,12 +171,7 @@ export interface LocaleNotDeclared<L extends string> {
     readonly __LOCALE_NOT_DECLARED__: `locale "${L}" is not among this site's locales, so anything keyed by it would never be read`;
 }
 
-/**
- * Editor-facing error for anything written for a locale a project does not ship.
- *
- * Lives here rather than beside one of its users because two of them need it:
- * `defineProject`, for locale metadata, and `defineMessageOverrides`, for copy.
- */
+/** Editor-facing error for anything written for a locale a project does not ship. */
 export interface LocaleNotEnabled<L extends string> {
     readonly __LOCALE_NOT_ENABLED__: `locale "${L}" is not among this project's enabledLocales, so anything written for it would never be built`;
 }

package/src/content/index.ts

@@ -17,7 +17,7 @@
  * <RichText spans={rich("about.intro")} />
  *
  * // the same sentence, where a string is what fits
- * description: plain(rich("about.intro"))
+ * description: site.plain(locale)("about.intro")
  * ```
  *
  * There is no authored `ContentItem[]`. Where a project needs to compose runs

package/src/content/marks.ts

@@ -48,7 +48,7 @@ export type ParsedSpan =
     | { readonly kind: "text"; readonly text: string }
     | { readonly kind: "bold"; readonly text: string }
     | {
-          readonly kind: "styled";
+          readonly kind: "variant";
           readonly text: string;
           readonly variant: string;
       }
@@ -58,8 +58,8 @@ export type ParsedSpan =
           /** The slot to fill, e.g. `venue` in `[a:venue]`. Never a URL. */
           readonly name: string;
       }
-    | { readonly kind: "email"; readonly text: string }
-    | { readonly kind: "phone"; readonly text: string }
+    | { readonly kind: "mail"; readonly text: string }
+    | { readonly kind: "tel"; readonly text: string }
     | { readonly kind: "break" };
 
 /**
@@ -81,10 +81,10 @@ export type ParsedSpan =
  */
 const MARKS = {
     b: "bold",
-    v: "styled",
+    v: "variant",
     a: "link",
-    mail: "email",
-    tel: "phone",
+    mail: "mail",
+    tel: "tel",
 } as const;
 
 type MarkName = keyof typeof MARKS;
@@ -244,9 +244,9 @@ export function parseMarks(
         switch (MARKS[mark.name]) {
             case "bold":
                 return { kind: "bold", text: content };
-            case "styled":
+            case "variant":
                 return {
-                    kind: "styled",
+                    kind: "variant",
                     text: content,
                     variant: mark.argument,
                 };
@@ -256,10 +256,10 @@ export function parseMarks(
                     text: content,
                     name: mark.argument,
                 };
-            case "email":
-                return { kind: "email", text: content };
-            case "phone":
-                return { kind: "phone", text: content };
+            case "mail":
+                return { kind: "mail", text: content };
+            case "tel":
+                return { kind: "tel", text: content };
         }
     }
 
@@ -407,7 +407,7 @@ export function assertNoMarks(template: string, at: string): void {
     );
     if (marked) {
         throw new Error(
-            `${at} carries marks, and t() can only print them. Read it with rich(), or with plain(rich(…)) for the words alone.`
+            `${at} carries marks, and t() can only print them. Read it with rich(), or with site.plain() for the words alone.`
         );
     }
 }

package/src/content/rich.ts

@@ -53,7 +53,7 @@ export type Span =
      * edit rather than a sweep through fifty-four deployments' copy.
      */
     | {
-          readonly kind: "styled";
+          readonly kind: "variant";
           readonly text: string;
           readonly variant: string;
       }
@@ -105,12 +105,12 @@ export type Span =
           readonly href: Hash;
       }
     | {
-          readonly kind: "email";
+          readonly kind: "mail";
           readonly text: string;
           readonly href: MailtoUrl;
       }
     | {
-          readonly kind: "phone";
+          readonly kind: "tel";
           readonly text: string;
           readonly href: TelUrl;
       }
@@ -230,7 +230,7 @@ export type RichTextFor<Catalog, RouteId extends string> = <
     ...args: RichArgsOf<Catalog, K, RouteId>
 ) => RichText;
 
-/** `plain()`, keyed and parameterised exactly as `t()` is. */
+/** `site.plain()`, keyed and parameterised exactly as `t()` is. */
 export type PlainTextFor<Catalog> = <K extends StringKeys<Catalog>>(
     ...args: TranslateArgsOf<Catalog, K>
 ) => string;
@@ -286,8 +286,8 @@ function resolve(
         case "text":
         case "bold":
             return { kind: span.kind, text };
-        case "styled":
-            return { kind: "styled", text, variant: span.variant };
+        case "variant":
+            return { kind: "variant", text, variant: span.variant };
         case "link":
             return resolveLink(
                 text,
@@ -296,10 +296,10 @@ function resolve(
                 link,
                 origin
             );
-        case "email":
-            return { kind: "email", text, href: mailto(text, at) };
-        case "phone":
-            return { kind: "phone", text, href: tel(text, at) };
+        case "mail":
+            return { kind: "mail", text, href: mailto(text, at) };
+        case "tel":
+            return { kind: "tel", text, href: tel(text, at) };
     }
 }
 
@@ -473,27 +473,6 @@ function tel(text: string, at: string): TelUrl {
     return `tel:${dialled}`;
 }
 
-/**
- * The words alone, for everywhere that takes a string rather than markup.
- *
- * The reason this whole module sits in lib rather than in each project. A meta
- * description, an `llms.txt` summary and a structured-data `description` all
- * want the same sentence the page renders, and every one of them takes a plain
- * string — so without this each project flattens the runs by hand, and they
- * drift. The implementation this replaces did exactly that: a chain of `if`s
- * per kind, `return ""` for the ones it could not render, and a `throw` on
- * anything it had not been taught.
- *
- * A `[br]` becomes a space, because that is what it is once the markup is gone,
- * and runs of whitespace collapse — copy split across a line break otherwise
- * arrives with a double space in the middle of a `<meta>` tag.
- */
-export function plain(rich: RichText): string {
-    return collapse(
-        rich.map((span) => (span.kind === "break" ? " " : span.text))
-    );
-}
-
 /**
  * The runs as inline HTML, for a field that takes markup rather than a page.
  *
@@ -512,7 +491,7 @@ export function html(rich: RichText): string {
         .map((span) => {
             switch (span.kind) {
                 case "text":
-                case "styled":
+                case "variant":
                     return escapeXml(span.text);
                 case "bold":
                     return `<strong>${escapeXml(span.text)}</strong>`;
@@ -520,8 +499,8 @@ export function html(rich: RichText): string {
                     return span.to === "anchor"
                         ? escapeXml(span.text)
                         : anchor(span.url, span.text);
-                case "email":
-                case "phone":
+                case "mail":
+                case "tel":
                     return anchor(span.href, span.text);
                 case "break":
                     return "<br>";
@@ -538,6 +517,16 @@ function anchor(href: string, text: string): string {
     return `<a href="${escapeXml(href)}">${escapeXml(text)}</a>`;
 }
 
+/**
+ * The words of runs already built — for a message whose values `rich()` was
+ * given in code. A `[br]` becomes a space and whitespace collapses.
+ */
+export function plain(rich: RichText): string {
+    return collapse(
+        rich.map((span) => (span.kind === "break" ? " " : span.text))
+    );
+}
+
 /**
  * Runs of whitespace become one, and the ends are trimmed.
  *
@@ -550,14 +539,9 @@ function collapse(parts: readonly string[]): string {
 }
 
 /**
- * The same, straight from a message key — `plain(rich(…))` without the nesting.
- *
- * Which sounds like sugar and is mostly about where it gets used. The callers
- * that want words rather than runs are the ones furthest from a renderer:
- * `llms()`'s `describe`, a `<meta name="description">`, a structured-data
- * `description`. Those are already assembling several strings at once, and
- * `plain(rich("about.intro", { company }))` reads as two operations there when
- * it is one question — what does this message say.
+ * The words of a message alone, for everywhere that takes a string rather than
+ * markup: a meta description, an `llms.txt` summary, a structured-data
+ * `description`. A `[br]` becomes a space and whitespace collapses.
  *
  * It also answers that question for a message with no marks at all, which `t()`
  * would too. That overlap is deliberate: a description built this way keeps

package/src/hours.ts

@@ -164,18 +164,22 @@ export function groupHours(
 }
 
 /**
- * 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.
+ * How to print a week. Day names come from `Intl` in `locale`; "closed" is
+ * copy, so the caller translates it.
  */
 export interface HoursFormat {
-    /** What to call a day. Usually a lookup in the project's catalog. */
-    day(day: Weekday): string;
+    /** The language the days are named in, e.g. `"el-GR"`. */
+    locale: string;
+    /** `Mon` or `Monday`. Defaults to `"short"`. */
+    weekday?: "short" | "long";
     /** The word for a day the venue is shut. */
     closed: string;
+    /**
+     * Times print as written (`14:00`) unless this is `"h12"` (`2:00 PM`).
+     * Not the locale's default, which gives Greek a 12-hour clock nobody there
+     * uses on a door.
+     */
+    hourCycle?: "h12";
     /** Between the ends of a span: `Mon–Thu`, `14:00–23:30`. */
     between?: string;
     /** Between spans: `Mon–Thu, Sun`. */
@@ -207,20 +211,53 @@ export function formatHours(
 ): readonly FormattedHours[] {
     const between = format.between ?? "–";
     const and = format.and ?? ", ";
+    // 2024-01-01 was a Monday, so `WEEK[i]` falls on the 1st plus `i`.
+    const names = new Intl.DateTimeFormat(format.locale, {
+        weekday: format.weekday ?? "short",
+        timeZone: "UTC",
+    });
+    const dayName = (day: Weekday): string =>
+        names.format(new Date(Date.UTC(2024, 0, 1 + WEEK.indexOf(day))));
+    const clock =
+        format.hourCycle === "h12"
+            ? new Intl.DateTimeFormat(format.locale, {
+                  hour: "numeric",
+                  minute: "2-digit",
+                  hourCycle: "h12",
+                  timeZone: "UTC",
+              })
+            : undefined;
+    const time = (at: TimeOfDay): string =>
+        clock === undefined
+            ? at
+            : clock.format(
+                  new Date(
+                      Date.UTC(
+                          2024,
+                          0,
+                          1,
+                          Number(at.slice(0, 2)),
+                          Number(at.slice(3, 5))
+                      )
+                  )
+              );
 
     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)}`
+                    ? dayName(first)
+                    : `${dayName(first)}${between}${dayName(last)}`
             )
             .join(and),
         times:
             group.hours === "closed"
                 ? format.closed
                 : group.hours
-                      .map((range) => `${range.opens}${between}${range.closes}`)
+                      .map(
+                          (range) =>
+                              `${time(range.opens)}${between}${time(range.closes)}`
+                      )
                       .join(and),
     }));
 }

package/src/i18n/define.ts

@@ -11,15 +11,15 @@ import type {
  * `true` when `Catalog` declares every key in `Required`; otherwise an object
  * type naming the ones it does not.
  *
- * Annotate a `const … = true` with it. A missing message then fails at that
- * declaration, and the error text lists exactly which keys are absent, rather
- * than surfacing later as a page with no `<title>`:
+ * Check it with `satisfies`. A missing message then fails on that line, and the
+ * error text lists exactly which keys are absent, rather than surfacing later
+ * as a page with no `<title>`:
  *
  * ```ts
- * export const routeMessagesAreComplete: CatalogCovers<
+ * true satisfies CatalogCovers<
  *     typeof baseMessages,
  *     `route.${RouteId}.${"nav" | "title"}`
- * > = true;
+ * >;
  * ```
  *
  * The pattern earns its keep over a plain `Required extends StringKeys<Catalog>`
@@ -67,7 +67,7 @@ type SelfConsistent<E, K> = [MismatchedLocales<E, EntryTokens<E>>] extends [
           MismatchedLocales<E, EntryTokens<E>> & string
       >;
 
-type ValidateBase<T> = { [K in keyof T]: SelfConsistent<T[K], K> };
+export type ValidateBase<T> = { [K in keyof T]: SelfConsistent<T[K], K> };
 
 /**
  * Rejects locale keys the site does not ship.
@@ -76,7 +76,7 @@ type ValidateBase<T> = { [K in keyof T]: SelfConsistent<T[K], K> };
  * from the literal rather than checked against a fixed target, so an extra key
  * structurally satisfies the constraint and would sit in the catalog unread.
  */
-type NoExtraLocales<T, L extends string> = {
+export type NoExtraLocales<T, L extends string> = {
     [K in keyof T]: NoExcessKeys<T[K], L>;
 };
 
@@ -102,21 +102,7 @@ export function defineMessages<
     return catalog;
 }
 
-/**
- * Everything a copy overlay must satisfy — and the only place it is stated.
- *
- * The mirror of `RouteOverlayKeys` / `RouteOverlayShape`, for the same reason:
- * `defineMessageOverrides` and `defineProject` both accept an overlay, and a
- * check added to one and not the other makes that one silently the safer place
- * to write copy. Both name these, so a new rule reaches both.
- *
- * Excess keys go in the constraint, where a typo'd message id reports on that
- * key; the placeholder and locale rules go in the parameter, because they map
- * the whole object.
- */
-export type MessageOverlayKeys<Base, T> = NoExcessKeys<T, StringKeys<Base>>;
-
-/** @see {@link MessageOverlayKeys} — the parameter-position half. */
+/** What `defineProject` checks an `overrideMessages` against: placeholders and locales. */
 export type ValidateOverrideCatalog<
     T,
     Base,
@@ -135,63 +121,17 @@ type ValidateOverrides<T, Base> = {
 };
 
 /**
- * Declares a project's copy overlay: any subset of keys, any subset of locales.
- *
- * Both the message ids and the locales are inferred from the base catalog you
- * pass in, so overriding one locale of one string needs no type arguments.
- *
- * Enforced at compile time:
- *  - the key must exist in the base catalog, so a typo is rejected rather than
- *    silently becoming a string nothing reads;
- *  - the replacement must use exactly the `{placeholders}` and `[marks]` of the
- *    base message, so every existing `t()` and `rich()` call site stays correct.
- */
-export function defineMessageOverrides<
-    const C extends SiteConfigShape,
-    const Base extends BaseCatalog<LocalesOf<C>>,
-    const T extends OverrideCatalog<LocalesOf<C>> & MessageOverlayKeys<Base, T>,
->(
-    // Read for its type only, and taken first like every other definer here.
-    // It supplies the locale universe directly rather than having it inferred
-    // from the catalog's entries: `LocalesOfCatalog` reads the locales actually
-    // *used*, which is the same union for a well-formed catalog and a narrower
-    // one for a partial or empty draft.
-    //
-    // Note what this does not do: `config` declares which locales the site has,
-    // not which ones a project publishes. Rejecting copy for a language a given
-    // deployment has switched off is `MessageOverrides`' job, because only the
-    // project knows its own `enabledLocales`.
-    _config: C,
-    _base: Base,
-    overrides: T & ValidateOverrides<T, Base> & NoExtraLocales<T, LocalesOf<C>>
-): T {
-    return overrides;
-}
-
-/**
- * The shape of one project's copy overrides: known keys, published locales.
- *
- * For annotating the object itself, which is what puts the error on the line
- * that is wrong:
+ * One project's copy overrides — known keys, published locales — for an overlay
+ * kept in its own file:
  *
  * ```ts
- * const overrides = {
+ * export const romeMessages = {
  *     "site.cta": { "en-US": "Book a room" },
- * } satisfies MessageOverrides<typeof defaultMessages, EnabledLocale>;
- *
- * export const overrideMessages = defineMessageOverrides(
- *     config,
- *     defaultMessages,
- *     overrides
- * );
+ * } as const satisfies MessageOverrides<typeof defaultMessages, EnabledLocale>;
  * ```
  *
- * The two halves do different jobs and both are needed. This type knows the
- * project's locale set, so it rejects copy for a language that is never built —
- * but it cannot compare an override's *text* with the default's, so it cannot
- * see a dropped `{placeholder}`. `defineMessageOverrides` is the reverse: it
- * reads both texts, and knows nothing about which locales this deployment
- * publishes. Annotate with one, wrap in the other.
+ * A dropped `{placeholder}` is not visible to a type like this; `defineProject`
+ * reports it, naming the key and locale.
  */
 export type MessageOverrides<Catalog, L extends string> = {
     readonly [K in StringKeys<Catalog>]?: Readonly<Partial<Record<L, string>>>;