@escape-game-over/atlas 0.1.26 → 0.1.28

package/docs/client-scripts.md

@@ -46,8 +46,8 @@ finding them.
 analytics={…}>` (`@escape-game-over/atlas/astro/consent-banner`) renders the
 site's markup as its children, skips itself — script included — when the
 analytics need no permission, and remembers, expires and applies the answer. The
-markup spreads `consent.accept` and `consent.decline` on its buttons, and
-`consent.reopen` on the control that brings it back.
+markup marks its buttons `data-consent="grant"` and `data-consent="deny"`,
+and the control that brings it back `data-consent-reopen hidden`.
 
 **Browser code has one import path: `@escape-game-over/atlas/client`**, which
 re-exports every module above. None of it touches the DOM at import, so an
@@ -73,15 +73,15 @@ runs when the element enters the page, `signal` ends what it registered when the
 element leaves, and what it returns is the undo for everything else.
 
 ```ts
-export const thing = element("go-thing", ({ host, signal }) => {
-    ref(host, "[data-thing-button]").addEventListener("click", open, { signal });   // ends with the visit
-    return loop.attach(host);                                                        // and so does this
+export const thing = element("go-thing", ({ root, signal }) => {
+    ref(root, "[data-thing-button]").addEventListener("click", open, { signal });   // ends with the visit
+    return loop.attach(root);                                                        // and so does this
 });
 ```
 
 An element can enter the page more than once — moving it in the DOM runs the
 undo and then the function again — so it has to be able to run twice. State that
-must survive a move goes in a `WeakMap` keyed by `host`, which is what the
+must survive a move goes in a `WeakMap` keyed by `root`, which is what the
 carousel example does with its index.
 
 **The trap this exists for is view transitions.** A bundled `<script src>` is an
@@ -98,50 +98,46 @@ handled. Without a re-`attach` there is simply nothing wired.
 ## `filters`
 
 A list already rendered by the server, narrowed in the browser and mirrored in
-the URL. The caller declares fields; the item shape follows from them.
+the URL. The caller declares fields and hands over its own items — elements,
+records, whatever it holds — with how to read each one's values.
 
 ```ts
 const list = filters({
-    fields: {
-        q:        { kind: "text" },
-        category: { kind: "choice" },
-        featured: { kind: "flag" },
+    fields: { q: "text", category: "choice", featured: "flag" },
+    items: rows,
+    values: (row) => ({
+        q: data(row, "text"),
+        category: data(row, "category"),
+        featured: row.hasAttribute("data-featured"),
+    }),
+    onChange: ({ matched }) => {
+        for (const row of rows) row.hidden = !matched.has(row);
     },
-    items: entries.map((entry) => ({
-        key: entry.id,
-        values: {
-            q: `${entry.title} ${entry.summary}`,
-            category: entry.category,
-            featured: entry.featured,
-        },
-    })),
-    onChange: ({ matched, state }) => { /* the project's DOM writes, all of them */ },
 });
 
 const detach = list.attach();
 ```
 
-Fields are plain data rather than `text()` / `choice()` / `flag()` builders:
-three exported names that general — `text` above all — in a module a project
-imports by name, to return exactly this object. `values` is typed *from*
+A field is its kind, and its URL parameter is its own name — to rename the
+parameter, rename the field. `{ kind: "text", url: false }` keeps a field out of
+the URL, for a list whose page owns the URL itself. `values` is typed *from*
 `fields`, so a `flag` demands a boolean and a mismatch is a compile error rather
-than an item that silently never matches.
+than an item that silently never matches. It is read once per item, at
+construction. `matched` is a set of the caller's own items, so there is no key
+to invent, carry in the markup and map back.
 
 | Kind     | State           | Item value      | Matches when                                     | In the URL                      | History |
 | -------- | --------------- | --------------- | ------------------------------------------------ | ------------------------------- | ------- |
 | `text`   | the query       | searchable text | every folded query word appears; empty keeps all | `?q=…`, dropped if empty        | replace |
 | `choice` | one value, `""` | one, or several | the item holds the chosen one; `""` keeps all    | `?category=…`, dropped if empty | push    |
-| `flag`   | boolean         | boolean         | off keeps all; on keeps only items that carry it | `?featured=1`, absent when off  | push    |
+| `flag`   | boolean         | boolean         | off keeps all; on keeps only items that carry it | `?featured`, absent when off    | push    |
 
 **A `choice` item may hold several values.** The state stays one — the tab strip
 picks one category, the URL carries one — but an item can sit in more than one
 and then answers to any of them:
 
 ```ts
-items: [
-    { key: "burgos", values: { category: "city" } },
-    { key: "avila",  values: { category: ["walk", "city"] } },
-]
+values: (room) => ({ category: data(room, "categories").split(" ") }),
 ```
 
 An escape room is adventure *and* sci-fi; a film is a comedy *and* a drama. This
@@ -175,8 +171,6 @@ pass. What is deliberately absent is one field holding several selected values;
 that is a `choices` kind, and it forces a URL encoding decision (repeated
 parameters or comma-joined) that nothing has needed yet.
 
-`param` defaults to the field's name. `param: false` keeps a field state-only, out of the URL.
-
 ### Facet counts: `matchedWithout`
 
 A dropdown that says how many results each option would give needs a different
@@ -191,7 +185,7 @@ onChange({ matched }) {
     for (const option of countryOptions) {
         const value = option.dataset.choice;
         const count = rows.filter(
-            (row) => rest.has(row.key) && row.country === value
+            (row) => rest.has(row) && row.country === value
         ).length;
         // …the project writes `count` wherever its design puts it
     }
@@ -236,21 +230,12 @@ instead of flashing the whole list back. Nothing writes to the URL before
 `attach`, because `attach` is what reads it — a `set` on an unattached instance
 would overwrite state nobody had loaded.
 
-A set flag is written `1` and an unset one is **absent** rather than `=0`. One
-spelling for off keeps the URL short and leaves a single form to parse; the cost
-is that a hand-written `?featured=0` reads as off, which is the answer it would have
-got anyway. `1` and not `true` because that is what the existing lists already
-emit, and links people have shared should keep resolving to the view they named.
-
-### Two things it refuses at construction
-
-Both are silent otherwise:
-
-- **Two items under one key.** `matched` could not say which of them matched.
-- **Two fields on one URL parameter.** Each write erases the other's value, which
-  reads as a filter that will not stay set.
+A flag is on by being there, as an HTML boolean attribute is: written as the bare
+`?featured`, and **absent** when off. Reading asks only whether the name is
+present, so `?featured=1` from an older link still reads as on — and so does a
+hand-written `?featured=false`, just as `hidden="false"` still hides.
 
-And a `set` to the value already held announces nothing and pushes nothing, so
+A `set` to the value already held announces nothing and pushes nothing, so
 re-clicking the current tab does not add a history step to walk back through.
 
 ## `filters-view`
@@ -275,9 +260,9 @@ const list = filters({
 });
 const detach = list.attach();
 const unbind = searchBox(list, "q", {
-    input: one<HTMLInputElement>("[data-filter-search]"),
-    clear: one("[data-filter-clear]"),
-    empty: one("[data-filter-empty]"),
+    input: ref<HTMLInputElement>(root, "[data-filter-search]"),
+    clear: ref(root, "[data-filter-clear]"),
+    empty: ref(root, "[data-filter-empty]"),
 });
 ```
 
@@ -369,9 +354,9 @@ behaviour and runs it for as long as the element is on the page, and `ref` and
 
 ```ts
 // faq.ts — imported by the template for the tag, and loaded by the page's script
-export const faq = element("go-faq", ({ host, signal }) => {
-    const input = ref<HTMLInputElement>(host, "[data-faq-search]");
-    for (const row of refs<HTMLDetailsElement>(host, "[data-faq-row]")) {
+export const faq = element("go-faq", ({ root, signal }) => {
+    const input = ref<HTMLInputElement>(root, "[data-faq-search]");
+    for (const row of refs<HTMLDetailsElement>(root, "[data-faq-row]")) {
         row.dataset.key;
     }
 });
@@ -422,7 +407,7 @@ attribute, and the script writes only that run:
 ```
 
 ```ts
-for (const each of refs(host, "[data-faq-count]")) each.textContent = String(hits.size);
+for (const each of refs(root, "[data-faq-count]")) each.textContent = String(hits.size);
 ```
 
 Marks are parsed before placeholders are filled, so a run filled with `""`
@@ -565,9 +550,11 @@ right properties is a faithful stand-in.
   that `ref` throws naming the root and the selector.
 - `tests/element.test.ts` stubs `customElements` to upgrade on `define`, as a
   browser does, and pins what `connect` is handed.
+- `tests/consent.test.ts` fakes `localStorage`, with a switch that makes it
+  throw, and the Google hook, and pins the six-month expiry to the day.
 
-`carousel` and `consent` have none, and `element` has no lifecycle test — moves
-and teardown. They need a real DOM and
+`carousel` has none, nor does the consent banner's element, and `element` has
+no lifecycle test — moves and teardown. They need a real DOM and
 this package carries no environment for one; adding `happy-dom` as a dev
 dependency and setting `environment` in `vitest.config.ts` is what that would
 take.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.26",
+    "version": "0.1.28",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,

package/src/analytics/index.ts

@@ -72,12 +72,9 @@ export function analyticsScripts(
 /**
  * Whether this deployment loads anything a visitor has to be asked about.
  *
- * The build-time twin of `consentApplies()` in `astro/consent.ts`, which asks
- * the same question in the browser by looking for the global the Google tag
- * defines. That one cannot answer it early enough to be useful: a consent
- * banner's script has to be downloaded, parsed and run before it can report
- * that there was nothing to consent to — three requests to learn that none of
- * them were needed. Asked here, a project leaves the banner out of the HTML.
+ * The one place that question is answered, and at build time: a project leaves
+ * the banner — script and all — out of the HTML, rather than shipping a script
+ * to find out in the browser that there was nothing to ask.
  *
  * Vendor by vendor rather than `analytics.google !== undefined`, because that
  * is not the question. A `google` block carrying no ids emits no tag and sets

package/src/astro/ConsentBanner.astro

@@ -1,11 +1,12 @@
 ---
 /**
  * The consent banner's behaviour; the site supplies its markup and copy as the
- * children, with `consent.accept` and `consent.decline` on its buttons.
+ * children, with `data-consent="grant"` and `data-consent="deny"` on its
+ * buttons.
  *
  * Renders nothing — and ships no script — when this site's analytics need no
  * permission. Otherwise the banner starts hidden and shows only to a visitor
- * with no answer on record, or when `consent.reopen` is pressed.
+ * with no answer on record, or when a `data-consent-reopen` control is pressed.
  */
 import type { HTMLAttributes } from "astro/types";
 import { type AnalyticsSettings, consentRequired } from "../analytics/index.ts";

package/src/astro/ConsentElement.astro

@@ -2,11 +2,13 @@
 /** Internal to `ConsentBanner.astro`, so its script ships only where it renders. */
 import type { HTMLAttributes } from "astro/types";
 import AtlasElement from "./AtlasElement.astro";
-import { consentBanner } from "./consent.ts";
+import { consentBanner } from "./consent-element.ts";
 
 type Props = HTMLAttributes<"div">;
 ---
 
+<script src="./consent-element.ts" />
+
 <AtlasElement
     of={consentBanner}
     {...Astro.props}
@@ -16,52 +18,3 @@ type Props = HTMLAttributes<"div">;
 >
     <slot />
 </AtlasElement>
-
-<script>
-import {
-    applyConsent,
-    CONSENT_ANSWER,
-    CONSENT_REOPEN,
-    consentApplies,
-    consentStore,
-} from "./consent.ts";
-import { element } from "./element.ts";
-import { refs } from "./ref.ts";
-
-element("atlas-consent", ({ host, signal }) => {
-    // The head script left no consent hook: nothing here sets a cookie.
-    if (!consentApplies()) return;
-
-    const store = consentStore();
-    const show = (): void => {
-        host.hidden = false;
-    };
-
-    for (const button of refs(host, `[${CONSENT_ANSWER}]`)) {
-        const choice = button.getAttribute(CONSENT_ANSWER);
-        if (choice !== "granted" && choice !== "denied") {
-            throw new Error(`${CONSENT_ANSWER} is "${choice}"`);
-        }
-        button.addEventListener(
-            "click",
-            () => {
-                store.record(choice);
-                host.hidden = true;
-            },
-            { signal }
-        );
-    }
-
-    // Outside the banner — withdrawing must be as easy as granting.
-    for (const button of refs(document, `[${CONSENT_REOPEN}]`)) {
-        button.hidden = false;
-        button.addEventListener("click", show, { signal });
-    }
-
-    // Applied, not re-recorded: recording stamps today's date, and an answer
-    // renewed on every page view never expires.
-    const stored = store.read();
-    if (stored === undefined) show();
-    else applyConsent(stored.choice);
-});
-</script>

package/src/astro/client.ts

@@ -11,15 +11,6 @@
 
 export * from "./background-video.ts";
 export * from "./carousel.ts";
-export {
-    applyConsent,
-    type ConsentChoice,
-    type ConsentRecord,
-    type ConsentStoreOptions,
-    consent,
-    consentApplies,
-    consentStore,
-} from "./consent.ts";
 export {
     type Connect,
     type ElementContext,

package/src/astro/consent-element.ts

@@ -0,0 +1,59 @@
+import {
+    applyConsent,
+    type ConsentChoice,
+    readConsent,
+    recordConsent,
+} from "./consent.ts";
+import { element } from "./element.ts";
+import { data, refs } from "./ref.ts";
+
+/** What each button does, in the words Consent Mode records. */
+const ACTIONS: Readonly<Record<string, ConsentChoice>> = {
+    grant: "granted",
+    deny: "denied",
+};
+
+/**
+ * The banner's behaviour. Its own module, and not re-exported from `client.ts`,
+ * so the script ships only where `<ConsentBanner>` renders.
+ *
+ * A site's markup marks the two buttons inside the banner `data-consent="grant"`
+ * and `data-consent="deny"`, and the control that brings it back — usually in
+ * the footer — `data-consent-reopen hidden`: it stays hidden until there is an
+ * answer to withdraw.
+ */
+export const consentBanner = element("atlas-consent", ({ root, signal }) => {
+    const show = (): void => {
+        root.hidden = false;
+    };
+
+    for (const button of refs(root, "[data-consent]")) {
+        const action = data(button, "consent");
+        const choice = Object.hasOwn(ACTIONS, action)
+            ? ACTIONS[action]
+            : undefined;
+        if (choice === undefined) {
+            throw new Error(`data-consent is "${action}", not grant or deny`);
+        }
+        button.addEventListener(
+            "click",
+            () => {
+                recordConsent(choice);
+                root.hidden = true;
+            },
+            { signal }
+        );
+    }
+
+    // Outside the banner — withdrawing must be as easy as granting.
+    for (const button of refs(document, "[data-consent-reopen]")) {
+        button.hidden = false;
+        button.addEventListener("click", show, { signal });
+    }
+
+    // Applied, not re-recorded: recording stamps today's date, and an answer
+    // renewed on every page view never expires.
+    const stored = readConsent();
+    if (stored === undefined) show();
+    else applyConsent(stored.choice);
+});

package/src/astro/consent.ts

@@ -1,24 +1,4 @@
 import { CONSENT_UPDATE_GLOBAL } from "../analytics/google.ts";
-import type { ElementTag } from "./element.ts";
-
-/** Internal to `ConsentBanner.astro`: the element, and what its script finds. */
-export const consentBanner: ElementTag<"atlas-consent"> = {
-    tag: "atlas-consent",
-};
-export const CONSENT_ANSWER = "data-atlas-consent-answer";
-export const CONSENT_REOPEN = "data-atlas-consent-reopen";
-
-/**
- * What a site's consent markup spreads: the two answer buttons inside
- * `<ConsentBanner>`, and the control that brings it back — which belongs on
- * every page, usually the footer, and stays hidden until there is something to
- * withdraw.
- */
-export const consent = {
-    accept: { [CONSENT_ANSWER]: "granted" },
-    decline: { [CONSENT_ANSWER]: "denied" },
-    reopen: { [CONSENT_REOPEN]: "", hidden: "" },
-};
 
 /**
  * The browser half of consent: remembering an answer, expiring it, and handing
@@ -57,104 +37,63 @@ export interface ConsentRecord {
  * is no way to expire it, and no way to answer "when did this visitor agree?",
  * which is a question only ever asked when somebody is already unhappy.
  */
-const DEFAULT_MONTHS = 6;
+const MONTHS = 6;
 
 /**
- * Where the answer is kept.
- *
- * `localStorage` is already scoped to an origin, so this does not need to
- * identify the site — what it needs is to not collide with something else on
- * the page, and a bare `"consent"` is exactly the key a third-party consent
- * tool or chat widget would reach for. The prefix matches
- * `CONSENT_UPDATE_GLOBAL`, so one concept has one name on both sides.
- *
- * Overridable for the case the default cannot cover: two deployments sharing
- * one origin — `example.com/rome` and `example.com/bucharest` — where one key
- * would mean one answer for both. See `consentStore`.
+ * The `localStorage` key the answer is kept under. Prefixed to keep clear of the
+ * bare `"consent"` a third-party widget would reach for.
  */
-const DEFAULT_KEY = "__consent";
-
-export interface ConsentStoreOptions {
-    /** Overrides `DEFAULT_KEY`. See it for the one case that needs this. */
-    readonly key?: string;
-    /** Overrides the six-month window. See `DEFAULT_MONTHS`. */
-    readonly months?: number;
-}
+const KEY = "atlas-consent";
 
 /**
- * Reading and writing an answer, bound to one key and one window.
+ * The answer this visitor gave, if it still counts.
  *
- * A factory rather than two functions each taking options, because the key and
- * the window have to *match* between them: a read that looked in one place and
- * a write that filled another would ask a visitor on every page while
- * faithfully recording each answer. Bound once, they cannot disagree.
+ * `undefined` for never asked, for an expired answer, and for anything
+ * unparseable — all three mean the same thing to a banner, and all three should
+ * ask rather than assume.
  */
-export function consentStore(options: ConsentStoreOptions = {}): {
-    read(): ConsentRecord | undefined;
-    record(choice: ConsentChoice): void;
-} {
-    const key = options.key ?? DEFAULT_KEY;
-    const months = options.months ?? DEFAULT_MONTHS;
-
-    return {
-        /**
-         * The answer this visitor gave, if it still counts.
-         *
-         * `undefined` for never asked, for an expired answer, and for anything
-         * unparseable — all three mean the same thing to a banner, and all
-         * three should ask rather than assume. Storage hand-edited, or written
-         * by an older version of this code, lands in the third case by design.
-         */
-        read(): ConsentRecord | undefined {
-            let raw: string | null = null;
-            try {
-                raw = localStorage.getItem(key);
-            } catch {
-                // Private browsing, or storage disabled. Nothing was
-                // remembered, so nothing is assumed.
-                return undefined;
-            }
-            if (raw === null) return undefined;
-
-            try {
-                const parsed = JSON.parse(raw) as Partial<ConsentRecord>;
-                if (parsed.choice !== "granted" && parsed.choice !== "denied") {
-                    return undefined;
-                }
-                if (typeof parsed.at !== "string") return undefined;
-
-                const expiry = new Date(parsed.at);
-                if (Number.isNaN(expiry.getTime())) return undefined;
-                expiry.setMonth(expiry.getMonth() + months);
-                if (expiry < new Date()) return undefined;
-
-                return { choice: parsed.choice, at: parsed.at };
-            } catch {
-                return undefined;
-            }
-        },
+export function readConsent(): ConsentRecord | undefined {
+    let raw: string | null = null;
+    try {
+        raw = localStorage.getItem(KEY);
+    } catch {
+        // Private browsing, or storage disabled. Nothing was remembered, so
+        // nothing is assumed.
+        return undefined;
+    }
+    if (raw === null) return undefined;
+
+    try {
+        const parsed = JSON.parse(raw) as Partial<ConsentRecord>;
+        if (parsed.choice !== "granted" && parsed.choice !== "denied") {
+            return undefined;
+        }
+        if (typeof parsed.at !== "string") return undefined;
+
+        const expiry = new Date(parsed.at);
+        if (Number.isNaN(expiry.getTime())) return undefined;
+        expiry.setMonth(expiry.getMonth() + MONTHS);
+        if (expiry < new Date()) return undefined;
+
+        return { choice: parsed.choice, at: parsed.at };
+    } catch {
+        return undefined;
+    }
+}
 
-        /**
-         * Remembers an answer, dated now, and tells Google about it.
-         *
-         * One call rather than two, because the two must not come apart: an
-         * answer stored but never applied leaves the visitor consented in name
-         * only, and one applied but never stored asks them again next page.
-         */
-        record(choice: ConsentChoice): void {
-            const record: ConsentRecord = {
-                choice,
-                at: new Date().toISOString(),
-            };
-            try {
-                localStorage.setItem(key, JSON.stringify(record));
-            } catch {
-                // Unable to remember it, which is a worse experience and not a
-                // wrong one — the choice still applies to this page.
-            }
-            applyConsent(choice);
-        },
-    };
+/**
+ * Remembers an answer, dated now, and tells Google about it — one call, so the
+ * two cannot come apart.
+ */
+export function recordConsent(choice: ConsentChoice): void {
+    const record: ConsentRecord = { choice, at: new Date().toISOString() };
+    try {
+        localStorage.setItem(KEY, JSON.stringify(record));
+    } catch {
+        // Unable to remember it, which is a worse experience and not a wrong
+        // one — the choice still applies to this page.
+    }
+    applyConsent(choice);
 }
 
 /**
@@ -174,12 +113,3 @@ export function applyConsent(choice: ConsentChoice): void {
     )[CONSENT_UPDATE_GLOBAL];
     update?.(choice);
 }
-
-/** Whether this deployment has a Google tag to consent to at all. */
-export function consentApplies(): boolean {
-    return (
-        (window as unknown as Record<string, unknown>)[
-            CONSENT_UPDATE_GLOBAL
-        ] !== undefined
-    );
-}

package/src/astro/element.ts

@@ -12,7 +12,8 @@ export const ROOT_ATTRIBUTE = "data-atlas-root";
 type Undo = void | (() => void);
 
 export interface ElementContext {
-    readonly host: HTMLElement;
+    /** The element itself: where `ref` and `refs` search from. */
+    readonly root: HTMLElement;
     /** Aborted when the element leaves, taking its listeners with it. */
     readonly signal: AbortSignal;
 }
@@ -33,8 +34,8 @@ export interface ElementTag<Tag extends string = string> {
  *
  * ```ts
  * // faq.ts — imported by the template for the tag, and by the page's script
- * export const faq = element("go-faq", ({ host, signal }) => {
- *     const input = ref<HTMLInputElement>(host, "[data-faq-search]");
+ * export const faq = element("go-faq", ({ root, signal }) => {
+ *     const input = ref<HTMLInputElement>(root, "[data-faq-search]");
  *     …
  * });
  * ```
@@ -48,7 +49,7 @@ export interface ElementTag<Tag extends string = string> {
  *
  * - **An element can enter the page more than once.** Moving it runs the undo
  *   and `connect` again; Astro's `ClientRouter` does so on every navigation.
- *   State that must survive belongs in a `WeakMap` keyed by `host`.
+ *   State that must survive belongs in a `WeakMap` keyed by `root`.
  * - **The page's script must stay a bundled module** (a plain `<script>`), so
  *   the element has its children when it upgrades.
  * - **Failures show in dev.** A `connect` that throws leaves that one element
@@ -115,7 +116,7 @@ function define(tag: string, connect: Connect): void {
                         );
                     }
                     this.#undo =
-                        connect({ host: this, signal: ac.signal }) ?? undefined;
+                        connect({ root: this, signal: ac.signal }) ?? undefined;
                 } catch (error) {
                     reportDevError(this.localName, error);
                 }

package/src/astro/filters-view.ts

@@ -10,21 +10,18 @@
  * on a clear button, an empty message or a section with nothing left. No class,
  * style or `aria`: that is where the choices live.
  *
- * Two notes for the markup:
- *
- * - **`hidden` needs help in a grid.** Any author rule setting `display` beats
- *   it. Tailwind v4's preflight ships `[hidden] { display: none !important }`;
- *   without something like it these writes are inert and nothing filters.
- * - **A result count wants `aria-live="polite"`**, in the template.
+ * **`hidden` needs help in a grid.** Any author rule setting `display` beats it.
+ * Tailwind v4's preflight ships `[hidden] { display: none !important }`; without
+ * something like it these writes are inert and nothing filters.
  *
  * See docs/client-scripts.md.
  */
 
-import type { FieldMap, FilterChange, Filters } from "./filters.ts";
+import type { FieldMap, FilterChange, Filters, KindOf } from "./filters.ts";
 
 /** The `text` fields of `F`, so a search box cannot be pointed at a flag. */
 export type TextFieldOf<F extends FieldMap> = {
-    [K in keyof F]: F[K] extends { kind: "text" } ? K : never;
+    [K in keyof F]: KindOf<F[K]> extends "text" ? K : never;
 }[keyof F];
 
 /**
@@ -38,12 +35,6 @@ export interface SearchBoxElements {
     readonly clear?: HTMLElement | null;
     /** The "nothing matched" message. Tracks the whole result set. */
     readonly empty?: HTMLElement | null;
-    /**
-     * How many matched, as digits and nothing else: the sentence around them is
-     * translated, and not something to take apart in a browser. Give the count
-     * its own element and let the copy sit beside it.
-     */
-    readonly count?: HTMLElement | null;
 }
 
 /**
@@ -54,20 +45,20 @@ export interface SearchBoxElements {
  * ```ts
  * const list = filters({ fields, items, onChange: … });
  * const detach = list.attach();
- * const unbind = searchBox(list, "q", { input, clear, empty, count });
+ * const unbind = searchBox(list, "q", { input, clear, empty });
  * ```
  */
-export function searchBox<F extends FieldMap>(
-    list: Filters<F>,
+export function searchBox<F extends FieldMap, T>(
+    list: Filters<F, T>,
     field: TextFieldOf<F>,
     elements: SearchBoxElements
 ): () => void {
-    const { input, clear, empty, count } = elements;
+    const { input, clear, empty } = elements;
     // The narrowing `TextFieldOf` already did: inside a generic function
     // TypeScript cannot see that this field holds a string.
     const name = field as Parameters<typeof list.set>[0];
 
-    const render = ({ state, matched }: FilterChange<F>): void => {
+    const render = ({ state, matched }: FilterChange<F, T>): void => {
         const query = String(state[name]);
         // Guarded by inequality: assigning `value` while someone types moves
         // the caret to the end, and this exists for state that moved without
@@ -75,7 +66,6 @@ export function searchBox<F extends FieldMap>(
         if (input != null && input.value !== query) input.value = query;
         if (clear != null) clear.hidden = query === "";
         if (empty != null) empty.hidden = matched.size > 0;
-        if (count != null) count.textContent = String(matched.size);
     };
 
     render(list);

package/src/astro/filters.ts

@@ -3,14 +3,9 @@
  *
  * ```ts
  * const list = filters({
- *     fields: {
- *         q: { kind: "text" },
- *         category: { kind: "choice" },
- *     },
- *     items: entries.map((entry) => ({
- *         key: entry.id,
- *         values: { q: `${entry.title} ${entry.summary}`, category: entry.category },
- *     })),
+ *     fields: { q: "text", category: "choice" },
+ *     items: entries,
+ *     values: (entry) => ({ q: `${entry.title} ${entry.summary}`, category: entry.category }),
  *     onChange: ({ matched }) => { /* every DOM write is the project's *\/ },
  * });
  *
@@ -40,19 +35,30 @@
  *
  * `flag` is not a tri-state: on, off and *either* is a `choice` with two values.
  */
-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;
-}
+export type FieldKind = "text" | "choice" | "flag";
+
+/**
+ * A field: its kind, which puts it in the URL under the field's own name, or
+ * `{ kind, url: false }` to keep it out. To rename the parameter, rename the
+ * field.
+ */
+export type Field =
+    | FieldKind
+    | { readonly kind: FieldKind; readonly url: false };
+
+/** A field's kind, from either spelling. */
+export type KindOf<F extends Field> = F extends FieldKind
+    ? F
+    : F extends { readonly kind: infer K }
+      ? K
+      : never;
 
 /** The fields of one list, named by the caller. */
 export type FieldMap = Readonly<Record<string, Field>>;
 
 /** What one field contributes in the state: what was typed, picked or toggled. */
-export type StateValue<F extends Field> = F["kind"] extends "flag"
-    ? boolean
-    : string;
+export type StateValue<F extends Field> =
+    KindOf<F> extends "flag" ? boolean : string;
 
 /**
  * What one field contributes on an item: what it *is*, where the state holds
@@ -61,11 +67,12 @@ export type StateValue<F extends Field> = F["kind"] extends "flag"
  * **A `choice` item may hold several values, and then answers to any of them** —
  * a room is adventure *and* sci-fi, while the chips still pick one.
  */
-export type ItemValue<F extends Field> = F["kind"] extends "flag"
-    ? boolean
-    : F["kind"] extends "choice"
-      ? string | readonly string[]
-      : string;
+export type ItemValue<F extends Field> =
+    KindOf<F> extends "flag"
+        ? boolean
+        : KindOf<F> extends "choice"
+          ? string | readonly string[]
+          : string;
 
 /** Every field's value for one item, derived from the field declaration. */
 export type ItemValues<F extends FieldMap> = {
@@ -77,33 +84,31 @@ export type FilterState<F extends FieldMap> = {
     readonly [K in keyof F]: StateValue<F[K]>;
 };
 
-export interface FilterItem<F extends FieldMap> {
-    /** Unique across the list: a duplicate makes `matched` ambiguous, and is refused. */
-    readonly key: string;
-    readonly values: ItemValues<F>;
-}
-
-export interface FilterChange<F extends FieldMap> {
+export interface FilterChange<F extends FieldMap, T> {
     readonly state: FilterState<F>;
     /**
-     * The keys that survive every field at once. A set, so a caller asks about
-     * the items it already holds, and `size` is the count a "showing N" wants.
+     * The items that survive every field at once — the caller's own, so it asks
+     * `matched.has(row)` of what it already holds, and `size` is the count a
+     * "showing N" wants.
      */
-    readonly matched: ReadonlySet<string>;
+    readonly matched: ReadonlySet<T>;
 }
 
-export interface FiltersOptions<F extends FieldMap> {
+export interface FiltersOptions<F extends FieldMap, T> {
     readonly fields: F;
     /**
      * The full list, every time — this filters, it does not paginate. Fixed for
      * the instance's lifetime; a list whose contents change is a new instance.
+     * Anything: elements, records, whatever the caller already holds.
      */
-    readonly items: readonly FilterItem<F>[];
+    readonly items: readonly T[];
+    /** Each item's value for every field. Read once per item, at construction. */
+    values(item: T): ItemValues<F>;
     /**
      * Called whenever the state moves, and once on `attach` with whatever the
      * URL already said. Never called for a `set` that changed nothing.
      */
-    onChange(change: FilterChange<F>): void;
+    onChange(change: FilterChange<F, T>): void;
 }
 
 export interface SetOptions {
@@ -117,11 +122,11 @@ export interface SetOptions {
     readonly history?: "push" | "replace";
 }
 
-export interface Filters<F extends FieldMap> {
+export interface Filters<F extends FieldMap, T> {
     readonly state: FilterState<F>;
-    readonly matched: ReadonlySet<string>;
+    readonly matched: ReadonlySet<T>;
     /**
-     * The keys that survive every field *except* this one: what a facet asks of
+     * The items that survive every field *except* this one: what a facet asks of
      * its own options, so each can say what picking it would give. Counted
      * against `matched` instead, a facet that is already set could only ever
      * offer its own value.
@@ -129,7 +134,7 @@ export interface Filters<F extends FieldMap> {
      * The same matcher as `matched`, so a count cannot drift from the list it
      * counts. Computed on first ask and kept until the state moves.
      */
-    matchedWithout(field: keyof F): ReadonlySet<string>;
+    matchedWithout(field: keyof F): ReadonlySet<T>;
     set<K extends keyof F>(
         field: K,
         value: StateValue<F[K]>,
@@ -141,7 +146,7 @@ export interface Filters<F extends FieldMap> {
      * 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;
+    subscribe(listener: (change: FilterChange<F, T>) => void): () => void;
     /**
      * Reads the URL, applies it, and starts listening — returns the undo.
      *
@@ -164,61 +169,38 @@ 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`. `1` and not `true`
- * because that is what shared links already carry.
- */
-const FLAG_ON = "1";
-
-export function filters<const F extends FieldMap>(
-    options: FiltersOptions<F>
-): Filters<F> {
+export function filters<const F extends FieldMap, T>(
+    options: FiltersOptions<F, T>
+): Filters<F, T> {
     const { fields, items, onChange } = options;
     const names = Object.keys(fields) as (keyof F & string)[];
 
-    // Checks types cannot express, and both failures are otherwise silent: a
-    // duplicate key makes `matched` ambiguous, and two fields sharing a
-    // parameter means each URL write erases the other's value.
-    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);
-    }
-    // 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 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}".`
-            );
-        }
-        taken.add(param);
-        params.set(name, param);
-    }
+    const kindOf = (name: keyof F & string): FieldKind | undefined => {
+        const field = fields[name];
+        return typeof field === "string" ? field : field?.kind;
+    };
 
-    // Folded once at construction: doing it per item per keystroke is the
-    // difference between filtering as you type and stuttering.
-    const haystacks = new Map<string, Map<string, string>>();
-    for (const item of items) {
-        const perField = new Map<string, string>();
+    // The fields in the URL, each under its own name.
+    const inUrl = names.filter((name) => {
+        const field = fields[name];
+        return typeof field === "string" || field?.url !== false;
+    });
+
+    // Each item's values read once, and its text folded once: doing it per item
+    // per keystroke is the difference between filtering as you type and
+    // stuttering.
+    const entries = items.map((item) => {
+        const values = options.values(item);
+        const haystacks = new Map<string, string>();
         for (const name of names) {
-            if (fields[name]?.kind !== "text") continue;
-            perField.set(name, fold(item.values[name] as string));
+            if (kindOf(name) !== "text") continue;
+            haystacks.set(name, fold(values[name] as string));
         }
-        haystacks.set(item.key, perField);
-    }
+        return { item, values, haystacks };
+    });
 
     const empty = (name: keyof F & string): StateValue<F[typeof name]> =>
-        (fields[name]?.kind === "flag" ? false : "") as StateValue<
-            F[typeof name]
-        >;
+        (kindOf(name) === "flag" ? false : "") as StateValue<F[typeof name]>;
 
     const blank = (): FilterState<F> =>
         Object.fromEntries(
@@ -226,13 +208,13 @@ export function filters<const F extends FieldMap>(
         ) as FilterState<F>;
 
     let state = blank();
-    let matched: ReadonlySet<string> = new Set(items.map((item) => item.key));
+    let matched: ReadonlySet<T> = new Set(items);
 
     /** Each `text` field's query, folded and split once per state. */
     let queries = new Map<string, readonly string[]>();
 
     /** `matchedWithout` answers for the current state. Emptied when it moves. */
-    const without = new Map<string, ReadonlySet<string>>();
+    const without = new Map<string, ReadonlySet<T>>();
 
     /**
      * Whether the URL is this instance's to write. An instance that was built
@@ -246,7 +228,7 @@ export function filters<const F extends FieldMap>(
      * a flag that is off all keep every item — the flag above all.
      */
     const narrows = (name: keyof F & string): boolean => {
-        const kind = fields[name]?.kind;
+        const kind = kindOf(name);
         if (kind === "text") return (queries.get(name) ?? []).length > 0;
         if (kind === "choice") return state[name] !== "";
         return state[name] === true;
@@ -256,17 +238,20 @@ export function filters<const F extends FieldMap>(
      * Whether one item survives every field but `except`. The one matcher, so a
      * facet count and the list it counts cannot disagree about what a match is.
      */
-    function passes(item: FilterItem<F>, except?: keyof F & string): boolean {
+    function passes(
+        entry: (typeof entries)[number],
+        except?: keyof F & string
+    ): boolean {
         for (const name of names) {
             if (name === except || !narrows(name)) continue;
-            const kind = fields[name]?.kind;
+            const kind = kindOf(name);
             if (kind === "text") {
                 // Every token must appear, rather than the query as one run: a
                 // haystack is several things joined, and matching it whole made
                 // the joining order load-bearing — "kettle kitchen" found
                 // nothing while "kettle" worked.
                 const tokens = queries.get(name) ?? [];
-                const haystack = haystacks.get(item.key)?.get(name) ?? "";
+                const haystack = entry.haystacks.get(name) ?? "";
                 if (!tokens.every((token) => haystack.includes(token))) {
                     return false;
                 }
@@ -274,12 +259,12 @@ export function filters<const F extends FieldMap>(
                 // An item may sit in several categories while the control picks
                 // one — see `ItemValue`.
                 const wanted = state[name] as string;
-                const held = item.values[name];
+                const held = entry.values[name];
                 const holds = Array.isArray(held)
                     ? held.includes(wanted)
                     : held === wanted;
                 if (!holds) return false;
-            } else if (item.values[name] !== true) {
+            } else if (entry.values[name] !== true) {
                 return false;
             }
         }
@@ -289,15 +274,15 @@ export function filters<const F extends FieldMap>(
     function recompute(): void {
         queries = new Map();
         for (const name of names) {
-            if (fields[name]?.kind !== "text") continue;
+            if (kindOf(name) !== "text") continue;
             const folded = fold(state[name] as string);
             queries.set(name, folded === "" ? [] : folded.split(/\s+/));
         }
         without.clear();
 
-        const next = new Set<string>();
-        for (const item of items) {
-            if (passes(item)) next.add(item.key);
+        const next = new Set<T>();
+        for (const entry of entries) {
+            if (passes(entry)) next.add(entry.item);
         }
         matched = next;
     }
@@ -306,18 +291,19 @@ export function filters<const F extends FieldMap>(
         const search = new URLSearchParams(window.location.search);
         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 (param === undefined) {
+            if (!inUrl.includes(name)) {
                 // 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(param);
-            next[name] = field.kind === "flag" ? raw === FLAG_ON : (raw ?? "");
+            // A flag is on by being there, as an HTML boolean attribute is:
+            // `?featured`, and `?featured=1` from an older link, alike.
+            next[name] =
+                kindOf(name) === "flag"
+                    ? search.has(name)
+                    : (search.get(name) ?? "");
         }
         state = next as FilterState<F>;
     }
@@ -331,17 +317,23 @@ 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 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);
+        for (const name of inUrl) search.delete(name);
+        const rest = search.toString();
+        const parts = rest === "" ? [] : [rest];
+        for (const name of inUrl) {
+            // Joined by hand because `URLSearchParams` always writes `=`, and a
+            // flag that is on is its bare name.
+            if (kindOf(name) === "flag") {
+                if (state[name] === true) parts.push(encodeURIComponent(name));
                 continue;
             }
             const value = (state[name] as string).trim();
-            if (value !== "") search.set(param, value);
+            if (value !== "") {
+                parts.push(new URLSearchParams({ [name]: value }).toString());
+            }
         }
 
-        const query = search.toString();
+        const query = parts.join("&");
         // The bare path when nothing is left, rather than a trailing `?`.
         const url = query === "" ? window.location.pathname : `?${query}`;
         // `null` on a pushed step, so Astro's `ClientRouter` leaves its popstate
@@ -352,9 +344,9 @@ export function filters<const F extends FieldMap>(
 
     /** 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;
+        kindOf(name) === "text" ? (value as string).trim() : value;
 
-    const listeners = new Set<(change: FilterChange<F>) => void>();
+    const listeners = new Set<(change: FilterChange<F, T>) => void>();
     const announce = (): void => {
         onChange({ state, matched });
         for (const listener of listeners) listener({ state, matched });
@@ -376,9 +368,9 @@ export function filters<const F extends FieldMap>(
             const cached = without.get(name);
             if (cached !== undefined) return cached;
 
-            const rest = new Set<string>();
-            for (const item of items) {
-                if (passes(item, name)) rest.add(item.key);
+            const rest = new Set<T>();
+            for (const entry of entries) {
+                if (passes(entry, name)) rest.add(entry.item);
             }
             without.set(name, rest);
             return rest;
@@ -398,7 +390,7 @@ export function filters<const F extends FieldMap>(
 
             state = { ...state, [name]: value };
             recompute();
-            const fallback = fields[name]?.kind === "text" ? "replace" : "push";
+            const fallback = kindOf(name) === "text" ? "replace" : "push";
             writeUrl(setOptions?.history ?? fallback);
             announce();
         },