@escape-game-over/atlas 0.1.15 → 0.1.17

package/src/astro/markup.ts

@@ -0,0 +1,432 @@
+/**
+ * A markup contract: the attributes a template writes and a script reads,
+ * named once, typed on both sides.
+ *
+ * In `astro/` because the reading half takes elements. The writing half runs in
+ * an Astro template at build time, and both halves come off the one object —
+ * which is the entire point.
+ *
+ * ```ts
+ * // network-markup.ts, imported by the template and by the script
+ * export const row = markup("network-row", {
+ *     key: { kind: "text" },
+ *     status: { kind: "choice", of: ["open", "soon"] },
+ *     state: { kind: "text", optional: true },
+ * });
+ *
+ * // StoreRow.astro
+ * <a {...row.attrs({ key, status: "open", state: store.state })}>
+ *
+ * // network.ts
+ * for (const { element, values } of row.all(this)) {
+ *     values.status; // "open" | "soon"
+ * }
+ * ```
+ *
+ * **Why it exists.** A client script and the template it enhances agree on
+ * attribute names, and nothing checks the agreement. `data-filter-regoin` in a
+ * template and `dataset.filterRegion` in a script compile, build and ship; the
+ * facet never matches, and the page reads as a filter with no results rather
+ * than as a typo. A shared constant pins the name of one attribute. This pins
+ * all of them, and their values with them:
+ *
+ * - **Names are derived, never spelled.** `data-network-row` marks the element
+ *   and `data-network-row-status` holds a field. Neither side writes either
+ *   string, so a rename is one edit, and a field that does not exist is a
+ *   compile error in the template and in the script alike.
+ * - **Values are typed on the way in.** `attrs` takes each field's own type, so
+ *   a missing required field, or a status outside its list, fails `astro check`.
+ * - **And checked on the way out.** A script cannot trust markup it did not
+ *   write — a page cached from before a deploy, a template that spread the wrong
+ *   role — so `read` parses every field and throws, naming the element and the
+ *   attribute, rather than handing back an `undefined` that filters to nothing.
+ *
+ * The rule in docs/client-scripts.md still holds, and this is the reading of it
+ * that admits a lookup. It finds only what carries its own marker, writes only
+ * its own attributes, and has no opinion about classes, `aria` or `hidden`. The
+ * names come from the project: nothing in this package has to be matched.
+ */
+
+/**
+ * What one field is, as data rather than a constructor — the choice `filters`
+ * makes, for the same reason: builder functions would put names as general as
+ * `text` into every module that imports this.
+ *
+ * - `text` — any string, the empty one included.
+ * - `number` — finite only; `NaN` and the infinities have no attribute form
+ *   that reads back as themselves.
+ * - `list` — several words, space-separated, as `class` is. No item may be
+ *   empty or contain whitespace, which is checked when it is written.
+ * - `choice` — one of `of`. Out-of-list values fail on both sides: at compile
+ *   time in the template, at run time when read.
+ * - `flag` — present or absent. Off is the attribute left out, not `"false"`,
+ *   so a stylesheet can select it with a bare `[data-…]`.
+ *
+ * `optional` lets a field be left off, and reads back `undefined` when it was.
+ * A `flag` has no `optional`: absent is already one of its two values.
+ */
+export type MarkupField =
+    | { readonly kind: "text"; readonly optional?: boolean }
+    | { readonly kind: "number"; readonly optional?: boolean }
+    | { readonly kind: "list"; readonly optional?: boolean }
+    | {
+          readonly kind: "choice";
+          readonly of: readonly [string, ...string[]];
+          readonly optional?: boolean;
+      }
+    | { readonly kind: "flag" };
+
+/** The fields of one role, named by the caller. */
+export type MarkupFields = Readonly<Record<string, MarkupField>>;
+
+/** The value a field holds when present. */
+type Held<F extends MarkupField> = F extends { kind: "text" }
+    ? string
+    : F extends { kind: "number" }
+      ? number
+      : F extends { kind: "list" }
+        ? readonly string[]
+        : F extends { kind: "choice"; of: readonly (infer V)[] }
+          ? V
+          : boolean;
+
+/** Whether a template may leave the field out. */
+type Omittable<F extends MarkupField> = F extends { kind: "flag" }
+    ? true
+    : F extends { optional: true }
+      ? true
+      : false;
+
+/** One field's value as a script reads it. */
+export type MarkupValue<F extends MarkupField> = F extends { optional: true }
+    ? Held<F> | undefined
+    : Held<F>;
+
+/** Every field's value, as a script reads it. */
+export type MarkupValues<F extends MarkupFields> = {
+    readonly [K in keyof F]: MarkupValue<F[K]>;
+};
+
+type RequiredKeys<F extends MarkupFields> = {
+    [K in keyof F]-?: Omittable<F[K]> extends true ? never : K;
+}[keyof F];
+
+type Flatten<T> = { [K in keyof T]: T[K] };
+
+/**
+ * What a template hands `attrs`: every required field, and any of the rest.
+ *
+ * The optional ones accept `undefined` as well as being left out, so a value
+ * that is itself optional — `store.state` — can be passed straight through
+ * without a conditional spread, whatever `exactOptionalPropertyTypes` says.
+ */
+export type MarkupInput<F extends MarkupFields> = Flatten<
+    { readonly [K in RequiredKeys<F>]: Held<F[K]> } & {
+        readonly [K in Exclude<keyof F, RequiredKeys<F>>]?:
+            | Held<F[K]>
+            | undefined;
+    }
+>;
+
+/** One marked element, and what its attributes say. */
+export interface Marked<T extends Element, F extends MarkupFields> {
+    readonly element: T;
+    readonly values: MarkupValues<F>;
+}
+
+export interface Markup<F extends MarkupFields> {
+    /**
+     * `[data-<name>]`: what finds this role.
+     *
+     * For the lookups the methods below do not cover — `closest`, a
+     * `matches` in an event handler — so those do not spell it either.
+     */
+    readonly selector: string;
+
+    /**
+     * The attribute one field lives in.
+     *
+     * For the rare consumer that needs the name as a string, such as a
+     * `MutationObserver`'s `attributeFilter`. A stylesheet cannot use it —
+     * Tailwind has to see its selectors as literals in the source — so a
+     * styling hook still spells the attribute once, in a class; see the docs.
+     */
+    attribute(field: keyof F & string): string;
+
+    /**
+     * The attributes to spread onto an element, in a template.
+     *
+     * Always includes the marker. A role with nothing required may be called
+     * with no argument at all.
+     */
+    attrs(
+        ...values: [RequiredKeys<F>] extends [never]
+            ? [values?: MarkupInput<F>]
+            : [values: MarkupInput<F>]
+    ): Record<string, string>;
+
+    /**
+     * One element's values, parsed.
+     *
+     * Throws when the element does not carry this role, or when any field is
+     * missing or malformed — naming the element and the attribute, because an
+     * `undefined` returned here would only resurface later as a list that
+     * silently matches nothing.
+     */
+    read(element: Element): MarkupValues<F>;
+
+    /** Every element under `root` carrying this role, each with its values. */
+    all<T extends Element = HTMLElement>(root: ParentNode): Marked<T, F>[];
+
+    /** The first element under `root` carrying this role, or `null`. */
+    one<T extends Element = HTMLElement>(root: ParentNode): Marked<T, F> | null;
+
+    /** The first, or a thrown error naming the marker nobody carried. */
+    require<T extends Element = HTMLElement>(root: ParentNode): Marked<T, F>;
+
+    /**
+     * Writes some of this role's fields back onto an element.
+     *
+     * For state a stylesheet reads — a dropdown that is blocked, a card that is
+     * selected — so the script sets it through the same names the template
+     * wrote. A field set to `undefined`, or a flag set to `false`, removes the
+     * attribute; fields left out of `values` are not touched.
+     */
+    write(element: Element, values: Partial<MarkupInput<F>>): void;
+}
+
+/** Lowercase words joined by single hyphens: what follows `data-`. */
+const NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+
+/**
+ * camelCase, so the hyphenated form below is unambiguous.
+ *
+ * `aB` → `a-b` is one-to-one only while a field cannot contain a hyphen of its
+ * own: allowing `a-b` too would give two fields one attribute, and each write
+ * would erase the other.
+ */
+const FIELD = /^[a-z][a-zA-Z0-9]*$/;
+
+const hyphenate = (field: string): string =>
+    field.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+
+/** A value for the error messages, quoted when it is a string. */
+const show = (value: unknown): string =>
+    typeof value === "string" ? `"${value}"` : String(value);
+
+/**
+ * One field's value as its attribute, or `undefined` to leave it off.
+ *
+ * Checked although the types already were: a template can reach here with a
+ * value typed as `string` that came from an env var or a cast, and this runs at
+ * build time, where a throw fails the build instead of shipping a page whose
+ * script will throw on every visit.
+ */
+function encode(
+    field: MarkupField,
+    value: unknown,
+    attribute: string
+): string | undefined {
+    if (field.kind === "flag") return value === true ? "" : undefined;
+    if (value === undefined && field.optional === true) return undefined;
+
+    const refuse = (why: string): never => {
+        throw new Error(`${attribute} cannot hold ${show(value)}: ${why}`);
+    };
+
+    switch (field.kind) {
+        case "text":
+            return typeof value === "string"
+                ? value
+                : refuse("it is a text field");
+        case "number":
+            return typeof value === "number" && Number.isFinite(value)
+                ? String(value)
+                : refuse("only a finite number reads back as itself");
+        case "choice":
+            return typeof value === "string" && field.of.includes(value)
+                ? value
+                : refuse(`expected one of ${field.of.join(", ")}`);
+        case "list": {
+            if (!Array.isArray(value)) return refuse("it is a list field");
+            for (const item of value) {
+                if (
+                    typeof item !== "string" ||
+                    item === "" ||
+                    /\s/.test(item)
+                ) {
+                    refuse(
+                        `the item ${show(item)} is empty or contains whitespace, which separates items`
+                    );
+                }
+            }
+            return value.join(" ");
+        }
+    }
+}
+
+/** An attribute's value as its field's, or a thrown error saying why not. */
+function decode(
+    field: MarkupField,
+    raw: string | null,
+    attribute: string
+): unknown {
+    if (field.kind === "flag") return raw !== null;
+    if (raw === null) {
+        if (field.optional === true) return undefined;
+        throw new Error(`${attribute} is missing`);
+    }
+
+    switch (field.kind) {
+        case "text":
+            return raw;
+        case "number": {
+            const value = Number(raw);
+            // `Number("")` is 0, so a blank attribute would read as a zero.
+            if (raw.trim() === "" || !Number.isFinite(value)) {
+                throw new Error(`${attribute} is ${show(raw)}, not a number`);
+            }
+            return value;
+        }
+        case "choice":
+            if (!field.of.includes(raw)) {
+                throw new Error(
+                    `${attribute} is ${show(raw)}, expected one of ${field.of.join(", ")}`
+                );
+            }
+            return raw;
+        case "list":
+            return raw.split(/\s+/).filter((item) => item !== "");
+    }
+}
+
+/**
+ * Declares one role: a marker attribute, and a typed attribute per field.
+ *
+ * `name` becomes `data-<name>`, and each field `data-<name>-<field>` with the
+ * field hyphenated. Both are checked here, at construction, because a name that
+ * is not a valid attribute would otherwise surface as a `querySelector` syntax
+ * error in the browser, far from the line that caused it.
+ *
+ * Two roles whose names make one a prefix of the other can collide:
+ * `markup("card")` with a field `title` and `markup("card-title")` both write
+ * `data-card-title`. Name roles so they do not.
+ */
+export function markup<const F extends MarkupFields = Record<never, never>>(
+    name: string,
+    fields?: F
+): Markup<F> {
+    if (!NAME.test(name)) {
+        throw new Error(
+            `markup(${show(name)}): a name is lowercase words joined by single hyphens, as in "store-row"`
+        );
+    }
+
+    const marker = `data-${name}`;
+    const selector = `[${marker}]`;
+
+    const entries = Object.entries(fields ?? {}).map(([key, field]) => {
+        if (!FIELD.test(key)) {
+            throw new Error(
+                `markup(${show(name)}): the field ${show(key)} must be camelCase — it becomes the last part of the attribute`
+            );
+        }
+        return { key, field, attribute: `${marker}-${hyphenate(key)}` };
+    });
+
+    const describe = (element: Element): string =>
+        `<${element.localName} ${marker}>`;
+
+    const read = (element: Element): MarkupValues<F> => {
+        if (!element.hasAttribute(marker)) {
+            throw new Error(
+                `<${element.localName}> does not carry ${marker}, so it has none of its fields`
+            );
+        }
+        const values: Record<string, unknown> = {};
+        for (const { key, field, attribute } of entries) {
+            try {
+                values[key] = decode(
+                    field,
+                    element.getAttribute(attribute),
+                    attribute
+                );
+            } catch (error) {
+                const reason =
+                    error instanceof Error ? error.message : String(error);
+                throw new Error(`${describe(element)}: ${reason}`, {
+                    cause: error,
+                });
+            }
+        }
+        return values as MarkupValues<F>;
+    };
+
+    const mark = <T extends Element>(element: T): Marked<T, F> => ({
+        element,
+        values: read(element),
+    });
+
+    const one = <T extends Element = HTMLElement>(
+        root: ParentNode
+    ): Marked<T, F> | null => {
+        const found = root.querySelector<T>(selector);
+        return found === null ? null : mark(found);
+    };
+
+    return {
+        selector,
+
+        attribute(key) {
+            const entry = entries.find((each) => each.key === key);
+            if (entry === undefined) {
+                throw new Error(`${marker} has no field ${show(key)}`);
+            }
+            return entry.attribute;
+        },
+
+        attrs(...[values]) {
+            const given = (values ?? {}) as Record<string, unknown>;
+            const out: Record<string, string> = { [marker]: "" };
+            for (const { key, field, attribute } of entries) {
+                const raw = encode(field, given[key], attribute);
+                if (raw !== undefined) out[attribute] = raw;
+            }
+            return out;
+        },
+
+        read,
+
+        all: <T extends Element = HTMLElement>(root: ParentNode) =>
+            [...root.querySelectorAll<T>(selector)].map(mark),
+
+        one,
+
+        require<T extends Element = HTMLElement>(root: ParentNode) {
+            const found = one<T>(root);
+            if (found === null) {
+                throw new Error(
+                    `nothing here carries ${marker} — is the script still a deferred module, and does the template spread its attrs?`
+                );
+            }
+            return found;
+        },
+
+        write(element, values) {
+            // Checked like `read` is: writing a role's fields onto an element
+            // that is not that role leaves it half-marked, and nothing reads it.
+            if (!element.hasAttribute(marker)) {
+                throw new Error(
+                    `<${element.localName}> does not carry ${marker}, so its fields cannot be written to it`
+                );
+            }
+            const given = values as Record<string, unknown>;
+            for (const { key, field, attribute } of entries) {
+                if (!Object.hasOwn(given, key)) continue;
+                const raw = encode(field, given[key], attribute);
+                if (raw === undefined) element.removeAttribute(attribute);
+                else element.setAttribute(attribute, raw);
+            }
+        },
+    };
+}

package/src/astro/youtube.ts

@@ -0,0 +1,160 @@
+/**
+ * A YouTube video that loads nothing from YouTube until a reader asks for it.
+ *
+ * In `astro/` because it listens for a click and makes an element, which the
+ * core is type-checked without.
+ *
+ * An embedded player is the heaviest thing most pages carry that nobody asked
+ * for: the iframe fetches the player, its scripts and its tracking on load, once
+ * per video, whether or not anyone presses play. So the page renders a poster
+ * and a button — the project's own markup, drawn however it likes — and this
+ * swaps the player in on the click, with `autoplay=1` so that the one press the
+ * reader already made is the one that starts it.
+ *
+ * ```ts
+ * const trailer = youtubeEmbed({
+ *     id: "dQw4w9WgXcQ",
+ *     title: "Trailer: The Blue Room",
+ *     frame: (iframe) => {
+ *         iframe.className = "absolute inset-0 h-full w-full";
+ *     },
+ * });
+ *
+ * const detach = trailer.attach(button, poster);
+ * ```
+ *
+ * **It draws one element, and decides nothing about how it looks.** Unlike
+ * `carousel` this has to put something into the page — the player is the
+ * behaviour — so it is the second exception to the rule in
+ * `docs/client-scripts.md`, after `filters-view`, and it is drawn as narrowly.
+ * What it sets on the iframe is what every embed needs and has no taste in it:
+ * the address, the title, the permissions, full screen, the referrer policy.
+ * Classes, size and position are the caller's, through `frame`.
+ *
+ * Kept apart from `videoObject` in `jsonld/video.ts` although both are about a
+ * YouTube video: that one describes it to a crawler at build time, this plays
+ * it in a browser, and the only thing they share is an id the caller already
+ * holds. They do not even want the same host — Google reads the `youtube.com`
+ * player as `embedUrl`, and a reader is better served by `youtube-nocookie.com`.
+ */
+
+export interface YouTubeEmbedOptions {
+    /**
+     * The video's id: what follows `v=` in a watch link, or `youtu.be/`.
+     *
+     * Checked at construction, because the tempting mistake is pasting the
+     * whole link, and that fails in the one place nobody looks — inside the
+     * player, after the click, as YouTube's own "video unavailable".
+     */
+    readonly id: string;
+    /**
+     * The iframe's title, which is its accessible name.
+     *
+     * Required and refused when blank: a frame without one is announced as
+     * "frame" and nothing else, and a screen-reader user tabbing into the
+     * player has no way to tell which video it is.
+     */
+    readonly title: string;
+    /**
+     * Anything the project wants on the iframe — classes, above all.
+     *
+     * Called once, after everything this module sets and before the iframe is
+     * in the page, so what it writes is the last word and nothing is drawn
+     * unstyled first.
+     */
+    readonly frame?: (iframe: HTMLIFrameElement) => void;
+}
+
+export interface YouTubeEmbed {
+    /**
+     * Swaps `container`'s contents for the player when `trigger` is clicked,
+     * and returns the undo.
+     *
+     * Two elements rather than one, because they are different things: the
+     * trigger is the button a reader presses, and the container is what the
+     * player replaces — usually the poster and that same button together. A
+     * click anywhere in the container would be simpler and wrong, since a
+     * caption link or a credit inside it would then start the video.
+     *
+     * Once only. The button is gone with the poster, and a second player in
+     * the same box would be two videos playing over each other.
+     *
+     * The undo removes the listener and nothing else. A player already loaded
+     * stays where it is — taking it out would stop a video someone is
+     * watching, and a page swap removes it anyway.
+     */
+    attach(trigger: HTMLElement, container: Element): () => void;
+}
+
+/**
+ * The shape of a YouTube video id.
+ *
+ * Eleven characters from the URL-safe base64 alphabet, which is what every id
+ * has been. A shape check rather than a lookup: it cannot say the video exists,
+ * only that what was handed over is an id and not a link.
+ */
+const VIDEO_ID = /^[\w-]{11}$/;
+
+/**
+ * The permissions YouTube's own embed code asks for.
+ *
+ * `autoplay` is the one that matters here: without it the `autoplay=1` in the
+ * address is refused, and the reader who pressed play gets a second play
+ * button to press.
+ */
+const ALLOW =
+    "accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share";
+
+export function youtubeEmbed(options: YouTubeEmbedOptions): YouTubeEmbed {
+    const { id, title, frame } = options;
+
+    if (!VIDEO_ID.test(id)) {
+        throw new Error(
+            `"${id}" is not a YouTube video id — expected the id alone, as it appears after "v=" or "youtu.be/", not a link.`
+        );
+    }
+    if (title.trim() === "") {
+        throw new Error(
+            `The YouTube embed for "${id}" has no title. It is the frame's accessible name — without one a screen reader announces "frame" and nothing else.`
+        );
+    }
+
+    // `youtube-nocookie.com` rather than `youtube.com`: the same player, which
+    // sets no cookie until the video is played — and here it is only ever
+    // loaded to be played, so nothing is lost by it.
+    const src = `https://www.youtube-nocookie.com/embed/${id}?autoplay=1`;
+
+    return {
+        attach(trigger, container) {
+            const listeners = new AbortController();
+
+            trigger.addEventListener(
+                "click",
+                () => {
+                    const iframe =
+                        container.ownerDocument.createElement("iframe");
+                    iframe.src = src;
+                    iframe.title = title;
+                    iframe.allow = ALLOW;
+                    iframe.allowFullscreen = true;
+                    // Stated rather than inherited. YouTube refuses to play an
+                    // embed that arrives with no referrer at all, and a site
+                    // sending `Referrer-Policy: no-referrer` would otherwise get
+                    // a player that loads and shows an error in place of the
+                    // video. This is the policy YouTube's own embed code sets.
+                    iframe.referrerPolicy = "strict-origin-when-cross-origin";
+                    frame?.(iframe);
+
+                    container.replaceChildren(iframe);
+                    // The button that had focus has just left the page, which
+                    // drops a keyboard reader back at the top of the document.
+                    // The player is where they were, and what they asked for.
+                    iframe.focus();
+                },
+                { once: true, signal: listeners.signal }
+            );
+
+            return () => listeners.abort();
+        },
+    };
+}