@loadbare/app 0.4.0

package/dist/tests/expand.test.js

@@ -0,0 +1,226 @@
+/**
+ * Expansion — see docs/expansion.md and docs/testing.md, tier 1.
+ *
+ * Definitions are written inline here because `expand` takes them as a map
+ * and a two-line definition beside its assertion reads better than a file
+ * reference. The cases that genuinely need files — the checks `loadDefinitions`
+ * runs, and directory ordering — use tests/fixtures/definitions.
+ */
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { fileURLToPath } from "node:url";
+import { JSDOM } from "jsdom";
+import { expand, loadDefinitions } from "../build/expand";
+const FIXTURES = fileURLToPath(new URL("./fixtures/definitions", import.meta.url));
+/**
+ * Read expansion's output as a tree.
+ *
+ * Used where the claim is about the document rather than about the text —
+ * which elements exist, which attributes an element has. Matching a
+ * serialization would test the serializer.
+ */
+function parseHtml(html) {
+    const holder = new JSDOM("").window.document.createElement("div");
+    holder.innerHTML = html;
+    return holder;
+}
+/** Definitions are keyed by the uppercased tag they define. */
+function defs(entries) {
+    const map = {};
+    for (const [tag, source] of Object.entries(entries)) {
+        map[tag.toUpperCase()] = source;
+    }
+    return map;
+}
+// --- Rejections ----------------------------------------------------------
+//
+// Expansion runs before any request exists, so every one of these is a build
+// that must not produce output. Each asserts on the message as well as the
+// throw: an author reads the message, and it is the whole of the diagnosis.
+describe("expansion rejects", () => {
+    it("a hub tag with no definition", () => {
+        assert.throws(() => expand(`<lb-nope></lb-nope>`, defs({})), /<lb-nope> has no definition/);
+    });
+    it("a parameter the definition never declared", () => {
+        assert.throws(() => expand(`<lb-thing exp-label="Name"></lb-thing>`, defs({ "lb-thing": `<div></div>` })), /given exp-label, but its definition has no \{\{label\}\}/);
+    });
+    it("a placeholder no tag could supply", async () => {
+        await assert.rejects(() => loadDefinitions([`${FIXTURES}/camel`]), /declares \{\{inputClass\}\}.*Write \{\{input-class\}\}/s);
+    });
+    it("a cycle in the definition graph", async () => {
+        await assert.rejects(() => loadDefinitions([`${FIXTURES}/cycle`]), /cycle in the definition graph/);
+    });
+    it("two destinations with one name", () => {
+        assert.throws(() => expand(`<lb-thing></lb-thing>`, defs({
+            "lb-thing": `<table><thead lb-template="head"></thead><tfoot lb-template="head"></tfoot></table>`,
+        })), /declares two lb-template="head" destinations/);
+    });
+    it("two templates for one destination", () => {
+        assert.throws(() => expand(`<lb-thing>` +
+            `<template lb-template="head"><tr></tr></template>` +
+            `<template lb-template="head"><tr></tr></template>` +
+            `</lb-thing>`, defs({
+            "lb-thing": `<table><thead lb-template="head"></thead></table>`,
+        })), /was given two templates for 'head'/);
+    });
+    it("a template naming a destination the definition does not have", () => {
+        assert.throws(() => expand(`<lb-thing><template lb-template="foot"><tr></tr></template></lb-thing>`, defs({
+            "lb-thing": `<table><thead lb-template="head"></thead></table>`,
+        })), /has no destination by that name/);
+    });
+    it("content written into a definition with no slot", () => {
+        assert.throws(() => expand(`<lb-thing><p>hello</p></lb-thing>`, defs({ "lb-thing": `<div></div>` })), /content was written inside <lb-thing>, whose definition has no lb-slot/);
+    });
+    it("a definition declaring more than one slot", () => {
+        assert.throws(() => expand(`<lb-thing></lb-thing>`, defs({
+            "lb-thing": `<div lb-slot></div><span lb-slot></span>`,
+        })), /declares more than one lb-slot/);
+    });
+});
+// --- Substitution --------------------------------------------------------
+describe("substitution", () => {
+    it("fills an attribute and a text node", () => {
+        const html = expand(`<lb-thing exp-label="Name" exp-name="who"></lb-thing>`, defs({
+            "lb-thing": `<label>{{label}}<input name="{{name}}" /></label>`,
+        }));
+        assert.match(html, /<label>Name<input name="who"><\/label>/);
+    });
+    it("drops an attribute whose placeholder was not supplied", () => {
+        // Presence propagates: an unsupplied placeholder must not emit
+        // readonly="", which HTML reads as readonly.
+        const html = expand(`<lb-thing></lb-thing>`, defs({ "lb-thing": `<input readonly="{{readonly}}" />` }));
+        assert.match(html, /<input>/);
+        assert.doesNotMatch(html, /readonly/);
+    });
+    it("keeps the whitespace around a text placeholder", () => {
+        // "{{label}} <input>" has to keep separating the label from the control.
+        const html = expand(`<lb-thing exp-label="Name"></lb-thing>`, defs({ "lb-thing": `<label>{{label}} <input /></label>` }));
+        assert.match(html, /<label>Name <input><\/label>/);
+    });
+    it("fills an unsupplied text placeholder with nothing", () => {
+        const html = expand(`<lb-thing></lb-thing>`, defs({ "lb-thing": `<label>{{label}}</label>` }));
+        assert.match(html, /<label><\/label>/);
+    });
+    it("reaches placeholders inside template content", () => {
+        // lb-picker ships a row template of its own, so {{key}} written inside
+        // one has to be a placeholder rather than literal text that ships.
+        const html = expand(`<lb-thing exp-key="id" exp-cell="name"></lb-thing>`, defs({
+            "lb-thing": `<select><template lb-key="{{key}}"><option lb-cell="{{cell}}"></option></template></select>`,
+        }));
+        assert.match(html, /<template lb-key="id">/);
+        assert.match(html, /<option lb-cell="name">/);
+    });
+    it("leaves a partial placeholder alone", () => {
+        // A placeholder is an entire attribute value or an entire text node.
+        const html = expand(`<lb-thing></lb-thing>`, defs({ "lb-thing": `<label title="a {{label}} b"></label>` }));
+        assert.match(html, /title="a \{\{label\}\} b"/);
+    });
+    it("refuses a parameter for a partial placeholder", () => {
+        // The consequence of the rule above, and the reason it is safe: a name
+        // that is not a placeholder is a name the definition never declared, so
+        // supplying it is the same error as supplying a name that is not there
+        // at all. The author is told rather than shipped literal braces.
+        assert.throws(() => expand(`<lb-thing exp-label="Name"></lb-thing>`, defs({ "lb-thing": `<label title="a {{label}} b"></label>` })), /has no \{\{label\}\}/);
+    });
+    it("keeps the exp- attributes on the expanded tag", () => {
+        // What ships shows what was asked for beside what it produced.
+        const html = expand(`<lb-thing exp-label="Name"></lb-thing>`, defs({ "lb-thing": `<label>{{label}}</label>` }));
+        assert.match(html, /<lb-thing exp-label="Name">/);
+    });
+    it("cannot inject markup, by construction", () => {
+        // Substitution goes through setAttribute and node values, never through a
+        // string. This test exists to fail if anyone reaches for concatenation.
+        //
+        // The assertion reparses rather than matching the serialization, because
+        // the serialization is not the claim. An expanded tag keeps the exp-
+        // attributes it was given, and `<` in an attribute value is legal HTML
+        // that no serializer has to escape — so the output does contain the
+        // characters. What must not exist is an element.
+        const html = expand(`<lb-thing exp-label="<img src=x onerror=alert(1)>" exp-name="&quot; onclick=&quot;alert(1)"></lb-thing>`, defs({
+            "lb-thing": `<label>{{label}}<input name="{{name}}" /></label>`,
+        }));
+        const tree = parseHtml(html);
+        assert.equal(tree.querySelectorAll("img").length, 0);
+        assert.equal(tree.querySelector("label").textContent, "<img src=x onerror=alert(1)>");
+        // The second value closes an attribute and opens an event handler, if it
+        // is ever concatenated. Through setAttribute it is one attribute's value.
+        const input = tree.querySelector("input");
+        assert.deepEqual([...input.attributes].map((a) => a.name), ["name"]);
+        assert.equal(input.getAttribute("name"), `" onclick="alert(1)`);
+    });
+});
+// --- Slots and destinations ---------------------------------------------
+describe("placement", () => {
+    it("puts authored content in the slot and removes the marker", () => {
+        const html = expand(`<lb-list><p>hello</p></lb-list>`, defs({ "lb-list": `<div lb-slot></div>` }));
+        assert.match(html, /<div><p>hello<\/p><\/div>/);
+        assert.doesNotMatch(html, /lb-slot/);
+    });
+    it("unwraps a named template into its destination as real markup", () => {
+        // The wrapper existed only to survive the parser. What ships is a real
+        // <tr> in a real <thead>, visible in view-source like everything else.
+        const html = expand(`<lb-table>` +
+            `<template lb-template="head"><tr><th>Name</th></tr></template>` +
+            `<template lb-key="id"><tr><td lb-cell="name"></td></tr></template>` +
+            `</lb-table>`, defs({
+            "lb-table": `<table><thead lb-template="head"></thead><tbody lb-slot></tbody></table>`,
+        }));
+        assert.match(html, /<thead><tr><th>Name<\/th><\/tr><\/thead>/);
+        assert.match(html, /<tbody><template lb-key="id">/);
+        assert.doesNotMatch(html, /lb-template/);
+    });
+    it("does not count whitespace as content", () => {
+        // An author who writes only named templates still leaves the newlines
+        // between them, and those are the file's formatting.
+        const html = expand(`<lb-thing>\n  \n</lb-thing>`, defs({ "lb-thing": `<div></div>` }));
+        assert.match(html, /<lb-thing><div><\/div><\/lb-thing>/);
+    });
+    it("expands a widget used inside a definition", () => {
+        const html = expand(`<lb-outer></lb-outer>`, defs({
+            "lb-outer": `<div><lb-inner exp-label="deep"></lb-inner></div>`,
+            "lb-inner": `<span>{{label}}</span>`,
+        }));
+        assert.match(html, /<span>deep<\/span>/);
+    });
+    it("expands a widget written inside a page's row template", () => {
+        // Template content is markup in a file like any other, and it is inert,
+        // so a row template ships already expanded.
+        const html = expand(`<lb-list><template lb-key="id"><lb-inner exp-label="row"></lb-inner></template></lb-list>`, defs({
+            "lb-list": `<div lb-slot></div>`,
+            "lb-inner": `<span>{{label}}</span>`,
+        }));
+        assert.match(html, /<span>row<\/span>/);
+    });
+    it("expands a tag outside the lb- namespace when it has a definition", () => {
+        // An application's widget can use its own prefix — see docs/getting-started.md.
+        // The definition must still apply; discovering it is not enough.
+        const html = expand(`<app-nav exp-label="Site"></app-nav>`, defs({ "app-nav": `<nav aria-label="{{label}}" lb-slot></nav>` }));
+        assert.match(html, /<nav aria-label="Site"><\/nav>/);
+    });
+    it("leaves a tag outside the lb- namespace alone when it has no definition", () => {
+        // A plain custom element, registered by script alone — see build/elements.ts.
+        const html = expand(`<app-box>hi</app-box>`, defs({}));
+        assert.match(html, /<app-box>hi<\/app-box>/);
+    });
+});
+// --- Loading -------------------------------------------------------------
+describe("loadDefinitions", () => {
+    it("keys a definition by the tag its filename names", async () => {
+        const loaded = await loadDefinitions([`${FIXTURES}/base`]);
+        assert.deepEqual(Object.keys(loaded), ["LB-THING"]);
+    });
+    it("lets a later directory override a built-in", async () => {
+        const loaded = await loadDefinitions([
+            `${FIXTURES}/base`,
+            `${FIXTURES}/override`,
+        ]);
+        assert.match(loaded["LB-THING"], /application/);
+    });
+    it("skips a directory that is not there", async () => {
+        const loaded = await loadDefinitions([
+            `${FIXTURES}/nothing-here`,
+            `${FIXTURES}/base`,
+        ]);
+        assert.deepEqual(Object.keys(loaded), ["LB-THING"]);
+    });
+});

package/dist/tests/fixtures/elements/collision/elements.d.ts

@@ -0,0 +1,5 @@
+declare const _default: {
+    "acme-widget": string;
+};
+export default _default;
+//# sourceMappingURL=elements.d.ts.map

package/dist/tests/fixtures/elements/collision/elements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elements.d.ts","sourceRoot":"","sources":["../../../../../tests/fixtures/elements/collision/elements.ts"],"names":[],"mappings":";;;AAAA,wBAEE"}

package/dist/tests/fixtures/elements/collision/elements.js

@@ -0,0 +1,3 @@
+export default {
+    "acme-widget": "@acme/widget",
+};

package/dist/tests/fixtures/elements/collision/widgets/acme-widget.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=acme-widget.d.ts.map

package/dist/tests/fixtures/elements/collision/widgets/acme-widget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acme-widget.d.ts","sourceRoot":"","sources":["../../../../../../tests/fixtures/elements/collision/widgets/acme-widget.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC"}

package/dist/tests/fixtures/elements/collision/widgets/acme-widget.js

@@ -0,0 +1 @@
+export {};

package/dist/tests/fixtures/elements/local/widgets/app-box.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=app-box.d.ts.map

package/dist/tests/fixtures/elements/local/widgets/app-box.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-box.d.ts","sourceRoot":"","sources":["../../../../../../tests/fixtures/elements/local/widgets/app-box.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC"}

package/dist/tests/fixtures/elements/local/widgets/app-box.js

@@ -0,0 +1 @@
+export {};

package/dist/tests/fixtures/elements/manifest/elements.d.ts

@@ -0,0 +1,5 @@
+declare const _default: {
+    "acme-widget": string;
+};
+export default _default;
+//# sourceMappingURL=elements.d.ts.map

package/dist/tests/fixtures/elements/manifest/elements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elements.d.ts","sourceRoot":"","sources":["../../../../../tests/fixtures/elements/manifest/elements.ts"],"names":[],"mappings":";;;AAAA,wBAEE"}

package/dist/tests/fixtures/elements/manifest/elements.js

@@ -0,0 +1,3 @@
+export default {
+    "acme-widget": "@acme/widget",
+};

package/dist/tests/fixtures/elements/manifest-bad-tag/elements.d.ts

@@ -0,0 +1,5 @@
+declare const _default: {
+    acmewidget: string;
+};
+export default _default;
+//# sourceMappingURL=elements.d.ts.map

package/dist/tests/fixtures/elements/manifest-bad-tag/elements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elements.d.ts","sourceRoot":"","sources":["../../../../../tests/fixtures/elements/manifest-bad-tag/elements.ts"],"names":[],"mappings":";;;AAAA,wBAEE"}

package/dist/tests/fixtures/elements/manifest-bad-tag/elements.js

@@ -0,0 +1,3 @@
+export default {
+    acmewidget: "@acme/widget",
+};

package/dist/tests/fixtures/elements/manifest-bad-value/elements.d.ts

@@ -0,0 +1,5 @@
+declare const _default: {
+    "acme-widget": number;
+};
+export default _default;
+//# sourceMappingURL=elements.d.ts.map

package/dist/tests/fixtures/elements/manifest-bad-value/elements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elements.d.ts","sourceRoot":"","sources":["../../../../../tests/fixtures/elements/manifest-bad-value/elements.ts"],"names":[],"mappings":";;;AAAA,wBAEE"}

package/dist/tests/fixtures/elements/manifest-bad-value/elements.js

@@ -0,0 +1,3 @@
+export default {
+    "acme-widget": 42,
+};

package/dist/tests/golden.test.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Golden files — see docs/testing.md, tier 1.
+ *
+ * Every page in demo/pages is expanded against the real definition
+ * directories and compared to a stored copy of its output. Ten cheap tests
+ * that cover the whole chain at once, including the directory ordering that
+ * lets an application override a built-in widget.
+ *
+ * The stored copy is formatted, because a golden file nobody can read is a
+ * diff nobody reviews. Formatting is cosmetic and may decline (see
+ * build/format.ts); if it does, the comparison is still exact — both sides
+ * went through the same function.
+ *
+ *     npm run test:golden      rewrite the stored copies
+ *
+ * Rewriting is not blessing. The diff is the point.
+ */
+export {};
+//# sourceMappingURL=golden.test.d.ts.map

package/dist/tests/golden.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"golden.test.d.ts","sourceRoot":"","sources":["../../tests/golden.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG"}

package/dist/tests/golden.test.js

@@ -0,0 +1,60 @@
+/**
+ * Golden files — see docs/testing.md, tier 1.
+ *
+ * Every page in demo/pages is expanded against the real definition
+ * directories and compared to a stored copy of its output. Ten cheap tests
+ * that cover the whole chain at once, including the directory ordering that
+ * lets an application override a built-in widget.
+ *
+ * The stored copy is formatted, because a golden file nobody can read is a
+ * diff nobody reviews. Formatting is cosmetic and may decline (see
+ * build/format.ts); if it does, the comparison is still exact — both sides
+ * went through the same function.
+ *
+ *     npm run test:golden      rewrite the stored copies
+ *
+ * Rewriting is not blessing. The diff is the point.
+ */
+import assert from "node:assert/strict";
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import { describe, it } from "node:test";
+import { fileURLToPath } from "node:url";
+import { expand, loadDefinitions } from "../build/expand";
+import { formatHtml } from "../build/format";
+const PAGES = fileURLToPath(new URL("../demo/pages", import.meta.url));
+const GOLDEN = fileURLToPath(new URL("./golden", import.meta.url));
+/** Built-in widgets first, then the demo's, exactly as demo/shell.ts orders them. */
+const DEFINITION_DIRS = [
+    fileURLToPath(new URL("../widgets", import.meta.url)),
+    fileURLToPath(new URL("../demo/widgets", import.meta.url)),
+];
+const rewrite = process.env.UPDATE_GOLDEN === "1";
+const PAGE_SUFFIX = ".page.html";
+const defs = await loadDefinitions(DEFINITION_DIRS);
+const names = (await readdir(PAGES))
+    .filter((name) => name.endsWith(PAGE_SUFFIX))
+    .map((name) => name.slice(0, -PAGE_SUFFIX.length))
+    .sort();
+describe("the demo pages expand to what they expanded to before", () => {
+    assert.ok(names.length > 0, "no demo pages found to expand");
+    for (const name of names) {
+        it(name, async () => {
+            const authored = await readFile(`${PAGES}/${name}${PAGE_SUFFIX}`, "utf-8");
+            const expanded = await formatHtml(expand(authored, defs));
+            const file = `${GOLDEN}/${name}.html`;
+            if (rewrite) {
+                await writeFile(file, expanded);
+                return;
+            }
+            let stored;
+            try {
+                stored = await readFile(file, "utf-8");
+            }
+            catch {
+                assert.fail(`no golden file for '${name}'. Review the expansion, then run ` +
+                    `npm run test:golden to store it.`);
+            }
+            assert.equal(expanded, stored);
+        });
+    }
+});

package/dist/tests/helpers/console.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The console is an interface — see docs/testing.md.
+ *
+ * Loadbare App reports what it survives through `console.warn` and `console.error`:
+ * a page that does not exist, a query with no scope, a list widget with no
+ * template. The behavior under test in those cases is that Loadbare App reported and
+ * carried on, so the report is as much the assertion as the return value is.
+ *
+ * This is the seam until those calls go through one `report()` in `core/`.
+ */
+type Line = string;
+export interface Captured<T> {
+    result: T;
+    warn: Line[];
+    error: Line[];
+}
+/** Run something with the console collected rather than printed. */
+export declare function captured<T>(run: () => T | Promise<T>): Promise<Captured<T>>;
+export {};
+//# sourceMappingURL=console.d.ts.map

package/dist/tests/helpers/console.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console.d.ts","sourceRoot":"","sources":["../../../tests/helpers/console.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,KAAK,IAAI,GAAG,MAAM,CAAC;AAEnB,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,MAAM,EAAE,CAAC,CAAC;IACV,IAAI,EAAE,IAAI,EAAE,CAAC;IACb,KAAK,EAAE,IAAI,EAAE,CAAC;CACf;AAED,oEAAoE;AACpE,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,GAAG,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACxB,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAgBtB"}

package/dist/tests/helpers/console.js

@@ -0,0 +1,28 @@
+/**
+ * The console is an interface — see docs/testing.md.
+ *
+ * Loadbare App reports what it survives through `console.warn` and `console.error`:
+ * a page that does not exist, a query with no scope, a list widget with no
+ * template. The behavior under test in those cases is that Loadbare App reported and
+ * carried on, so the report is as much the assertion as the return value is.
+ *
+ * This is the seam until those calls go through one `report()` in `core/`.
+ */
+/** Run something with the console collected rather than printed. */
+export async function captured(run) {
+    const warn = [];
+    const error = [];
+    const realWarn = console.warn;
+    const realError = console.error;
+    // Arguments are joined the way the console would show them, so a test can
+    // match one string against the message an author would read.
+    console.warn = (...args) => void warn.push(args.join(" "));
+    console.error = (...args) => void error.push(args.join(" "));
+    try {
+        return { result: await run(), warn, error };
+    }
+    finally {
+        console.warn = realWarn;
+        console.error = realError;
+    }
+}

package/dist/tests/helpers/dom.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A document for tier 3 — see docs/testing.md.
+ *
+ * The landing code touches nothing global: it is handed a root and calls
+ * `matches`, `querySelectorAll`, `cloneNode` and `setAttribute` on it. So a
+ * test needs a parsed tree and nothing else — no globals installed, no
+ * custom elements registered, no window on the loose between test files.
+ *
+ * Markup is parsed as the body of a document rather than into a detached
+ * `<div>`, because the parser's content models are half of what this code
+ * exists to work around: a `<tr>` assigned to a div's innerHTML is discarded,
+ * and a test that lost its rows would be testing the parser.
+ */
+/** Parse markup and hand back the body holding it. */
+export declare function body(html: string): HTMLElement;
+/** Parse markup and hand back its first element. */
+export declare function one(html: string): Element;
+//# sourceMappingURL=dom.d.ts.map

package/dist/tests/helpers/dom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../../../tests/helpers/dom.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,sDAAsD;AACtD,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAE9C;AAED,oDAAoD;AACpD,wBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzC"}

package/dist/tests/helpers/dom.js

@@ -0,0 +1,22 @@
+/**
+ * A document for tier 3 — see docs/testing.md.
+ *
+ * The landing code touches nothing global: it is handed a root and calls
+ * `matches`, `querySelectorAll`, `cloneNode` and `setAttribute` on it. So a
+ * test needs a parsed tree and nothing else — no globals installed, no
+ * custom elements registered, no window on the loose between test files.
+ *
+ * Markup is parsed as the body of a document rather than into a detached
+ * `<div>`, because the parser's content models are half of what this code
+ * exists to work around: a `<tr>` assigned to a div's innerHTML is discarded,
+ * and a test that lost its rows would be testing the parser.
+ */
+import { JSDOM } from "jsdom";
+/** Parse markup and hand back the body holding it. */
+export function body(html) {
+    return new JSDOM(`<!doctype html><body>${html}</body>`).window.document.body;
+}
+/** Parse markup and hand back its first element. */
+export function one(html) {
+    return body(html).firstElementChild;
+}

package/dist/tests/helpers/window.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A window for the widget half of tier 4 — see docs/testing.md.
+ *
+ * Tier 3 needed no globals: the landing code is handed a root and calls
+ * methods on it. A widget is the opposite. It extends `HTMLElement`, it
+ * registers itself with `customElements` when its module loads, and it
+ * reaches `document` to build the scaffolding it owns. So the window has to
+ * exist before the module does, which is why widget modules are imported
+ * dynamically, after `installWindow()` has run:
+ *
+ *     installWindow();
+ *     await import("../widgets/index");
+ *
+ * One window per test file, which is what node:test gives us for free by
+ * running each file in its own process. Registration is global and permanent,
+ * so sharing a process across widget files would mean sharing a registry.
+ *
+ * What this buys is real upgrades: a widget's constructor, its
+ * connectedCallback, and attributeChangedCallback for attributes already
+ * present. That is most of what a widget is, and it is the same in jsdom as
+ * in a browser. What it does not buy is layout, painting, or navigation —
+ * which is why the hub is tested in a browser instead.
+ */
+import type { HubRequest } from "../../core/lb-types";
+export declare function installWindow(): void;
+/**
+ * Put markup in the document and hand back the first element of it.
+ *
+ * Connected, because a widget that is not in the document has not upgraded,
+ * and half of what is under test happens on upgrade.
+ */
+export declare function mount(html: string): Element;
+/**
+ * Collect the requests a widget dispatches.
+ *
+ * Listening on the body rather than on the widget, because a request that
+ * does not bubble never reaches the hub — the hub is an ancestor, and that
+ * is the whole delivery mechanism.
+ */
+export declare function requests(): HubRequest[];
+/** Fire the event a control fires when a person uses it. */
+export declare function change(el: Element): void;
+//# sourceMappingURL=window.d.ts.map

package/dist/tests/helpers/window.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"window.d.ts","sourceRoot":"","sources":["../../../tests/helpers/window.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAoBtD,wBAAgB,aAAa,IAAI,IAAI,CASpC;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAG3C;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,IAAI,UAAU,EAAE,CAMvC;AAED,4DAA4D;AAC5D,wBAAgB,MAAM,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAExC"}

package/dist/tests/helpers/window.js

@@ -0,0 +1,78 @@
+/**
+ * A window for the widget half of tier 4 — see docs/testing.md.
+ *
+ * Tier 3 needed no globals: the landing code is handed a root and calls
+ * methods on it. A widget is the opposite. It extends `HTMLElement`, it
+ * registers itself with `customElements` when its module loads, and it
+ * reaches `document` to build the scaffolding it owns. So the window has to
+ * exist before the module does, which is why widget modules are imported
+ * dynamically, after `installWindow()` has run:
+ *
+ *     installWindow();
+ *     await import("../widgets/index");
+ *
+ * One window per test file, which is what node:test gives us for free by
+ * running each file in its own process. Registration is global and permanent,
+ * so sharing a process across widget files would mean sharing a registry.
+ *
+ * What this buys is real upgrades: a widget's constructor, its
+ * connectedCallback, and attributeChangedCallback for attributes already
+ * present. That is most of what a widget is, and it is the same in jsdom as
+ * in a browser. What it does not buy is layout, painting, or navigation —
+ * which is why the hub is tested in a browser instead.
+ */
+import { JSDOM } from "jsdom";
+import { LB_EVENT_NAME } from "../../core/lb-constants";
+/** The globals a widget module reaches for as it loads and runs. */
+const GLOBALS = [
+    "window",
+    "document",
+    "customElements",
+    "HTMLElement",
+    "HTMLTemplateElement",
+    "HTMLSelectElement",
+    "HTMLOptGroupElement",
+    "HTMLOptionElement",
+    "Element",
+    "Node",
+    "Event",
+    "CustomEvent",
+    "MouseEvent",
+    "DocumentFragment",
+];
+export function installWindow() {
+    const { window } = new JSDOM(`<!doctype html><body></body>`, {
+        url: "http://localhost/",
+    });
+    for (const name of GLOBALS) {
+        globalThis[name] = window[name];
+    }
+}
+/**
+ * Put markup in the document and hand back the first element of it.
+ *
+ * Connected, because a widget that is not in the document has not upgraded,
+ * and half of what is under test happens on upgrade.
+ */
+export function mount(html) {
+    document.body.innerHTML = html;
+    return document.body.firstElementChild;
+}
+/**
+ * Collect the requests a widget dispatches.
+ *
+ * Listening on the body rather than on the widget, because a request that
+ * does not bubble never reaches the hub — the hub is an ancestor, and that
+ * is the whole delivery mechanism.
+ */
+export function requests() {
+    const seen = [];
+    document.body.addEventListener(LB_EVENT_NAME, (e) => {
+        seen.push(e.detail);
+    });
+    return seen;
+}
+/** Fire the event a control fires when a person uses it. */
+export function change(el) {
+    el.dispatchEvent(new Event("change", { bubbles: true }));
+}

package/dist/tests/lb-apply.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Landing data on a live host — see docs/testing.md, tier 3.
+ *
+ * hub/lb-apply.ts is pure DOM: no fetch, no widget upgrade, no history.
+ * jsdom is real evidence for it, which is not true one file further on.
+ */
+export {};
+//# sourceMappingURL=lb-apply.test.d.ts.map

package/dist/tests/lb-apply.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lb-apply.test.d.ts","sourceRoot":"","sources":["../../tests/lb-apply.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}