@escape-game-over/atlas 0.1.22 → 0.1.23

package/docs/client-scripts.md

@@ -81,12 +81,15 @@ what it registered when the element leaves, and what it returns is the undo for
 everything else.
 
 ```ts
-defineElement("atlas-thing", (host, signal) => {
+defineElement(thing, (host, signal) => {
     host.addEventListener("click", open, { signal });   // ends with the visit
     return loop.attach(host);                           // and so does this
 });
 ```
 
+It takes the component rather than a tag name, so the element it registers and
+the roles it hands the function are the same contract the template spread.
+
 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
@@ -472,15 +475,15 @@ export const faq = component("go-faq", {
 ```
 
 ```astro
-<faq.tag>
+<faq.tag {...faq.root}>
     <input {...faq.search.attrs()} type="search">
     <details {...faq.row.attrs({ key, text })}>…</details>
 </faq.tag>
 ```
 
 ```ts
-defineElement(faq.tag, (host, signal) => {
-    for (const { element, values } of faq.row.all(host)) { … }
+defineElement(faq, (host, signal, { row }) => {
+    for (const { element, values } of row.all()) { … }
 });
 ```
 
@@ -494,8 +497,8 @@ defineElement(faq.tag, (host, signal) => {
   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 what
-  `defineElement` registers the behaviour under. A contract stays inert either
+- **The tag is written once.** `faq.tag` is what the template renders, and the
+  component itself is 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
@@ -507,9 +510,17 @@ defineElement(faq.tag, (host, signal) => {
 - **Most roles carry nothing**, and say so: `search: marker` rather than
   `search: {}`, which reads like options somebody forgot to fill in.
 
-`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`.
+- **The roles arrive bound to the instance.** `defineElement` takes the
+  component, so `all`, `one` and `require` need no root: there is no way to
+  write `faq.row.all(document)`, which compiles and returns the roles belonging
+  to no instance at all.
+- **The root says it is one.** `{...faq.root}` writes `data-atlas-root`, so a
+  project gives every root a display in one stylesheet rule rather than a class
+  per component. Forget it and the element says so on the dev server.
+
+`tag` and `root` 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`.
 
 ## `youtube`
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.22",
+    "version": "0.1.23",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,
@@ -59,9 +59,9 @@
     "devDependencies": {
         "@biomejs/biome": "2.5.13",
         "@types/node": "26.5.1",
-        "@vitest/coverage-istanbul": "5.0.0",
+        "@vitest/coverage-istanbul": "5.0.1",
         "astro": "7.3.2",
         "typescript": "6.0.3",
-        "vitest": "5.0.0"
+        "vitest": "5.0.1"
     }
 }

package/src/astro/element.ts

@@ -1,4 +1,6 @@
 import { reportDevError } from "./dev-log.ts";
+import type { Marked, Markup } from "./markup.ts";
+import { ROOT_ATTRIBUTE } from "./markup.ts";
 
 /**
  * What is left to undo when the element leaves, or nothing.
@@ -10,43 +12,87 @@ import { reportDevError } from "./dev-log.ts";
 // biome-ignore lint/suspicious/noConfusingVoidType: that is the distinction.
 type Undo = void | (() => void);
 
+/** One role's lookups, already pointed at the element they belong to. */
+type Bound<M> =
+    M extends Markup<infer F>
+        ? {
+              all<T extends Element = HTMLElement>(): Marked<T, F>[];
+              one<T extends Element = HTMLElement>(): Marked<T, F> | null;
+              require<T extends Element = HTMLElement>(): Marked<T, F>;
+          }
+        : never;
+
+/**
+ * Every role of a component, bound to one instance.
+ *
+ * The root is not a parameter here, which is the point: `faq.row.all(document)`
+ * compiles and quietly returns the roles that belong to *no* instance, and this
+ * removes the chance to write it.
+ */
+export type Roles<C> = {
+    readonly [K in Exclude<keyof C, "tag" | "root">]: Bound<C[K]>;
+};
+
 /**
  * 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.
+ * `host` is the element itself, `signal` is aborted when it leaves — so
+ * anything registered with `signal` comes down on its own — and `roles` are
+ * this instance's. Whatever else has to be undone is the returned function,
+ * which runs at the same moment.
  */
-export type Connect = (host: HTMLElement, signal: AbortSignal) => Undo;
+export type Connect<C> = (
+    host: HTMLElement,
+    signal: AbortSignal,
+    roles: Roles<C>
+) => Undo;
+
+/** The shape this file needs off a role, without importing its field types. */
+interface AnyRole {
+    all(root: ParentNode): unknown;
+    one(root: ParentNode): unknown;
+    require(root: ParentNode): unknown;
+}
 
 /**
- * Registers a custom element whose behaviour is one function.
+ * Registers a component's custom element, with its behaviour as one function.
  *
  * ```ts
- * defineElement("atlas-thing", (host, signal) => {
- *     host.querySelector("form")?.addEventListener("submit", send, { signal });
+ * export const faq = component("go-faq", { row: { key: { kind: "text" } } });
+ *
+ * defineElement(faq, (host, signal, { row }) => {
+ *     for (const { element, values } of row.all()) { … }
  *     return loop.attach(host); // runs when the element leaves the page
  * });
  * ```
  *
  * - **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.
+ *   and then `connect` again, so `connect` has to be able to run twice. Astro's
+ *   `ClientRouter` connects a persisted element three times per navigation.
+ *   State that must survive belongs in a `WeakMap` keyed by `host`.
  * - **The defining script must stay a deferred module.** Astro emits
  *   `<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.
+ *   rather than taking its siblings down with it.
  *
  * See docs/client-scripts.md.
  */
-export function defineElement(tag: string, connect: Connect): void {
+export function defineElement<C extends { readonly tag: string }>(
+    component: C,
+    connect: Connect<C>
+): void {
+    const { tag } = component;
+
+    // Read once: the roles are fixed when the component is built, and only the
+    // element they point at changes.
+    const roleNames = Object.keys(component).filter(
+        (key) => key !== "tag" && key !== "root"
+    );
+
     // 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.
+    // is only read in a browser.
     customElements.define(
         tag,
         class extends HTMLElement {
@@ -68,7 +114,16 @@ export function defineElement(tag: string, connect: Connect): void {
                 const ac = new AbortController();
                 this.#ac = ac;
                 try {
-                    this.#undo = connect(this, ac.signal) ?? undefined;
+                    if (
+                        import.meta.env.DEV &&
+                        !this.hasAttribute(ROOT_ATTRIBUTE)
+                    ) {
+                        throw new Error(
+                            `<${tag}> carries no ${ROOT_ATTRIBUTE} — does the template spread {...x.root} on it?`
+                        );
+                    }
+                    this.#undo =
+                        connect(this, ac.signal, this.#roles()) ?? undefined;
                 } catch (error) {
                     this.#report(error);
                 }
@@ -83,6 +138,22 @@ export function defineElement(tag: string, connect: Connect): void {
                 this.#end();
             }
 
+            /** This instance's roles: the component's, with the root supplied. */
+            #roles(): Roles<C> {
+                const bound: Record<string, unknown> = {};
+                for (const name of roleNames) {
+                    const role = (component as Record<string, unknown>)[
+                        name
+                    ] as AnyRole;
+                    bound[name] = {
+                        all: () => role.all(this),
+                        one: () => role.one(this),
+                        require: () => role.require(this),
+                    };
+                }
+                return bound as Roles<C>;
+            }
+
             #end(): void {
                 // Aborted before the undo runs, so an async continuation that
                 // checks the signal can see the visit is over.

package/src/astro/markup.ts

@@ -514,13 +514,28 @@ export function markup<
 /** A component's roles, by name: each is the fields of one `markup` role. */
 export type ComponentRoles = Readonly<Record<string, MarkupFields>>;
 
-/** The key the component object uses itself, so no role may take it. */
-type Reserved = "tag";
+/** The keys the component object uses itself, so no role may take them. */
+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 `defineElement` 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
      * `defineElement` 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]> };
 
 /**
@@ -533,8 +548,8 @@ export type Component<Tag extends string, R extends ComponentRoles> = {
  *     search: {},
  * });
  *
- * // template: <faq.tag> … <details {...faq.row.attrs({ key, text })}>
- * // script:   defineElement(faq.tag, (host) => faq.row.all(host).forEach(…));
+ * // template: <faq.tag {...faq.root}> … <details {...faq.row.attrs({ key, text })}>
+ * // script:   defineElement(faq, (host, signal, { row }) => row.all().forEach(…));
  * ```
  *
  * Two things `markup` alone leaves to the project:
@@ -630,7 +645,10 @@ export function component<
         };
     };
 
-    const built: Record<string, unknown> = { tag };
+    const built: Record<string, unknown> = {
+        tag,
+        root: { [ROOT_ATTRIBUTE]: "" },
+    };
     for (const [name, fields] of Object.entries(roles)) {
         built[name] = scoped(name, fields);
     }