@escape-game-over/atlas 0.1.2 → 0.1.4

package/src/astro/filters.ts

@@ -0,0 +1,505 @@
+/**
+ * A filtered list's state and its URL — not its markup.
+ *
+ * In `astro/` for the reason `carousel.ts` is: it reaches for `location`,
+ * `history` and `window`, which the core is type-checked without.
+ *
+ * **It draws nothing.** No `hidden`, no `aria-selected`, no counts, no empty
+ * state. It owns which items match and what the address bar says, and calls
+ * `onChange` when either moves; a project does every DOM write, and its markup
+ * contract — however many data attributes that turns out to be — stays where the
+ * markup is. That is the whole split, and it is why one function can serve a
+ * game grid with tabs and a two-input directory.
+ *
+ * Matching is the one place this cannot copy `carousel`. A carousel's entire
+ * state is an integer, so it never needs to know anything about the page. A
+ * predicate needs each item's text, and that text lives in the markup — so the
+ * caller hands it over once, as plain values, rather than the library reaching
+ * into the DOM for it. Keys are strings for the same reason: nothing here holds
+ * an element, and the whole module is testable without a document.
+ *
+ * ```ts
+ * const list = filters({
+ *     fields: {
+ *         q: { kind: "text", param: "q" },
+ *         category: { kind: "choice", param: "category" },
+ *     },
+ *     items: entries.map((entry) => ({
+ *         key: entry.id,
+ *         values: { q: `${entry.title} ${entry.summary}`, category: entry.category },
+ *     })),
+ *     onChange: ({ matched }) => {
+ *         for (const [key, element] of elements) element.hidden = !matched.has(key);
+ *     },
+ * });
+ *
+ * const detach = list.attach();
+ * ```
+ *
+ * What it owns is the handful of things identical in every filtered list and
+ * quietly wrong in most: folding so a query without accents still matches words
+ * with them, a query and its facets resolved together rather than in two passes,
+ * and a URL that behaves — replaced while typing so one search does not bury the
+ * previous page in history, pushed on a deliberate choice so the back button
+ * undoes it, empty parameters dropped rather than left as `?q=`, and `popstate`
+ * applied rather than ignored.
+ *
+ * Reading the URL in `attach` is also what lets a list work before this script
+ * arrives: a `<form method="get">` submits, the server renders the filtered
+ * page, and the first `onChange` here continues from that state instead of
+ * resetting it.
+ */
+
+/**
+ * What a field is, as data rather than a constructor.
+ *
+ * A plain object because that is all a field is — a kind and, if it belongs in
+ * the URL, a parameter name. Three exported builder functions would add three
+ * very general names to a module a project imports by name (`text` above all)
+ * and would return exactly this.
+ *
+ * The kinds are closed, and deliberately few:
+ *
+ * - `text` — free entry, folded and substring-matched. The search box.
+ * - `choice` — one of a set, or none. Tabs, a `<select>`, a radio group.
+ * - `flag` — a narrowing toggle: off matches everything, on keeps only the
+ *   items that carry it. "In stock", "Step-free access".
+ *
+ * `flag` is not a tri-state and should not become one. On, off and *either* is
+ * a `choice` with two values; folding that into a toggle gives a control with a
+ * third position nothing can reach.
+ */
+export type Field =
+    | { readonly kind: "text"; readonly param?: string }
+    | { readonly kind: "choice"; readonly param?: string }
+    | { readonly kind: "flag"; readonly param?: string };
+
+/** The fields of one list, named by the caller. */
+export type FieldMap = Readonly<Record<string, Field>>;
+
+/**
+ * What one field contributes, on an item and in the state.
+ *
+ * One type for both roles because per kind they genuinely coincide, though they
+ * mean different things: on an item a `text` value is everything that field
+ * searches — a name and a blurb joined — while in the state it is what someone
+ * typed. A `flag` is what the item is on one side and what was asked for on the
+ * other.
+ */
+export type FieldValue<F extends Field> = F["kind"] extends "flag"
+    ? boolean
+    : string;
+
+/** Every field's value for one item, derived from the field declaration. */
+export type ItemValues<F extends FieldMap> = {
+    readonly [K in keyof F]: FieldValue<F[K]>;
+};
+
+/** What the list is filtered to right now. */
+export type FilterState<F extends FieldMap> = {
+    readonly [K in keyof F]: FieldValue<F[K]>;
+};
+
+export interface FilterItem<F extends FieldMap> {
+    /**
+     * How the caller finds this item again.
+     *
+     * Opaque here and unique across the list — a duplicate is rejected at
+     * construction, because two items answering to one key make `matched`
+     * unable to say which of them matched.
+     */
+    readonly key: string;
+    readonly values: ItemValues<F>;
+}
+
+export interface FilterChange<F extends FieldMap> {
+    readonly state: FilterState<F>;
+    /**
+     * The keys that survive every field at once.
+     *
+     * A set rather than a filtered list, so a caller renders by asking about the
+     * items it already holds instead of diffing two arrays — and `size` is the
+     * count a "showing N" line wants, with no second pass.
+     */
+    readonly matched: ReadonlySet<string>;
+}
+
+export interface FiltersOptions<F extends FieldMap> {
+    readonly fields: F;
+    /**
+     * The full list, every time — this filters, it does not paginate.
+     *
+     * Fixed for the lifetime of the instance. A list whose contents change is a
+     * new instance, which is one line at the call site and avoids this owning a
+     * second lifecycle it would have to keep in step with `attach`.
+     */
+    readonly items: readonly FilterItem<F>[];
+    /**
+     * Called whenever the state moves, and once on `attach` with whatever the
+     * URL already said.
+     *
+     * Never called for a `set` that changes nothing: re-rendering an unchanged
+     * list on every keystroke that did not alter the query is work a caller
+     * cannot skip on its own, because by then it has been told the state
+     * changed.
+     */
+    onChange(change: FilterChange<F>): void;
+}
+
+export interface SetOptions {
+    /**
+     * Whether this move is worth a step in history.
+     *
+     * Defaults from the kind — `text` replaces, `choice` and `flag` push —
+     * because that is the pairing almost every control wants: typing emits an
+     * event per keystroke and would otherwise fill history with a word being
+     * spelled, while picking a category is one deliberate act the back button
+     * should undo.
+     *
+     * It is an override rather than a fixed rule because the default is really
+     * a fact about the *input*, not the field. A `<select>` that sets a `text`
+     * field, or a preset link, is a deliberate choice and wants `"push"`.
+     */
+    readonly history?: "push" | "replace";
+}
+
+export interface Filters<F extends FieldMap> {
+    readonly state: FilterState<F>;
+    readonly matched: ReadonlySet<string>;
+    set<K extends keyof F>(
+        field: K,
+        value: FieldValue<F[K]>,
+        options?: SetOptions
+    ): void;
+    /** Clears one field, or all of them. Always a push: clearing is deliberate. */
+    reset(field?: keyof F): void;
+    /**
+     * Reads the URL, applies it, and starts listening — returns the undo.
+     *
+     * One lifecycle rather than two, as `carousel.attach` is, and for a reason
+     * that bites harder here: with view transitions on, a module bound at top
+     * level executes once per session rather than once per navigation, so the
+     * incoming page gets a live list and dead controls. Driving this from
+     * `astro:page-load` and calling the returned function on teardown is what
+     * makes that correct — and the listener is aborted by its own undo, so it
+     * cannot outlive the page that added it.
+     *
+     * Nothing writes to the URL before this runs. `attach` is what reads it, and
+     * a `set` on an unattached instance would otherwise overwrite state it never
+     * loaded.
+     */
+    attach(): () => void;
+}
+
+/** Combining marks, left behind by `NFD` once the base character is separated. */
+const DIACRITICS = /[̀-ͯ]/g;
+
+/**
+ * A string reduced to what a query should match against.
+ *
+ * Decompose, drop the marks, lowercase, trim. This is the part every list needs
+ * and few have: without it a reader typing `malaga` is told there is no
+ * *Málaga*, and a Romanian catalogue hides every entry spelled with `ă`, `ș` or
+ * `ț` from anyone whose keyboard does not carry them.
+ */
+function fold(value: string): string {
+    return value.normalize("NFD").replace(DIACRITICS, "").toLowerCase().trim();
+}
+
+/**
+ * How a set flag is spelled in the query string, and the only spelling read
+ * back as set.
+ *
+ * An unset flag is *absent* rather than `=0`. One way to say off keeps the URL
+ * short and means there is a single form to handle; two would both have to be
+ * understood forever, and a reader could not tell which of them a link was
+ * carrying. The cost is that a hand-written `?featured=0` reads as off, which is
+ * the answer it would get anyway.
+ *
+ * `1` and not `true` because that is what the existing lists already emit:
+ * links people have shared or bookmarked resolve to the view they named, and a
+ * spelling change would quietly reset every one of them.
+ */
+const FLAG_ON = "1";
+
+export function filters<const F extends FieldMap>(
+    options: FiltersOptions<F>
+): Filters<F> {
+    const { fields, items, onChange } = options;
+    const names = Object.keys(fields) as (keyof F & string)[];
+
+    // Checks that types cannot express, run once. Both failures are silent
+    // otherwise: a duplicate key makes `matched` ambiguous about which item it
+    // meant, and two fields sharing a parameter means each URL write erases the
+    // other's value, which reads as a filter that will not stay set.
+    const keys = new Set<string>();
+    for (const item of items) {
+        if (keys.has(item.key)) {
+            throw new Error(`Two filter items share the key "${item.key}".`);
+        }
+        keys.add(item.key);
+    }
+    const params = new Set<string>();
+    for (const name of names) {
+        const param = fields[name]?.param;
+        if (param === undefined) continue;
+        if (params.has(param)) {
+            throw new Error(
+                `Two filter fields share the URL parameter "${param}".`
+            );
+        }
+        params.add(param);
+    }
+
+    /**
+     * Every item's searchable text, folded once at construction.
+     *
+     * Folding is four string operations, and doing it per item per keystroke is
+     * the difference between a list that filters as you type and one that
+     * stutters. Only the query is folded per render, and there is one of those.
+     */
+    const haystacks = new Map<string, Map<string, string>>();
+    for (const item of items) {
+        const perField = new Map<string, string>();
+        for (const name of names) {
+            if (fields[name]?.kind !== "text") continue;
+            perField.set(name, fold(item.values[name] as string));
+        }
+        haystacks.set(item.key, perField);
+    }
+
+    const empty = (name: keyof F & string): FieldValue<F[typeof name]> =>
+        (fields[name]?.kind === "flag" ? false : "") as FieldValue<
+            F[typeof name]
+        >;
+
+    const blank = (): FilterState<F> =>
+        Object.fromEntries(
+            names.map((name) => [name, empty(name)])
+        ) as FilterState<F>;
+
+    let state = blank();
+    let matched: ReadonlySet<string> = new Set(items.map((item) => item.key));
+
+    /**
+     * Whether the URL is this instance's to write.
+     *
+     * Gates every write, for the reason `carousel` gates autoplay on the same
+     * flag: an instance that was built but never attached has not read the URL,
+     * so writing to it would replace state that nobody here has loaded.
+     */
+    let attached = false;
+
+    function recompute(): void {
+        // The query folded once per render rather than once per item. The other
+        // kinds compare values as they are, so there is nothing to prepare.
+        // Split into tokens, all of which must appear — not one substring that
+        // must appear whole. A haystack is several things joined (a title, plus
+        // its category, plus its summary), and the order they were joined in is
+        // an accident of whoever wrote the template. Matching the query as one
+        // run made that accident load-bearing: against "Copper Kettle" in the
+        // Kitchen category, "kettle kitchen" found nothing while "kettle" alone
+        // worked, and the first is what someone narrowing a list types.
+        const queries = new Map<string, string[]>();
+        for (const name of names) {
+            if (fields[name]?.kind !== "text") continue;
+            const folded = fold(state[name] as string);
+            queries.set(name, folded === "" ? [] : folded.split(/\s+/));
+        }
+
+        const next = new Set<string>();
+        for (const item of items) {
+            let hit = true;
+            for (const name of names) {
+                const kind = fields[name]?.kind;
+                if (kind === "text") {
+                    const tokens = queries.get(name) ?? [];
+                    if (tokens.length === 0) continue;
+                    const haystack = haystacks.get(item.key)?.get(name) ?? "";
+                    if (!tokens.every((token) => haystack.includes(token))) {
+                        hit = false;
+                        break;
+                    }
+                } else if (kind === "choice") {
+                    const wanted = state[name] as string;
+                    if (wanted === "") continue;
+                    if (item.values[name] !== wanted) {
+                        hit = false;
+                        break;
+                    }
+                } else {
+                    // A flag off is not a filter: it keeps everything, rather
+                    // than keeping the items that are *not* flagged. See `Field`.
+                    if (state[name] !== true) continue;
+                    if (item.values[name] !== true) {
+                        hit = false;
+                        break;
+                    }
+                }
+            }
+            if (hit) next.add(item.key);
+        }
+        matched = next;
+    }
+
+    function readUrl(): void {
+        const search = new URLSearchParams(window.location.search);
+        const next: Record<string, string | boolean> = {};
+        for (const name of names) {
+            const field = fields[name];
+            if (field === undefined) continue;
+            if (field.param === undefined) {
+                // A state-only field is not in the URL, so the URL has nothing
+                // to say about it — and a back button is the URL speaking.
+                // Clearing it here read "absent from the URL" as "empty", which
+                // wiped a search the reader was in the middle of the moment any
+                // other parameter on the page moved. Left as it is instead: this
+                // function applies the URL, and this field is not in it.
+                next[name] = state[name];
+                continue;
+            }
+            const raw = search.get(field.param);
+            next[name] = field.kind === "flag" ? raw === FLAG_ON : (raw ?? "");
+        }
+        state = next as FilterState<F>;
+    }
+
+    function writeUrl(history: "push" | "replace"): void {
+        if (!attached) return;
+
+        // Started from the URL that is there, not from an empty set. A list owns
+        // the parameters it declared and nothing else, and the page around it is
+        // full of parameters that are not its business — `utm_*` on a link
+        // someone shared, a page number, another widget's state. Building from
+        // scratch published a URL with all of them gone, and the loss only
+        // showed up somewhere else: a campaign that stopped being attributed the
+        // first time a visitor typed in the search box.
+        //
+        // Its own are deleted first, then rewritten, so a parameter this list
+        // owns and no longer needs is dropped rather than surviving because
+        // nobody thought to remove it. Deletion and writing both run in
+        // declaration order, so one state still produces 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);
+                continue;
+            }
+            const value = (state[name] as string).trim();
+            if (value !== "") search.set(field.param, value);
+        }
+
+        const query = search.toString();
+        // The bare path when nothing is left, rather than a trailing `?`: the
+        // two are the same page, and only one of them is worth sharing. Read
+        // from the merged set, so a page carrying somebody else's parameter
+        // keeps it instead of being reduced to its path.
+        const url = query === "" ? window.location.pathname : `?${query}`;
+        if (history === "push") window.history.pushState({}, "", url);
+        else window.history.replaceState({}, "", url);
+    }
+
+    /**
+     * One field's value as the matcher and the URL will read it.
+     *
+     * Only `text` has a form that differs from what was handed over — the other
+     * kinds compare and publish exactly what they hold.
+     */
+    const normalized = (name: keyof F & string, value: unknown): unknown =>
+        fields[name]?.kind === "text" ? (value as string).trim() : value;
+
+    const announce = (): void => onChange({ state, matched });
+
+    recompute();
+
+    return {
+        get state() {
+            return state;
+        },
+        get matched() {
+            return matched;
+        },
+
+        set(field, value, setOptions) {
+            const name = field as keyof F & string;
+            // Compared as everything downstream will read it, not as it arrived.
+            // Both the matcher and the URL trim a query, so "sol" and "sol "
+            // filter the same list and publish the same address — but comparing
+            // them raw called that a change, and a trailing space cost a
+            // recompute, a `replaceState` to a URL identical to the current one,
+            // and a full re-render of every item.
+            //
+            // The *raw* value is what gets stored, though, and that asymmetry is
+            // deliberate. A search box mirrors the state back into the input
+            // (see `filters-view`), so normalising here would delete the space a
+            // reader had just typed, from under the caret, every time they
+            // reached for the second word.
+            if (normalized(name, state[name]) === normalized(name, value)) {
+                return;
+            }
+
+            state = { ...state, [name]: value };
+            recompute();
+            const fallback = fields[name]?.kind === "text" ? "replace" : "push";
+            writeUrl(setOptions?.history ?? fallback);
+            announce();
+        },
+
+        reset(field) {
+            if (field === undefined) {
+                // Short-circuited like the single-field arm below, which it was
+                // not. A "clear all" on a list nobody has filtered yet is a
+                // no-op, and pushing for it puts a step in history that goes
+                // back to the state it is already in — so the back button looks
+                // broken to the one reader who pressed clear twice.
+                if (names.every((name) => state[name] === empty(name))) return;
+                state = blank();
+            } else {
+                const name = field as keyof F & string;
+                if (state[name] === empty(name)) return;
+                state = { ...state, [name]: empty(name) };
+            }
+            recompute();
+            writeUrl("push");
+            announce();
+        },
+
+        attach() {
+            const listeners = new AbortController();
+
+            // On `window`, and with the same signal as everything else, so a
+            // detach takes it with them. A `popstate` listener that outlives its
+            // page is the one leak here that has no visible symptom: it keeps
+            // rendering into markup that has been replaced.
+            window.addEventListener(
+                "popstate",
+                () => {
+                    readUrl();
+                    recompute();
+                    announce();
+                },
+                { signal: listeners.signal }
+            );
+
+            attached = true;
+            // Read before the first announcement, not after: the URL may already
+            // carry a state — from a shared link, a reload, or a no-script form
+            // submission the server rendered — and announcing the empty one
+            // first would flash the unfiltered list over it.
+            readUrl();
+            recompute();
+            announce();
+
+            return () => {
+                listeners.abort();
+                attached = false;
+            };
+        },
+    };
+}

package/src/astro/images.ts

@@ -10,6 +10,7 @@ import { getImage } from "astro:assets";
 import type { ImageAsset } from "../image.ts";
 import type { ThemeColor } from "../meta/index.ts";
 import type { Percentage } from "../types.ts";
+import { isUrlPath, type UrlPath } from "../url.ts";
 import { warn } from "../warn.ts";
 
 /**
@@ -313,3 +314,75 @@ export async function photoSet(
         })
     );
 }
+
+/**
+ * What `getImage` takes, less the source.
+ *
+ * A passthrough of Astro's own options, which is a deliberate departure from
+ * `ShareImageOptions` and `PhotoSetOptions` above. Those two are closed shapes
+ * because they are *builders*: each decides a box, and letting a caller reach
+ * past that decision would defeat the point of having made it. This one decides
+ * nothing — it exists to hand back a path instead of an object — so narrowing
+ * the options would only make it strictly less useful than the call it wraps.
+ */
+export type ImagePathOptions = Omit<Parameters<typeof getImage>[0], "src">;
+
+/**
+ * The built URL of an optimised image, for the places that take a path rather
+ * than an `<img>` — a JSON-LD node, a `<link>`, a manifest.
+ *
+ * ```ts
+ * import logo from "~/assets/logo.png";
+ * import { imagePath } from "@escape-game-over/atlas/astro/images";
+ *
+ * const company = organization({
+ *     logo: await imagePath(logo, { width: 512, height: 512, format: "png" }),
+ *     // …
+ * });
+ * ```
+ *
+ * The narrowing is the reason this is a function rather than three lines at
+ * each call site. `getImage().src` is typed `string`, every field it feeds here
+ * is typed `UrlPath`, and a cast at each of those would put the same unchecked
+ * assumption in as many places as there are consumers.
+ *
+ * **Not for entity data.** What comes back is `/_astro/logo.<hash>.png`, and the
+ * hash moves every time the source file is touched. That is right for a page
+ * resource, which is re-fetched from a document that was just re-fetched, and
+ * wrong for anything a search engine stores against an identity — an
+ * `Organization.logo` above all, which is held long after the build that
+ * produced it. Those want a stable path out of `public/`, written as `/logo.png`
+ * and joined to the site's own origin; both examples in this repository do that
+ * deliberately and say so at the call site.
+ *
+ * So the fit is: a `<link rel="preload">`, a manifest icon, an `<img>` built by
+ * hand — resources fetched *with* the page. Long-lived references belong in
+ * `public/`.
+ */
+export async function imagePath(
+    src: ImageMetadata,
+    options: ImagePathOptions = {}
+): Promise<UrlPath> {
+    const image = await getImage({ ...options, src });
+
+    // Thrown rather than warned, and thrown here rather than widened away.
+    //
+    // `UrlPath` is root-relative by definition and the fields this feeds are
+    // typed that way on purpose — a `logo` on an `Organization` node is read by
+    // a crawler that already has the origin. What trips this is not a bad image
+    // but a different deployment: `build.assetsPrefix`, or an image service that
+    // returns absolute URLs. Both are a decision about where the whole site's
+    // assets live, and answering it by loosening one return type would leave
+    // every consumer of `UrlPath` accepting a value it cannot use.
+    //
+    // So this stops at the boundary and says which boundary it is. There is
+    // nothing useful to return: a caller that carried on would put a string into
+    // structured data that no crawler can resolve.
+    if (!isUrlPath(image.src)) {
+        throw new Error(
+            `imagePath produced "${image.src}", which is not root-relative. This build serves assets from somewhere else — build.assetsPrefix, or a remote image service — and the fields this feeds are typed UrlPath, which cannot express that. Serving assets from another origin is a site-wide decision and needs the absolute form carried end to end, not this one return type widened.`
+        );
+    }
+
+    return image.src;
+}

package/src/astro/site-routes.ts

@@ -10,6 +10,7 @@ import {
 import type { Sitemap } from "../sitemap.ts";
 import type { HttpsUrl } from "../url.ts";
 import { warn } from "../warn.ts";
+import { buildCacheDir } from "./build-cache.ts";
 
 /**
  * What this integration needs of a site, and no more.
@@ -187,6 +188,19 @@ export function siteRoutes(options: SiteRoutesOptions): AstroIntegration {
              *   images. A default worth overriding per site, not a rule —
              *   though not into `prerender`; see the refusal below.
              *
+             * A fifth is set only when the environment asks for it:
+             *
+             * - `cacheDir`, moved onto whatever cache volume CI mounted. Not a
+             *   preference — Astro's default sits inside `node_modules`, which
+             *   a CI install deletes before every run, so a build there
+             *   re-optimizes every image and re-downloads every font each time,
+             *   however little changed. Set here rather than per repo because
+             *   Astro exposes no environment variable for it, and `updateConfig`
+             *   is already how this integration says what a site's build looks
+             *   like. Off CI the value is `undefined`, the merge skips the key,
+             *   and the default stays exactly where it was. See
+             *   `build-cache.ts` for what shares the volume and what would not.
+             *
              * Two are refused rather than set, both because Astro resolves them
              * to a default a deliberate value is distinguishable from — so the
              * check fires at whoever asked for it rather than at everyone:
@@ -273,6 +287,7 @@ export function siteRoutes(options: SiteRoutesOptions): AstroIntegration {
                         prefetchAll: true,
                         defaultStrategy: "viewport",
                     },
+                    cacheDir: buildCacheDir(),
                 };
                 updateConfig(config);
                 // Said out loud: a setting changed from under you is worth a

package/src/contact-form.ts

@@ -41,7 +41,7 @@ export interface MailEndpoint {
      */
     readonly url: HttpsUrl;
     /**
-     * The account the message is sent on behalf of: `"b2b_cube"`.
+     * The account the message is sent on behalf of, e.g. `"acme_b2b"`.
      *
      * What the API looks the mailbox and the allowed domains up by. A domain
      * that is not registered against it is refused, and nothing configured here

package/src/index.ts

@@ -101,6 +101,8 @@ export {
     breadcrumbList,
     businessId,
     type CatalogEntry,
+    type FaqEntry,
+    faqPage,
     geoCoordinates,
     type JsonLdNode,
     type LocalBusinessInput,