@escape-game-over/atlas 0.1.19 → 0.1.20

package/docs/client-scripts.md

@@ -54,6 +54,13 @@ 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. It is browser-only — `element.ts` evaluates
+`class AtlasElement extends HTMLElement` as it loads, which throws in Node — so
+frontmatter and `astro.config.ts` cannot use it. 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
@@ -408,9 +415,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.
@@ -476,6 +498,8 @@ faq.define(Faq);
   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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.19",
+    "version": "0.1.20",
     "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 { AtlasElement, filters, searchBox } from "@escape-game-over/atlas/client";
+ * ```
+ *
+ * **Browser only.** `element.ts` evaluates `class AtlasElement extends
+ * HTMLElement` as this module loads, which throws in Node — so frontmatter and
+ * `astro.config.ts` must not import it. 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,5 +1,4 @@
 import { reportDevError } from "./dev-log.ts";
-import { within } from "./dom.ts";
 
 /**
  * A base for custom elements: two lifetimes, and one abort signal.
@@ -8,7 +7,7 @@ import { within } from "./dom.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, {
+ *         this.querySelector("form")?.addEventListener("submit", send, {
  *             signal: this.signal,
  *         });
  *     }
@@ -153,29 +152,4 @@ export abstract class AtlasElement extends HTMLElement {
 
     /** 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);
-    }
-
-    /** Every match inside this element, as an array. */
-    protected all<T extends Element = HTMLElement>(selector: string): T[] {
-        return within(this).all<T>(selector);
-    }
-
-    /**
-     * 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?`
-            );
-        }
-        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
+                );
     }
 }