@escape-game-over/atlas 0.1.19 → 0.1.21

package/docs/client-scripts.md

@@ -41,7 +41,7 @@ finding them.
 | `./astro/youtube`          | the swap from poster to player, on the click and not before    | the poster, the button, the iframe's classes    |
 | `./astro/background-video` | playing or paused, playable or not, and which cut is loaded    | the play/pause control, its icons and its label |
 | `./astro/consent`          | remembering an answer, expiring it, handing it to Google       | the banner — its wording, its buttons, its law  |
-| `./astro/element`          | the two lifetimes a custom element has, and one abort signal   | what the element is and does                    |
+| `./astro/element`          | registering a custom element, and ending what it started        | what the element does while it is on the page   |
 | `./astro/dom`              | scoped `one`/`all` lookups, typed                              | the selectors                                   |
 | `./astro/dev-log`          | a panel a failed wiring can announce itself in, in dev only    | calling it behind `import.meta.env.DEV`         |
 
@@ -54,6 +54,12 @@ from the package root is the same question at build time: false, and the banner
 never reaches the HTML. Gate the render on that and keep the runtime check for
 the banner that is rendered. See NOT-BUILT.md on where the halves divide.
 
+**A script imports one path: `@escape-game-over/atlas/client`**, which re-exports
+every module above. All of it exists to touch a live document, so it belongs in
+a `<script src>` and not in 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.
+
 ## Lifetimes are the recurring bug
 
 Every module here that binds a listener hands back the undo, and the undo is
@@ -69,15 +75,23 @@ const detach = loop.attach(video);            // background-video: the <video>
 const detach = trailer.attach(button, box);   // youtube: what is pressed, what it replaces
 ```
 
-`AtlasElement` says the same thing in the shape a custom element needs, because
-an element is constructed once and may be connected many times — moving it in
-the DOM runs `disconnectedCallback` and then `connectedCallback` again:
+`defineElement` says the same thing in the shape a custom element needs. One
+function per element: it runs when the element enters the page, `signal` ends
+what it registered when the element leaves, and what it returns is the undo for
+everything else.
 
 ```ts
-protected setup(): void { … }     // once, ever: what the element is
-protected connect(): void { … }   // every connection: bind with this.signal
+defineElement("atlas-thing", (host, signal) => {
+    host.addEventListener("click", open, { signal });   // ends with the visit
+    return loop.attach(host);                           // and so does this
+});
 ```
 
+An element can enter the page more than once — moving it in the DOM runs the
+undo and then the function again — so it has to be able to run twice. State that
+must survive a move goes in a `WeakMap` keyed by `host`, which is what the
+carousel example does with its index.
+
 **The trap this exists for is view transitions.** A bundled `<script src>` is an
 ES module, cached by URL, so it executes once per session — not once per
 navigation. Bind at module scope with `ClientRouter` on and the incoming page
@@ -408,9 +422,24 @@ const input = search.require<HTMLInputElement>(this).element;
   a list that quietly loses a row is the failure this exists to prevent.
 
 The kinds are data, not builders, for the reason `filters` gives:
-`text`, `number`, `list`, `choice` and `flag`, the first four optionally
-`optional`. A `flag` is off by being absent, never `"false"`, so a stylesheet can
-select it with a bare attribute.
+`text`, `number`, `list`, `template`, `choice` and `flag`, all but `flag`
+optionally `optional`. A `flag` is off by being absent, never `"false"`, so a
+stylesheet can select it with a bare attribute.
+
+A `template` is the one that keeps a sentence out of the script. It is written
+as the translated string with its placeholders left in, and read back as the
+function that fills them:
+
+```astro
+<p {...faq.line.attrs({ sentence: t("faq.matched", { count: "{count}" }) })}></p>
+```
+
+```ts
+line.element.textContent = line.values.sentence({ count: String(hits.size) });
+```
+
+So no script spells `"{count}"`, and a sentence that never says one of its own
+placeholders fails the build rather than shipping a brace to a reader.
 
 `write` sets fields back onto an element, for state a stylesheet reads — a
 dropdown that is blocked — so the script uses the names the template did.
@@ -450,12 +479,9 @@ export const faq = component("go-faq", {
 ```
 
 ```ts
-class Faq extends AtlasElement {
-    protected connect(): void {
-        for (const { element, values } of faq.row.all(this)) { … }
-    }
-}
-faq.define(Faq);
+defineElement(faq.tag, (host, signal) => {
+    for (const { element, values } of faq.row.all(host)) { … }
+});
 ```
 
 - **Names come from the tag.** Every attribute is `data-<tag>-<role>` plus the
@@ -468,18 +494,22 @@ faq.define(Faq);
   keeps its elements, and a lookup from an element inside the instance, like a
   dropdown's own panel, still counts as that instance. Elements are filtered
   before they are read, so a broken nested copy cannot fail the outer lookup.
-- **The tag is written once.** `faq.tag` is what the template renders and
-  `faq.define` registers the class under it.
+- **The tag is written once.** `faq.tag` is what the template renders and what
+  `defineElement` registers the behaviour under. A contract stays inert either
+  way: it names things, and nothing in it touches a document, which is why
+  frontmatter can import it.
 - **The names are checked in the editor.** A tag without a hyphen, or a role
   that is not camelCase, is a compile error where it is written — the rules are
   types, character by character, as in `i18n/placeholders.ts`. Nothing is
   validated at run time, because a name that reached the browser malformed would
   already have been refused there: by `setAttribute`, by `querySelectorAll`, or
   by `customElements.define`.
+- **Most roles carry nothing**, and say so: `search: marker` rather than
+  `search: {}`, which reads like options somebody forgot to fill in.
 
-`tag` and `define` are the component's own keys, so no role may take them. A role
-that lives outside every instance, such as a footer button that reopens a
-banner, is still plain `markup`.
+`tag` is the component's own key, so no role may take it. A role that lives
+outside every instance, such as a footer button that reopens a banner, is still
+plain `markup`.
 
 ## `youtube`
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.19",
+    "version": "0.1.21",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,
@@ -17,6 +17,7 @@
         "./astro/images": "./src/astro/images.ts",
         "./astro/background-video": "./src/astro/background-video.ts",
         "./astro/carousel": "./src/astro/carousel.ts",
+        "./client": "./src/astro/client.ts",
         "./astro/consent": "./src/astro/consent.ts",
         "./astro/dev-log": "./src/astro/dev-log.ts",
         "./astro/dom": "./src/astro/dom.ts",

package/src/astro/client.ts

@@ -0,0 +1,23 @@
+/**
+ * Everything a client script needs, from one import.
+ *
+ * ```ts
+ * 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.
+ */
+
+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 * from "./filters.ts";
+export * from "./filters-view.ts";
+export * from "./markup.ts";
+export * from "./youtube.ts";

package/src/astro/element.ts

@@ -1,181 +1,112 @@
 import { reportDevError } from "./dev-log.ts";
-import { within } from "./dom.ts";
 
 /**
- * A base for custom elements: two lifetimes, and one abort signal.
+ * 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`.
+ */
+// biome-ignore lint/suspicious/noConfusingVoidType: that is the distinction.
+type Undo = void | (() => void);
+
+/**
+ * What an element does while it is on the page.
+ *
+ * `host` is the element itself and `signal` is aborted when it leaves, so
+ * anything registered with `signal` comes down on its own. Whatever else has to
+ * be undone is the returned function, which runs at the same moment.
+ */
+export type Connect = (host: HTMLElement, signal: AbortSignal) => Undo;
+
+/**
+ * Registers a custom element whose behaviour is one function.
  *
  * ```ts
- * class Thing extends AtlasElement {
- *     protected setup(): void { … }        // once, ever: what the element is
- *     protected connect(): void {          // every connection: bind with signal
- *         this.require("form").addEventListener("submit", send, {
- *             signal: this.signal,
- *         });
- *     }
- * }
- * customElements.define("atlas-thing", Thing);
+ * defineElement("atlas-thing", (host, signal) => {
+ *     host.querySelector("form")?.addEventListener("submit", send, { signal });
+ *     return loop.attach(host); // runs when the element leaves the page
+ * });
  * ```
  *
- * - **An element is constructed once and connected many times.** Moving it in
- *   the DOM runs `disconnectedCallback` then `connectedCallback` again, so
- *   state belongs in `setup` and listeners in `connect`. Anything registered
- *   with `signal` is dropped on disconnect and rebound on the next connect.
- * - **Override `setup`, `connect` and `disconnect`, never the callbacks.**
- *   Overriding `connectedCallback` skips the controller and leaks every
- *   listener; that mistake throws in development, below.
+ * - **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. State
+ *   that must survive a move belongs in a `WeakMap` keyed by `host`, as the
+ *   carousel example keeps its index.
  * - **The defining script must stay a deferred module.** Astro emits
- *   `<script src>` as `type="module"`, so the element has its children when it
- *   is upgraded. `is:inline` runs it too early and every lookup finds nothing.
- * - **`attributeChangedCallback` runs before `connectedCallback`**, where
- *   `signal` is not readable yet. Record what changed and act on it in
- *   `connect`.
- * - **`disconnect` is not a destructor.** A move fires it and connects again a
- *   moment later, so it is connection teardown and nothing else.
+ *   `<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 — which is what lets a lookup
+ *   like `require` throw and say what is missing.
  *
  * See docs/client-scripts.md.
  */
-export abstract class AtlasElement extends HTMLElement {
-    /**
-     * This connection's listeners, and only this connection's. Remade on every
-     * connect: an `AbortController` is single-use, and a reused one comes back
-     * already aborted, leaving the element inert but normal-looking.
-     */
-    #ac?: AbortController;
-
-    #ready = false;
-
-    constructor() {
-        super();
-        // The bare expression Vite substitutes, so this collapses to
-        // `if (false)` and the method below leaves the bundle.
-        if (import.meta.env.DEV) this.#assertHooks();
-    }
-
-    /**
-     * Refuses a subclass that overrode the wrong lifecycle method. An override
-     * is an *own* property of the subclass prototype; the loop covers an
-     * intermediate base class that got it wrong.
-     */
-    #assertHooks(): void {
-        // A tuple array, not an object: `Object.entries` would widen the keys
-        // back to `string` and stop checking the pairing.
-        const wrong = [
-            ["connectedCallback", "connect"],
-            ["disconnectedCallback", "disconnect"],
-        ] as const;
-
-        for (
-            let proto = Object.getPrototypeOf(this);
-            proto && proto !== AtlasElement.prototype;
-            proto = Object.getPrototypeOf(proto)
-        ) {
-            for (const [callback, hook] of wrong) {
-                if (Object.hasOwn(proto, callback)) {
-                    const error = new Error(
-                        `override "${hook}", not "${callback}" — see AtlasElement`
-                    );
-                    // Reported before throwing: this runs during upgrade, where
-                    // a throw would only surface as an uncaught console error.
-                    reportDevError(this.constructor.name, error);
-                    throw error;
+export function defineElement(tag: string, connect: Connect): void {
+    // The class is built in here rather than at module scope so `HTMLElement`
+    // is only read in a browser: `astro/markup` reaches this file, templates
+    // import it, and the build runs in Node.
+    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.
+             */
+            #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 {
+                    this.#undo = connect(this, ac.signal) ?? undefined;
+                } catch (error) {
+                    this.#report(error);
                 }
             }
-        }
-    }
-
-    /**
-     * Pass to `addEventListener`, observers, anything that should stop when the
-     * element leaves the document. Throws outside a connection.
-     */
-    protected get signal(): AbortSignal {
-        if (!this.#ac) {
-            throw new Error(
-                `${this.localName}: signal read outside a connection`
-            );
-        }
-        return this.#ac.signal;
-    }
-
-    connectedCallback(): void {
-        // Insurance: overwriting a live controller would orphan its listeners.
-        this.#ac?.abort();
-        this.#ac = new AbortController();
 
-        // Caught so one broken element logs and sits inert rather than taking
-        // its siblings with it — which is what lets `require` throw.
-        try {
-            if (!this.#ready) {
-                this.setup();
-                // Only once it returned, so a `setup` that threw is retried
-                // rather than leaving `connect` to run against nothing.
-                this.#ready = true;
+            disconnectedCallback(): void {
+                this.#end();
             }
-            this.connect();
-        } catch (error) {
-            this.#report(error);
-        }
-    }
-
-    disconnectedCallback(): void {
-        // Idempotent, so `adoptedCallback` can delegate here.
-        if (!this.#ac) return;
-        this.#ac.abort();
-
-        try {
-            // Before `#ac` is cleared, so `this.signal` is readable and already
-            // aborted: an async continuation can check it and bail.
-            this.disconnect();
-        } catch (error) {
-            this.#report(error);
-        }
-
-        this.#ac = undefined;
-    }
-
-    /** Moving to another document ends the old document's connection. */
-    adoptedCallback(): void {
-        this.disconnectedCallback();
-    }
-
-    #report(error: unknown): void {
-        if (import.meta.env.DEV) {
-            reportDevError(this.localName, error);
-            return;
-        }
-        console.error(`${this.localName}:`, error);
-    }
 
-    /** Runs once per element, before its first `connect`. State belongs here. */
-    protected setup(): void {}
-
-    /** Runs on every connect, with `signal` and the children both available. */
-    protected abstract connect(): void;
-
-    /** Runs on every disconnect, once the signal has been aborted. */
-    protected disconnect(): void {}
-
-    /** The first match inside this element, or `null`. */
-    protected one<T extends Element = HTMLElement>(selector: string): T | null {
-        return within(this).one<T>(selector);
-    }
+            /** Moving to another document ends the old document's visit. */
+            adoptedCallback(): void {
+                this.#end();
+            }
 
-    /** Every match inside this element, as an array. */
-    protected all<T extends Element = HTMLElement>(selector: string): T[] {
-        return within(this).all<T>(selector);
-    }
+            #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);
+                }
+            }
 
-    /**
-     * The first match, or a thrown error naming what was missing. Throws rather
-     * than returning `null`, because the `?.` at every call site swallows the
-     * failure as thoroughly as the missing element did.
-     */
-    protected require<T extends Element = HTMLElement>(selector: string): T {
-        const found = this.one<T>(selector);
-        if (!found) {
-            throw new Error(
-                `nothing matched "${selector}" — is the script still a deferred module?`
-            );
+            #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);
+            }
         }
-        return found;
-    }
+    );
 }

package/src/astro/markup.ts

@@ -123,6 +123,9 @@ type CheckedKeys<T> = {
  * - `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-…]`.
@@ -134,6 +137,11 @@ 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[]];
@@ -144,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" }
@@ -164,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> = {
@@ -281,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) {
@@ -331,6 +372,13 @@ 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
+                );
     }
 }
 
@@ -466,14 +514,13 @@ export function markup<
 /** A component's roles, by name: each is the fields of one `markup` role. */
 export type ComponentRoles = Readonly<Record<string, MarkupFields>>;
 
-/** Keys the component object uses itself, so no role may take them. */
-type Reserved = "tag" | "define";
+/** The key the component object uses itself, so no role may take it. */
+type Reserved = "tag";
 
 export type Component<Tag extends string, R extends ComponentRoles> = {
-    /** The custom element's name: what the template renders. */
+    /** The custom element's name: what the template renders, and what
+     * `defineElement` registers the behaviour under. */
     readonly tag: Tag;
-    /** Registers the element's class under `tag`. */
-    define(element: CustomElementConstructor): void;
 } & { readonly [K in keyof R]: Markup<R[K]> };
 
 /**
@@ -487,7 +534,7 @@ export type Component<Tag extends string, R extends ComponentRoles> = {
  * });
  *
  * // template: <faq.tag> … <details {...faq.row.attrs({ key, text })}>
- * // script:   faq.row.all(this); faq.define(Faq);
+ * // script:   defineElement(faq.tag, (host) => faq.row.all(host).forEach(…));
  * ```
  *
  * Two things `markup` alone leaves to the project:
@@ -531,9 +578,9 @@ export function component<
         name: string,
         fields: MarkupFields
     ): Markup<MarkupFields> => {
-        // 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") {
+        // 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`
             );
@@ -583,11 +630,7 @@ export function component<
         };
     };
 
-    const built: Record<string, unknown> = {
-        tag,
-        define: (element: CustomElementConstructor) =>
-            customElements.define(tag, element),
-    };
+    const built: Record<string, unknown> = { tag };
     for (const [name, fields] of Object.entries(roles)) {
         built[name] = scoped(name, fields);
     }