@escape-game-over/atlas 0.1.24 → 0.1.25

package/src/astro/consent.ts

@@ -1,4 +1,24 @@
 import { CONSENT_UPDATE_GLOBAL } from "../analytics/google.ts";
+import { component, markup } from "./markup.ts";
+
+/** Internal to `ConsentBanner.astro`: the element and the footer control. */
+export const CONSENT_ROLES = {
+    answer: { choice: { kind: "choice", of: ["granted", "denied"] } },
+} as const;
+export const consentBanner = component("atlas-consent", CONSENT_ROLES);
+export const consentReopen = markup("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: consentBanner.answer.attrs({ choice: "granted" }),
+    decline: consentBanner.answer.attrs({ choice: "denied" }),
+    reopen: { ...consentReopen.attrs(), hidden: "" },
+};
 
 /**
  * The browser half of consent: remembering an answer, expiring it, and handing

package/src/astro/dev-log.ts

@@ -7,20 +7,9 @@
  * least of all the person who broke it ten seconds ago. This puts the same
  * message where it cannot be missed.
  *
- * **Every call site must be behind `import.meta.env.DEV`.** The check belongs
- * to the caller rather than to this module, so the whole thing — panel, styles
- * and message strings — is dead code in a production build and gets dropped
- * instead of shipped and never called.
- *
- * ```ts
- * if (import.meta.env.DEV) reportDevError(this.localName, error);
- * ```
- *
- * Written as the bare expression, without an optional chain: Vite substitutes
- * `import.meta.env.DEV` with a literal, so the branch collapses and everything
- * below is dropped. `import.meta.env?.DEV` is replaced as `import.meta.env` —
- * an object literal whose property access a minifier has to fold rather than
- * simply delete.
+ * In a production build it is a `console.error` and nothing else: Vite
+ * substitutes the bare `import.meta.env.DEV` with a literal, so the panel,
+ * styles and message strings are dead code and get dropped.
  *
  * Not a custom element, deliberately. It would need registering, it would
  * collide with a project that registered the same name, and nothing ever
@@ -102,6 +91,11 @@ function panel(): HTMLElement {
  * second bug underneath them.
  */
 export function reportDevError(source: string, error: unknown): void {
+    if (!import.meta.env.DEV) {
+        console.error(`${source}:`, error);
+        return;
+    }
+
     const text = `${source} — ${describe(error)}`;
 
     console.error(text, error);

package/src/astro/element.ts

@@ -1,116 +1,143 @@
 import { reportDevError } from "./dev-log.ts";
-import type { Marked, Markup } from "./markup.ts";
-import { ROOT_ATTRIBUTE } from "./markup.ts";
-
-/**
- * What is left to undo when the element leaves, or nothing.
- *
- * Nothing is the common case — a connect that registered everything with
- * `signal` has already said how it comes down — so `void` rather than
- * `undefined`, which would make every connect end in a `return`.
- */
+import {
+    type CheckedKeys,
+    type CheckedTagName,
+    type Component,
+    type ComponentRoles,
+    component,
+    type Marked,
+    type MarkupFields,
+    type Reserved,
+    ROOT_ATTRIBUTE,
+} from "./markup.ts";
+
+/** What is left to undo when the element leaves; usually nothing. */
 // biome-ignore lint/suspicious/noConfusingVoidType: that is the distinction.
 type Undo = void | (() => void);
 
-/** One role's lookups, already pointed at the element they belong to. */
-type Bound<M> =
-    M extends Markup<infer F>
-        ? {
-              all<T extends Element = HTMLElement>(): Marked<T, F>[];
-              one<T extends Element = HTMLElement>(): Marked<T, F> | null;
-              require<T extends Element = HTMLElement>(): Marked<T, F>;
-          }
-        : never;
-
 /**
- * Every role of a component, bound to one instance.
- *
- * The root is not a parameter here, which is the point: `faq.row.all(document)`
- * compiles and quietly returns the roles that belong to *no* instance, and this
- * removes the chance to write it.
+ * One role's lookups inside this instance. A role with no fields is found for
+ * the element alone; one with fields comes back with its values read.
  */
-export type Roles<C> = {
-    readonly [K in Exclude<keyof C, "tag" | "root">]: Bound<C[K]>;
+type Lookups<F extends MarkupFields> = [keyof F] extends [never]
+    ? {
+          all<T extends Element = HTMLElement>(): T[];
+          one<T extends Element = HTMLElement>(): T | null;
+          require<T extends Element = HTMLElement>(): T;
+      }
+    : {
+          all<T extends Element = HTMLElement>(): Marked<T, F>[];
+          one<T extends Element = HTMLElement>(): Marked<T, F> | null;
+          require<T extends Element = HTMLElement>(): Marked<T, F>;
+      };
+
+/** Every role of an element, bound to one instance. */
+export type ElementRoles<R extends ComponentRoles> = {
+    readonly [K in keyof R]: Lookups<R[K]>;
 };
 
 /**
- * What an element does while it is on the page.
- *
- * `host` is the element itself, `signal` is aborted when it leaves — so
- * anything registered with `signal` comes down on its own — and `roles` are
- * this instance's. Whatever else has to be undone is the returned function,
- * which runs at the same moment.
+ * What an element does while it is on the page. `signal` is aborted when it
+ * leaves, so listeners registered with it come down on their own; anything else
+ * to undo is the returned function.
  */
-export type Connect<C> = (
+export type Connect<R extends ComponentRoles> = (
     host: HTMLElement,
-    signal: AbortSignal,
-    roles: Roles<C>
+    roles: ElementRoles<R>,
+    signal: AbortSignal
 ) => Undo;
 
-/** The shape this file needs off a role, without importing its field types. */
-interface AnyRole {
-    all(root: ParentNode): unknown;
-    one(root: ParentNode): unknown;
-    require(root: ParentNode): unknown;
-}
-
 /**
- * Registers a component's custom element, with its behaviour as one function.
+ * A custom element: its markup contract and its behaviour, in one call.
  *
  * ```ts
- * export const faq = component("go-faq", { row: { key: { kind: "text" } } });
- *
- * defineElement(faq, (host, signal, { row }) => {
- *     for (const { element, values } of row.all()) { … }
- *     return loop.attach(host); // runs when the element leaves the page
- * });
+ * // faq.ts — imported by the template, and by the page's script
+ * export const faq = element("go-faq", { row: { key: { kind: "text" } }, search: marker },
+ *     (host, { row, search }, signal) => { … });
+ * ```
+ * ```astro
+ * <script src="./faq.ts"></script>
  * ```
  *
+ * Registers itself when loaded in a browser and does nothing in Node, so the
+ * template imports the same file for the contract.
+ *
  * - **An element can enter the page more than once.** Moving it runs the undo
- *   and then `connect` again, so `connect` has to be able to run twice. Astro's
- *   `ClientRouter` connects a persisted element three times per navigation.
+ *   and `connect` again; Astro's `ClientRouter` does so on every navigation.
  *   State that must survive belongs in a `WeakMap` keyed by `host`.
- * - **The defining script must stay a deferred module.** Astro emits
- *   `<script src>` as `type="module"`, so the element has its children by the
- *   time it is upgraded. `is:inline` runs it too early and every lookup inside
- *   the element finds nothing.
- * - **A `connect` that throws leaves that one element inert** and reports it,
- *   rather than taking its siblings down with it.
- *
- * See docs/client-scripts.md.
+ * - **The page's script must stay a bundled module** (a plain `<script>`), so
+ *   the element has its children when it upgrades.
+ * - **A `connect` that throws leaves that one element inert** and reports it.
+ * - **A tag defined twice keeps the first definition** and reports the second.
  */
-export function defineElement<C extends { readonly tag: string }>(
-    component: C,
-    connect: Connect<C>
-): void {
-    const { tag } = component;
+export function element<
+    const Tag extends string,
+    const R extends ComponentRoles &
+        CheckedKeys<R> & { readonly [K in Reserved]?: never },
+>(
+    tag: Tag & CheckedTagName<Tag>,
+    roles: R,
+    connect: Connect<R>
+): Component<Tag, R> {
+    // Already checked by this function's own signature.
+    const contract = component(tag as never, roles) as Component<Tag, R>;
+    if (typeof customElements !== "undefined") {
+        define(contract, roles, connect);
+    }
+    return contract;
+}
 
-    // Read once: the roles are fixed when the component is built, and only the
-    // element they point at changes.
-    const roleNames = Object.keys(component).filter(
-        (key) => key !== "tag" && key !== "root"
-    );
+/** The shape this file needs off a role, without its field types. */
+interface AnyRole {
+    all(root: ParentNode): Marked<Element, MarkupFields>[];
+    one(root: ParentNode): Marked<Element, MarkupFields> | null;
+    require(root: ParentNode): Marked<Element, MarkupFields>;
+}
+
+function define<R extends ComponentRoles>(
+    contract: Component<string, R>,
+    roles: R,
+    connect: Connect<R>
+): void {
+    const { tag } = contract;
+    if (customElements.get(tag) !== undefined) {
+        reportDevError(
+            tag,
+            new Error(`<${tag}> is already defined; this definition is ignored`)
+        );
+        return;
+    }
+
+    const bind = (host: HTMLElement): ElementRoles<R> => {
+        const bound: Record<string, unknown> = {};
+        for (const [name, fields] of Object.entries(roles)) {
+            const role = (contract as unknown as Record<string, AnyRole>)[name];
+            if (role === undefined) continue;
+            bound[name] =
+                Object.keys(fields).length === 0
+                    ? {
+                          all: () => role.all(host).map((each) => each.element),
+                          one: () => role.one(host)?.element ?? null,
+                          require: () => role.require(host).element,
+                      }
+                    : {
+                          all: () => role.all(host),
+                          one: () => role.one(host),
+                          require: () => role.require(host),
+                      };
+        }
+        return bound as ElementRoles<R>;
+    };
 
-    // The class is built in here rather than at module scope so `HTMLElement`
-    // is only read in a browser.
     customElements.define(
         tag,
         class extends HTMLElement {
-            /**
-             * This visit's listeners, and only this visit's. Remade every time:
-             * an `AbortController` is single-use, and a reused one comes back
-             * already aborted, leaving the element inert but normal-looking.
-             */
+            /** This visit's listeners. Remade every time: a controller is single-use. */
             #ac?: AbortController;
-
-            /** What `connect` handed back, if anything. */
             #undo?: () => void;
 
             connectedCallback(): void {
-                // Insurance: a live controller still here would orphan its
-                // listeners.
                 this.#end();
-
                 const ac = new AbortController();
                 this.#ac = ac;
                 try {
@@ -123,9 +150,9 @@ export function defineElement<C extends { readonly tag: string }>(
                         );
                     }
                     this.#undo =
-                        connect(this, ac.signal, this.#roles()) ?? undefined;
+                        connect(this, bind(this), ac.signal) ?? undefined;
                 } catch (error) {
-                    this.#report(error);
+                    reportDevError(this.localName, error);
                 }
             }
 
@@ -133,50 +160,22 @@ export function defineElement<C extends { readonly tag: string }>(
                 this.#end();
             }
 
-            /** Moving to another document ends the old document's visit. */
             adoptedCallback(): void {
                 this.#end();
             }
 
-            /** This instance's roles: the component's, with the root supplied. */
-            #roles(): Roles<C> {
-                const bound: Record<string, unknown> = {};
-                for (const name of roleNames) {
-                    const role = (component as Record<string, unknown>)[
-                        name
-                    ] as AnyRole;
-                    bound[name] = {
-                        all: () => role.all(this),
-                        one: () => role.one(this),
-                        require: () => role.require(this),
-                    };
-                }
-                return bound as Roles<C>;
-            }
-
             #end(): void {
                 // Aborted before the undo runs, so an async continuation that
                 // checks the signal can see the visit is over.
                 this.#ac?.abort();
                 this.#ac = undefined;
-
                 const undo = this.#undo;
                 this.#undo = undefined;
                 try {
                     undo?.();
                 } catch (error) {
-                    this.#report(error);
-                }
-            }
-
-            #report(error: unknown): void {
-                // The bare expression Vite substitutes, so this collapses to
-                // `if (false)` and the dev panel leaves the bundle.
-                if (import.meta.env.DEV) {
                     reportDevError(this.localName, error);
-                    return;
                 }
-                console.error(`${this.localName}:`, error);
             }
         }
     );

package/src/astro/filters-view.ts

@@ -20,7 +20,7 @@
  * See docs/client-scripts.md.
  */
 
-import type { FieldMap, Filters } from "./filters.ts";
+import type { FieldMap, FilterChange, Filters } from "./filters.ts";
 
 /** The `text` fields of `F`, so a search box cannot be pointed at a flag. */
 export type TextFieldOf<F extends FieldMap> = {
@@ -46,77 +46,61 @@ export interface SearchBoxElements {
     readonly count?: HTMLElement | null;
 }
 
-export interface SearchBox {
-    /**
-     * Brings the box into line with the state, from inside `onChange`. Two
-     * scalars rather than the change object, so this does not care what the
-     * field was named.
-     */
-    render(query: string, matchCount: number): void;
-    /**
-     * Points the input and the clear button at one `text` field, and returns
-     * the undo. Separate from construction because `render` is called from the
-     * list's `onChange`: the box has to exist before the list, and this needs
-     * the list.
-     */
-    bind<F extends FieldMap>(
-        list: Filters<F>,
-        field: TextFieldOf<F>
-    ): () => void;
-}
-
 /**
- * The search input beside a `filters` list.
+ * The search input beside a `filters` list, kept in step with it: typing sets
+ * `field`, the clear button resets it, and every change repaints the box.
+ * Returns the undo.
  *
  * ```ts
- * const search = searchBox({ input, clear, empty, count });
- * const list = filters({
- *     fields,
- *     items,
- *     onChange: ({ state, matched }) => search.render(state.q, matched.size),
- * });
- * const unbind = search.bind(list, "q");
+ * const list = filters({ fields, items, onChange: … });
+ * const detach = list.attach();
+ * const unbind = searchBox(list, "q", { input, clear, empty, count });
  * ```
  */
-export function searchBox(elements: SearchBoxElements): SearchBox {
+export function searchBox<F extends FieldMap>(
+    list: Filters<F>,
+    field: TextFieldOf<F>,
+    elements: SearchBoxElements
+): () => void {
     const { input, clear, empty, count } = 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];
 
-    return {
-        render(query, matchCount) {
-            // Guarded by inequality: assigning `value` while someone types
-            // moves the caret to the end, and this exists for state that moved
-            // without the keyboard — the back button, or a `reset`.
-            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: inside a generic
-            // function TypeScript cannot see that this field holds a string.
-            const name = field as Parameters<typeof list.set>[0];
-
-            input?.addEventListener(
-                "input",
-                () => list.set(name, input.value as never),
-                { signal }
-            );
+    const render = ({ state, matched }: FilterChange<F>): 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
+        // the keyboard — the back button, or a `reset`.
+        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);
+    };
 
-            clear?.addEventListener(
-                "click",
-                () => {
-                    list.reset(name);
-                    // The button just hid itself; focus must not stay on it.
-                    input?.focus();
-                },
-                { signal }
-            );
+    render(list);
+    const unsubscribe = list.subscribe(render);
 
-            return () => listeners.abort();
+    const events = new AbortController();
+    const { signal } = events;
+    input?.addEventListener(
+        "input",
+        () => list.set(name, input.value as never),
+        { signal }
+    );
+    clear?.addEventListener(
+        "click",
+        () => {
+            list.reset(name);
+            // The button just hid itself; focus must not stay on it.
+            input?.focus();
         },
+        { signal }
+    );
+
+    return () => {
+        events.abort();
+        unsubscribe();
     };
 }
 
@@ -131,8 +115,8 @@ export function searchBox(elements: SearchBoxElements): SearchBox {
  * **So the order is load-bearing: innermost first.**
  *
  * ```ts
- * hideEmpty(countries, (c) => within(c).all("[data-city]"));
- * hideEmpty(regions, (r) => within(r).all("[data-country]"));
+ * hideEmpty(countries, (c) => citiesIn.get(c) ?? []);
+ * hideEmpty(regions, (r) => countriesIn.get(r) ?? []);
  * ```
  */
 export function hideEmpty<T extends HTMLElement>(

package/src/astro/filters.ts

@@ -4,8 +4,8 @@
  * ```ts
  * const list = filters({
  *     fields: {
- *         q: { kind: "text", param: "q" },
- *         category: { kind: "choice", param: "category" },
+ *         q: { kind: "text" },
+ *         category: { kind: "choice" },
  *     },
  *     items: entries.map((entry) => ({
  *         key: entry.id,
@@ -40,10 +40,11 @@
  *
  * `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 }
-    | { readonly kind: "choice"; readonly param?: string }
-    | { readonly kind: "flag"; readonly param?: string };
+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;
+}
 
 /** The fields of one list, named by the caller. */
 export type FieldMap = Readonly<Record<string, Field>>;
@@ -66,14 +67,6 @@ export type ItemValue<F extends Field> = F["kind"] extends "flag"
       ? string | readonly string[]
       : string;
 
-/**
- * What one field contributes.
- *
- * @deprecated Say which side you are on: `StateValue` or `ItemValue`. This
- * named both while they were the same type, and is `StateValue` now.
- */
-export type FieldValue<F extends Field> = StateValue<F>;
-
 /** Every field's value for one item, derived from the field declaration. */
 export type ItemValues<F extends FieldMap> = {
     readonly [K in keyof F]: ItemValue<F[K]>;
@@ -144,6 +137,11 @@ export interface Filters<F extends FieldMap> {
     ): void;
     /** Clears one field, or all of them. Always a push: clearing is deliberate. */
     reset(field?: keyof F): void;
+    /**
+     * 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;
     /**
      * Reads the URL, applies it, and starts listening — returns the undo.
      *
@@ -189,16 +187,20 @@ export function filters<const F extends FieldMap>(
         }
         keys.add(item.key);
     }
-    const params = new Set<string>();
+    // 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 param = fields[name]?.param;
-        if (param === undefined) continue;
-        if (params.has(param)) {
+        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}".`
             );
         }
-        params.add(param);
+        taken.add(param);
+        params.set(name, param);
     }
 
     // Folded once at construction: doing it per item per keystroke is the
@@ -305,15 +307,16 @@ export function filters<const F extends FieldMap>(
         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 (field.param === undefined) {
+            if (param === undefined) {
                 // 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(field.param);
+            const raw = search.get(param);
             next[name] = field.kind === "flag" ? raw === FLAG_ON : (raw ?? "");
         }
         state = next as FilterState<F>;
@@ -328,19 +331,14 @@ 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 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;
-            if (field.kind === "flag") {
-                if (state[name] === true) search.set(field.param, FLAG_ON);
+        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);
                 continue;
             }
             const value = (state[name] as string).trim();
-            if (value !== "") search.set(field.param, value);
+            if (value !== "") search.set(param, value);
         }
 
         const query = search.toString();
@@ -356,7 +354,11 @@ export function filters<const F extends FieldMap>(
     const normalized = (name: keyof F & string, value: unknown): unknown =>
         fields[name]?.kind === "text" ? (value as string).trim() : value;
 
-    const announce = (): void => onChange({ state, matched });
+    const listeners = new Set<(change: FilterChange<F>) => void>();
+    const announce = (): void => {
+        onChange({ state, matched });
+        for (const listener of listeners) listener({ state, matched });
+    };
 
     recompute();
 
@@ -417,8 +419,13 @@ export function filters<const F extends FieldMap>(
             announce();
         },
 
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+
         attach() {
-            const listeners = new AbortController();
+            const events = new AbortController();
 
             // A `popstate` listener that outlives its page is the leak with no
             // visible symptom: it keeps rendering into markup that was replaced.
@@ -429,7 +436,7 @@ export function filters<const F extends FieldMap>(
                     recompute();
                     announce();
                 },
-                { signal: listeners.signal }
+                { signal: events.signal }
             );
 
             attached = true;
@@ -441,7 +448,7 @@ export function filters<const F extends FieldMap>(
             announce();
 
             return () => {
-                listeners.abort();
+                events.abort();
                 attached = false;
             };
         },