@escape-game-over/atlas 0.1.1 → 0.1.3

package/src/astro/filters.ts

@@ -0,0 +1,457 @@
+/**
+ * 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: games.map((game) => ({
+ *         key: game.id,
+ *         values: { q: `${game.name} ${game.blurb}`, category: game.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. "Arena only", "In stock".
+ *
+ * `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 `abilita` is told there is no
+ * *Abilità*, 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 `?arena=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.
+        const queries = new Map<string, string>();
+        for (const name of names) {
+            if (fields[name]?.kind !== "text") continue;
+            queries.set(name, fold(state[name] as string));
+        }
+
+        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 query = queries.get(name) ?? "";
+                    if (query === "") continue;
+                    if (
+                        !(haystacks.get(item.key)?.get(name) ?? "").includes(
+                            query
+                        )
+                    ) {
+                        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) {
+                // No parameter: the field is state-only, and a reload starts it
+                // empty rather than carrying a value the URL never held.
+                next[name] = empty(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;
+
+        // Built from the declaration rather than from the URL that is there, so
+        // a parameter this list owns and no longer needs is dropped instead of
+        // surviving because nobody thought to delete it. Fields are written in
+        // declaration order, so the same state always produces the same URL.
+        const search = new URLSearchParams();
+        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 set, rather than a trailing `?`: the two
+        // are the same page, and only one of them is worth sharing.
+        const url = query === "" ? window.location.pathname : `?${query}`;
+        if (history === "push") window.history.pushState({}, "", url);
+        else window.history.replaceState({}, "", url);
+    }
+
+    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;
+            // Nothing changed, so nothing is announced and nothing is pushed.
+            // Typing a character that does not alter a trimmed query, or
+            // re-selecting the tab that is already current, should not put a
+            // step in history for the back button to walk through.
+            if (state[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) {
+                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;
+}