@escape-game-over/atlas 0.1.18 → 0.1.19

package/docs/client-scripts.md

@@ -470,6 +470,12 @@ faq.define(Faq);
   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
   `faq.define` registers the class under it.
+- **The names are checked in the editor.** A tag without a hyphen, or a role
+  that is not camelCase, is a compile error where it is written — the rules are
+  types, character by character, as in `i18n/placeholders.ts`. Nothing is
+  validated at run time, because a name that reached the browser malformed would
+  already have been refused there: by `setAttribute`, by `querySelectorAll`, or
+  by `customElements.define`.
 
 `tag` and `define` 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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.18",
+    "version": "0.1.19",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,

package/src/astro/dom.ts

@@ -1,40 +1,20 @@
 /**
- * Scoped element lookups, without the ceremony.
- *
- * `querySelector` returns `Element`, so anything that wants to set `hidden`,
- * read `dataset` or call `focus` has to say `<HTMLElement>` at every call — long
- * enough that the line wraps, on lookups that are otherwise trivial. And
- * `querySelectorAll` returns a `NodeList`, which needs spreading before it will
- * `map` or `entries`. Both are noise, and both hide the one thing worth reading:
- * what is being looked for.
+ * Scoped element lookups, typed.
  *
  * ```ts
  * const { one, all } = within(root);
- * const track = one("[data-carousel-track]");
  * const dots = all<HTMLButtonElement>("[data-carousel-dot]");
  * ```
  *
- * The root is bound once, which is the point: a client script that looks
- * everything up inside the element it was given cannot reach a second copy of
- * itself elsewhere on the page. `document` is a valid root, and should appear
- * exactly once per script — to find the roots.
+ * The root is bound once, so a script cannot reach a second copy of itself
+ * elsewhere on the page. `document` belongs in one place per script: finding
+ * the roots.
  *
  * **A selector with a combinator still matches against the whole document.**
- * `within(form).one("form p")` can match a `<p>` whose ancestor `<form>` is not
- * the one bound here; only the final filter is scoped. Simple selectors — an
- * attribute, a class — are unaffected, which is what these are for. Use
- * `:scope` if a combinator is ever genuinely needed.
+ * `within(form).one("form p")` can match a `<p>` under a different form; only
+ * the final filter is scoped. Use `:scope` if a combinator is needed.
  */
 
-/**
- * Constrained to `Element` but defaulting to `HTMLElement`.
- *
- * The default is what almost every lookup wants — `hidden`, `dataset` and
- * `focus` all live on `HTMLElement`, and having to name it at each call is the
- * noise this exists to remove. The wider constraint is for the rest: inline
- * `<svg>` and `<use>` are `SVGElement`, which is an `Element` and not an
- * `HTMLElement`, so a narrower bound would refuse a perfectly ordinary lookup.
- */
 export interface Within {
     /** The first match inside the root, or `null`. */
     one<T extends Element = HTMLElement>(selector: string): T | null;
@@ -42,6 +22,8 @@ export interface Within {
     all<T extends Element = HTMLElement>(selector: string): T[];
 }
 
+// `HTMLElement` by default because `hidden`, `dataset` and `focus` live there;
+// the bound stays `Element` so inline `<svg>` lookups are not refused.
 export function within(root: ParentNode): Within {
     return {
         one: <T extends Element = HTMLElement>(selector: string) =>

package/src/astro/element.ts

@@ -2,19 +2,13 @@ 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.
+ * A base for custom elements: two lifetimes, and one abort signal.
  *
  * ```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, {
+ *     protected setup(): void { … }        // once, ever: what the element is
+ *     protected connect(): void {          // every connection: bind with signal
+ *         this.require("form").addEventListener("submit", send, {
  *             signal: this.signal,
  *         });
  *     }
@@ -22,75 +16,49 @@ import { within } from "./dom.ts";
  * 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.
+ * - **An element is constructed once and connected many times.** Moving it in
+ *   the DOM runs `disconnectedCallback` then `connectedCallback` again, so
+ *   state belongs in `setup` and listeners in `connect`. Anything registered
+ *   with `signal` is dropped on disconnect and rebound on the next connect.
+ * - **Override `setup`, `connect` and `disconnect`, never the callbacks.**
+ *   Overriding `connectedCallback` skips the controller and leaks every
+ *   listener; that mistake throws in development, below.
+ * - **The defining script must stay a deferred module.** Astro emits
+ *   `<script src>` as `type="module"`, so the element has its children when it
+ *   is upgraded. `is:inline` runs it too early and every lookup finds nothing.
+ * - **`attributeChangedCallback` runs before `connectedCallback`**, where
+ *   `signal` is not readable yet. Record what changed and act on it in
+ *   `connect`.
+ * - **`disconnect` is not a destructor.** A move fires it and connects again a
+ *   moment later, so it is connection teardown and nothing else.
  *
- * **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.
+ * See docs/client-scripts.md.
  */
 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.
+     * This connection's listeners, and only this connection's. Remade on every
+     * connect: an `AbortController` is single-use, and a reused one comes back
+     * already aborted, leaving the element inert but normal-looking.
      */
     #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.
+        // The bare expression Vite substitutes, so this collapses to
+        // `if (false)` and the method below leaves the bundle.
         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.
+     * Refuses a subclass that overrode the wrong lifecycle method. An override
+     * is an *own* property of the subclass prototype; the loop covers an
+     * intermediate base class 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.
+        // A tuple array, not an object: `Object.entries` would widen the keys
+        // back to `string` and stop checking the pairing.
         const wrong = [
             ["connectedCallback", "connect"],
             ["disconnectedCallback", "disconnect"],
@@ -106,11 +74,8 @@ export abstract class AtlasElement extends HTMLElement {
                     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.
+                    // Reported before throwing: this runs during upgrade, where
+                    // a throw would only surface as an uncaught console error.
                     reportDevError(this.constructor.name, error);
                     throw error;
                 }
@@ -120,10 +85,7 @@ export abstract class AtlasElement extends HTMLElement {
 
     /**
      * 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.
+     * element leaves the document. Throws outside a connection.
      */
     protected get signal(): AbortSignal {
         if (!this.#ac) {
@@ -135,25 +97,17 @@ export abstract class AtlasElement extends HTMLElement {
     }
 
     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.
+        // Insurance: overwriting a live controller would orphan its listeners.
         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.
+        // Caught so one broken element logs and sits inert rather than taking
+        // its siblings with it — which is what lets `require` throw.
         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.
+                // Only once it returned, so a `setup` that threw is retried
+                // rather than leaving `connect` to run against nothing.
                 this.#ready = true;
             }
             this.connect();
@@ -163,18 +117,13 @@ export abstract class AtlasElement extends HTMLElement {
     }
 
     disconnectedCallback(): void {
-        // Idempotent, so `adoptedCallback` can delegate here without running a
-        // subclass's teardown twice.
+        // Idempotent, so `adoptedCallback` can delegate here.
         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.
+            // aborted: an async continuation can check it and bail.
             this.disconnect();
         } catch (error) {
             this.#report(error);
@@ -183,13 +132,7 @@ export abstract class AtlasElement extends HTMLElement {
         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.
-     */
+    /** Moving to another document ends the old document's connection. */
     adoptedCallback(): void {
         this.disconnectedCallback();
     }
@@ -202,30 +145,13 @@ export abstract class AtlasElement extends HTMLElement {
         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.
-     */
+    /** Runs once per element, before its first `connect`. State belongs here. */
     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.
-     */
+    /** Runs on every disconnect, once the signal has been aborted. */
     protected disconnect(): void {}
 
     /** The first match inside this element, or `null`. */
@@ -239,13 +165,9 @@ export abstract class AtlasElement extends HTMLElement {
     }
 
     /**
-     * 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.
+     * The first match, or a thrown error naming what was missing. Throws rather
+     * than returning `null`, because the `?.` at every call site swallows the
+     * failure as thoroughly as the missing element did.
      */
     protected require<T extends Element = HTMLElement>(selector: string): T {
         const found = this.one<T>(selector);

package/src/astro/filters-view.ts

@@ -1,120 +1,63 @@
 /**
- * The DOM writes every filtered list turns out to make, and only those.
+ * The two DOM writes every filtered list turned out to share.
  *
- * `filters` decides which items match and what the address bar says, and hands
- * both to `onChange`. Everything a page does about that answer is its own — and
- * mostly stays that way: three lists in one repository draw their results three
- * different ways, with tabs and a blurb on one, an exclusive `<details>`
- * accordion on another, a two-level country roll-up on the third.
+ * `filters` decides which items match; what a page does about that is its own.
+ * These are the parts three lists wrote identically, and getting wrong was
+ * silent. Both take elements, never selectors, so no attribute name in this
+ * package has to be matched by a consumer.
  *
- * These two helpers are what all three, or two of three, wrote identically. That
- * is the whole bar for being here: not "a list might want this" but "every list
- * we have written already did, character for character, and getting it wrong was
- * silent". Anything the three disagreed about is still theirs.
+ * They write only what is binary and derived — an input's `value`, and `hidden`
+ * on a clear button, an empty message or a section with nothing left. No class,
+ * style or `aria`: that is where the choices live.
  *
- * **Both take elements, never selectors.** A project decides what its markup is
- * called and hands over what it found, so no attribute name in this package has
- * to be matched by any consumer — the reason `filters` itself has no markup
- * contract, kept intact one layer up.
+ * Two notes for the markup:
  *
- * These write to elements, which the rest of `astro/` refuses to do, and the
- * line is worth being exact about. `carousel` will not write a transform because
- * a transform is a design decision with no single right answer. Everything
- * written here is the opposite: an input's `value` is the control's own state,
- * and `hidden` on a clear button, an empty message or a section with nothing
- * left in it is binary and derived. Nothing here sets a class, a style or an
- * `aria` attribute, which is where the choices live.
+ * - **`hidden` needs help in a grid.** Any author rule setting `display` beats
+ *   it. Tailwind v4's preflight ships `[hidden] { display: none !important }`;
+ *   without something like it these writes are inert and nothing filters.
+ * - **A result count wants `aria-live="polite"`**, in the template.
  *
- * Two notes for the markup on the other side of that boundary:
- *
- * - **`hidden` needs help in a grid.** It is a `display: none` from the user
- *   agent, and any author rule setting `display: flex` or `grid` beats it. A
- *   project on Tailwind v4 gets `[hidden] { display: none !important }` from
- *   preflight and needs nothing; anything else should ship that rule itself, or
- *   every one of these writes is inert and the list simply never filters.
- * - **A result count wants `aria-live="polite"`.** Filtering as you type changes
- *   the page silently for anyone not looking at it. The attribute belongs on the
- *   element in the template, not here — this package is handed elements and does
- *   not decide what they are.
+ * See docs/client-scripts.md.
  */
 
 import type { FieldMap, Filters } from "./filters.ts";
 
-/**
- * The fields of `F` that hold text, so a search box cannot be pointed at a flag.
- *
- * `list.set(field, input.value)` hands over a string; aimed at a `flag` that is
- * a type error worth getting at the call site rather than a filter that silently
- * never matches.
- */
+/** The `text` fields of `F`, so a search box cannot be pointed at a flag. */
 export type TextFieldOf<F extends FieldMap> = {
     [K in keyof F]: F[K] extends { kind: "text" } ? K : never;
 }[keyof F];
 
 /**
- * What a search box is made of, as much of it as exists.
- *
- * Every part is optional and `null` is accepted, because `within(root).one(…)`
- * returns `null` and a page is allowed to have a search field with no clear
- * button, or a list with no empty state. Handing over what a lookup returned,
- * without checking it first, is the point.
+ * What a search box is made of, as much of it as exists. Every part is
+ * optional and `null` is accepted, so what a lookup returned can be handed over
+ * without checking it first.
  */
 export interface SearchBoxElements {
     readonly input?: HTMLInputElement | null;
     /** Clears the field. Hidden while the field is already empty. */
     readonly clear?: HTMLElement | null;
-    /**
-     * The "nothing matched" message.
-     *
-     * Tracks the whole result set rather than this field alone — a list emptied
-     * by a category is as empty as one emptied by a query, and there is one
-     * message either way. It lives here because it is the same line in every
-     * consumer, not because it belongs to the search box.
-     */
+    /** The "nothing matched" message. Tracks the whole result set. */
     readonly empty?: HTMLElement | null;
     /**
-     * How many matched, written as digits and nothing else.
-     *
-     * Two of the three write this, and the same way. Digits only, because the
-     * sentence around them is not ours to build: a list that reads "6 of 42" in
-     * one language reads "6 din 42" in another, and a translated string is not
-     * something to take apart in a browser to get at one number. Give the count
-     * an element of its own and let the copy sit beside it — which is what the
-     * consumer doing this already had to do.
-     *
-     * Same rule as the rest of this file, one field further: derived, and with
-     * no choice in it. Where the number *goes* is still the template's.
-     *
-     * Give it `aria-live="polite"` there. Filtering as you type changes the
-     * page silently for anyone not watching it, and this package is handed
-     * elements rather than deciding what they are.
+     * How many matched, as digits and nothing else: the sentence around them is
+     * translated, and not something to take apart in a browser. Give the count
+     * its own element and let the copy sit beside it.
      */
     readonly count?: HTMLElement | null;
 }
 
 export interface SearchBox {
     /**
-     * Brings the box into line with the state, from inside `onChange`.
-     *
-     * Takes two scalars rather than the change object, so this stays independent
-     * of what the field was named and of which other fields the list has.
-     *
-     * Safe before `bind` and after the undo it returns: this only writes to the
-     * elements it was given, so a box that is no longer wired renders the last
-     * thing it was told rather than throwing.
+     * Brings the box into line with the state, from inside `onChange`. Two
+     * scalars rather than the change object, so this does not care what the
+     * field was named.
      */
     render(query: string, matchCount: number): void;
     /**
-     * Points the input and the clear button at one `text` field of a list, and
-     * returns the undo.
-     *
-     * Separate from construction because of an ordering knot rather than a
-     * preference: `render` is called from the list's own `onChange`, so the box
-     * has to exist before the list, and this needs the list. Two calls and a
-     * `const` each way is the honest version of that; the alternative is a `let`
-     * the reader has to hold in their head.
-     *
-     * One `AbortController`, as everywhere else here — see `carousel.attach`.
+     * Points the input and the clear button at one `text` field, and returns
+     * the undo. Separate from construction because `render` is called from the
+     * list's `onChange`: the box has to exist before the list, and this needs
+     * the list.
      */
     bind<F extends FieldMap>(
         list: Filters<F>,
@@ -123,45 +66,26 @@ export interface SearchBox {
 }
 
 /**
- * The search input beside a `filters` list, and the two things every one of them
- * has to remember.
+ * The search input beside a `filters` list.
  *
  * ```ts
- * const search = searchBox({
- *     input: one<HTMLInputElement>("[data-filter-search]"),
- *     clear: one("[data-filter-clear]"),
- *     empty: one("[data-filter-empty]"),
- *     count: one("[data-filter-count]"),
- * });
- *
+ * const search = searchBox({ input, clear, empty, count });
  * const list = filters({
- *     fields, items,
- *     onChange({ state, matched }) {
- *         search.render(state.q, matched.size);
- *         // …everything this list draws for itself
- *     },
+ *     fields,
+ *     items,
+ *     onChange: ({ state, matched }) => search.render(state.q, matched.size),
  * });
- *
  * const unbind = search.bind(list, "q");
- * const detach = list.attach();
  * ```
- *
- * It writes rather than calling back, and that is the only reason it exists.
- * `filters.onChange` is already the callback that hands a consumer the value and
- * gets out of the way; a second one here would hand back `query` and `count` and
- * leave the same three writes to be spelled out at every call site, which is the
- * duplication this was extracted from.
  */
 export function searchBox(elements: SearchBoxElements): SearchBox {
     const { input, clear, empty, count } = elements;
 
     return {
         render(query, matchCount) {
-            // Guarded by inequality, not written unconditionally. Assigning
-            // `value` while someone is typing in the field moves the caret to
-            // the end, so the one case this exists for — state that moved
-            // without the keyboard, from the back button or a `reset` — must not
-            // cost a caret jump on every other keystroke.
+            // Guarded by inequality: assigning `value` while someone types
+            // moves the caret to the end, and this exists for state that moved
+            // without the keyboard — the back button, or a `reset`.
             if (input != null && input.value !== query) input.value = query;
             if (clear != null) clear.hidden = query === "";
             if (empty != null) empty.hidden = matchCount > 0;
@@ -171,9 +95,8 @@ export function searchBox(elements: SearchBoxElements): SearchBox {
         bind(list, field) {
             const listeners = new AbortController();
             const { signal } = listeners;
-            // The narrowing `TextFieldOf` already did, restated for the
-            // implementation: inside a generic function TypeScript cannot see
-            // that this field's value type is `string`, though every caller can.
+            // The narrowing `TextFieldOf` already did: inside a generic
+            // function TypeScript cannot see that this field holds a string.
             const name = field as Parameters<typeof list.set>[0];
 
             input?.addEventListener(
@@ -186,10 +109,7 @@ export function searchBox(elements: SearchBoxElements): SearchBox {
                 "click",
                 () => {
                     list.reset(name);
-                    // Focus follows the click, because the button the pointer
-                    // was on has just hidden itself — leaving focus on a
-                    // `hidden` element strands a keyboard reader at a control
-                    // that is no longer there.
+                    // The button just hid itself; focus must not stay on it.
                     input?.focus();
                 },
                 { signal }
@@ -201,40 +121,19 @@ export function searchBox(elements: SearchBoxElements): SearchBox {
 }
 
 /**
- * Hides each group that has nothing visible left inside it.
- *
- * ```ts
- * onChange({ matched }) {
- *     for (const item of items) item.hidden = !matched.has(keyOf(item));
- *     hideEmpty(groups, (group) => within(group).all("[data-faq-key]"));
- * }
- * ```
- *
- * A filtered list that renders its results under headings has this problem and
- * nothing else does: hide the items and the headings stay, so a search for one
- * word leaves a page of section titles with nothing under them. It reads as a
- * broken template rather than as a result, which is what makes forgetting it
- * expensive — nothing errors, and the page looks wrong in a way that does not
- * point at the filter.
+ * Hides each group that has nothing visible left inside it — the heading
+ * problem a list with sections has and nothing else does.
  *
- * **Reads `hidden`, rather than taking the matched set.** The items were just
- * hidden by the caller, so their state is the shortest true description of what
- * survived — and reading it is what lets this nest. A country is empty when
- * every city in it is hidden; a region is empty when every country in it is
- * hidden, *including the ones this call just hid*.
+ * **Reads `hidden` rather than the matched set**, which is what lets it nest: a
+ * country is empty when every city is hidden, a region when every country is,
+ * *including the ones the previous call just hid*.
  *
- * **Which makes the order load-bearing: innermost first.**
+ * **So the order is load-bearing: innermost first.**
  *
  * ```ts
  * hideEmpty(countries, (c) => within(c).all("[data-city]"));
  * hideEmpty(regions, (r) => within(r).all("[data-country]"));
  * ```
- *
- * Run the other way round, the regions are judged against countries that have
- * not been hidden yet, and a region with nothing in it survives.
- *
- * A group with no children at all is hidden, which is the same answer by the
- * same rule — there is nothing visible in it.
  */
 export function hideEmpty<T extends HTMLElement>(
     groups: Iterable<T>,