@escape-game-over/atlas 0.1.18 → 0.1.20

package/src/astro/markup.ts

@@ -1,10 +1,6 @@
 /**
- * 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.
+ * 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
@@ -23,52 +19,129 @@
  * }
  * ```
  *
- * **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:
+ * **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.
  *
- * - **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.
+ * `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.
  *
- * 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.
+ * 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>;
+
+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. */
+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, for the same reason: builder functions would put names as general as
- * `text` into every module that imports this.
+ * makes, and for the same reason.
  *
  * - `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"`,
+ * - `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` when it was.
- * A `flag` has no `optional`: absent is already one of its two values.
+ * `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[]];
@@ -79,16 +152,36 @@ export type MarkupField =
 /** The fields of one role, named by the caller. */
 export type MarkupFields = Readonly<Record<string, MarkupField>>;
 
-/** The value a field holds when present. */
+/**
+ * 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: "choice"; of: readonly (infer V)[] }
-          ? V
-          : boolean;
+        : 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" }
@@ -99,8 +192,8 @@ type Omittable<F extends MarkupField> = F extends { kind: "flag" }
 
 /** One field's value as a script reads it. */
 export type MarkupValue<F extends MarkupField> = F extends { optional: true }
-    ? Held<F> | undefined
-    : Held<F>;
+    ? Read<F> | undefined
+    : Read<F>;
 
 /** Every field's value, as a script reads it. */
 export type MarkupValues<F extends MarkupFields> = {
@@ -115,10 +208,8 @@ 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.
+ * 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]> } & {
@@ -135,29 +226,19 @@ export interface Marked<T extends Element, F extends MarkupFields> {
 }
 
 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.
-     */
+    /** `[data-<name>]`: what finds this role, for the lookups below and `closest`. */
     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.
+     * 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 may be called
-     * with no argument at all.
+     * 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]
@@ -166,12 +247,9 @@ export interface Markup<F extends MarkupFields> {
     ): 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.
+     * 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>;
 
@@ -185,28 +263,13 @@ export interface Markup<F extends MarkupFields> {
     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.
+     * 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;
 }
 
-/** 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()}`);
 
@@ -217,10 +280,9 @@ const show = (value: unknown): string =>
 /**
  * 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.
+ * 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,
@@ -247,6 +309,19 @@ function encode(
             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) {
@@ -297,45 +372,35 @@ function decode(
             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
+                );
     }
 }
 
 /**
- * Declares one role: a marker attribute, and a typed attribute per field.
+ * One role, built from a name the caller has already vouched for.
  *
- * `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.
+ * 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.
  */
-export function markup<const F extends MarkupFields = Record<never, never>>(
+function role<const F extends MarkupFields>(
     name: string,
-    fields?: F
+    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 entries = Object.entries(fields).map(([key, field]) => ({
+        key,
+        field,
+        attribute: `${marker}-${hyphenate(key)}`,
+    }));
 
     const read = (element: Element): MarkupValues<F> => {
         if (!element.hasAttribute(marker)) {
@@ -354,7 +419,7 @@ export function markup<const F extends MarkupFields = Record<never, never>>(
             } catch (error) {
                 const reason =
                     error instanceof Error ? error.message : String(error);
-                throw new Error(`${describe(element)}: ${reason}`, {
+                throw new Error(`<${element.localName} ${marker}>: ${reason}`, {
                     cause: error,
                 });
             }
@@ -413,8 +478,8 @@ export function markup<const F extends MarkupFields = Record<never, never>>(
         },
 
         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.
+            // 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`
@@ -431,6 +496,21 @@ export function markup<const F extends MarkupFields = Record<never, never>>(
     };
 }
 
+/**
+ * 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>>;
 
@@ -444,9 +524,6 @@ export type Component<Tag extends string, R extends ComponentRoles> = {
     define(element: CustomElementConstructor): void;
 } & { readonly [K in keyof R]: Markup<R[K]> };
 
-/** A custom element name, as far as a pattern can check it: needs a hyphen. */
-const TAG = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)+$/;
-
 /**
  * A custom element and the roles inside it, with lookups scoped to one
  * instance.
@@ -466,8 +543,8 @@ const TAG = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)+$/;
  * - **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
+ * - **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.
  *
@@ -476,14 +553,9 @@ const TAG = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)+$/;
  */
 export function component<
     const Tag extends string,
-    const R extends ComponentRoles & { readonly [K in Reserved]?: never },
->(tag: Tag, roles: R): Component<Tag, R> {
-    if (!TAG.test(tag)) {
-        throw new Error(
-            `component(${show(tag)}): a custom element name is lowercase words with at least one hyphen, as in "go-faq"`
-        );
-    }
-
+    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>();
@@ -504,24 +576,21 @@ export function component<
             : null;
 
     const scoped = (
-        role: string,
+        name: string,
         fields: MarkupFields
     ): Markup<MarkupFields> => {
-        if (role === "tag" || role === "define") {
-            throw new Error(
-                `component(${show(tag)}): ${show(role)} is taken by the component itself`
-            );
-        }
-        if (!FIELD.test(role)) {
+        // A compile error already, and cheap to keep: these two would overwrite
+        // the component's own keys and leave nothing to define the element with.
+        if (name === "tag" || name === "define") {
             throw new Error(
-                `component(${show(tag)}): the role ${show(role)} must be camelCase — it becomes part of the attribute`
+                `component(${show(tag)}): ${show(name)} is taken by the component itself`
             );
         }
 
-        const base = markup(`${tag}-${hyphenate(role)}`, fields);
-        claim(base.selector.slice(1, -1), `the role ${show(role)}`);
+        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), `${role}.${field}`);
+            claim(base.attribute(field), `${name}.${field}`);
         }
 
         // Filtered before anything is read, so a malformed element in a nested
@@ -567,8 +636,8 @@ export function component<
         define: (element: CustomElementConstructor) =>
             customElements.define(tag, element),
     };
-    for (const [role, fields] of Object.entries(roles)) {
-        built[role] = scoped(role, fields);
+    for (const [name, fields] of Object.entries(roles)) {
+        built[name] = scoped(name, fields);
     }
     return built as Component<Tag, R>;
 }