@escape-game-over/atlas 0.1.3 → 0.1.5

package/src/astro/filters-view.ts

@@ -0,0 +1,253 @@
+/**
+ * The DOM writes every filtered list turns out to make, and only those.
+ *
+ * `filters` decides which items match and what the address bar says, and hands
+ * both to `onChange`. Everything a page does about that answer is its own — and
+ * mostly stays that way: three lists in one repository draw their results three
+ * different ways, with tabs and a blurb on one, an exclusive `<details>`
+ * accordion on another, a two-level country roll-up on the third.
+ *
+ * These two helpers are what all three, or two of three, wrote identically. That
+ * is the whole bar for being here: not "a list might want this" but "every list
+ * we have written already did, character for character, and getting it wrong was
+ * silent". Anything the three disagreed about is still theirs.
+ *
+ * **Both take elements, never selectors.** A project decides what its markup is
+ * called and hands over what it found, so no attribute name in this package has
+ * to be matched by any consumer — the reason `filters` itself has no markup
+ * contract, kept intact one layer up.
+ *
+ * These write to elements, which the rest of `astro/` refuses to do, and the
+ * line is worth being exact about. `carousel` will not write a transform because
+ * a transform is a design decision with no single right answer. Everything
+ * written here is the opposite: an input's `value` is the control's own state,
+ * and `hidden` on a clear button, an empty message or a section with nothing
+ * left in it is binary and derived. Nothing here sets a class, a style or an
+ * `aria` attribute, which is where the choices live.
+ *
+ * Two notes for the markup on the other side of that boundary:
+ *
+ * - **`hidden` needs help in a grid.** It is a `display: none` from the user
+ *   agent, and any author rule setting `display: flex` or `grid` beats it. A
+ *   project on Tailwind v4 gets `[hidden] { display: none !important }` from
+ *   preflight and needs nothing; anything else should ship that rule itself, or
+ *   every one of these writes is inert and the list simply never filters.
+ * - **A result count wants `aria-live="polite"`.** Filtering as you type changes
+ *   the page silently for anyone not looking at it. The attribute belongs on the
+ *   element in the template, not here — this package is handed elements and does
+ *   not decide what they are.
+ */
+
+import type { FieldMap, Filters } from "./filters.ts";
+
+/**
+ * The fields of `F` that hold text, so a search box cannot be pointed at a flag.
+ *
+ * `list.set(field, input.value)` hands over a string; aimed at a `flag` that is
+ * a type error worth getting at the call site rather than a filter that silently
+ * never matches.
+ */
+export type TextFieldOf<F extends FieldMap> = {
+    [K in keyof F]: F[K] extends { kind: "text" } ? K : never;
+}[keyof F];
+
+/**
+ * What a search box is made of, as much of it as exists.
+ *
+ * Every part is optional and `null` is accepted, because `within(root).one(…)`
+ * returns `null` and a page is allowed to have a search field with no clear
+ * button, or a list with no empty state. Handing over what a lookup returned,
+ * without checking it first, is the point.
+ */
+export interface SearchBoxElements {
+    readonly input?: HTMLInputElement | null;
+    /** Clears the field. Hidden while the field is already empty. */
+    readonly clear?: HTMLElement | null;
+    /**
+     * The "nothing matched" message.
+     *
+     * Tracks the whole result set rather than this field alone — a list emptied
+     * by a category is as empty as one emptied by a query, and there is one
+     * message either way. It lives here because it is the same line in every
+     * consumer, not because it belongs to the search box.
+     */
+    readonly empty?: HTMLElement | null;
+    /**
+     * How many matched, written as digits and nothing else.
+     *
+     * Two of the three write this, and the same way. Digits only, because the
+     * sentence around them is not ours to build: a list that reads "6 of 42" in
+     * one language reads "6 din 42" in another, and a translated string is not
+     * something to take apart in a browser to get at one number. Give the count
+     * an element of its own and let the copy sit beside it — which is what the
+     * consumer doing this already had to do.
+     *
+     * Same rule as the rest of this file, one field further: derived, and with
+     * no choice in it. Where the number *goes* is still the template's.
+     *
+     * Give it `aria-live="polite"` there. Filtering as you type changes the
+     * page silently for anyone not watching it, and this package is handed
+     * elements rather than deciding what they are.
+     */
+    readonly count?: HTMLElement | null;
+}
+
+export interface SearchBox {
+    /**
+     * Brings the box into line with the state, from inside `onChange`.
+     *
+     * Takes two scalars rather than the change object, so this stays independent
+     * of what the field was named and of which other fields the list has.
+     *
+     * Safe before `bind` and after the undo it returns: this only writes to the
+     * elements it was given, so a box that is no longer wired renders the last
+     * thing it was told rather than throwing.
+     */
+    render(query: string, matchCount: number): void;
+    /**
+     * Points the input and the clear button at one `text` field of a list, and
+     * returns the undo.
+     *
+     * Separate from construction because of an ordering knot rather than a
+     * preference: `render` is called from the list's own `onChange`, so the box
+     * has to exist before the list, and this needs the list. Two calls and a
+     * `const` each way is the honest version of that; the alternative is a `let`
+     * the reader has to hold in their head.
+     *
+     * One `AbortController`, as everywhere else here — see `carousel.attach`.
+     */
+    bind<F extends FieldMap>(
+        list: Filters<F>,
+        field: TextFieldOf<F>
+    ): () => void;
+}
+
+/**
+ * The search input beside a `filters` list, and the two things every one of them
+ * has to remember.
+ *
+ * ```ts
+ * const search = searchBox({
+ *     input: one<HTMLInputElement>("[data-filter-search]"),
+ *     clear: one("[data-filter-clear]"),
+ *     empty: one("[data-filter-empty]"),
+ *     count: one("[data-filter-count]"),
+ * });
+ *
+ * const list = filters({
+ *     fields, items,
+ *     onChange({ state, matched }) {
+ *         search.render(state.q, matched.size);
+ *         // …everything this list draws for itself
+ *     },
+ * });
+ *
+ * const unbind = search.bind(list, "q");
+ * const detach = list.attach();
+ * ```
+ *
+ * It writes rather than calling back, and that is the only reason it exists.
+ * `filters.onChange` is already the callback that hands a consumer the value and
+ * gets out of the way; a second one here would hand back `query` and `count` and
+ * leave the same three writes to be spelled out at every call site, which is the
+ * duplication this was extracted from.
+ */
+export function searchBox(elements: SearchBoxElements): SearchBox {
+    const { input, clear, empty, count } = elements;
+
+    return {
+        render(query, matchCount) {
+            // Guarded by inequality, not written unconditionally. Assigning
+            // `value` while someone is typing in the field moves the caret to
+            // the end, so the one case this exists for — state that moved
+            // without the keyboard, from the back button or a `reset` — must not
+            // cost a caret jump on every other keystroke.
+            if (input != null && input.value !== query) input.value = query;
+            if (clear != null) clear.hidden = query === "";
+            if (empty != null) empty.hidden = matchCount > 0;
+            if (count != null) count.textContent = String(matchCount);
+        },
+
+        bind(list, field) {
+            const listeners = new AbortController();
+            const { signal } = listeners;
+            // The narrowing `TextFieldOf` already did, restated for the
+            // implementation: inside a generic function TypeScript cannot see
+            // that this field's value type is `string`, though every caller can.
+            const name = field as Parameters<typeof list.set>[0];
+
+            input?.addEventListener(
+                "input",
+                () => list.set(name, input.value as never),
+                { signal }
+            );
+
+            clear?.addEventListener(
+                "click",
+                () => {
+                    list.reset(name);
+                    // Focus follows the click, because the button the pointer
+                    // was on has just hidden itself — leaving focus on a
+                    // `hidden` element strands a keyboard reader at a control
+                    // that is no longer there.
+                    input?.focus();
+                },
+                { signal }
+            );
+
+            return () => listeners.abort();
+        },
+    };
+}
+
+/**
+ * Hides each group that has nothing visible left inside it.
+ *
+ * ```ts
+ * onChange({ matched }) {
+ *     for (const item of items) item.hidden = !matched.has(keyOf(item));
+ *     hideEmpty(groups, (group) => within(group).all("[data-faq-key]"));
+ * }
+ * ```
+ *
+ * A filtered list that renders its results under headings has this problem and
+ * nothing else does: hide the items and the headings stay, so a search for one
+ * word leaves a page of section titles with nothing under them. It reads as a
+ * broken template rather than as a result, which is what makes forgetting it
+ * expensive — nothing errors, and the page looks wrong in a way that does not
+ * point at the filter.
+ *
+ * **Reads `hidden`, rather than taking the matched set.** The items were just
+ * hidden by the caller, so their state is the shortest true description of what
+ * survived — and reading it is what lets this nest. A country is empty when
+ * every city in it is hidden; a region is empty when every country in it is
+ * hidden, *including the ones this call just hid*.
+ *
+ * **Which makes the order load-bearing: innermost first.**
+ *
+ * ```ts
+ * hideEmpty(countries, (c) => within(c).all("[data-city]"));
+ * hideEmpty(regions, (r) => within(r).all("[data-country]"));
+ * ```
+ *
+ * Run the other way round, the regions are judged against countries that have
+ * not been hidden yet, and a region with nothing in it survives.
+ *
+ * A group with no children at all is hidden, which is the same answer by the
+ * same rule — there is nothing visible in it.
+ */
+export function hideEmpty<T extends HTMLElement>(
+    groups: Iterable<T>,
+    childrenOf: (group: T) => Iterable<HTMLElement>
+): void {
+    for (const group of groups) {
+        let visible = false;
+        for (const child of childrenOf(group)) {
+            if (!child.hidden) {
+                visible = true;
+                break;
+            }
+        }
+        group.hidden = !visible;
+    }
+}

package/src/astro/filters.ts

@@ -24,9 +24,9 @@
  *         q: { kind: "text", param: "q" },
  *         category: { kind: "choice", param: "category" },
  *     },
- *     items: games.map((game) => ({
- *         key: game.id,
- *         values: { q: `${game.name} ${game.blurb}`, category: game.category },
+ *     items: entries.map((entry) => ({
+ *         key: entry.id,
+ *         values: { q: `${entry.title} ${entry.summary}`, category: entry.category },
  *     })),
  *     onChange: ({ matched }) => {
  *         for (const [key, element] of elements) element.hidden = !matched.has(key);
@@ -63,7 +63,7 @@
  * - `text` — free entry, folded and substring-matched. The search box.
  * - `choice` — one of a set, or none. Tabs, a `<select>`, a radio group.
  * - `flag` — a narrowing toggle: off matches everything, on keeps only the
- *   items that carry it. "Arena only", "In stock".
+ *   items that carry it. "In stock", "Step-free access".
  *
  * `flag` is not a tri-state and should not become one. On, off and *either* is
  * a `choice` with two values; folding that into a toggle gives a control with a
@@ -198,8 +198,8 @@ const DIACRITICS = /[̀-ͯ]/g;
  * A string reduced to what a query should match against.
  *
  * Decompose, drop the marks, lowercase, trim. This is the part every list needs
- * and few have: without it a reader typing `abilita` is told there is no
- * *Abilità*, and a Romanian catalogue hides every entry spelled with `ă`, `ș` or
+ * and few have: without it a reader typing `malaga` is told there is no
+ * *Málaga*, and a Romanian catalogue hides every entry spelled with `ă`, `ș` or
  * `ț` from anyone whose keyboard does not carry them.
  */
 function fold(value: string): string {
@@ -213,7 +213,7 @@ function fold(value: string): string {
  * An unset flag is *absent* rather than `=0`. One way to say off keeps the URL
  * short and means there is a single form to handle; two would both have to be
  * understood forever, and a reader could not tell which of them a link was
- * carrying. The cost is that a hand-written `?arena=0` reads as off, which is
+ * 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:
@@ -293,10 +293,18 @@ export function filters<const F extends FieldMap>(
     function recompute(): void {
         // The query folded once per render rather than once per item. The other
         // kinds compare values as they are, so there is nothing to prepare.
-        const queries = new Map<string, string>();
+        // Split into tokens, all of which must appear — not one substring that
+        // must appear whole. A haystack is several things joined (a title, plus
+        // its category, plus its summary), and the order they were joined in is
+        // an accident of whoever wrote the template. Matching the query as one
+        // run made that accident load-bearing: against "Copper Kettle" in the
+        // Kitchen category, "kettle kitchen" found nothing while "kettle" alone
+        // worked, and the first is what someone narrowing a list types.
+        const queries = new Map<string, string[]>();
         for (const name of names) {
             if (fields[name]?.kind !== "text") continue;
-            queries.set(name, fold(state[name] as string));
+            const folded = fold(state[name] as string);
+            queries.set(name, folded === "" ? [] : folded.split(/\s+/));
         }
 
         const next = new Set<string>();
@@ -305,13 +313,10 @@ export function filters<const F extends FieldMap>(
             for (const name of names) {
                 const kind = fields[name]?.kind;
                 if (kind === "text") {
-                    const query = queries.get(name) ?? "";
-                    if (query === "") continue;
-                    if (
-                        !(haystacks.get(item.key)?.get(name) ?? "").includes(
-                            query
-                        )
-                    ) {
+                    const tokens = queries.get(name) ?? [];
+                    if (tokens.length === 0) continue;
+                    const haystack = haystacks.get(item.key)?.get(name) ?? "";
+                    if (!tokens.every((token) => haystack.includes(token))) {
                         hit = false;
                         break;
                     }
@@ -344,9 +349,13 @@ export function filters<const F extends FieldMap>(
             const field = fields[name];
             if (field === undefined) continue;
             if (field.param === undefined) {
-                // No parameter: the field is state-only, and a reload starts it
-                // empty rather than carrying a value the URL never held.
-                next[name] = empty(name);
+                // A state-only field is not in the URL, so the URL has nothing
+                // to say about it — and a back button is the URL speaking.
+                // Clearing it here read "absent from the URL" as "empty", which
+                // wiped a search the reader was in the middle of the moment any
+                // other parameter on the page moved. Left as it is instead: this
+                // function applies the URL, and this field is not in it.
+                next[name] = state[name];
                 continue;
             }
             const raw = search.get(field.param);
@@ -358,11 +367,23 @@ export function filters<const F extends FieldMap>(
     function writeUrl(history: "push" | "replace"): void {
         if (!attached) return;
 
-        // Built from the declaration rather than from the URL that is there, so
-        // a parameter this list owns and no longer needs is dropped instead of
-        // surviving because nobody thought to delete it. Fields are written in
-        // declaration order, so the same state always produces the same URL.
-        const search = new URLSearchParams();
+        // Started from the URL that is there, not from an empty set. A list owns
+        // the parameters it declared and nothing else, and the page around it is
+        // full of parameters that are not its business — `utm_*` on a link
+        // someone shared, a page number, another widget's state. Building from
+        // scratch published a URL with all of them gone, and the loss only
+        // showed up somewhere else: a campaign that stopped being attributed the
+        // first time a visitor typed in the search box.
+        //
+        // Its own are deleted first, then rewritten, so a parameter this list
+        // owns and no longer needs is dropped rather than surviving because
+        // nobody thought to remove it. Deletion and writing both run in
+        // declaration order, so one state still produces one URL.
+        const search = new URLSearchParams(window.location.search);
+        for (const name of names) {
+            const param = fields[name]?.param;
+            if (param !== undefined) search.delete(param);
+        }
         for (const name of names) {
             const field = fields[name];
             if (field?.param === undefined) continue;
@@ -375,13 +396,24 @@ export function filters<const F extends FieldMap>(
         }
 
         const query = search.toString();
-        // The bare path when nothing is set, rather than a trailing `?`: the two
-        // are the same page, and only one of them is worth sharing.
+        // The bare path when nothing is left, rather than a trailing `?`: the
+        // two are the same page, and only one of them is worth sharing. Read
+        // from the merged set, so a page carrying somebody else's parameter
+        // keeps it instead of being reduced to its path.
         const url = query === "" ? window.location.pathname : `?${query}`;
         if (history === "push") window.history.pushState({}, "", url);
         else window.history.replaceState({}, "", url);
     }
 
+    /**
+     * One field's value as the matcher and the URL will read it.
+     *
+     * Only `text` has a form that differs from what was handed over — the other
+     * kinds compare and publish exactly what they hold.
+     */
+    const normalized = (name: keyof F & string, value: unknown): unknown =>
+        fields[name]?.kind === "text" ? (value as string).trim() : value;
+
     const announce = (): void => onChange({ state, matched });
 
     recompute();
@@ -396,11 +428,21 @@ export function filters<const F extends FieldMap>(
 
         set(field, value, setOptions) {
             const name = field as keyof F & string;
-            // Nothing changed, so nothing is announced and nothing is pushed.
-            // Typing a character that does not alter a trimmed query, or
-            // re-selecting the tab that is already current, should not put a
-            // step in history for the back button to walk through.
-            if (state[name] === value) return;
+            // Compared as everything downstream will read it, not as it arrived.
+            // Both the matcher and the URL trim a query, so "sol" and "sol "
+            // filter the same list and publish the same address — but comparing
+            // them raw called that a change, and a trailing space cost a
+            // recompute, a `replaceState` to a URL identical to the current one,
+            // and a full re-render of every item.
+            //
+            // The *raw* value is what gets stored, though, and that asymmetry is
+            // deliberate. A search box mirrors the state back into the input
+            // (see `filters-view`), so normalising here would delete the space a
+            // reader had just typed, from under the caret, every time they
+            // reached for the second word.
+            if (normalized(name, state[name]) === normalized(name, value)) {
+                return;
+            }
 
             state = { ...state, [name]: value };
             recompute();
@@ -411,6 +453,12 @@ 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.
+                if (names.every((name) => state[name] === empty(name))) return;
                 state = blank();
             } else {
                 const name = field as keyof F & string;

package/src/contact-form.ts

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

package/src/contact.ts

@@ -1,4 +1,5 @@
-import type { Digit, Letter } from "./types.ts";
+import type { CountryCode } from "./countries.ts";
+import type { Digit } from "./types.ts";
 import { warn } from "./warn.ts";
 
 /**
@@ -129,13 +130,13 @@ export function mailtoHref(email: EmailAddress): string {
 }
 
 /**
- * An ISO 3166-1 alpha-2 country code: `"IT"`, `"GR"`, `"RO"`.
+ * Re-exported so an address and its country code stay one import.
  *
- * Two uppercase letters, which is what `addressCountry` is read as. A name —
- * `"Italy"`, `"Ιταλία"` — is a translation of a country rather than an
- * identifier for one, and belongs in the sentence a page prints, not here.
+ * Defined beside the list it is read from — see `countries.ts`. Imported at the
+ * top as well: `export … from` forwards a name without binding it here, and
+ * `PostalAddress` below needs it in scope.
  */
-export type CountryCode = `${Letter}${Letter}`;
+export type { CountryCode };
 
 /**
  * Where a place is, to the precision a map needs.