@escape-game-over/atlas 0.1.1 → 0.1.2

package/src/astro/carousel.ts

@@ -0,0 +1,342 @@
+/**
+ * A carousel's arithmetic and its input handling — not its markup.
+ *
+ * In `astro/` because it touches the DOM and timers, which the core is
+ * type-checked without — this and `consent.ts` are the folder allowed them.
+ *
+ * **It draws nothing.** No transform, no classes, no dots, no arrows, no
+ * `aria`. It owns which slide is current and calls `onChange` when that
+ * changes; a project does the one line that moves the track, and every design
+ * decision stays where the design is. That is the whole split, and it is why
+ * one function can serve a full-bleed hero and a three-up logo strip.
+ *
+ * What it does own is the handful of things that are identical in every
+ * carousel and quietly wrong in most: the negative modulo going backwards, a
+ * lock so a fast swipe cannot start a second move mid-transition, autoplay that
+ * restarts on interaction rather than fighting it, and a swipe threshold that
+ * does not steal a vertical scroll.
+ *
+ * ```ts
+ * const slider = carousel({
+ *     length: slides.length,
+ *     autoplayMs: 6000,
+ *     onChange: (index) => {
+ *         track.style.transform = `translateX(-${index * 100}%)`;
+ *     },
+ * });
+ * slider.attach(viewport);
+ * ```
+ *
+ * The element handed to `attach` wants `touch-action: pan-y` in CSS. Without
+ * it a browser may claim the horizontal gesture before this sees it; with it,
+ * vertical scrolling still works over the carousel, which is what a reader on a
+ * phone expects.
+ */
+
+export interface CarouselOptions {
+    /** How many slides there are. Fewer than two and everything is inert. */
+    readonly length: number;
+    /**
+     * Milliseconds between automatic advances. Omitted, nothing advances on its
+     * own.
+     *
+     * The timer restarts on every manual move rather than continuing, so a
+     * reader who just pressed *next* gets a full interval to look at what they
+     * asked for instead of the remainder of the last one.
+     */
+    readonly autoplayMs?: number;
+    /** Pixels of horizontal travel before a drag counts as a swipe. */
+    readonly swipeThreshold?: number;
+    /**
+     * How long a move is protected from the next one, in milliseconds.
+     *
+     * Should match the CSS transition. Too short and a fast swipe queues a
+     * second move over an unfinished one; too long and the carousel feels
+     * unresponsive.
+     */
+    readonly lockMs?: number;
+    /**
+     * Called with the new index, and only when it actually changed.
+     *
+     * Never called on creation: the markup already renders whichever slide it
+     * renders, and calling would make a project write the first position twice.
+     */
+    readonly onChange: (index: number) => void;
+}
+
+export interface Carousel {
+    /** The slide showing now. */
+    readonly index: number;
+    next(): void;
+    prev(): void;
+    goTo(index: number): void;
+    /**
+     * Wires one element up, and returns the undo.
+     *
+     * Starts input *and* autoplay, and the returned function stops both — one
+     * lifecycle rather than two. Nothing rotates before `attach`, because a
+     * carousel nobody can reach has no business advancing, and nothing rotates
+     * after detach, because writing a transform to a track that has left the
+     * document is a leak with no visible symptom.
+     *
+     * One element per carousel. Buttons and dots are wired by the caller to
+     * `next`, `prev` and `goTo` — this is only for the surface a gesture lands
+     * on, and there is one of those.
+     *
+     * `index` is not touched by either, which is the point of the split: the
+     * slide a reader left it on survives a detach and a re-attach.
+     */
+    attach(element: HTMLElement): () => void;
+    /**
+     * Holds autoplay until the matching `resume`.
+     *
+     * `attach` already pauses on hover, on focus within, and while the tab is
+     * hidden — WCAG 2.2.2 asks for a way to stop anything auto-updating for
+     * more than five seconds, and this rotates every six. This is for the rest:
+     * a play/pause button, a modal opening over the slider.
+     */
+    pause(): void;
+    /** Releases a `pause`. Does nothing if something else is still holding. */
+    resume(): void;
+}
+
+export function carousel(options: CarouselOptions): Carousel {
+    const {
+        length,
+        autoplayMs,
+        swipeThreshold = 10,
+        lockMs = 500,
+        onChange,
+    } = options;
+
+    /**
+     * Whether there is anywhere to go.
+     *
+     * One slide is a picture, not a carousel: nothing advances, nothing is
+     * scheduled, and a swipe does nothing rather than wrapping to itself.
+     */
+    const canMove = length > 1;
+
+    let index = 0;
+    let locked = false;
+    let lockTimer: ReturnType<typeof setTimeout> | undefined;
+    let autoplayTimer: ReturnType<typeof setInterval> | undefined;
+
+    /**
+     * Whether anything is wired up.
+     *
+     * Gates autoplay: a carousel that was built but never attached, or has been
+     * detached, has no business scheduling a timer that writes transforms to
+     * markup nobody is connected to.
+     */
+    let attached = false;
+
+    /**
+     * Everything currently holding autoplay still. Empty means it may run.
+     *
+     * A set of reasons rather than a flag, because the reasons are independent
+     * and overlap: leave the tab while hovering, come back with the pointer
+     * somewhere else, and `pointerleave` never fires — with one boolean,
+     * whichever source wrote last wins and autoplay is stuck off or wrongly on.
+     * Each source only ever adds and removes its own key, so no source can
+     * release another's hold.
+     */
+    const holds = new Set<string>();
+
+    const hold = (reason: string): void => {
+        holds.add(reason);
+        clearInterval(autoplayTimer);
+    };
+
+    const release = (reason: string): void => {
+        holds.delete(reason);
+        restartAutoplay();
+    };
+
+    /**
+     * Claims the carousel for one move, or says it is already busy.
+     *
+     * Everything that moves goes through this, autoplay included — a tick that
+     * landed mid-transition without it would let the next swipe start a second
+     * move over an unfinished one, which is the exact case the lock exists for.
+     */
+    const claim = (): boolean => {
+        if (locked) return false;
+        locked = true;
+        clearTimeout(lockTimer);
+        lockTimer = setTimeout(() => {
+            locked = false;
+        }, lockMs);
+        return true;
+    };
+
+    const restartAutoplay = (): void => {
+        clearInterval(autoplayTimer);
+        // Nothing to rotate through, nobody watching, or no autoplay asked
+        // for — in each case, nothing to schedule.
+        if (autoplayMs === undefined || !canMove || !attached) return;
+        if (holds.size > 0) return;
+        autoplayTimer = setInterval(() => {
+            // No `restartAutoplay` here: the interval already paces itself, and
+            // resetting it from inside its own tick would only churn timers.
+            if (claim()) move(index + 1);
+        }, autoplayMs);
+    };
+
+    /** The only place `index` changes. `at` may be out of range or negative. */
+    const move = (at: number): void => {
+        if (!canMove) return;
+        // `+ length` before the modulo: in JavaScript `-1 % 5` is `-1`, not
+        // `4`, so going backwards from the first slide without it lands on
+        // nothing.
+        const next = ((at % length) + length) % length;
+        if (next === index) return;
+
+        index = next;
+        onChange(index);
+    };
+
+    /** A move a reader asked for: refuses during one, and resets autoplay. */
+    const request = (at: number): void => {
+        if (!canMove || !claim()) return;
+        move(at);
+        restartAutoplay();
+    };
+
+    // Nothing is scheduled here: autoplay begins on the first `attach` and ends
+    // with the last detach, so a carousel that was built but never wired up
+    // does not sit rotating against markup nobody has connected to it.
+
+    return {
+        get index() {
+            return index;
+        },
+        next: () => request(index + 1),
+        prev: () => request(index - 1),
+        goTo: (at: number) => request(at),
+        pause: () => hold("manual"),
+        resume: () => release("manual"),
+
+        attach(element: HTMLElement): () => void {
+            let startX: number | null = null;
+            let startY = 0;
+            let lastX = 0;
+
+            const down = (event: PointerEvent): void => {
+                startX = event.clientX;
+                startY = event.clientY;
+                lastX = event.clientX;
+                // Capture, so a drag that leaves the element still finishes
+                // here rather than being lost to whatever it passed over.
+                element.setPointerCapture(event.pointerId);
+            };
+
+            const pointermove = (event: PointerEvent): void => {
+                if (startX === null) return;
+                lastX = event.clientX;
+                // Traveling more vertically than horizontally means they are
+                // scrolling the page, not the carousel. Abandon rather than
+                // compete: a carousel that eats a scroll is worse than one that
+                // misses a swipe.
+                if (
+                    Math.abs(event.clientY - startY) >
+                    Math.abs(event.clientX - startX)
+                ) {
+                    startX = null;
+                }
+            };
+
+            const up = (): void => {
+                if (startX === null) return;
+                const traveled = startX - lastX;
+                startX = null;
+
+                if (traveled > swipeThreshold) request(index + 1);
+                else if (traveled < -swipeThreshold) request(index - 1);
+            };
+
+            const cancel = (): void => {
+                startX = null;
+            };
+
+            const wheel = (event: WheelEvent): void => {
+                // Horizontal intent only — a track-pad reports both axes, and a
+                // mouse wheel reports `deltaY` alone, which is the page's.
+                if (Math.abs(event.deltaX) <= Math.abs(event.deltaY)) return;
+                if (Math.abs(event.deltaX) <= swipeThreshold) return;
+
+                event.preventDefault();
+                request(event.deltaX > 0 ? index + 1 : index - 1);
+            };
+
+            // One controller for the lot, rather than a `removeEventListener`
+            // mirroring each `addEventListener`. Those pairs have to match on
+            // both the function reference and the options, and the failure is
+            // silent: a listener added later without its twin simply survives
+            // teardown. Here the undo cannot drift from what it undoes.
+            const listeners = new AbortController();
+            const { signal } = listeners;
+
+            element.addEventListener("pointerdown", down, { signal });
+            element.addEventListener("pointermove", pointermove, { signal });
+            element.addEventListener("pointerup", up, { signal });
+            element.addEventListener("pointercancel", cancel, { signal });
+            // `passive: false` is load-bearing: a wheel listener is passive by
+            // default, where `preventDefault` silently does nothing and the
+            // page scrolls sideways underneath the carousel.
+            element.addEventListener("wheel", wheel, {
+                passive: false,
+                signal,
+            });
+
+            // Pointer and keyboard, kept apart: a reader hovering a slide and a
+            // reader tabbing through its links are both looking at it, but
+            // either can end while the other continues.
+            element.addEventListener("pointerenter", () => hold("hover"), {
+                signal,
+            });
+            element.addEventListener("pointerleave", () => release("hover"), {
+                signal,
+            });
+            element.addEventListener("focusin", () => hold("focus"), {
+                signal,
+            });
+            element.addEventListener("focusout", () => release("focus"), {
+                signal,
+            });
+
+            // On the document, not the element: a hidden tab is not a fact
+            // about the carousel. Registered with the same signal, so it goes
+            // when the carousel does rather than outliving it.
+            document.addEventListener(
+                "visibilitychange",
+                () => {
+                    if (document.hidden) hold("hidden");
+                    else release("hidden");
+                },
+                { signal }
+            );
+
+            attached = true;
+            // A tab that was already hidden when this ran gets no event, so the
+            // initial state is read rather than waited for.
+            if (document.hidden) holds.add("hidden");
+            restartAutoplay();
+
+            return () => {
+                listeners.abort();
+                attached = false;
+                clearInterval(autoplayTimer);
+
+                // The automatic holds belong to this attachment: an element
+                // detached while hovered would otherwise keep "hover" forever,
+                // and no `pointerleave` is ever coming for it — autoplay would
+                // never resume on re-attach. A manual pause is a deliberate
+                // choice and survives.
+                holds.delete("hover");
+                holds.delete("focus");
+                holds.delete("hidden");
+            };
+        },
+    };
+}

package/src/astro/dev-log.ts

@@ -0,0 +1,128 @@
+/**
+ * A development-only panel that failures announce themselves in.
+ *
+ * The problem it solves is narrow and real: a client component that fails to
+ * wire itself looks exactly like one that had nothing to do. A `console.error`
+ * is correct and invisible — nobody has devtools open while reading a page, and
+ * least of all the person who broke it ten seconds ago. This puts the same
+ * message where it cannot be missed.
+ *
+ * **Every call site must be behind `import.meta.env.DEV`.** The check belongs
+ * to the caller rather than to this module, so the whole thing — panel, styles
+ * and message strings — is dead code in a production build and gets dropped
+ * instead of shipped and never called.
+ *
+ * ```ts
+ * if (import.meta.env.DEV) reportDevError(this.localName, error);
+ * ```
+ *
+ * Written as the bare expression, without an optional chain: Vite substitutes
+ * `import.meta.env.DEV` with a literal, so the branch collapses and everything
+ * below is dropped. `import.meta.env?.DEV` is replaced as `import.meta.env` —
+ * an object literal whose property access a minifier has to fold rather than
+ * simply delete.
+ *
+ * Not a custom element, deliberately. It would need registering, it would
+ * collide with a project that registered the same name, and nothing ever
+ * extends it — the panel is an artefact of a broken page, not a part of the
+ * page's design.
+ */
+
+const PANEL_ID = "atlas-dev-log";
+
+/** Everything already reported, so a repeated failure counts rather than spams. */
+const seen = new Map<string, HTMLElement>();
+
+/** The message a line shows, for anything that might be thrown. */
+function describe(error: unknown): string {
+    if (error instanceof Error) return error.message;
+    if (typeof error === "object" && error !== null) {
+        // A thrown plain object stringifies to "[object Object]", which is the
+        // same non-message this panel exists to replace.
+        try {
+            return JSON.stringify(error);
+        } catch {
+            return Object.prototype.toString.call(error);
+        }
+    }
+    return String(error);
+}
+
+function panel(): HTMLElement {
+    const existing = document.getElementById(PANEL_ID);
+    if (existing) return existing;
+
+    // Either nothing has failed yet, or the document this lived in was swapped
+    // out from under it — a client router replacing `<body>`. Either way every
+    // line in `seen` is detached, and counting into one would report nothing.
+    seen.clear();
+
+    const created = document.createElement("div");
+    created.id = PANEL_ID;
+    // Inline, because a project's stylesheet is not this module's to depend on
+    // — and a panel that needed setting up would not be there the one time it
+    // mattered. `z-index` at the maximum: whatever is broken, this outranks it.
+    created.style.cssText = [
+        "position:fixed",
+        "inset:auto 0 0 0",
+        "z-index:2147483647",
+        "max-height:40vh",
+        "overflow:auto",
+        "background:#7f1d1d",
+        "color:#fff",
+        "font:12px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace",
+    ].join(";");
+
+    // Dismissable, because a panel pinned over the bottom 40% of the viewport
+    // will eventually be covering the component being debugged.
+    const close = document.createElement("button");
+    close.type = "button";
+    close.textContent = "✕";
+    close.setAttribute("aria-label", "Dismiss");
+    close.style.cssText =
+        "position:sticky;top:0;float:right;border:0;background:transparent;color:#fff;cursor:pointer;font:inherit;padding:.4rem .6rem";
+    close.addEventListener("click", () => {
+        created.remove();
+        seen.clear();
+    });
+    created.append(close);
+
+    document.body.append(created);
+    return created;
+}
+
+/**
+ * Reports a failure to the console and to the panel.
+ *
+ * `source` names what broke — an element's `localName`, a module's name —
+ * because the message alone rarely says which of six carousels it came from.
+ *
+ * Identical reports collapse into one line with a count. Six broken instances
+ * of the same component are one bug, and six identical lines would bury the
+ * second bug underneath them.
+ */
+export function reportDevError(source: string, error: unknown): void {
+    const text = `${source} — ${describe(error)}`;
+
+    console.error(text, error);
+
+    // `isConnected`, not merely present: after a body swap the remembered line
+    // is detached, and incrementing its count would report into a node nobody
+    // can see. Falling through rebuilds it in the new document — the count
+    // restarts, which is right, since it is a different page.
+    const already = seen.get(text);
+    if (already?.isConnected) {
+        const count = Number(already.dataset.count ?? "1") + 1;
+        already.dataset.count = String(count);
+        already.textContent = `${text}  ×${count}`;
+        return;
+    }
+
+    const line = document.createElement("p");
+    line.style.cssText =
+        "margin:0;padding:.4rem .6rem;border-top:1px solid rgba(255,255,255,.25)";
+    line.textContent = text;
+
+    seen.set(text, line);
+    panel().append(line);
+}

package/src/astro/dom.ts

@@ -0,0 +1,53 @@
+/**
+ * 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.
+ *
+ * ```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.
+ *
+ * **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.
+ */
+
+/**
+ * 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;
+    /** Every match inside the root, as an array rather than a `NodeList`. */
+    all<T extends Element = HTMLElement>(selector: string): T[];
+}
+
+export function within(root: ParentNode): Within {
+    return {
+        one: <T extends Element = HTMLElement>(selector: string) =>
+            root.querySelector<T>(selector),
+        all: <T extends Element = HTMLElement>(selector: string) => [
+            ...root.querySelectorAll<T>(selector),
+        ],
+    };
+}