@escape-game-over/atlas 0.1.25 → 0.1.26

package/src/astro/element.ts

@@ -1,105 +1,91 @@
 import { reportDevError } from "./dev-log.ts";
-import {
-    type CheckedKeys,
-    type CheckedTagName,
-    type Component,
-    type ComponentRoles,
-    component,
-    type Marked,
-    type MarkupFields,
-    type Reserved,
-    ROOT_ATTRIBUTE,
-} from "./markup.ts";
+
+/**
+ * What `AtlasElement` puts on every root: one name, so a project gives every
+ * root a display in a single stylesheet rule, and so `element` can say when a
+ * root was rendered by hand.
+ */
+export const ROOT_ATTRIBUTE = "data-atlas-root";
 
 /** What is left to undo when the element leaves; usually nothing. */
 // biome-ignore lint/suspicious/noConfusingVoidType: that is the distinction.
 type Undo = void | (() => void);
 
-/**
- * One role's lookups inside this instance. A role with no fields is found for
- * the element alone; one with fields comes back with its values read.
- */
-type Lookups<F extends MarkupFields> = [keyof F] extends [never]
-    ? {
-          all<T extends Element = HTMLElement>(): T[];
-          one<T extends Element = HTMLElement>(): T | null;
-          require<T extends Element = HTMLElement>(): T;
-      }
-    : {
-          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>;
-      };
-
-/** Every role of an element, bound to one instance. */
-export type ElementRoles<R extends ComponentRoles> = {
-    readonly [K in keyof R]: Lookups<R[K]>;
-};
+export interface ElementContext {
+    readonly host: HTMLElement;
+    /** Aborted when the element leaves, taking its listeners with it. */
+    readonly signal: AbortSignal;
+}
 
 /**
- * What an element does while it is on the page. `signal` is aborted when it
- * leaves, so listeners registered with it come down on their own; anything else
- * to undo is the returned function.
+ * What an element does while it is on the page. Anything `signal` does not
+ * already undo is the returned function.
  */
-export type Connect<R extends ComponentRoles> = (
-    host: HTMLElement,
-    roles: ElementRoles<R>,
-    signal: AbortSignal
-) => Undo;
+export type Connect = (context: ElementContext) => Undo;
+
+/** What a template renders the element from, with `AtlasElement`. */
+export interface ElementTag<Tag extends string = string> {
+    readonly tag: Tag;
+}
 
 /**
- * A custom element: its markup contract and its behaviour, in one call.
+ * A custom element's behaviour, registered under `tag`.
  *
  * ```ts
- * // faq.ts — imported by the template, and by the page's script
- * export const faq = element("go-faq", { row: { key: { kind: "text" } }, search: marker },
- *     (host, { row, search }, signal) => { … });
+ * // faq.ts — imported by the template for the tag, and by the page's script
+ * export const faq = element("go-faq", ({ host, signal }) => {
+ *     const input = ref<HTMLInputElement>(host, "[data-faq-search]");
+ *     …
+ * });
  * ```
  * ```astro
  * <script src="./faq.ts"></script>
+ * <AtlasElement of={faq}><input data-faq-search type="search"></AtlasElement>
  * ```
  *
  * Registers itself when loaded in a browser and does nothing in Node, so the
- * template imports the same file for the contract.
+ * template imports the same file.
  *
  * - **An element can enter the page more than once.** Moving it runs the undo
  *   and `connect` again; Astro's `ClientRouter` does so on every navigation.
  *   State that must survive belongs in a `WeakMap` keyed by `host`.
  * - **The page's script must stay a bundled module** (a plain `<script>`), so
  *   the element has its children when it upgrades.
- * - **A `connect` that throws leaves that one element inert** and reports it.
+ * - **Failures show in dev.** A `connect` that throws leaves that one element
+ *   inert, and it, or any uncaught error on the page, lands in the dev panel.
  * - **A tag defined twice keeps the first definition** and reports the second.
  */
-export function element<
-    const Tag extends string,
-    const R extends ComponentRoles &
-        CheckedKeys<R> & { readonly [K in Reserved]?: never },
->(
-    tag: Tag & CheckedTagName<Tag>,
-    roles: R,
-    connect: Connect<R>
-): Component<Tag, R> {
-    // Already checked by this function's own signature.
-    const contract = component(tag as never, roles) as Component<Tag, R>;
+export function element<const Tag extends string>(
+    tag: Tag,
+    connect: Connect
+): ElementTag<Tag> {
     if (typeof customElements !== "undefined") {
-        define(contract, roles, connect);
+        watchDevErrors();
+        // Defining upgrades elements already on the page synchronously; a
+        // microtask later, `const x = element(…)` is assigned first.
+        queueMicrotask(() => define(tag, connect));
     }
-    return contract;
+    return { tag };
 }
 
-/** The shape this file needs off a role, without its field types. */
-interface AnyRole {
-    all(root: ParentNode): Marked<Element, MarkupFields>[];
-    one(root: ParentNode): Marked<Element, MarkupFields> | null;
-    require(root: ParentNode): Marked<Element, MarkupFields>;
+let watching = false;
+
+/**
+ * Puts errors thrown outside `connect` — in a listener, after an `await` — in
+ * the dev panel too. Once per page load: the listeners outlive a body swap.
+ */
+function watchDevErrors(): void {
+    if (!import.meta.env.DEV || watching) return;
+    watching = true;
+    window.addEventListener("error", (event) => {
+        reportDevError("page", event.error ?? event.message);
+    });
+    window.addEventListener("unhandledrejection", (event) => {
+        reportDevError("page", event.reason);
+    });
 }
 
-function define<R extends ComponentRoles>(
-    contract: Component<string, R>,
-    roles: R,
-    connect: Connect<R>
-): void {
-    const { tag } = contract;
+function define(tag: string, connect: Connect): void {
     if (customElements.get(tag) !== undefined) {
         reportDevError(
             tag,
@@ -108,27 +94,6 @@ function define<R extends ComponentRoles>(
         return;
     }
 
-    const bind = (host: HTMLElement): ElementRoles<R> => {
-        const bound: Record<string, unknown> = {};
-        for (const [name, fields] of Object.entries(roles)) {
-            const role = (contract as unknown as Record<string, AnyRole>)[name];
-            if (role === undefined) continue;
-            bound[name] =
-                Object.keys(fields).length === 0
-                    ? {
-                          all: () => role.all(host).map((each) => each.element),
-                          one: () => role.one(host)?.element ?? null,
-                          require: () => role.require(host).element,
-                      }
-                    : {
-                          all: () => role.all(host),
-                          one: () => role.one(host),
-                          require: () => role.require(host),
-                      };
-        }
-        return bound as ElementRoles<R>;
-    };
-
     customElements.define(
         tag,
         class extends HTMLElement {
@@ -146,11 +111,11 @@ function define<R extends ComponentRoles>(
                         !this.hasAttribute(ROOT_ATTRIBUTE)
                     ) {
                         throw new Error(
-                            `<${tag}> carries no ${ROOT_ATTRIBUTE} — does the template spread {...x.root} on it?`
+                            `<${tag}> carries no ${ROOT_ATTRIBUTE} — is it rendered with <AtlasElement of={…}>?`
                         );
                     }
                     this.#undo =
-                        connect(this, bind(this), ac.signal) ?? undefined;
+                        connect({ host: this, signal: ac.signal }) ?? undefined;
                 } catch (error) {
                     reportDevError(this.localName, error);
                 }

package/src/astro/ref.ts

@@ -0,0 +1,46 @@
+/**
+ * Finding the elements a script works on, by a selector the template wrote as
+ * a plain attribute — `[data-faq-search]` — so what the script asks for is what
+ * devtools shows.
+ */
+
+/** Names the root in an error, for a selector that matched nothing. */
+const where = (root: ParentNode): string =>
+    "localName" in root && typeof root.localName === "string"
+        ? `<${root.localName}>`
+        : "the document";
+
+/**
+ * The first match under `root`, or a thrown error naming the selector. Inside
+ * `element`'s `connect`, that error lands in the dev panel.
+ */
+export function ref<T extends Element = HTMLElement>(
+    root: ParentNode,
+    selector: string
+): T {
+    const found = root.querySelector<T>(selector);
+    if (found === null) {
+        throw new Error(`${where(root)} has nothing matching ${selector}`);
+    }
+    return found;
+}
+
+/**
+ * An element's `data-<name>` value, or a thrown error naming the element and
+ * the attribute. For an optional one, read `dataset` directly.
+ */
+export function data(element: Element, name: string): string {
+    const value = element.getAttribute(`data-${name}`);
+    if (value === null) {
+        throw new Error(`<${element.localName}> has no data-${name}`);
+    }
+    return value;
+}
+
+/** Every match under `root`. None is an answer here, not an error. */
+export function refs<T extends Element = HTMLElement>(
+    root: ParentNode,
+    selector: string
+): T[] {
+    return [...root.querySelectorAll<T>(selector)];
+}