@escape-game-over/atlas 0.1.27 → 0.1.29

package/docs/client-scripts.md

@@ -46,8 +46,8 @@ finding them.
 analytics={…}>` (`@escape-game-over/atlas/astro/consent-banner`) renders the
 site's markup as its children, skips itself — script included — when the
 analytics need no permission, and remembers, expires and applies the answer. The
-markup spreads `consent.accept` and `consent.decline` on its buttons, and
-`consent.reopen` on the control that brings it back.
+markup marks its buttons `data-consent="grant"` and `data-consent="deny"`,
+and the control that brings it back `data-consent-reopen hidden`.
 
 **Browser code has one import path: `@escape-game-over/atlas/client`**, which
 re-exports every module above. None of it touches the DOM at import, so an
@@ -550,9 +550,11 @@ right properties is a faithful stand-in.
   that `ref` throws naming the root and the selector.
 - `tests/element.test.ts` stubs `customElements` to upgrade on `define`, as a
   browser does, and pins what `connect` is handed.
+- `tests/consent.test.ts` fakes `localStorage`, with a switch that makes it
+  throw, and the Google hook, and pins the six-month expiry to the day.
 
-`carousel` and `consent` have none, and `element` has no lifecycle test — moves
-and teardown. They need a real DOM and
+`carousel` has none, nor does the consent banner's element, and `element` has
+no lifecycle test — moves and teardown. They need a real DOM and
 this package carries no environment for one; adding `happy-dom` as a dev
 dependency and setting `environment` in `vitest.config.ts` is what that would
 take.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.27",
+    "version": "0.1.29",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,
@@ -54,7 +54,7 @@
         "@biomejs/biome": "2.5.14",
         "@types/node": "26.6.2",
         "@vitest/coverage-istanbul": "5.0.1",
-        "astro": "7.3.3",
+        "astro": "7.3.4",
         "typescript": "6.0.3",
         "vitest": "5.0.1"
     }

package/src/analytics/index.ts

@@ -72,12 +72,9 @@ export function analyticsScripts(
 /**
  * Whether this deployment loads anything a visitor has to be asked about.
  *
- * The build-time twin of `consentApplies()` in `astro/consent.ts`, which asks
- * the same question in the browser by looking for the global the Google tag
- * defines. That one cannot answer it early enough to be useful: a consent
- * banner's script has to be downloaded, parsed and run before it can report
- * that there was nothing to consent to — three requests to learn that none of
- * them were needed. Asked here, a project leaves the banner out of the HTML.
+ * The one place that question is answered, and at build time: a project leaves
+ * the banner — script and all — out of the HTML, rather than shipping a script
+ * to find out in the browser that there was nothing to ask.
  *
  * Vendor by vendor rather than `analytics.google !== undefined`, because that
  * is not the question. A `google` block carrying no ids emits no tag and sets

package/src/astro/ConsentBanner.astro

@@ -1,11 +1,12 @@
 ---
 /**
  * The consent banner's behaviour; the site supplies its markup and copy as the
- * children, with `consent.accept` and `consent.decline` on its buttons.
+ * children, with `data-consent="grant"` and `data-consent="deny"` on its
+ * buttons.
  *
  * Renders nothing — and ships no script — when this site's analytics need no
  * permission. Otherwise the banner starts hidden and shows only to a visitor
- * with no answer on record, or when `consent.reopen` is pressed.
+ * with no answer on record, or when a `data-consent-reopen` control is pressed.
  */
 import type { HTMLAttributes } from "astro/types";
 import { type AnalyticsSettings, consentRequired } from "../analytics/index.ts";

package/src/astro/ConsentElement.astro

@@ -2,11 +2,13 @@
 /** Internal to `ConsentBanner.astro`, so its script ships only where it renders. */
 import type { HTMLAttributes } from "astro/types";
 import AtlasElement from "./AtlasElement.astro";
-import { consentBanner } from "./consent.ts";
+import { consentBanner } from "./consent-element.ts";
 
 type Props = HTMLAttributes<"div">;
 ---
 
+<script src="./consent-element.ts" />
+
 <AtlasElement
     of={consentBanner}
     {...Astro.props}
@@ -16,52 +18,3 @@ type Props = HTMLAttributes<"div">;
 >
     <slot />
 </AtlasElement>
-
-<script>
-import {
-    applyConsent,
-    CONSENT_ANSWER,
-    CONSENT_REOPEN,
-    consentApplies,
-    consentStore,
-} from "./consent.ts";
-import { element } from "./element.ts";
-import { refs } from "./ref.ts";
-
-element("atlas-consent", ({ root, signal }) => {
-    // The head script left no consent hook: nothing here sets a cookie.
-    if (!consentApplies()) return;
-
-    const store = consentStore();
-    const show = (): void => {
-        root.hidden = false;
-    };
-
-    for (const button of refs(root, `[${CONSENT_ANSWER}]`)) {
-        const choice = button.getAttribute(CONSENT_ANSWER);
-        if (choice !== "granted" && choice !== "denied") {
-            throw new Error(`${CONSENT_ANSWER} is "${choice}"`);
-        }
-        button.addEventListener(
-            "click",
-            () => {
-                store.record(choice);
-                root.hidden = true;
-            },
-            { signal }
-        );
-    }
-
-    // Outside the banner — withdrawing must be as easy as granting.
-    for (const button of refs(document, `[${CONSENT_REOPEN}]`)) {
-        button.hidden = false;
-        button.addEventListener("click", show, { signal });
-    }
-
-    // Applied, not re-recorded: recording stamps today's date, and an answer
-    // renewed on every page view never expires.
-    const stored = store.read();
-    if (stored === undefined) show();
-    else applyConsent(stored.choice);
-});
-</script>

package/src/astro/client.ts

@@ -11,15 +11,6 @@
 
 export * from "./background-video.ts";
 export * from "./carousel.ts";
-export {
-    applyConsent,
-    type ConsentChoice,
-    type ConsentRecord,
-    type ConsentStoreOptions,
-    consent,
-    consentApplies,
-    consentStore,
-} from "./consent.ts";
 export {
     type Connect,
     type ElementContext,

package/src/astro/consent-element.ts

@@ -0,0 +1,59 @@
+import {
+    applyConsent,
+    type ConsentChoice,
+    readConsent,
+    recordConsent,
+} from "./consent.ts";
+import { element } from "./element.ts";
+import { data, refs } from "./ref.ts";
+
+/** What each button does, in the words Consent Mode records. */
+const ACTIONS: Readonly<Record<string, ConsentChoice>> = {
+    grant: "granted",
+    deny: "denied",
+};
+
+/**
+ * The banner's behaviour. Its own module, and not re-exported from `client.ts`,
+ * so the script ships only where `<ConsentBanner>` renders.
+ *
+ * A site's markup marks the two buttons inside the banner `data-consent="grant"`
+ * and `data-consent="deny"`, and the control that brings it back — usually in
+ * the footer — `data-consent-reopen hidden`: it stays hidden until there is an
+ * answer to withdraw.
+ */
+export const consentBanner = element("atlas-consent", ({ root, signal }) => {
+    const show = (): void => {
+        root.hidden = false;
+    };
+
+    for (const button of refs(root, "[data-consent]")) {
+        const action = data(button, "consent");
+        const choice = Object.hasOwn(ACTIONS, action)
+            ? ACTIONS[action]
+            : undefined;
+        if (choice === undefined) {
+            throw new Error(`data-consent is "${action}", not grant or deny`);
+        }
+        button.addEventListener(
+            "click",
+            () => {
+                recordConsent(choice);
+                root.hidden = true;
+            },
+            { signal }
+        );
+    }
+
+    // Outside the banner — withdrawing must be as easy as granting.
+    for (const button of refs(document, "[data-consent-reopen]")) {
+        button.hidden = false;
+        button.addEventListener("click", show, { signal });
+    }
+
+    // Applied, not re-recorded: recording stamps today's date, and an answer
+    // renewed on every page view never expires.
+    const stored = readConsent();
+    if (stored === undefined) show();
+    else applyConsent(stored.choice);
+});

package/src/astro/consent.ts

@@ -1,24 +1,4 @@
 import { CONSENT_UPDATE_GLOBAL } from "../analytics/google.ts";
-import type { ElementTag } from "./element.ts";
-
-/** Internal to `ConsentBanner.astro`: the element, and what its script finds. */
-export const consentBanner: ElementTag<"atlas-consent"> = {
-    tag: "atlas-consent",
-};
-export const CONSENT_ANSWER = "data-atlas-consent-answer";
-export const CONSENT_REOPEN = "data-atlas-consent-reopen";
-
-/**
- * What a site's consent markup spreads: the two answer buttons inside
- * `<ConsentBanner>`, and the control that brings it back — which belongs on
- * every page, usually the footer, and stays hidden until there is something to
- * withdraw.
- */
-export const consent = {
-    accept: { [CONSENT_ANSWER]: "granted" },
-    decline: { [CONSENT_ANSWER]: "denied" },
-    reopen: { [CONSENT_REOPEN]: "", hidden: "" },
-};
 
 /**
  * The browser half of consent: remembering an answer, expiring it, and handing
@@ -57,104 +37,63 @@ export interface ConsentRecord {
  * is no way to expire it, and no way to answer "when did this visitor agree?",
  * which is a question only ever asked when somebody is already unhappy.
  */
-const DEFAULT_MONTHS = 6;
+const MONTHS = 6;
 
 /**
- * Where the answer is kept.
- *
- * `localStorage` is already scoped to an origin, so this does not need to
- * identify the site — what it needs is to not collide with something else on
- * the page, and a bare `"consent"` is exactly the key a third-party consent
- * tool or chat widget would reach for. The prefix matches
- * `CONSENT_UPDATE_GLOBAL`, so one concept has one name on both sides.
- *
- * Overridable for the case the default cannot cover: two deployments sharing
- * one origin — `example.com/rome` and `example.com/bucharest` — where one key
- * would mean one answer for both. See `consentStore`.
+ * The `localStorage` key the answer is kept under. Prefixed to keep clear of the
+ * bare `"consent"` a third-party widget would reach for.
  */
-const DEFAULT_KEY = "__consent";
-
-export interface ConsentStoreOptions {
-    /** Overrides `DEFAULT_KEY`. See it for the one case that needs this. */
-    readonly key?: string;
-    /** Overrides the six-month window. See `DEFAULT_MONTHS`. */
-    readonly months?: number;
-}
+const KEY = "atlas-consent";
 
 /**
- * Reading and writing an answer, bound to one key and one window.
+ * The answer this visitor gave, if it still counts.
  *
- * A factory rather than two functions each taking options, because the key and
- * the window have to *match* between them: a read that looked in one place and
- * a write that filled another would ask a visitor on every page while
- * faithfully recording each answer. Bound once, they cannot disagree.
+ * `undefined` for never asked, for an expired answer, and for anything
+ * unparseable — all three mean the same thing to a banner, and all three should
+ * ask rather than assume.
  */
-export function consentStore(options: ConsentStoreOptions = {}): {
-    read(): ConsentRecord | undefined;
-    record(choice: ConsentChoice): void;
-} {
-    const key = options.key ?? DEFAULT_KEY;
-    const months = options.months ?? DEFAULT_MONTHS;
-
-    return {
-        /**
-         * The answer this visitor gave, if it still counts.
-         *
-         * `undefined` for never asked, for an expired answer, and for anything
-         * unparseable — all three mean the same thing to a banner, and all
-         * three should ask rather than assume. Storage hand-edited, or written
-         * by an older version of this code, lands in the third case by design.
-         */
-        read(): ConsentRecord | undefined {
-            let raw: string | null = null;
-            try {
-                raw = localStorage.getItem(key);
-            } catch {
-                // Private browsing, or storage disabled. Nothing was
-                // remembered, so nothing is assumed.
-                return undefined;
-            }
-            if (raw === null) return undefined;
-
-            try {
-                const parsed = JSON.parse(raw) as Partial<ConsentRecord>;
-                if (parsed.choice !== "granted" && parsed.choice !== "denied") {
-                    return undefined;
-                }
-                if (typeof parsed.at !== "string") return undefined;
-
-                const expiry = new Date(parsed.at);
-                if (Number.isNaN(expiry.getTime())) return undefined;
-                expiry.setMonth(expiry.getMonth() + months);
-                if (expiry < new Date()) return undefined;
-
-                return { choice: parsed.choice, at: parsed.at };
-            } catch {
-                return undefined;
-            }
-        },
+export function readConsent(): ConsentRecord | undefined {
+    let raw: string | null = null;
+    try {
+        raw = localStorage.getItem(KEY);
+    } catch {
+        // Private browsing, or storage disabled. Nothing was remembered, so
+        // nothing is assumed.
+        return undefined;
+    }
+    if (raw === null) return undefined;
+
+    try {
+        const parsed = JSON.parse(raw) as Partial<ConsentRecord>;
+        if (parsed.choice !== "granted" && parsed.choice !== "denied") {
+            return undefined;
+        }
+        if (typeof parsed.at !== "string") return undefined;
+
+        const expiry = new Date(parsed.at);
+        if (Number.isNaN(expiry.getTime())) return undefined;
+        expiry.setMonth(expiry.getMonth() + MONTHS);
+        if (expiry < new Date()) return undefined;
+
+        return { choice: parsed.choice, at: parsed.at };
+    } catch {
+        return undefined;
+    }
+}
 
-        /**
-         * Remembers an answer, dated now, and tells Google about it.
-         *
-         * One call rather than two, because the two must not come apart: an
-         * answer stored but never applied leaves the visitor consented in name
-         * only, and one applied but never stored asks them again next page.
-         */
-        record(choice: ConsentChoice): void {
-            const record: ConsentRecord = {
-                choice,
-                at: new Date().toISOString(),
-            };
-            try {
-                localStorage.setItem(key, JSON.stringify(record));
-            } catch {
-                // Unable to remember it, which is a worse experience and not a
-                // wrong one — the choice still applies to this page.
-            }
-            applyConsent(choice);
-        },
-    };
+/**
+ * Remembers an answer, dated now, and tells Google about it — one call, so the
+ * two cannot come apart.
+ */
+export function recordConsent(choice: ConsentChoice): void {
+    const record: ConsentRecord = { choice, at: new Date().toISOString() };
+    try {
+        localStorage.setItem(KEY, JSON.stringify(record));
+    } catch {
+        // Unable to remember it, which is a worse experience and not a wrong
+        // one — the choice still applies to this page.
+    }
+    applyConsent(choice);
 }
 
 /**
@@ -174,12 +113,3 @@ export function applyConsent(choice: ConsentChoice): void {
     )[CONSENT_UPDATE_GLOBAL];
     update?.(choice);
 }
-
-/** Whether this deployment has a Google tag to consent to at all. */
-export function consentApplies(): boolean {
-    return (
-        (window as unknown as Record<string, unknown>)[
-            CONSENT_UPDATE_GLOBAL
-        ] !== undefined
-    );
-}

package/src/redirects.ts

@@ -101,11 +101,12 @@ export type ValidateRedirectTargets<Rules> = {
  * against what this project builds and its URL is derived — a redirect cannot
  * outlive the page it points at, or miss a slug that was retranslated. The
  * locale is optional and defaults to the site's own, since an old URL usually
- * predates translation.
+ * predates translation. `page` names a page of a paginated list, and is refused
+ * the same way `pathFor` refuses it when the list has no such page.
  */
 export type RedirectTarget<Id extends string, L extends string> =
     | ExternalUrl
-    | { readonly route: Id; readonly locale?: L }
+    | { readonly route: Id; readonly locale?: L; readonly page?: number }
     /**
      * A file served verbatim from `public/` — a PDF, a spreadsheet.
      *

package/src/site/create.ts

@@ -577,12 +577,14 @@ export function createSite<
             from: rule.from,
             // Three kinds of target, told apart by shape: a string is external
             // and passes through, `file` is served verbatim from `public/`, and
-            // a route is resolved to whatever URL it has in the locale asked
-            // for.
+            // a route is resolved to whatever URL it has in the locale and on
+            // the page asked for.
             to: ((): string => {
                 if (typeof rule.to === "string") return rule.to;
                 if ("file" in rule.to) return rule.to.file;
-                return pathFor(rule.to.route, rule.to.locale ?? defaultLocale);
+                return pathFor(rule.to.route, rule.to.locale ?? defaultLocale, {
+                    page: rule.to.page,
+                });
             })(),
             status: statusFor(rule.kind),
         }));