@escape-game-over/atlas 0.1.23 → 0.1.25

package/src/astro/Zoom.astro

@@ -0,0 +1,61 @@
+---
+/**
+ * Internal to `Image.astro`. No script: `command="show-modal"` opens the dialog
+ * and `closedby="any"` lets a click outside close it. The large image is lazy
+ * inside a closed dialog, so it is fetched on open.
+ */
+
+import { getImage } from "astro:assets";
+import type { ImageMetadata } from "astro";
+
+interface Props {
+    readonly src: ImageMetadata;
+    readonly alt: string;
+    readonly closeLabel: string;
+    /** On the `<dialog>`. */
+    readonly class?: string;
+}
+
+const { src, alt, closeLabel, class: dialogClass } = Astro.props;
+const large = await getImage({
+    src,
+    width: Math.min(src.width, 2048),
+    format: "webp",
+});
+// The file's URL carries Astro's content hash, so the id is the same every
+// build. The same image zoomed twice on a page opening one dialog is harmless.
+const id = `atlas-zoom${large.src.replace(/[^\w-]/g, "-")}`;
+---
+
+<button
+    type="button"
+    commandfor={id}
+    command="show-modal"
+    style="padding:0;border:0;background:none;cursor:zoom-in"
+>
+    <slot />
+</button>
+<dialog
+    id={id}
+    closedby="any"
+    class={dialogClass}
+    aria-label={alt}
+>
+    <button
+        type="button"
+        commandfor={id}
+        command="close"
+        aria-label={closeLabel}
+    >
+        ×
+    </button>
+    <img
+        src={large.src}
+        width={large.attributes.width}
+        height={large.attributes.height}
+        alt={alt}
+        loading="lazy"
+        decoding="async"
+        style="display:block;max-width:100%;max-height:85vh;height:auto"
+    >
+</dialog>

package/src/astro/client.ts

@@ -5,19 +5,29 @@
  * import { filters, searchBox } from "@escape-game-over/atlas/client";
  * ```
  *
- * **For the browser.** Everything here exists to touch a live document, and is
- * meant for a `<script src>`, not for frontmatter or `astro.config.ts`. A
- * component's contract is the one thing both halves need, and it stays on
- * `astro/markup`, which touches nothing.
+ * The only import path for browser code. Nothing here touches the DOM at
+ * import, so a component's contract can be imported from frontmatter too.
  */
 
 export * from "./background-video.ts";
 export * from "./carousel.ts";
-export * from "./consent.ts";
-export * from "./dev-log.ts";
-export * from "./dom.ts";
-export * from "./element.ts";
+export {
+    applyConsent,
+    type ConsentChoice,
+    type ConsentRecord,
+    type ConsentStoreOptions,
+    consent,
+    consentApplies,
+    consentStore,
+} from "./consent.ts";
+export { type Connect, type ElementRoles, element } from "./element.ts";
 export * from "./filters.ts";
 export * from "./filters-view.ts";
-export * from "./markup.ts";
+export {
+    type Component,
+    type Marked,
+    type Markup,
+    marker,
+    markup,
+} from "./markup.ts";
 export * from "./youtube.ts";

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>(