@escape-game-over/atlas 0.1.18 → 0.1.19

package/src/astro/filters.ts

@@ -1,23 +1,6 @@
 /**
  * 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: {
@@ -28,48 +11,34 @@
  *         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);
- *     },
+ *     onChange: ({ matched }) => { /* every DOM write is the project's *\/ },
  * });
  *
  * 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.
+ * **It draws nothing** and holds no element: the caller hands over each item's
+ * values once, as plain data, which is also why the whole module is testable
+ * without a document.
+ *
+ * What it owns is what every filtered list needs and most get wrong: folding, so
+ * a query without accents matches words with them; a query and its facets
+ * resolved together; and a URL that behaves — replaced while typing, pushed on a
+ * deliberate choice, empty parameters dropped, `popstate` applied.
  *
- * 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.
+ * In `astro/` because it reaches for `location`, `history` and `window`. See
+ * docs/client-scripts.md.
  */
 
 /**
- * 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:
+ * What a field is, as data rather than a constructor: builder functions would
+ * put names as general as `text` into every module that imports this.
  *
  * - `text` — free entry, folded and matched word by word. The search box.
- * - `choice` — one of a set, or none. Tabs, a `<select>`, a radio group. The
- *   control picks one; an item may hold several and answer to any — see
- *   `ItemValue`.
- * - `flag` — a narrowing toggle: off matches everything, on keeps only the
- *   items that carry it. "In stock", "Step-free access".
+ * - `choice` — one of a set, or none. Tabs, a `<select>`, a radio group.
+ * - `flag` — a narrowing toggle: off keeps everything, on keeps what carries it.
  *
- * `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.
+ * `flag` is not a tri-state: on, off and *either* is a `choice` with two values.
  */
 export type Field =
     | { readonly kind: "text"; readonly param?: string }
@@ -79,36 +48,17 @@ export type Field =
 /** The fields of one list, named by the caller. */
 export type FieldMap = Readonly<Record<string, Field>>;
 
-/**
- * What one field contributes, in the state.
- *
- * Always one value per field, whatever the kind: a `choice` is the one category
- * asked for, a `text` is what someone typed, a `flag` is whether the toggle is
- * on. This is what `set` takes and what reaches the address bar.
- */
+/** 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;
 
 /**
- * What one field contributes, on an item.
+ * What one field contributes on an item: what it *is*, where the state holds
+ * what was *asked for*. A `text` value is everything that field searches.
  *
- * The two roles read alike but are not the same, and `choice` is where they part
- * company. 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.
- *
- * **A `choice` item may hold several values, and then it answers to any of
- * them.** The asymmetry is the point: an escape room is adventure *and* sci-fi,
- * a film is a comedy *and* a drama, but the tab strip above them still picks
- * one, and the URL still carries one. Widened here rather than given a kind of
- * its own, because a second kind would carry the same state, the same
- * parameter, the same `set` semantics and the same control, and differ by one
- * operator — two kinds doing one job, which is exactly what `Field` refuses
- * when it declines to let `flag` become a tri-state.
- *
- * A list whose items each sit in one category writes a bare string and is
- * untouched by this.
+ * **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
@@ -135,13 +85,7 @@ export type FilterState<F extends FieldMap> = {
 };
 
 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.
-     */
+    /** Unique across the list: a duplicate makes `matched` ambiguous, and is refused. */
     readonly key: string;
     readonly values: ItemValues<F>;
 }
@@ -149,11 +93,8 @@ export interface FilterItem<F extends FieldMap> {
 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.
+     * 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.
      */
     readonly matched: ReadonlySet<string>;
 }
@@ -161,38 +102,24 @@ export interface FilterChange<F extends FieldMap> {
 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`.
+     * 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.
      */
     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.
+     * URL already said. Never called for a `set` that changed nothing.
      */
     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"`.
+     * Whether this move is worth a step in history. Defaults from the kind —
+     * `text` replaces, `choice` and `flag` push — because typing would otherwise
+     * fill history with a word being spelled. An override, because the default
+     * is really a fact about the input: a `<select>` setting a `text` field is a
+     * deliberate choice and wants `"push"`.
      */
     readonly history?: "push" | "replace";
 }
@@ -201,26 +128,13 @@ export interface Filters<F extends FieldMap> {
     readonly state: FilterState<F>;
     readonly matched: ReadonlySet<string>;
     /**
-     * The keys that survive every field *except* this one.
+     * The keys 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.
      *
-     * The question a facet asks of its own options: how many results would
-     * picking each of them give, with everything else as it stands. Counted
-     * against `matched` instead, a dropdown whose value is already set could
-     * only ever offer that value — every other option would read zero, since
-     * the items holding it have just been filtered out by the very field being
-     * asked about.
-     *
-     * The same matcher as `matched`, folding and tokens included, rather than a
-     * second one in the caller. A facet count computed by a hand-written
-     * predicate drifts from the list it is counting the moment either changes —
-     * a count of four above a list of three — and nothing reports it.
-     *
-     * Computed on first ask and kept until the state next moves, so a render
-     * that asks once per option pays one pass per field rather than one per
-     * option. A field that is not narrowing anything answers with `matched`
-     * itself: without it, the rest is exactly what already matched.
-     *
-     * Safe to call from `onChange`, which never runs during construction.
+     * 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>;
     set<K extends keyof F>(
@@ -233,17 +147,10 @@ export interface Filters<F extends FieldMap> {
     /**
      * 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.
+     * One lifecycle, which matters with view transitions: a module bound at top
+     * level runs once per session, not once per navigation, so the incoming page
+     * would get a live list and dead controls. Nothing writes to the URL before
+     * this runs.
      */
     attach(): () => void;
 }
@@ -252,30 +159,17 @@ export interface Filters<F extends FieldMap> {
 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.
+ * A string reduced to what a query should match against. Without it, a reader
+ * typing `malaga` is told there is no *Málaga*.
  */
 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.
+ * 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";
 
@@ -285,10 +179,9 @@ export function filters<const F extends FieldMap>(
     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.
+    // 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)) {
@@ -308,13 +201,8 @@ export function filters<const F extends FieldMap>(
         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.
-     */
+    // 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>();
@@ -338,32 +226,22 @@ export function filters<const F extends FieldMap>(
     let state = blank();
     let matched: ReadonlySet<string> = new Set(items.map((item) => item.key));
 
-    /**
-     * Each `text` field's query, folded and split, for the current state.
-     *
-     * Folded once per state rather than once per item. The other kinds compare
-     * values as they are, so there is nothing to prepare for them.
-     */
+    /** 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>>();
 
     /**
-     * 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.
+     * Whether the URL is this instance's to write. An instance that was built
+     * but never attached has not read the URL, so writing would replace state
+     * nobody here loaded.
      */
     let attached = false;
 
     /**
-     * Whether a field is narrowing anything in the current state.
-     *
-     * An empty query, no choice and a flag that is off all keep every item —
-     * the flag above all, which keeps everything rather than keeping the items
-     * that are *not* flagged. See `Field`.
+     * Whether a field is narrowing anything now. An empty query, no choice and
+     * 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;
@@ -373,34 +251,26 @@ export function filters<const F extends FieldMap>(
     };
 
     /**
-     * Whether one item survives every field but `except`, in the current state.
-     *
-     * The one matcher. `matched` is this with nothing excepted and
-     * `matchedWithout` is this with one field excepted, so a facet count and
-     * the list it counts cannot disagree about what a match is.
+     * 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 {
         for (const name of names) {
             if (name === except || !narrows(name)) continue;
             const kind = fields[name]?.kind;
             if (kind === "text") {
-                // Every token must appear, not one run 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.
+                // 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) ?? "";
                 if (!tokens.every((token) => haystack.includes(token))) {
                     return false;
                 }
             } else if (kind === "choice") {
-                // An item may sit in several categories while the control
-                // still picks one — see `ItemValue`. One value is the same
-                // question asked of a set of one.
+                // 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 holds = Array.isArray(held)
@@ -438,11 +308,8 @@ export function filters<const F extends FieldMap>(
             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.
+                // to say about it. Clearing it here wiped a search mid-typing
+                // whenever another parameter on the page moved.
                 next[name] = state[name];
                 continue;
             }
@@ -455,18 +322,11 @@ export function filters<const F extends FieldMap>(
     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.
+        // Started from the URL that is there: the page is full of parameters
+        // that are not this list's business (`utm_*`, a page number), and
+        // building from scratch dropped them — a campaign stopped being
+        // attributed the first time someone typed in the search box. Its own
+        // are deleted first, then rewritten, so one state gives one URL.
         const search = new URLSearchParams(window.location.search);
         for (const name of names) {
             const param = fields[name]?.param;
@@ -484,21 +344,13 @@ export function filters<const F extends FieldMap>(
         }
 
         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.
+        // The bare path when nothing is left, rather than a trailing `?`.
         const url = query === "" ? window.location.pathname : `?${query}`;
         if (history === "push") window.history.pushState({}, "", url);
         else window.history.replaceState({}, "", url);
     }
 
-    /**
-     * 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.
-     */
+    /** 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;
 
@@ -530,18 +382,12 @@ export function filters<const F extends FieldMap>(
 
         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.
+            // Compared as everything downstream will read it: "sol" and "sol "
+            // filter the same list, and comparing them raw cost a recompute, a
+            // `replaceState` to the same URL and a full re-render. The *raw*
+            // value is stored, though — the search box mirrors the state back
+            // into the input, and normalising here would delete the space a
+            // reader just typed.
             if (normalized(name, state[name]) === normalized(name, value)) {
                 return;
             }
@@ -555,11 +401,8 @@ export function filters<const F extends FieldMap>(
 
         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.
+                // A "clear all" on an unfiltered list is a no-op; pushing for it
+                // puts a history step that goes back to where it already is.
                 if (names.every((name) => state[name] === empty(name))) return;
                 state = blank();
             } else {
@@ -575,10 +418,8 @@ export function filters<const F extends FieldMap>(
         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.
+            // A `popstate` listener that outlives its page is the leak with no
+            // visible symptom: it keeps rendering into markup that was replaced.
             window.addEventListener(
                 "popstate",
                 () => {
@@ -590,10 +431,9 @@ export function filters<const F extends FieldMap>(
             );
 
             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.
+            // Read before the first announcement: the URL may already carry a
+            // state, and announcing the empty one first flashes the unfiltered
+            // list over it.
             readUrl();
             recompute();
             announce();