@escape-game-over/atlas 0.1.25 → 0.1.27

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();
         },

package/src/astro/ref.ts

@@ -0,0 +1,46 @@
+/**
+ * Finding the elements a script works on, by a selector the template wrote as
+ * a plain attribute — `[data-faq-search]` — so what the script asks for is what
+ * devtools shows.
+ */
+
+/** Names the root in an error, for a selector that matched nothing. */
+const where = (root: ParentNode): string =>
+    "localName" in root && typeof root.localName === "string"
+        ? `<${root.localName}>`
+        : "the document";
+
+/**
+ * The first match under `root`, or a thrown error naming the selector. Inside
+ * `element`'s `connect`, that error lands in the dev panel.
+ */
+export function ref<T extends Element = HTMLElement>(
+    root: ParentNode,
+    selector: string
+): T {
+    const found = root.querySelector<T>(selector);
+    if (found === null) {
+        throw new Error(`${where(root)} has nothing matching ${selector}`);
+    }
+    return found;
+}
+
+/**
+ * An element's `data-<name>` value, or a thrown error naming the element and
+ * the attribute. For an optional one, read `dataset` directly.
+ */
+export function data(element: Element, name: string): string {
+    const value = element.getAttribute(`data-${name}`);
+    if (value === null) {
+        throw new Error(`<${element.localName}> has no data-${name}`);
+    }
+    return value;
+}
+
+/** Every match under `root`. None is an answer here, not an error. */
+export function refs<T extends Element = HTMLElement>(
+    root: ParentNode,
+    selector: string
+): T[] {
+    return [...root.querySelectorAll<T>(selector)];
+}