@escape-game-over/atlas 0.1.25 → 0.1.27

package/src/astro/markup.ts

@@ -1,656 +0,0 @@
-/**
- * A markup contract: the attributes a template writes and a script reads, named
- * once and typed on both sides.
- *
- * ```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.** A script and the template it enhances agree on attribute names, and
- * nothing checks the agreement: `data-filter-regoin` in one and
- * `dataset.filterRegion` in the other compile, build and ship, and the facet
- * just never matches. Here names are derived rather than spelled, values are
- * typed on the way in, and parsed on the way out — a missing or malformed
- * attribute throws, naming the element, instead of reading as an empty string.
- *
- * `component` below binds a set of roles to one custom element, which is what
- * most consumers want. See docs/client-scripts.md.
- */
-
-import type { Digit, Letter } from "../types.ts";
-
-/**
- * The names below become attributes, and a malformed one is not a small
- * mistake: `data-store row` is refused by `setAttribute`, `[data-store row]`
- * is refused by `querySelectorAll`, and a tag without a hyphen is refused by
- * `customElements.define` — each of them in the reader's browser, long after
- * the page was built. They are literals in a source file, so the rules are
- * spelled as types and the mistake is an error in the editor instead.
- *
- * Per character rather than by pattern, in the way `i18n/placeholders.ts`
- * checks a placeholder's name. A widened `string` — from a variable rather than
- * a literal — is accepted: there is nothing to check.
- */
-type WordChar = Lowercase<Letter> | Digit;
-
-/** `store`, `row2`: one lowercase word. */
-type IsWord<S extends string> = S extends `${infer Head}${infer Tail}`
-    ? Head extends WordChar
-        ? Tail extends ""
-            ? true
-            : IsWord<Tail>
-        : false
-    : false;
-
-/** `store-row`, `go-faq`: lowercase words joined by single hyphens. */
-type IsHyphenated<S extends string> = S extends `${infer Head}-${infer Rest}`
-    ? IsWord<Head> extends true
-        ? IsHyphenated<Rest>
-        : false
-    : IsWord<S>;
-
-/** Letters and digits, in either case: what follows a field's first letter. */
-type IsAlphanumeric<S extends string> = S extends `${infer Head}${infer Tail}`
-    ? Head extends Letter | Lowercase<Letter> | Digit
-        ? Tail extends ""
-            ? true
-            : IsAlphanumeric<Tail>
-        : false
-    : false;
-
-/** `blockedLabel`: a lowercase letter, then letters and digits. */
-type IsCamelCase<S extends string> = S extends `${infer Head}${infer Tail}`
-    ? Head extends Lowercase<Letter>
-        ? Tail extends ""
-            ? true
-            : IsAlphanumeric<Tail>
-        : false
-    : false;
-
-export interface MalformedMarkupName<N extends string> {
-    readonly __MALFORMED_MARKUP_NAME__: `"${N}" cannot be a role name: it becomes an attribute, so it must be lowercase words joined by single hyphens, as in "store-row"`;
-}
-
-export interface MalformedTagName<N extends string> {
-    readonly __MALFORMED_TAG_NAME__: `"${N}" cannot be a custom element name: lowercase words with at least one hyphen, as in "go-faq"`;
-}
-
-export interface MalformedKey<N extends string> {
-    readonly __MALFORMED_KEY__: `"${N}" cannot be a field or role name: it becomes part of an attribute, so it must be camelCase, as in "blockedLabel"`;
-}
-
-/** Nothing extra for a good name, and an impossible shape for a bad one. */
-type CheckedMarkupName<N extends string> = string extends N
-    ? unknown
-    : IsHyphenated<N> extends true
-      ? unknown
-      : MalformedMarkupName<N>;
-
-export type CheckedTagName<N extends string> = string extends N
-    ? unknown
-    : IsHyphenated<N> extends true
-      ? N extends `${string}-${string}`
-          ? unknown
-          : MalformedTagName<N>
-      : MalformedTagName<N>;
-
-/** The same, for every key of a fields or roles object. */
-export type CheckedKeys<T> = {
-    [K in keyof T]: K extends string
-        ? IsCamelCase<K> extends true
-            ? unknown
-            : MalformedKey<K>
-        : never;
-};
-
-/**
- * What one field is, as data rather than a constructor — the choice `filters`
- * makes, and for the same reason.
- *
- * - `text` — any string, the empty one included.
- * - `number` — finite only.
- * - `list` — several words, space-separated, as `class` is.
- * - `template` — a sentence with `{placeholders}` in it, read back as the
- *   function that fills them. A template that never says one of its own
- *   `params` fails the build, rather than shipping a brace to a reader.
- * - `choice` — one of `of`, checked at compile time and again when read.
- * - `flag` — present or absent. Off is the attribute left out, never `"false"`,
- *   so a stylesheet can select it with a bare `[data-…]`.
- *
- * `optional` lets a field be left off, and reads back `undefined`. 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: "template";
-          readonly params: readonly [string, ...string[]];
-          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>>;
-
-/**
- * A role that carries nothing: `search: marker`, where `search: {}` reads like
- * options somebody forgot to fill in. Most roles are these — they name an
- * element the script has to find, and hold no values.
- */
-export const marker = {} as const;
-
-/** What `attrs` takes for a field, and what lands in the attribute. */
-type Held<F extends MarkupField> = F extends { kind: "text" }
-    ? string
-    : F extends { kind: "number" }
-      ? number
-      : F extends { kind: "list" }
-        ? readonly string[]
-        : F extends { kind: "template" }
-          ? string
-          : F extends { kind: "choice"; of: readonly (infer V)[] }
-            ? V
-            : boolean;
-
-/**
- * What a script reads back — the same, except that a `template` arrives as the
- * function that fills it, so no script spells a placeholder.
- */
-type Read<F extends MarkupField> = F extends {
-    kind: "template";
-    params: readonly (infer P)[];
-}
-    ? (values: Record<P & string, string>) => string
-    : Held<F>;
-
-/** 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 }
-    ? Read<F> | undefined
-    : Read<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 also accept `undefined`, so a value that is itself optional
- * — `store.state` — passes straight through.
- */
-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 below and `closest`. */
-    readonly selector: string;
-
-    /**
-     * The attribute one field lives in, for a consumer that needs the name as a
-     * string — a `MutationObserver`'s `attributeFilter`. A stylesheet cannot use
-     * it: Tailwind only sees selectors written as literals.
-     */
-    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 takes 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 a field is missing or malformed — an `undefined` 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 field set to `undefined`, or a flag set to `false`,
-     * removes the attribute; fields left out are not touched.
-     */
-    write(element: Element, values: Partial<MarkupInput<F>>): void;
-}
-
-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 were: a value can reach here from a cast or an env
- * var, and this runs at build time, where a throw fails the build instead of
- * shipping a page whose script throws 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 "template": {
-            if (typeof value !== "string") {
-                return refuse("it is a template field");
-            }
-            for (const param of field.params) {
-                if (!value.includes(`{${param}}`)) {
-                    refuse(
-                        `it never says {${param}}, so that value would have nowhere to go`
-                    );
-                }
-            }
-            return value;
-        }
-        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 !== "");
-        case "template":
-            return (values: Record<string, string>) =>
-                field.params.reduce(
-                    (text, param) =>
-                        text.replaceAll(`{${param}}`, values[param] ?? ""),
-                    raw
-                );
-    }
-}
-
-/**
- * One role, built from a name the caller has already vouched for.
- *
- * Not exported: `markup` is this with the name checked, and `component` builds
- * its names from a tag it checked itself, so neither can reach here with
- * something malformed.
- */
-function role<const F extends MarkupFields>(
-    name: string,
-    fields: F
-): Markup<F> {
-    const marker = `data-${name}`;
-    const selector = `[${marker}]`;
-
-    const entries = Object.entries(fields).map(([key, field]) => ({
-        key,
-        field,
-        attribute: `${marker}-${hyphenate(key)}`,
-    }));
-
-    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(`<${element.localName} ${marker}>: ${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`: 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);
-            }
-        },
-    };
-}
-
-/**
- * Declares one role: `data-<name>` marks the element, `data-<name>-<field>`
- * holds each field.
- *
- * Two roles whose names make one a prefix of the other collide: `markup("card")`
- * with a field `title`, and `markup("card-title")`, both write `data-card-title`.
- * `component` below refuses that; here, name them so it cannot happen.
- */
-export function markup<
-    const N extends string,
-    const F extends MarkupFields & CheckedKeys<F> = Record<never, never>,
->(name: N & CheckedMarkupName<N>, fields?: F): Markup<F> {
-    return role(name, (fields ?? {}) as F);
-}
-
-/** A component's roles, by name: each is the fields of one `markup` role. */
-export type ComponentRoles = Readonly<Record<string, MarkupFields>>;
-
-/** The keys the component object uses itself, so no role may take them. */
-export type Reserved = "tag" | "root";
-
-/**
- * What marks a component's root element.
- *
- * One name, so a project gives every root a display in a single stylesheet rule
- * rather than a class per component, and so `element` can say when a
- * template forgot to spread it.
- */
-export const ROOT_ATTRIBUTE = "data-atlas-root";
-
-export type Component<Tag extends string, R extends ComponentRoles> = {
-    /** The custom element's name: what the template renders, and what
-     * `element` registers the behaviour under. */
-    readonly tag: Tag;
-
-    /**
-     * What the root element carries, spread by the template that renders it:
-     * `<faq.tag {...faq.root}>`.
-     */
-    readonly root: Readonly<Record<string, string>>;
-} & { readonly [K in keyof R]: Markup<R[K]> };
-
-/**
- * A custom element and the roles inside it, with lookups scoped to one
- * instance.
- *
- * ```ts
- * export const faq = component("go-faq", {
- *     row: { key: { kind: "text" }, text: { kind: "text" } },
- *     search: {},
- * });
- *
- * // template: <faq.tag {...faq.root}> … <details {...faq.row.attrs({ key, text })}>
- * // behaviour: see `element` in element.ts, which builds on this.
- * ```
- *
- * Two things `markup` alone leaves to the project:
- *
- * - **Names.** Every attribute is `data-<tag>-<role>[-<field>]`. The browser
- *   refuses to define one tag twice, so two components cannot share an
- *   attribute, and clashes inside one component are refused here.
- * - **Scope.** A lookup returns only elements owned by the same instance as its
- *   root — the owner being the nearest ancestor with this tag. A nested
- *   instance keeps its elements to itself, and the root may be any element
- *   inside the instance, not only the instance itself.
- *
- * Roles outside any instance, like a footer button that reopens a banner, are
- * what plain `markup` is still for.
- */
-export function component<
-    const Tag extends string,
-    const R extends ComponentRoles &
-        CheckedKeys<R> & { readonly [K in Reserved]?: never },
->(tag: Tag & CheckedTagName<Tag>, roles: R): Component<Tag, R> {
-    // Every attribute the component writes, so two that coincide are refused
-    // rather than left to overwrite each other.
-    const claimed = new Map<string, string>();
-    const claim = (attribute: string, by: string): void => {
-        const earlier = claimed.get(attribute);
-        if (earlier !== undefined) {
-            throw new Error(
-                `component(${show(tag)}): ${by} and ${earlier} would both write ${attribute}`
-            );
-        }
-        claimed.set(attribute, by);
-    };
-
-    /** The instance a root belongs to; `null` for the document. */
-    const ownerOf = (root: ParentNode): Element | null =>
-        "closest" in root && typeof root.closest === "function"
-            ? root.closest(tag)
-            : null;
-
-    const scoped = (
-        name: string,
-        fields: MarkupFields
-    ): Markup<MarkupFields> => {
-        // A compile error already, and cheap to keep: this one would overwrite
-        // the component's own key and leave nothing to render the element as.
-        if (name === "tag") {
-            throw new Error(
-                `component(${show(tag)}): ${show(name)} is taken by the component itself`
-            );
-        }
-
-        const base = role(`${tag}-${hyphenate(name)}`, fields);
-        claim(base.selector.slice(1, -1), `the role ${show(name)}`);
-        for (const field of Object.keys(fields)) {
-            claim(base.attribute(field), `${name}.${field}`);
-        }
-
-        // Filtered before anything is read, so a malformed element in a nested
-        // instance cannot fail a lookup that was never going to return it.
-        const mine = <T extends Element>(root: ParentNode): T[] => {
-            const owner = ownerOf(root);
-            return [...root.querySelectorAll<T>(base.selector)].filter(
-                (element) => element.closest(tag) === owner
-            );
-        };
-
-        const one = <T extends Element = HTMLElement>(
-            root: ParentNode
-        ): Marked<T, MarkupFields> | null => {
-            const [found] = mine<T>(root);
-            return found === undefined
-                ? null
-                : { element: found, values: base.read(found) };
-        };
-
-        return {
-            ...base,
-            all: <T extends Element = HTMLElement>(root: ParentNode) =>
-                mine<T>(root).map((element) => ({
-                    element,
-                    values: base.read(element),
-                })),
-            one,
-            require<T extends Element = HTMLElement>(root: ParentNode) {
-                const found = one<T>(root);
-                if (found === null) {
-                    throw new Error(
-                        `nothing in this <${tag}> carries ${base.selector.slice(1, -1)} — does the template spread its attrs inside the element?`
-                    );
-                }
-                return found;
-            },
-        };
-    };
-
-    const built: Record<string, unknown> = {
-        tag,
-        root: { [ROOT_ATTRIBUTE]: "" },
-    };
-    for (const [name, fields] of Object.entries(roles)) {
-        built[name] = scoped(name, fields);
-    }
-    return built as Component<Tag, R>;
-}