@escape-game-over/atlas 0.1.1 → 0.1.3

package/src/astro/element.ts

@@ -0,0 +1,259 @@
+import { reportDevError } from "./dev-log.ts";
+import { within } from "./dom.ts";
+
+/**
+ * A base for custom elements, holding the parts every one of them gets wrong.
+ *
+ * In `astro/` because it touches the DOM, which the core is type-checked
+ * without — this, `consent.ts`, `carousel.ts` and `dom.ts` are the folder
+ * allowed it.
+ *
+ * ```ts
+ * class Thing extends AtlasElement {
+ *     #count = 0;
+ *
+ *     protected setup(): void { … }        // once, ever
+ *     protected connect(): void {          // every time it enters the document
+ *         this.require("form").addEventListener("submit", this.#send, {
+ *             signal: this.signal,
+ *         });
+ *     }
+ * }
+ * customElements.define("atlas-thing", Thing);
+ * ```
+ *
+ * **Two lifetimes, and confusing them is the whole reason this class exists.**
+ * An element is constructed once and may be connected many times: moving it in
+ * the DOM runs `disconnectedCallback` then `connectedCallback` again. So
+ * `setup` is for what the element *is* — state, defaults, anything a reader
+ * would be annoyed to lose — and `connect` is for what a connection *owns* —
+ * listeners, timers, observers. Anything registered with `signal` is torn down
+ * on every disconnect and re-registered on every connect, so a re-entry rebinds
+ * rather than duplicating.
+ *
+ * **Subclasses implement `setup`, `connect` and `disconnect` — never
+ * `connectedCallback` or `disconnectedCallback`.** Overriding those replaces
+ * this class's, the controller is never created, and every listener leaks on
+ * each disconnect. `connect` is abstract, so forgetting it is a compile error;
+ * the adjacent mistake is caught at construction in development, below.
+ *
+ * **The script that defines a subclass must stay a deferred module.** Astro
+ * emits `<script>` and `<script src="./…">` as `type="module"`, which runs after
+ * the document is parsed, so an element has its children by the time it is
+ * upgraded. `is:inline` opts out and runs the script where it sits — usually
+ * above the element it wires — and every lookup then finds nothing. The
+ * protection comes from the bundling, not from custom elements.
+ *
+ * **`attributeChangedCallback` runs before `connectedCallback`** for attributes
+ * present in the initial markup, so `signal` is not available there and reading
+ * it throws. A subclass with `observedAttributes` should record what changed and
+ * act on it in `connect`.
+ *
+ * What is deliberately *not* modelled is destruction. `disconnect` fires on
+ * every move, so it is connection teardown and nothing else — it is not the
+ * place to flush state or release something genuinely scarce, because the
+ * element may well be back a microtask later.
+ */
+export abstract class AtlasElement extends HTMLElement {
+    /**
+     * Cancels this connection's listeners, and only this connection's.
+     *
+     * Remade on every connect rather than held in a field initializer, because
+     * an `AbortController` is single-use: a controller that outlived the first
+     * connection would come back already aborted, `addEventListener` with an
+     * aborted signal silently adds nothing, and the element would return looking
+     * perfectly normal and be inert forever.
+     */
+    #ac?: AbortController;
+
+    /** Whether `setup` has run. See the two-lifetimes note above. */
+    #ready = false;
+
+    constructor() {
+        super();
+        // Written as the bare expression Vite substitutes: `import.meta.env.DEV`
+        // is replaced with a literal, so this collapses to `if (false)` and the
+        // method below is dropped from the bundle. An optional chain would be
+        // replaced as `import.meta.env` instead — an object literal, whose
+        // `.DEV` a minifier has to fold rather than simply delete.
+        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, where the
+     * inherited one is not — so walking up to this class's prototype finds it.
+     * The loop rather than a single check, because an intermediate base class
+     * could be the one that got it wrong.
+     */
+    #assertHooks(): void {
+        // A tuple array rather than an object: `Object.entries` widens its keys
+        // back to `string`, so the pairing would stop being checked exactly
+        // where a typo would matter.
+        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, so
+                    // `connectedCallback`'s catch has not been entered and the
+                    // throw would surface only as an uncaught error in the
+                    // console — invisible, for the one mistake this whole
+                    // apparatus exists to catch.
+                    reportDevError(this.constructor.name, error);
+                    throw error;
+                }
+            }
+        }
+    }
+
+    /**
+     * Pass to `addEventListener`, observers, anything that should stop when the
+     * element leaves the document.
+     *
+     * Throws when read outside a connection, which is a programming error
+     * rather than a state to handle: there is nothing sensible to return.
+     */
+    protected get signal(): AbortSignal {
+        if (!this.#ac) {
+            throw new Error(
+                `${this.localName}: signal read outside a connection`
+            );
+        }
+        return this.#ac.signal;
+    }
+
+    connectedCallback(): void {
+        // Insurance. The spec pairs the callbacks, so this should never find a
+        // live controller — but if it ever did, overwriting one would orphan
+        // every listener it owned, silently, which is the failure this class
+        // exists to make impossible.
+        this.#ac?.abort();
+        this.#ac = new AbortController();
+
+        // Caught here so one broken element logs and sits inert rather than
+        // taking its siblings with it: the browser calls this once per element,
+        // so the blast radius is already one. That is what lets `require`
+        // throw instead of returning something every call site has to check.
+        try {
+            if (!this.#ready) {
+                this.setup();
+                // Only once it returned. Setting the flag first would mean a
+                // `setup` that threw was never retried, and the next connect
+                // would run `connect` against state that was never initialized
+                // — a component that renders perfectly and does nothing, which
+                // is the failure this class exists to make impossible.
+                this.#ready = true;
+            }
+            this.connect();
+        } catch (error) {
+            this.#report(error);
+        }
+    }
+
+    disconnectedCallback(): void {
+        // Idempotent, so `adoptedCallback` can delegate here without running a
+        // subclass's teardown twice.
+        if (!this.#ac) return;
+        this.#ac.abort();
+
+        // Caught for the same reason as `connect`, and it matters more: a
+        // throw here escapes into whatever is swapping the DOM — a router, a
+        // view transition — rather than staying in the component.
+        try {
+            // Before `#ac` is cleared, so `this.signal` is readable and already
+            // aborted: an async continuation can check `signal.aborted` and
+            // bail rather than finishing against a detached element.
+            this.disconnect();
+        } catch (error) {
+            this.#report(error);
+        }
+
+        this.#ac = undefined;
+    }
+
+    /**
+     * Fires when the element moves to another document.
+     *
+     * Delegates, because the controller belongs to the connection in the old
+     * document and nothing else would tear it down. Exotic — `adoptNode` and
+     * iframe work — and one line either way.
+     */
+    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`.
+     *
+     * Where state belongs. A move re-runs `connect` but never this, so anything
+     * initialised here survives one — which is the difference between a reader
+     * coming back to the slide they left and coming back to the first one.
+     */
+    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.
+     *
+     * `signal` is still readable here and reports `aborted` — which is what an
+     * async continuation should check before touching a now-detached element.
+     * What it is *not* is a destructor: a move fires this and then `connect`
+     * again a moment later, so it is connection teardown and nothing else.
+     * Flushing state or releasing something scarce does not belong here.
+     *
+     * Empty by default: anything registered with `signal` is already gone, and
+     * most elements have nothing else to undo.
+     */
+    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 `T | null`, because a nullable return puts an
+     * `?.` at every call site — and that optional chain swallows the failure
+     * just as thoroughly as the missing element did, which is the thing worth
+     * avoiding. `connectedCallback` catches it, so one element with broken
+     * markup logs and stops while every other element on the page is untouched.
+     */
+    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;
+    }
+}