@adobe/ecs 0.0.0-stage → 0.1.0

package/src/samples/todo/app/proportional.browser.test.ts

@@ -0,0 +1,157 @@
+import { afterEach, expect, it } from "vitest";
+import { Entity, type World } from "../../../index.js";
+import { toggleAll } from "../features/completion/model.js";
+import { setFilter } from "../features/filter/model.js";
+import { addGenerated } from "../features/generate/model.js";
+import { TodoRow } from "../features/todos/elements/todo-row.js";
+import { addTodo, deleteTodo, editTodo, moveTodo, toggleTodo } from "../features/todos/model.js";
+import { entityOfElement } from "../shared/attach.js";
+import { nextTick, watchTicks } from "../shared/ticks.test-helper.js";
+import { createApp } from "./app.js";
+
+/**
+ * Each operation's work follows what it changed, whatever the list holds: both the DOM's mutations and how often the
+ * DOM systems reach rows, since elements drop equal writes and systems skip rows already right, which would hide a
+ * system that visits every row. `app/todo.perf-browser-test.ts` times them.
+ */
+
+const markup = `<todo-toggle-all></todo-toggle-all><todo-list></todo-list><todo-summary></todo-summary><todo-filters></todo-filters>`;
+
+afterEach(() => {
+    document.body.replaceChildren();
+});
+
+/** How often the DOM systems reached rows: the row properties they write, `hidden`, and what placing reads and calls. */
+let reaches = 0;
+
+/** Counts calls of an accessor's `kind` on `target`, until the returned function puts it back. */
+const countAccessor = (target: object, name: string, kind: "get" | "set"): (() => void) => {
+    const descriptor = Object.getOwnPropertyDescriptor(target, name);
+    const original = descriptor?.[kind];
+    if (descriptor === undefined || original === undefined) throw new Error(`No ${kind} ${name}.`);
+    Object.defineProperty(target, name, {
+        ...descriptor,
+        [kind]: function (this: unknown, ...values: unknown[]): unknown {
+            reaches += 1;
+            return Reflect.apply(original, this, values);
+        },
+    });
+    return () => Object.defineProperty(target, name, descriptor);
+};
+
+/** Counts calls of a method on `target`, until the returned function puts it back. */
+const countMethod = (target: object, name: string): (() => void) => {
+    const descriptor = Object.getOwnPropertyDescriptor(target, name);
+    const original: unknown = descriptor?.value;
+    if (descriptor === undefined || typeof original !== "function") throw new Error(`No method ${name}.`);
+    Object.defineProperty(target, name, {
+        ...descriptor,
+        value: function (this: unknown, ...values: unknown[]): unknown {
+            reaches += 1;
+            return Reflect.apply(original, this, values);
+        },
+    });
+    return () => Object.defineProperty(target, name, descriptor);
+};
+
+const countReaches = (): (() => void) => {
+    const restores = [
+        countAccessor(TodoRow.prototype, "label", "set"),
+        countAccessor(TodoRow.prototype, "done", "set"),
+        countAccessor(HTMLElement.prototype, "hidden", "get"),
+        countAccessor(HTMLElement.prototype, "hidden", "set"),
+        countAccessor(Element.prototype, "nextElementSibling", "get"),
+        countAccessor(Element.prototype, "firstElementChild", "get"),
+        countMethod(Element.prototype, "moveBefore"),
+        countMethod(Node.prototype, "insertBefore"),
+    ];
+    return () => {
+        for (const restore of restores) restore();
+    };
+};
+
+type Work = { readonly mutations: number; readonly reaches: number };
+
+/** The mutations of the page and its open shadow roots, and the rows reached, from `change` until the tick after it. */
+const workOf = async (change: () => Promise<number>): Promise<Work> => {
+    let mutations = 0;
+    const observer = new MutationObserver(records => {
+        mutations += records.length;
+    });
+    const options = { attributes: true, childList: true, characterData: true, subtree: true };
+    observer.observe(document.body, options);
+    for (const element of document.body.querySelectorAll("*")) if (element.shadowRoot !== null) observer.observe(element.shadowRoot, options);
+    reaches = 0;
+    await change();
+    await nextTick();
+    mutations += observer.takeRecords().length;
+    observer.disconnect();
+    return { mutations, reaches };
+};
+
+/** Work less `rows` mutations and `perRow` reaches for each of them. */
+const beyond = (work: Work, rows: number, perRow: number): Work => ({ mutations: work.mutations - rows, reaches: work.reaches - perRow * rows });
+
+/** Each operation's work, on an app holding `n` todos, every other one done. */
+const workWith = async (n: number): Promise<Record<string, Work>> => {
+    document.body.innerHTML = markup;
+    const app = createApp(document.body);
+    await watchTicks(app.world);
+    const { world } = app;
+    await world.run(addGenerated, { count: n });
+    await nextTick();
+    const listed = [...document.querySelectorAll("todo-row")].map(entityOfElement);
+    const at = (index: number): Entity => listed[(index + n) % n] ?? Entity.none;
+    for (let i = 0; i < n; i += 2) await world.run(toggleTodo, { entity: at(i) });
+    await nextTick();
+    const rows = (): HTMLElementTagNameMap["todo-row"][] => [...document.querySelectorAll("todo-row")];
+    const work: Record<string, Work> = {
+        "toggle one": await workOf(() => world.run(toggleTodo, { entity: at(1) })),
+        "edit one": await workOf(() => world.run(editTodo, { entity: at(3), label: "edited" })),
+        "move one": await workOf(() => world.run(moveTodo, { entity: at(-1), before: at(0) })),
+        "add one": await workOf(() => world.run(addTodo, { label: "added" })),
+        "delete one": await workOf(() => world.run(deleteTodo, { entity: at(5) })),
+    };
+    // A new filter passes every row, reading whether it's hidden, and writes those that change.
+    const filtered = await workOf(() => world.run(setFilter, { filter: "active" }));
+    const hidden = rows().filter(row => row.hidden).length;
+    work["filter, beyond each row read and each hidden"] = beyond({ mutations: filtered.mutations, reaches: filtered.reaches - rows().length }, hidden, 1);
+    await world.run(setFilter, { filter: "all" });
+    await nextTick();
+    // Each row marked done gets its label and done written and its visibility read.
+    const notDone = rows().filter(row => !row.done).length;
+    work["toggle all, beyond each row marked done"] = beyond(await workOf(() => world.run(toggleAll, { done: true })), notDone, 3);
+    await app.dispose();
+    return work;
+};
+
+it("does work in proportion to what changed, not to how many todos there are", async () => {
+    const restore = countReaches();
+    try {
+        const small = await workWith(100);
+        const large = await workWith(2000);
+        expect(large).toEqual(small);
+        expect(small).toEqual({
+            // The row's done attribute, and the summary's count; its label, done and visibility, and the summary's
+            // clear button, shown.
+            "toggle one": { mutations: 2, reaches: 4 },
+            // The row's label; its label and done.
+            "edit one": { mutations: 1, reaches: 2 },
+            // The row out of the list and in again; where it is, and the move.
+            "move one": { mutations: 2, reaches: 2 },
+            // The new row into the list, the tabindex and draggable it sets once connected, and the summary's count,
+            // its label being written in a shadow root made after the count began; its label, done, visibility, and
+            // where it goes, and its placing.
+            "add one": { mutations: 4, reaches: 5 },
+            // The row out of the list, and the summary's count.
+            "delete one": { mutations: 2, reaches: 0 },
+            // The filter buttons pressed and released.
+            "filter, beyond each row read and each hidden": { mutations: 2, reaches: 0 },
+            // The summary's count; its clear button.
+            "toggle all, beyond each row marked done": { mutations: 1, reaches: 1 },
+        });
+    }
+    finally {
+        restore();
+    }
+});

package/src/samples/todo/app/todo.perf-browser-test.ts

@@ -0,0 +1,207 @@
+import { it } from "vitest";
+import { Entity, Report, System, workers, World } from "../../../index.js";
+import { toggleAll } from "../features/completion/model.js";
+import { filter } from "../features/filter/data.js";
+import { setFilter } from "../features/filter/model.js";
+import { addGenerated } from "../features/generate/model.js";
+import { done } from "../features/todos/data.js";
+import { createRows, dom, list } from "../features/todos/dom.js";
+import { addTodo, editTodo, moveTodo, toggleTodo } from "../features/todos/model.js";
+import { entityOfElement } from "../shared/attach.js";
+import { nextTick, watchTicks } from "../shared/ticks.test-helper.js";
+import { createApp } from "./app.js";
+
+/**
+ * How the app's DOM path scales, with 1K and 10K todos: each operation's run is timed, the observer systems that run
+ * after it included, and then run once more with the DOM's mutations counted, those of the tick after it included.
+ * Numbers are logged, never asserted: `pnpm test:perf src/samples/todo`.
+ */
+
+const markup = `
+<header><todo-toggle-all></todo-toggle-all><todo-entry></todo-entry></header>
+<todo-list style="display: block; max-height: 600px"></todo-list>
+<footer><todo-summary></todo-summary><todo-filters></todo-filters></footer>`;
+
+const found = <K extends keyof HTMLElementTagNameMap>(name: K): HTMLElementTagNameMap[K] => {
+    const element = document.querySelector(name);
+    if (element === null) throw new Error(`No ${name}.`);
+    return element;
+};
+
+/** The mutations of the page and of every open shadow root on it that `change` makes, until the tick after it. */
+const mutationsOf = async (change: () => Promise<unknown>): Promise<number> => {
+    let count = 0;
+    const observer = new MutationObserver(records => {
+        count += records.length;
+    });
+    const options = { attributes: true, childList: true, characterData: true, subtree: true };
+    observer.observe(document.body, options);
+    for (const element of document.body.querySelectorAll("*")) if (element.shadowRoot !== null) observer.observe(element.shadowRoot, options);
+    await change();
+    await nextTick();
+    count += observer.takeRecords().length;
+    observer.disconnect();
+    return count;
+};
+
+/** Null where not measured. */
+type Result = { readonly operation: string; readonly n: number; readonly ms: number; readonly mutations: number | null; readonly tick: number | null };
+const results: Result[] = [];
+
+const median = (values: readonly number[]): number => [...values].sort((a, b) => a - b)[Math.floor(values.length / 2)] ?? NaN;
+
+/** When the last animation frame's callback began, which a tick runs in. */
+let frameStart = 0;
+const platformFrame = globalThis.requestAnimationFrame.bind(globalThis);
+globalThis.requestAnimationFrame = callback => platformFrame(time => {
+    frameStart = performance.now();
+    callback(time);
+});
+
+/**
+ * Runs `operation` `repeats` times, each timed and followed by the tick a run brings, timed from its frame's start to
+ * the end of its observer systems; then once more, counting its mutations.
+ */
+const measure = async (operation: string, n: number, repeats: number, run: (repeat: number) => Promise<number>, settle: () => void = () => {}): Promise<void> => {
+    const once = async (repeat: number): Promise<number> => {
+        const start = performance.now();
+        await run(repeat);
+        settle();
+        const ms = performance.now() - start;
+        // A failing run's report is spawned before its pass, which logs it.
+        if (failed.length > 0) throw new Error(`${operation} failed: ${JSON.stringify(failed)}`);
+        return ms;
+    };
+    const times: number[] = [];
+    const ticks: number[] = [];
+    for (let repeat = 0; repeat < repeats; repeat++) {
+        times.push(await once(repeat));
+        await nextTick();
+        ticks.push(performance.now() - frameStart);
+    }
+    const mutations = await mutationsOf(() => once(repeats));
+    results.push({ operation, n, ms: median(times), mutations, tick: median(ticks) });
+};
+
+const nothing = System.create({ name: "perf/nothing" }, () => {});
+
+/** The failures of every report the apps measured spawned, which none should. */
+const failed: Report.Failure[] = [];
+const collectFailures = System.create({ name: "perf/collectFailures", observer: true, components: { read: [Report.errors], changed: [Report.errors] } }, row => {
+    failed.push(...row[Report.errors].failures);
+});
+
+/**
+ * The todos in list order, read once, before anything's timed: indexing a list's `children` far from the last index
+ * read walks them.
+ */
+const listedTodos = (): readonly Entity[] => [...found("todo-list").children].map(entityOfElement);
+
+/** Forces the style and layout a change left, so their cost counts too. */
+const forceLayout = (): void => {
+    void document.body.offsetHeight;
+};
+
+/** Marks every other todo done, for filters to hide half the rows. */
+const halfDone = System.create({ name: "perf/halfDone", components: { write: [done] } }, item => {
+    item[done] = item.entity % 2 === 0;
+});
+
+const alternateFilter = (world: World) => (repeat: number) => world.run(setFilter, { filter: repeat % 2 === 0 ? "active" : "all" });
+
+/** A new app on the page holding `n` generated todos, with no rows yet: the tick that would make them hasn't come. */
+const generated = async (n: number): Promise<{ readonly app: ReturnType<typeof createApp>; readonly ms: number }> => {
+    document.body.innerHTML = markup;
+    const app = createApp(document.body);
+    app.world.add(collectFailures);
+    await watchTicks(app.world);
+    const start = performance.now();
+    await app.world.run(addGenerated, { count: n });
+    const ms = performance.now() - start;
+    if (found("todo-list").children.length > 0) throw new Error("A tick made the rows before they were timed.");
+    return { app, ms };
+};
+
+const benchmarkApp = async (n: number): Promise<void> => {
+    // Rows are created and placed by a run of the system the tick after a run would run, counted on another app.
+    const counted = await generated(n);
+    const createMutations = await mutationsOf(() => counted.app.world.run(createRows));
+    await counted.app.dispose();
+    const { app, ms: generateMs } = await generated(n);
+    const { world } = app;
+    const start = performance.now();
+    await world.run(createRows);
+    const created = performance.now();
+    forceLayout();
+    results.push({ operation: "generate N todos", n, ms: generateMs, mutations: null, tick: null });
+    results.push({ operation: "create and place N rows", n, ms: created - start, mutations: createMutations, tick: null });
+    results.push({ operation: "lay N rows out", n, ms: performance.now() - created, mutations: null, tick: null });
+    await nextTick();
+    await measure("add one, with its row", n, 11, async repeat => {
+        await world.run(addTodo, { label: `added ${repeat}` });
+        return world.run(createRows);
+    });
+    const listed = listedTodos();
+    const at = (index: number): Entity => listed[(index + listed.length) % listed.length] ?? Entity.none;
+    await measure("run that changes nothing", n, 21, () => world.run(nothing));
+    await measure("toggle one", n, 21, repeat => world.run(toggleTodo, { entity: at(repeat * 7) }));
+    await measure("edit one", n, 21, repeat => world.run(editTodo, { entity: at(repeat * 11), label: `edited ${repeat}` }));
+    // Each move rotates the list by one: after r of them, the last is the one r + 1 from the end, the first r from it.
+    await measure("move last to first", n, 21, repeat => world.run(moveTodo, { entity: at(-1 - repeat), before: at(-repeat) }));
+    await measure("toggle all", n, 4, repeat => world.run(toggleAll, { done: repeat % 2 === 0 }));
+    await world.run(halfDone);
+    await measure("filter half the rows", n, 20, alternateFilter(world));
+    await measure("filter half the rows, laid out", n, 20, alternateFilter(world), forceLayout);
+    await world.run(setFilter, { filter: "all" });
+    // The move by the DOM alone, outside the world, which leaves the rows out of list order: measured last.
+    const element = found("todo-list");
+    await measure("move last to first, the DOM alone", n, 21, () => {
+        const last = element.lastElementChild;
+        if (last !== null) element.prepend(last);
+        return world.run(nothing);
+    });
+    await app.dispose();
+    document.body.replaceChildren();
+};
+
+/** The filter not kept: an attribute of the list, which a style sheet selects rows by. */
+const markList = System.create({
+    name: "perf/markList",
+    observer: true,
+    resources: { read: [filter], changed: [filter], is: [list] },
+}, ({ resources }) => {
+    resources[list].dataset.filter = resources[filter];
+});
+
+const listStyle = `
+todo-list[data-filter="active"] > todo-row[done],
+todo-list[data-filter="completed"] > todo-row:not([done]) { display: none; }`;
+
+const benchmarkListFilter = async (n: number): Promise<void> => {
+    const style = document.createElement("style");
+    style.textContent = listStyle;
+    const element = document.createElement("todo-list");
+    element.style.display = "block";
+    element.style.maxHeight = "600px";
+    document.body.append(style, element);
+    await using world = World.create({ [workers]: 0, [list]: element });
+    await watchTicks(world);
+    for (const system of [dom, markList]) world.add(system);
+    await world.run(addGenerated, { count: n });
+    await world.run(createRows);
+    await world.run(halfDone);
+    forceLayout();
+    await nextTick();
+    await measure("filter half the rows by a list attribute (not kept)", n, 20, alternateFilter(world));
+    await measure("filter half the rows by a list attribute, laid out (not kept)", n, 20, alternateFilter(world), forceLayout);
+    document.body.replaceChildren();
+};
+
+it("measures the todo app's DOM path", async () => {
+    for (const n of [1000, 10000]) {
+        await benchmarkApp(n);
+        await benchmarkListFilter(n);
+    }
+    const cell = (value: number | null, digits = 0): string => value === null ? "—" : value.toFixed(digits);
+    console.log(["| Operation | N | Run ms | Tick after it, ms | DOM mutations |", "|---|---:|---:|---:|---:|", ...results.map(result => `| ${result.operation} | ${result.n} | ${result.ms.toFixed(3)} | ${cell(result.tick, 3)} | ${cell(result.mutations)} |`)].join("\n"));
+});

package/src/samples/todo/build.test.ts

@@ -0,0 +1,23 @@
+/// <reference types="node" />
+import { mkdtempSync, readFileSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterAll, expect, it } from "vitest";
+import { build, type Rollup } from "vite";
+
+const packageRoot = fileURLToPath(new URL("../../..", import.meta.url));
+const outDir = realpathSync(mkdtempSync(join(tmpdir(), "ecs-sample-")));
+afterAll(() => rmSync(outDir, { recursive: true, force: true }));
+
+it("the todo sample builds as an application that defines its elements", async () => {
+    const output = await build({
+        configFile: join(packageRoot, "vite.sample.config.ts"), root: join(packageRoot, "src/samples/todo"), logLevel: "silent",
+        build: { outDir, emptyOutDir: true },
+    });
+    const items = (Array.isArray(output) ? output : [output]).flatMap((result: Rollup.RollupOutput | Rollup.RollupWatcher) => "output" in result ? result.output : []);
+    expect(items.some(item => item.fileName === "index.html")).toBe(true);
+    const code = items.flatMap(item => item.type === "chunk" ? [item.code] : []).join("\n");
+    for (const name of ["todo-row", "todo-list", "todo-entry", "todo-filters", "todo-summary", "todo-toggle-all", "todo-generate"]) expect(code).toMatch(new RegExp(`["'\`]${name}["'\`]`));
+    expect(readFileSync(join(outDir, "index.html"), "utf8")).toContain("<todo-list>");
+}, 30000);

package/src/samples/todo/features/completion/data.ts

@@ -0,0 +1,5 @@
+import { Index } from "../../../../index.js";
+import { done, todo } from "../todos/data.js";
+
+/** Todos by whether they're done: its lists' lengths are the counts, kept as todos change. */
+export const byDone = Index.create({ name: "completion/byDone", key: [done], components: { has: [todo] } });

package/src/samples/todo/features/completion/dom.browser.test.ts

@@ -0,0 +1,53 @@
+import { afterEach, expect, it } from "vitest";
+import { Entity, workers, World } from "../../../../index.js";
+import { entityOfElement } from "../../shared/attach.js";
+import { settled, watchTicks } from "../../shared/ticks.test-helper.js";
+import * as todos from "../todos/dom.js";
+import { TodoList } from "../todos/elements/todo-list.js";
+import { TodoRow } from "../todos/elements/todo-row.js";
+import { addTodo, deleteTodo, editTodo, toggleTodo } from "../todos/model.js";
+import { dom, summary, toggleAllBox } from "./dom.js";
+import { TodoSummary } from "./elements/todo-summary.js";
+import { TodoToggleAll } from "./elements/todo-toggle-all.js";
+import { clearCompleted, toggleAll } from "./model.js";
+import { define } from "../../shared/elements/define.js";
+
+define({ "todo-list": TodoList, "todo-row": TodoRow, "todo-summary": TodoSummary, "todo-toggle-all": TodoToggleAll });
+
+afterEach(() => {
+    document.body.replaceChildren();
+});
+
+it("shows the counts and whether all are done, and clears the rows of todos done", async () => {
+    const list = document.createElement("todo-list");
+    const count = document.createElement("todo-summary");
+    const box = document.createElement("todo-toggle-all");
+    document.body.append(box, list, count);
+    await using world = World.create({ [workers]: 0, [todos.list]: list, [summary]: count, [toggleAllBox]: box });
+    await watchTicks(world);
+    for (const system of [todos.dom, dom]) world.add(system);
+    const state = (): string => `${count.remaining} left, ${count.completed} done, ${box.empty ? "empty" : box.checked ? "all done" : "some left"}, ${list.children.length} rows`;
+    await settled(world.run(clearCompleted));
+    expect(state()).toBe("0 left, 0 done, empty, 0 rows");
+
+    for (const text of ["a", "b"]) await world.run(addTodo, { label: text });
+    await settled(world.run(addTodo, { label: "c" }));
+    expect(state()).toBe("3 left, 0 done, some left, 3 rows");
+    const entityAt = (index: number) => {
+        const row = list.children[index];
+        const entity = entityOfElement(row ?? null);
+        if (entity === Entity.none) throw new Error(`No row ${index}.`);
+        return entity;
+    };
+    await settled(world.run(toggleTodo, { entity: entityAt(0) }));
+    expect(state()).toBe("2 left, 1 done, some left, 3 rows");
+    await settled(world.run(toggleAll, { done: true }));
+    expect(state()).toBe("0 left, 3 done, all done, 3 rows");
+    await settled(world.run(toggleTodo, { entity: entityAt(1) }));
+    await settled(world.run(editTodo, { entity: entityAt(1), label: "B" }));
+    expect(state()).toBe("1 left, 2 done, some left, 3 rows");
+    await settled(world.run(clearCompleted));
+    expect(state()).toBe("1 left, 0 done, some left, 1 rows");
+    await settled(world.run(deleteTodo, { entity: entityAt(0) }));
+    expect(state()).toBe("0 left, 0 done, empty, 0 rows");
+});

package/src/samples/todo/features/completion/dom.ts

@@ -0,0 +1,39 @@
+import { Resource, System } from "../../../../index.js";
+import { byDone } from "./data.js";
+import { TodoSummary } from "./elements/todo-summary.js";
+import { TodoToggleAll } from "./elements/todo-toggle-all.js";
+
+/** The page's summary and toggle-all checkbox; null until the page provides them. */
+export const summary = Symbol("summary");
+export const toggleAllBox = Symbol("toggleAllBox");
+
+declare module "@adobe/ecs" {
+    interface Resources {
+        [summary]: { type: TodoSummary | null; thread: "main" };
+        [toggleAllBox]: { type: TodoToggleAll | null; thread: "main" };
+    }
+}
+
+Resource.register(summary, { thread: "main" });
+Resource.register(toggleAllBox, { thread: "main" });
+
+/**
+ * Writes the counts, read off the index's lists, and whether all are done, after a pass in which a todo was added,
+ * removed or toggled: the index's entries changing is its only change filter.
+ */
+export const bindCompletion = System.create({
+    name: "completion/bindCompletion",
+    observer: true,
+    resources: { is: [summary, toggleAllBox] },
+    lookup: { byDone: { index: byDone, changed: true } },
+}, ({ resources, lookup }) => {
+    const remaining = lookup.byDone(false).length;
+    const completed = lookup.byDone(true).length;
+    resources[summary].remaining = remaining;
+    resources[summary].completed = completed;
+    resources[toggleAllBox].checked = remaining === 0 && completed > 0;
+    resources[toggleAllBox].empty = remaining + completed === 0;
+});
+
+/** The completion feature's DOM systems, as one composite: added, it runs on every tick. */
+export const dom = System.create([bindCompletion]);

package/src/samples/todo/features/completion/elements/elements.browser.test.ts

@@ -0,0 +1,68 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { part, record } from "../../../shared/elements/elements.test-helper.js";
+import { TodoSummary } from "./todo-summary.js";
+import { TodoToggleAll } from "./todo-toggle-all.js";
+import { define } from "../../../shared/elements/define.js";
+
+define({ "todo-summary": TodoSummary, "todo-toggle-all": TodoToggleAll });
+
+afterEach(() => {
+    document.body.replaceChildren();
+});
+
+describe("todo-summary", () => {
+    it("shows what's left, and the clear button only while some are done; empty while there are none", () => {
+        const summary = document.createElement("todo-summary");
+        document.body.append(summary);
+        const count = part(summary, ".count", HTMLElement);
+        const clear = part(summary, ".clear", HTMLButtonElement);
+        expect(summary.hasAttribute("empty")).toBe(true);
+        expect(count.textContent).toBe("0 items left");
+        expect(clear.hidden).toBe(true);
+        summary.remaining = 1;
+        expect(summary.hasAttribute("empty")).toBe(false);
+        expect(count.textContent).toBe("1 item left");
+        summary.completed = 2;
+        expect(clear.hidden).toBe(false);
+        summary.remaining = 0;
+        expect(summary.hasAttribute("empty")).toBe(false);
+        summary.completed = 0;
+        expect(summary.hasAttribute("empty")).toBe(true);
+        expect(clear.hidden).toBe(true);
+    });
+
+    it("dispatches todo-clear-completed", () => {
+        const summary = document.createElement("todo-summary");
+        document.body.append(summary);
+        summary.completed = 1;
+        const seen = record(document.body, "todo-clear-completed");
+        part(summary, ".clear", HTMLButtonElement).click();
+        expect(seen).toEqual([{ type: "todo-clear-completed", detail: null, target: summary }]);
+    });
+});
+
+describe("todo-toggle-all", () => {
+    it("is empty until told otherwise, and checked as told", () => {
+        const toggleAll = document.createElement("todo-toggle-all");
+        document.body.append(toggleAll);
+        expect(toggleAll.hasAttribute("empty")).toBe(true);
+        toggleAll.empty = false;
+        toggleAll.checked = true;
+        expect(toggleAll.hasAttribute("empty")).toBe(false);
+        expect(part(toggleAll, "input", HTMLInputElement).checked).toBe(true);
+    });
+
+    it("dispatches todo-toggle-all with the state clicked, keeping the state it was given", () => {
+        const toggleAll = document.createElement("todo-toggle-all");
+        document.body.append(toggleAll);
+        const seen = record(document.body, "todo-toggle-all");
+        const input = part(toggleAll, "input", HTMLInputElement);
+        input.click();
+        expect(seen).toEqual([{ type: "todo-toggle-all", detail: { done: true }, target: toggleAll }]);
+        expect(input.checked).toBe(false);
+        toggleAll.checked = true;
+        input.click();
+        expect(seen[1]?.detail).toEqual({ done: false });
+        expect(input.checked).toBe(true);
+    });
+});

package/src/samples/todo/features/completion/elements/todo-summary.ts

@@ -0,0 +1,82 @@
+/**
+ * `<todo-summary>`: how many todos are left, and the button that clears those done, shown only while some are.
+ * Properties `remaining` and `completed` drive it; `empty`, reflected as an attribute, is set while both are 0. The
+ * button dispatches `todo-clear-completed`.
+ */
+
+const template = document.createElement("template");
+template.innerHTML = `
+<style>
+    :host { display: contents; }
+    .count { white-space: nowrap; }
+    button { font: inherit; padding: 2px 8px; border: 0; background: none; color: inherit; cursor: pointer; }
+    button:hover { text-decoration: underline; }
+    [hidden] { display: none; }
+</style>
+<span class="count"></span>
+<button class="clear" hidden>Clear completed</button>`;
+
+export type TodoSummaryEvents = {
+    readonly "todo-clear-completed": CustomEvent<null>;
+};
+
+type Parts = { readonly count: HTMLElement; readonly clear: HTMLButtonElement };
+
+const partsOf = (root: ShadowRoot): Parts => {
+    const count = root.querySelector(".count");
+    const clear = root.querySelector(".clear");
+    if (!(count instanceof HTMLElement) || !(clear instanceof HTMLButtonElement)) throw new Error("todo-summary's template is missing a part.");
+    return { count, clear };
+};
+
+const remainingText = (remaining: number): string => `${remaining} ${remaining === 1 ? "item" : "items"} left`;
+
+export class TodoSummary extends HTMLElement {
+    readonly #parts: Parts;
+    #remaining = 0;
+    #completed = 0;
+
+    constructor() {
+        super();
+        const root = this.attachShadow({ mode: "open" });
+        root.append(template.content.cloneNode(true));
+        this.#parts = partsOf(root);
+        this.#parts.count.textContent = remainingText(0);
+        this.#parts.clear.addEventListener("click", () => {
+            this.dispatchEvent(new CustomEvent("todo-clear-completed", { detail: null, bubbles: true, composed: true }));
+        });
+    }
+
+    connectedCallback(): void {
+        this.toggleAttribute("empty", this.#remaining + this.#completed === 0);
+    }
+
+    get remaining(): number {
+        return this.#remaining;
+    }
+
+    set remaining(value: number) {
+        if (value === this.#remaining) return;
+        this.#remaining = value;
+        this.#parts.count.textContent = remainingText(value);
+        this.toggleAttribute("empty", value + this.#completed === 0);
+    }
+
+    get completed(): number {
+        return this.#completed;
+    }
+
+    set completed(value: number) {
+        if (value === this.#completed) return;
+        this.#completed = value;
+        this.#parts.clear.hidden = value === 0;
+        this.toggleAttribute("empty", this.#remaining + value === 0);
+    }
+}
+
+declare global {
+    interface HTMLElementTagNameMap {
+        "todo-summary": TodoSummary;
+    }
+    interface HTMLElementEventMap extends TodoSummaryEvents {}
+}