@escape-game-over/atlas 0.1.23 → 0.1.25

package/src/astro/filters.ts

@@ -4,8 +4,8 @@
  * ```ts
  * const list = filters({
  *     fields: {
- *         q: { kind: "text", param: "q" },
- *         category: { kind: "choice", param: "category" },
+ *         q: { kind: "text" },
+ *         category: { kind: "choice" },
  *     },
  *     items: entries.map((entry) => ({
  *         key: entry.id,
@@ -40,10 +40,11 @@
  *
  * `flag` is not a tri-state: on, off and *either* is a `choice` with two values.
  */
-export type Field =
-    | { readonly kind: "text"; readonly param?: string }
-    | { readonly kind: "choice"; readonly param?: string }
-    | { readonly kind: "flag"; readonly param?: string };
+export interface Field {
+    readonly kind: "text" | "choice" | "flag";
+    /** The URL parameter. Defaults to the field's name; `false` keeps it out of the URL. */
+    readonly param?: string | false;
+}
 
 /** The fields of one list, named by the caller. */
 export type FieldMap = Readonly<Record<string, Field>>;
@@ -66,14 +67,6 @@ export type ItemValue<F extends Field> = F["kind"] extends "flag"
       ? string | readonly string[]
       : string;
 
-/**
- * What one field contributes.
- *
- * @deprecated Say which side you are on: `StateValue` or `ItemValue`. This
- * named both while they were the same type, and is `StateValue` now.
- */
-export type FieldValue<F extends Field> = StateValue<F>;
-
 /** Every field's value for one item, derived from the field declaration. */
 export type ItemValues<F extends FieldMap> = {
     readonly [K in keyof F]: ItemValue<F[K]>;
@@ -144,6 +137,11 @@ export interface Filters<F extends FieldMap> {
     ): void;
     /** Clears one field, or all of them. Always a push: clearing is deliberate. */
     reset(field?: keyof F): void;
+    /**
+     * Also called on every change, after `onChange`. Returns the undo. For a
+     * helper like `searchBox` that keeps its own part of the page in step.
+     */
+    subscribe(listener: (change: FilterChange<F>) => void): () => void;
     /**
      * Reads the URL, applies it, and starts listening — returns the undo.
      *
@@ -189,16 +187,20 @@ export function filters<const F extends FieldMap>(
         }
         keys.add(item.key);
     }
-    const params = new Set<string>();
+    // Field name → URL parameter, for the fields that are in the URL.
+    const params = new Map<string, string>();
+    const taken = new Set<string>();
     for (const name of names) {
-        const param = fields[name]?.param;
-        if (param === undefined) continue;
-        if (params.has(param)) {
+        const given = fields[name]?.param;
+        if (given === false) continue;
+        const param = given ?? name;
+        if (taken.has(param)) {
             throw new Error(
                 `Two filter fields share the URL parameter "${param}".`
             );
         }
-        params.add(param);
+        taken.add(param);
+        params.set(name, param);
     }
 
     // Folded once at construction: doing it per item per keystroke is the
@@ -305,15 +307,16 @@ export function filters<const F extends FieldMap>(
         const next: Record<string, string | boolean> = {};
         for (const name of names) {
             const field = fields[name];
+            const param = params.get(name);
             if (field === undefined) continue;
-            if (field.param === undefined) {
+            if (param === undefined) {
                 // A state-only field is not in the URL, so the URL has nothing
                 // to say about it. Clearing it here wiped a search mid-typing
                 // whenever another parameter on the page moved.
                 next[name] = state[name];
                 continue;
             }
-            const raw = search.get(field.param);
+            const raw = search.get(param);
             next[name] = field.kind === "flag" ? raw === FLAG_ON : (raw ?? "");
         }
         state = next as FilterState<F>;
@@ -328,33 +331,34 @@ export function filters<const F extends FieldMap>(
         // attributed the first time someone typed in the search box. Its own
         // are deleted first, then rewritten, so one state gives one URL.
         const search = new URLSearchParams(window.location.search);
-        for (const name of names) {
-            const param = fields[name]?.param;
-            if (param !== undefined) search.delete(param);
-        }
-        for (const name of names) {
-            const field = fields[name];
-            if (field?.param === undefined) continue;
-            if (field.kind === "flag") {
-                if (state[name] === true) search.set(field.param, FLAG_ON);
+        for (const param of params.values()) search.delete(param);
+        for (const [name, param] of params) {
+            if (fields[name]?.kind === "flag") {
+                if (state[name] === true) search.set(param, FLAG_ON);
                 continue;
             }
             const value = (state[name] as string).trim();
-            if (value !== "") search.set(field.param, value);
+            if (value !== "") search.set(param, value);
         }
 
         const query = search.toString();
         // The bare path when nothing is left, rather than a trailing `?`.
         const url = query === "" ? window.location.pathname : `?${query}`;
-        if (history === "push") window.history.pushState({}, "", url);
-        else window.history.replaceState({}, "", url);
+        // `null` on a pushed step, so Astro's `ClientRouter` leaves its popstate
+        // to this module; a replaced entry keeps whatever state it already had.
+        if (history === "push") window.history.pushState(null, "", url);
+        else window.history.replaceState(window.history.state, "", url);
     }
 
     /** One field's value as the matcher and the URL will read it. */
     const normalized = (name: keyof F & string, value: unknown): unknown =>
         fields[name]?.kind === "text" ? (value as string).trim() : value;
 
-    const announce = (): void => onChange({ state, matched });
+    const listeners = new Set<(change: FilterChange<F>) => void>();
+    const announce = (): void => {
+        onChange({ state, matched });
+        for (const listener of listeners) listener({ state, matched });
+    };
 
     recompute();
 
@@ -415,8 +419,13 @@ export function filters<const F extends FieldMap>(
             announce();
         },
 
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+
         attach() {
-            const listeners = new AbortController();
+            const events = new AbortController();
 
             // A `popstate` listener that outlives its page is the leak with no
             // visible symptom: it keeps rendering into markup that was replaced.
@@ -427,7 +436,7 @@ export function filters<const F extends FieldMap>(
                     recompute();
                     announce();
                 },
-                { signal: listeners.signal }
+                { signal: events.signal }
             );
 
             attached = true;
@@ -439,7 +448,7 @@ export function filters<const F extends FieldMap>(
             announce();
 
             return () => {
-                listeners.abort();
+                events.abort();
                 attached = false;
             };
         },

package/src/astro/images.ts

@@ -158,16 +158,6 @@ export async function shareImage(
     // Not warned about here. `metaFor` already warns about an undersized
     // `og:image`, on every page and whether or not this helper made it, so
     // saying it twice would only halve the chance either line is read.
-    //
-    // Measured as a scale factor, not by comparing dimensions, because the two
-    // fits reach the box differently. `cover` scales until *both* sides are
-    // covered, so a source short in either dimension would be enlarged.
-    // `contain` scales until the *first* side fits, so an 800x800 logo lands at
-    // 630x630 — a reduction, though it is narrower than 1200.
-    const scale =
-        fit === "cover"
-            ? Math.max(width / source.width, height / source.height)
-            : Math.min(width / source.width, height / source.height);
     const image = await getImage({
         src: source,
         width,
@@ -187,20 +177,32 @@ export async function shareImage(
         })(),
     });
 
-    // The size that came *back*, not the size asked for.
-    //
-    // Neither `attributes` nor `options` can be trusted here: both echo the
-    // request, and the request is exactly what was not honoured. What is known
-    // is the rule — Astro refuses to enlarge — so a source too small for the box
-    // comes back untouched, at its own size. Reporting the request instead would
-    // put an `og:image:width` in every head that the file does not match, which
-    // is worse than a small image: a scraper lays out a space and finds
-    // something else in it.
-    const produced =
-        scale > 1
-            ? { width: source.width, height: source.height }
-            : { width, height };
-    return { src: image.src, ...produced, format };
+    return {
+        src: image.src,
+        ...producedSize(source, width, height, fit),
+        format,
+    };
+}
+
+/**
+ * The size `getImage` actually returns, not the size asked for.
+ *
+ * Neither `attributes` nor `options` can be trusted: both echo the request.
+ * Astro refuses to enlarge, so a source too small for the box comes back
+ * untouched, at its own size. Measured as a scale factor because the fits reach
+ * the box differently: `cover` scales until *both* sides are covered, `contain`
+ * until the *first* side fits.
+ */
+function producedSize(
+    source: ImageMetadata,
+    width: number,
+    height: number,
+    fit: "cover" | "contain"
+): { width: number; height: number } {
+    const pick = fit === "cover" ? Math.max : Math.min;
+    return pick(width / source.width, height / source.height) > 1
+        ? { width: source.width, height: source.height }
+        : { width, height };
 }
 
 /**
@@ -307,8 +309,7 @@ export async function photoSet(
             });
             return {
                 src: image.src,
-                width: ratio.width,
-                height: ratio.height,
+                ...producedSize(source, ratio.width, ratio.height, "cover"),
                 format,
             };
         })

package/src/astro/index.ts

@@ -22,15 +22,8 @@
  * - `public-files.ts` types the contents of `public/`, the one part of a site
  *   the compiler cannot otherwise see.
  *
- * The rest of this folder is imported directly rather than from here, because
- * each is reached from a different place in a project: `…/astro/images` from
- * a view or a config, `…/astro/consent` from a client-side script, and
- * `…/astro/meta-tags` from a layout.
- *
- * That last one is a `.astro` component, and the only one lib carries. It is
- * here rather than in a project's `src/` because it holds no design and no
- * copy — it renders the `MetaTag` union and nothing else, which makes it the
- * mirror of `asMetaTag` in `lib/meta/tag.ts` rather than a piece of a theme.
+ * The rest is imported from its own path: `…/astro/images` from a view,
+ * `…/astro/document` from a layout, `…/client` from a script.
  */
 
 export {

package/src/astro/markup.ts

@@ -99,7 +99,7 @@ type CheckedMarkupName<N extends string> = string extends N
       ? unknown
       : MalformedMarkupName<N>;
 
-type CheckedTagName<N extends string> = string extends N
+export type CheckedTagName<N extends string> = string extends N
     ? unknown
     : IsHyphenated<N> extends true
       ? N extends `${string}-${string}`
@@ -108,7 +108,7 @@ type CheckedTagName<N extends string> = string extends N
       : MalformedTagName<N>;
 
 /** The same, for every key of a fields or roles object. */
-type CheckedKeys<T> = {
+export type CheckedKeys<T> = {
     [K in keyof T]: K extends string
         ? IsCamelCase<K> extends true
             ? unknown
@@ -515,20 +515,20 @@ export function markup<
 export type ComponentRoles = Readonly<Record<string, MarkupFields>>;
 
 /** The keys the component object uses itself, so no role may take them. */
-type Reserved = "tag" | "root";
+export type Reserved = "tag" | "root";
 
 /**
  * What marks a component's root element.
  *
  * One name, so a project gives every root a display in a single stylesheet rule
- * rather than a class per component, and so `defineElement` can say when a
+ * rather than a class per component, and so `element` can say when a
  * template forgot to spread it.
  */
 export const ROOT_ATTRIBUTE = "data-atlas-root";
 
 export type Component<Tag extends string, R extends ComponentRoles> = {
     /** The custom element's name: what the template renders, and what
-     * `defineElement` registers the behaviour under. */
+     * `element` registers the behaviour under. */
     readonly tag: Tag;
 
     /**
@@ -549,7 +549,7 @@ export type Component<Tag extends string, R extends ComponentRoles> = {
  * });
  *
  * // template: <faq.tag {...faq.root}> … <details {...faq.row.attrs({ key, text })}>
- * // script:   defineElement(faq, (host, signal, { row }) => row.all().forEach(…));
+ * // behaviour: see `element` in element.ts, which builds on this.
  * ```
  *
  * Two things `markup` alone leaves to the project:

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.
@@ -280,6 +271,7 @@ export function siteRoutes(options: SiteRoutesOptions): AstroIntegration {
                 // optional, so `buld: {…}` would be assignable and silently do
                 // nothing. The annotation is what makes a typo an error.
                 const config: ConfigUpdate = {
+                    site: site.url,
                     output: "static",
                     build: { format: "file" },
                     trailingSlash: "ignore",
@@ -348,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
@@ -29,6 +29,7 @@ export { assertNoMarks, type ParsedSpan, parseMarks } from "./marks.ts";
 export {
     createPlainText,
     createRichText,
+    html,
     type LinkResolver,
     type LinkTarget,
     type PlainTextFor,

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.`
         );
     }
 }