@escape-game-over/atlas 0.1.15 → 0.1.17

package/src/astro/background-video.ts

@@ -0,0 +1,290 @@
+/**
+ * A decorative background video's playback — not its markup, and not its button.
+ *
+ * In `astro/` because it reaches for `matchMedia` and a media element, which the
+ * core is type-checked without.
+ *
+ * **It draws nothing.** No icon, no label, no `hidden`, no `aria`. It owns
+ * whether the video is playing, whether there is anything to play, and which of
+ * its cuts is loaded, and calls `onChange` when the first two move; the project
+ * draws its own play/pause control from that and points the control at
+ * `toggle`.
+ *
+ * ```ts
+ * const loop = backgroundVideo({
+ *     onChange: ({ playing, playable }) => {
+ *         button.hidden = !playable;
+ *         button.setAttribute("aria-label", playing ? pauseLabel : playLabel);
+ *     },
+ * });
+ *
+ * button.addEventListener("click", () => loop.toggle(), { signal });
+ * const detach = loop.attach(video);
+ * ```
+ *
+ * What it owns is the handful of things every looping hero needs and most get
+ * quietly wrong:
+ *
+ * - **Reduced motion starts it paused.** A reader who asked their system for
+ *   less motion should not get a full-width loop behind the headline.
+ * - **A way to stop it.** WCAG 2.2.2 asks for one on anything that moves for
+ *   more than five seconds, and a loop moves forever. The control is the
+ *   project's; the state it shows is this.
+ * - **No control over nothing.** A `<source media>` that matches no viewport
+ *   leaves the element empty, and a pause button beside an empty element pauses
+ *   nothing. `playable` says so, and the caller hides it.
+ * - **The right cut after a rotation.** A browser chooses among `<source
+ *   media>` once, when the element loads, and never again — so a phone turned
+ *   sideways keeps the portrait cut, cropped across a landscape screen, until
+ *   something reloads it.
+ * - **The reader's pause surviving that reload.** A reload resets the element
+ *   to its markup, and markup that says `autoplay` starts again the video they
+ *   had just stopped.
+ *
+ * The markup wants `muted`, `loop` and `playsinline`, and — being decoration —
+ * `aria-hidden="true"` and `tabindex="-1"`. `autoplay` is better left out: this
+ * starts the video itself, and without this script there is no control to stop
+ * it with, while with the attribute a reduced-motion reader sees the first
+ * frames move before this gets to pause them. Left in, everything still works.
+ */
+
+export interface BackgroundVideoState {
+    /** Whether it is playing now: the element's own `paused`, inverted. */
+    readonly playing: boolean;
+    /**
+     * Whether a source was chosen for this viewport.
+     *
+     * False when no `<source media>` matched, or every one that did failed —
+     * there is nothing on screen to pause, so the control has nothing to do
+     * and should not be offered.
+     */
+    readonly playable: boolean;
+}
+
+export interface BackgroundVideoOptions {
+    /**
+     * Called once on `attach`, and then whenever `playing` or `playable` moves.
+     *
+     * Once on `attach` although nothing moved, because the control's first
+     * state is only known then: whether the viewport matched a source and
+     * whether reduced motion held it still are both read from the page, and the
+     * markup cannot say either in advance. Never called for an event that
+     * changed neither, so a caller can redraw unconditionally.
+     */
+    readonly onChange: (state: BackgroundVideoState) => void;
+}
+
+export interface BackgroundVideo {
+    readonly state: BackgroundVideoState;
+    /** Plays, as the reader's choice: it outlives a reload and a re-attach. */
+    play(): void;
+    /** Pauses, as the reader's choice: it outlives a reload and a re-attach. */
+    pause(): void;
+    /** Whichever of the two the video is not doing now. What a button wants. */
+    toggle(): void;
+    /**
+     * Takes over one `<video>`, and returns the undo.
+     *
+     * Applies the starting state — the reader's earlier choice if they made
+     * one, otherwise playing unless reduced motion is set — and starts
+     * listening to the element and to each of its sources' media queries. The
+     * undo stops listening and leaves the video as it is.
+     *
+     * Before `attach` and after the undo, `play`, `pause` and `toggle` do
+     * nothing: there is no element to act on. The reader's choice is kept
+     * across the gap, as `carousel` keeps its index.
+     */
+    attach(video: HTMLVideoElement): () => void;
+}
+
+const REDUCED_MOTION = "(prefers-reduced-motion: reduce)";
+
+/**
+ * `HTMLMediaElement.NETWORK_NO_SOURCE`, as a literal.
+ *
+ * The state an element settles in when it has run out of sources to try —
+ * none matched, or each that did failed. Written out so nothing global is read
+ * at import, which is when a module like this must do nothing at all.
+ */
+const NETWORK_NO_SOURCE = 3;
+
+/**
+ * The media element events after which either half of the state may differ.
+ *
+ * `emptied` is a reload beginning, `loadstart` a source having been chosen.
+ * `error` is listened to separately, in the capture phase — see `attach`.
+ */
+const EVENTS = ["play", "pause", "emptied", "loadstart"] as const;
+
+export function backgroundVideo(
+    options: BackgroundVideoOptions
+): BackgroundVideo {
+    const { onChange } = options;
+
+    /** The element while attached, and nothing otherwise. */
+    let video: HTMLVideoElement | undefined;
+
+    /**
+     * What the reader chose, once they have chosen.
+     *
+     * Undefined until they press something, and then it outranks reduced
+     * motion: a reader who asked for less motion and then pressed play has
+     * answered the question for this video. Kept across a detach, so an element
+     * moved in the DOM comes back as the reader left it.
+     */
+    let chosen: boolean | undefined;
+
+    let state: BackgroundVideoState = { playing: false, playable: false };
+
+    /**
+     * Whether this attachment has announced yet.
+     *
+     * The first read of an attachment is announced even if it matches the last
+     * state, since the control has never been drawn from it. A flag rather
+     * than a forced call at the end of `attach`, because applying the starting
+     * state can fire `play` on its own — and then the control was told twice.
+     */
+    let fresh = false;
+
+    /** Reads the element, and announces if anything moved. */
+    const sync = (): void => {
+        if (video === undefined) return;
+        const next: BackgroundVideoState = {
+            playing: !video.paused,
+            // Both halves, because neither alone is true. `currentSrc` is empty
+            // until a source is chosen, but is not reliably cleared when a
+            // reload then finds none; `networkState` says an element has run
+            // out of sources, but passes through that state for a moment at
+            // the start of every reload too.
+            playable:
+                video.currentSrc !== "" &&
+                video.networkState !== NETWORK_NO_SOURCE,
+        };
+        if (
+            !fresh &&
+            next.playing === state.playing &&
+            next.playable === state.playable
+        ) {
+            return;
+        }
+        fresh = false;
+        state = next;
+        onChange(state);
+    };
+
+    /**
+     * Puts the element in the wanted state, and makes it stay there.
+     *
+     * `autoplay` is the half that stays. A reload resets the element to paused
+     * and then consults the attribute, so keeping it equal to what is wanted is
+     * what carries a reader's pause — or their play — across one.
+     */
+    const apply = (playing: boolean): void => {
+        if (video === undefined) return;
+        video.autoplay = playing;
+        if (playing) {
+            // Refused when a browser will not autoplay even a muted video —
+            // iOS in low-power mode is the one people meet. The element stays
+            // paused, and the control should say "play".
+            video.play().catch(() => sync());
+        } else {
+            video.pause();
+        }
+    };
+
+    const choose = (playing: boolean): void => {
+        if (video === undefined) return;
+        chosen = playing;
+        apply(playing);
+    };
+
+    return {
+        get state() {
+            return state;
+        },
+        play: () => choose(true),
+        pause: () => choose(false),
+        // From the element rather than from `chosen`. The control shows what
+        // the video is doing, so pressing it must do the opposite of that —
+        // including when the browser paused it rather than the reader.
+        toggle: () => {
+            if (video !== undefined) choose(video.paused);
+        },
+
+        attach(element) {
+            video = element;
+            fresh = true;
+            const listeners = new AbortController();
+            const { signal } = listeners;
+
+            // What decorative means, and what every browser requires before it
+            // will start a video nobody pressed play on.
+            element.muted = true;
+
+            for (const type of EVENTS) {
+                element.addEventListener(type, () => sync(), { signal });
+            }
+            // A `<source>` that is skipped or fails fires `error` at itself, and
+            // `error` does not bubble. The capture phase passes through the
+            // video on the way down, so this hears every source's failure —
+            // the last of which is how an element says it found nothing.
+            element.addEventListener("error", () => sync(), {
+                capture: true,
+                signal,
+            });
+
+            const sources = [...element.querySelectorAll("source")];
+
+            /**
+             * Which source a browser would choose now: the first whose media
+             * matches and whose type it can play.
+             *
+             * Compared before reloading rather than reloading on every change,
+             * because not every crossing changes the answer. A later source's
+             * query flipping while an earlier one still matches picks the same
+             * file, and a reload would only restart the loop from its first
+             * frame for nothing.
+             */
+            const choice = (): number =>
+                sources.findIndex(
+                    (source) =>
+                        (source.media === "" ||
+                            matchMedia(source.media).matches) &&
+                        (source.type === "" ||
+                            element.canPlayType(source.type) !== "")
+                );
+
+            let chosenSource = choice();
+            // One listener per distinct query: two sources sharing one would
+            // otherwise reload twice for a single rotation.
+            const queries = new Set(
+                sources
+                    .map((source) => source.media)
+                    .filter((media) => media !== "")
+            );
+            for (const media of queries) {
+                matchMedia(media).addEventListener(
+                    "change",
+                    () => {
+                        const next = choice();
+                        if (next === chosenSource) return;
+                        chosenSource = next;
+                        // `emptied` and then `loadstart` follow, and `sync`
+                        // hears both — so the control follows without a call
+                        // from here.
+                        element.load();
+                    },
+                    { signal }
+                );
+            }
+
+            apply(chosen ?? !matchMedia(REDUCED_MOTION).matches);
+            sync();
+
+            return () => {
+                listeners.abort();
+                video = undefined;
+            };
+        },
+    };
+}

package/src/astro/filters.ts

@@ -60,7 +60,7 @@
  *
  * The kinds are closed, and deliberately few:
  *
- * - `text` — free entry, folded and substring-matched. The search box.
+ * - `text` — free entry, folded and matched word by word. The search box.
  * - `choice` — one of a set, or none. Tabs, a `<select>`, a radio group. The
  *   control picks one; an item may hold several and answer to any — see
  *   `ItemValue`.
@@ -200,6 +200,29 @@ export interface SetOptions {
 export interface Filters<F extends FieldMap> {
     readonly state: FilterState<F>;
     readonly matched: ReadonlySet<string>;
+    /**
+     * The keys that survive every field *except* this one.
+     *
+     * The question a facet asks of its own options: how many results would
+     * picking each of them give, with everything else as it stands. Counted
+     * against `matched` instead, a dropdown whose value is already set could
+     * only ever offer that value — every other option would read zero, since
+     * the items holding it have just been filtered out by the very field being
+     * asked about.
+     *
+     * The same matcher as `matched`, folding and tokens included, rather than a
+     * second one in the caller. A facet count computed by a hand-written
+     * predicate drifts from the list it is counting the moment either changes —
+     * a count of four above a list of three — and nothing reports it.
+     *
+     * Computed on first ask and kept until the state next moves, so a render
+     * that asks once per option pays one pass per field rather than one per
+     * option. A field that is not narrowing anything answers with `matched`
+     * itself: without it, the rest is exactly what already matched.
+     *
+     * Safe to call from `onChange`, which never runs during construction.
+     */
+    matchedWithout(field: keyof F): ReadonlySet<string>;
     set<K extends keyof F>(
         field: K,
         value: StateValue<F[K]>,
@@ -315,6 +338,17 @@ export function filters<const F extends FieldMap>(
     let state = blank();
     let matched: ReadonlySet<string> = new Set(items.map((item) => item.key));
 
+    /**
+     * Each `text` field's query, folded and split, for the current state.
+     *
+     * Folded once per state rather than once per item. The other kinds compare
+     * values as they are, so there is nothing to prepare for them.
+     */
+    let queries = new Map<string, readonly string[]>();
+
+    /** `matchedWithout` answers for the current state. Emptied when it moves. */
+    const without = new Map<string, ReadonlySet<string>>();
+
     /**
      * Whether the URL is this instance's to write.
      *
@@ -324,61 +358,74 @@ export function filters<const F extends FieldMap>(
      */
     let attached = false;
 
+    /**
+     * Whether a field is narrowing anything in the current state.
+     *
+     * An empty query, no choice and a flag that is off all keep every item —
+     * the flag above all, which keeps everything rather than keeping the items
+     * that are *not* flagged. See `Field`.
+     */
+    const narrows = (name: keyof F & string): boolean => {
+        const kind = fields[name]?.kind;
+        if (kind === "text") return (queries.get(name) ?? []).length > 0;
+        if (kind === "choice") return state[name] !== "";
+        return state[name] === true;
+    };
+
+    /**
+     * Whether one item survives every field but `except`, in the current state.
+     *
+     * The one matcher. `matched` is this with nothing excepted and
+     * `matchedWithout` is this with one field excepted, so a facet count and
+     * the list it counts cannot disagree about what a match is.
+     */
+    function passes(item: FilterItem<F>, except?: keyof F & string): boolean {
+        for (const name of names) {
+            if (name === except || !narrows(name)) continue;
+            const kind = fields[name]?.kind;
+            if (kind === "text") {
+                // Every token must appear, not one run that must appear whole.
+                // A haystack is several things joined (a title, plus its
+                // category, plus its summary), and the order they were joined
+                // in is an accident of whoever wrote the template. Matching
+                // the query as one run made that accident load-bearing:
+                // against "Copper Kettle" in the Kitchen category, "kettle
+                // kitchen" found nothing while "kettle" alone worked, and the
+                // first is what someone narrowing a list types.
+                const tokens = queries.get(name) ?? [];
+                const haystack = haystacks.get(item.key)?.get(name) ?? "";
+                if (!tokens.every((token) => haystack.includes(token))) {
+                    return false;
+                }
+            } else if (kind === "choice") {
+                // An item may sit in several categories while the control
+                // still picks one — see `ItemValue`. One value is the same
+                // question asked of a set of one.
+                const wanted = state[name] as string;
+                const held = item.values[name];
+                const holds = Array.isArray(held)
+                    ? held.includes(wanted)
+                    : held === wanted;
+                if (!holds) return false;
+            } else if (item.values[name] !== true) {
+                return false;
+            }
+        }
+        return true;
+    }
+
     function recompute(): void {
-        // The query folded once per render rather than once per item. The other
-        // kinds compare values as they are, so there is nothing to prepare.
-        // Split into tokens, all of which must appear — not one substring that
-        // must appear whole. A haystack is several things joined (a title, plus
-        // its category, plus its summary), and the order they were joined in is
-        // an accident of whoever wrote the template. Matching the query as one
-        // run made that accident load-bearing: against "Copper Kettle" in the
-        // Kitchen category, "kettle kitchen" found nothing while "kettle" alone
-        // worked, and the first is what someone narrowing a list types.
-        const queries = new Map<string, string[]>();
+        queries = new Map();
         for (const name of names) {
             if (fields[name]?.kind !== "text") continue;
             const folded = fold(state[name] as string);
             queries.set(name, folded === "" ? [] : folded.split(/\s+/));
         }
+        without.clear();
 
         const next = new Set<string>();
         for (const item of items) {
-            let hit = true;
-            for (const name of names) {
-                const kind = fields[name]?.kind;
-                if (kind === "text") {
-                    const tokens = queries.get(name) ?? [];
-                    if (tokens.length === 0) continue;
-                    const haystack = haystacks.get(item.key)?.get(name) ?? "";
-                    if (!tokens.every((token) => haystack.includes(token))) {
-                        hit = false;
-                        break;
-                    }
-                } else if (kind === "choice") {
-                    const wanted = state[name] as string;
-                    if (wanted === "") continue;
-                    // An item may sit in several categories while the control
-                    // still picks one — see `ItemValue`. One value is the same
-                    // question asked of a set of one.
-                    const held = item.values[name];
-                    const holds = Array.isArray(held)
-                        ? held.includes(wanted)
-                        : held === wanted;
-                    if (!holds) {
-                        hit = false;
-                        break;
-                    }
-                } else {
-                    // A flag off is not a filter: it keeps everything, rather
-                    // than keeping the items that are *not* flagged. See `Field`.
-                    if (state[name] !== true) continue;
-                    if (item.values[name] !== true) {
-                        hit = false;
-                        break;
-                    }
-                }
-            }
-            if (hit) next.add(item.key);
+            if (passes(item)) next.add(item.key);
         }
         matched = next;
     }
@@ -467,6 +514,20 @@ export function filters<const F extends FieldMap>(
             return matched;
         },
 
+        matchedWithout(field) {
+            const name = field as keyof F & string;
+            if (!narrows(name)) return matched;
+            const cached = without.get(name);
+            if (cached !== undefined) return cached;
+
+            const rest = new Set<string>();
+            for (const item of items) {
+                if (passes(item, name)) rest.add(item.key);
+            }
+            without.set(name, rest);
+            return rest;
+        },
+
         set(field, value, setOptions) {
             const name = field as keyof F & string;
             // Compared as everything downstream will read it, not as it arrived.