@escape-game-over/atlas 0.1.51 → 0.1.54

package/docs/client-scripts.md

@@ -43,7 +43,8 @@ finding them.
 | `element`          | registering a custom element, and ending what it started       | what the element does while it is on the page   |
 
 `consent` is the one module that ships its own behaviour: `<ConsentBanner
-analytics={…}>` (`@escape-game-over/atlas/astro/consent-banner`) renders the
+slot="consent" analytics={…}>` (`@escape-game-over/atlas/astro/consent-banner`),
+passed to `Document`, which fails the build when a page needs one and has none. It 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
 answer is two, one per category: `analytics` (Google's `analytics_storage`) and

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.51",
+    "version": "0.1.54",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,
@@ -16,9 +16,11 @@
         "./astro": "./src/astro/index.ts",
         "./astro/images": "./src/astro/images.ts",
         "./client": "./src/astro/client.ts",
+        "./astro/auto-dialog": "./src/astro/AutoDialog.astro",
         "./astro/consent-banner": "./src/astro/ConsentBanner.astro",
         "./astro/document": "./src/astro/Document.astro",
         "./astro/element": "./src/astro/AtlasElement.astro",
+        "./astro/google-map": "./src/astro/GoogleMap.astro",
         "./astro/image": "./src/astro/Image.astro",
         "./astro/rich-text": "./src/astro/RichText.astro"
     },
@@ -45,6 +47,9 @@
         "fmt": "biome format --write .",
         "check-fmt": "biome check . --error-on-warnings"
     },
+    "dependencies": {
+        "@types/google.maps": "3.66.4"
+    },
     "peerDependencies": {
         "@types/node": ">=22",
         "astro": ">=7",

package/src/analytics/index.ts

@@ -70,7 +70,7 @@ export function analyticsScripts(
 }
 
 /**
- * Whether this deployment loads anything a visitor has to be asked about.
+ * The vendors this deployment loads that a visitor has to be asked about.
  *
  * 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
@@ -88,10 +88,10 @@ export function analyticsScripts(
  * permission — which is the failure worth having, since the alternative is a
  * new vendor silently setting cookies behind a banner that never appears.
  */
-export function consentRequired(
+export function consentVendors(
     analytics: AnalyticsSettings | undefined
-): boolean {
-    if (analytics === undefined) return false;
+): readonly (keyof AnalyticsSettings)[] {
+    if (analytics === undefined) return [];
 
     const VENDORS: Readonly<Record<keyof AnalyticsSettings, boolean>> = {
         // Cookieless by design — nothing to permit, nothing to withdraw.
@@ -100,7 +100,16 @@ export function consentRequired(
         google: googleEmits(analytics.google),
     };
 
-    return Object.values(VENDORS).some(Boolean);
+    return (Object.keys(VENDORS) as (keyof AnalyticsSettings)[]).filter(
+        (vendor) => VENDORS[vendor]
+    );
+}
+
+/** Whether any vendor this deployment loads needs permission. */
+export function consentRequired(
+    analytics: AnalyticsSettings | undefined
+): boolean {
+    return consentVendors(analytics).length > 0;
 }
 
 /**

package/src/astro/AutoDialog.astro

@@ -0,0 +1,40 @@
+---
+/**
+ * A native `<dialog>` that opens by itself, around the site's own markup. The
+ * browser handles focus, Escape, the backdrop and a click outside
+ * (`closedby="any"`). Close it with `<form method="dialog"><button>…</button></form>`.
+ *
+ * ```astro
+ * <AutoDialog id="promo" aria-label="…" after={2000} once="session">…</AutoDialog>
+ * ```
+ *
+ * A dialog opened only by a button or a script needs none of this: write
+ * `<dialog closedby="any">`.
+ */
+import type { HTMLAttributes } from "astro/types";
+import AtlasElement from "./AtlasElement.astro";
+import { type AutoOpen, autoDialog } from "./auto-dialog.ts";
+
+type Props = AutoOpen &
+    Omit<HTMLAttributes<"dialog">, "id" | "open"> & {
+        readonly id: string;
+    };
+
+const { after, once, waitForConsent, modal, ...attrs } = Astro.props;
+const auto: AutoOpen = { after, once, waitForConsent, modal };
+---
+
+<script src="./auto-dialog.ts" />
+
+<AtlasElement
+    of={autoDialog}
+    data-auto={JSON.stringify(auto)}
+    style="display:contents"
+>
+    <dialog
+        closedby="any"
+        {...attrs}
+    >
+        <slot />
+    </dialog>
+</AtlasElement>

package/src/astro/Document.astro

@@ -16,6 +16,9 @@
  * It sends a reader arriving from elsewhere to the page in the language they
  * last chose; see `RememberLocale.astro`. `rememberLocale={false}` turns it off.
  *
+ * A deployment whose analytics need permission must pass its banner in the
+ * `consent` slot — `<ConsentBanner slot="consent" …>` — or the build fails.
+ *
  * `fonts={site.fonts}` writes the `@font-face` rules and preloads for the
  * faces `siteFonts(site)` registered in the Astro config.
  *
@@ -58,6 +61,12 @@ const {
     rememberCampaign = false,
     rememberLocale = true,
 } = Astro.props;
+
+if (meta.consentVendors.length > 0 && !Astro.slots.has("consent")) {
+    throw new Error(
+        `${meta.consentVendors.join(", ")} ${meta.consentVendors.length === 1 ? "needs" : "need"} permission, but this page has no consent banner. Pass one to Document: <ConsentBanner slot="consent" …>.`
+    );
+}
 ---
 
 <!doctype html>
@@ -71,13 +80,17 @@ const {
         <MetaTags tags={meta.tags} />
         {rememberLocale && <RememberLocale />}
         {Object.entries(fonts).map(([key, font]) => (
-            <Font cssVariable={`--${key}`} preload={font.preload === true} />
-        ))}
+    <Font
+        cssVariable={`--${key}`}
+        preload={font.preload === true}
+    />
+))}
         <slot name="head" />
     </head>
     <body {...body}>
         <MetaTags tags={meta.bodyTags} />
         <slot />
+        <slot name="consent" />
         {restoreScroll && <ScrollRestore />}
         {rememberCampaign && <RememberCampaign />}
     </body>

package/src/astro/GoogleMap.astro

@@ -0,0 +1,76 @@
+---
+/**
+ * A Google map of `places`, loaded only when asked for. Until then the element
+ * shows its children: a picture and a button, say. With `load="click"` (the
+ * default) a click anywhere on them loads it; with `"visible"`, scrolling near.
+ *
+ * `mapId` is required: markers are `AdvancedMarkerElement`, which needs one,
+ * and its colours are set on the Map ID in the Cloud console. `colorScheme`
+ * picks that style's light or dark variant; the site's own, so a dark site
+ * never gets Google's default light map.
+ *
+ * Give the element its size; the map fills it.
+ *
+ * ```astro
+ * <GoogleMap apiKey={key} mapId={id} colorScheme="DARK" places={[{ at, label, href }]} class="block h-96">
+ *     <button type="button">Show map</button>
+ * </GoogleMap>
+ * ```
+ */
+import type { HTMLAttributes } from "astro/types";
+import { type MapPlace, mapFrame } from "../map.ts";
+import type { NonEmpty } from "../types.ts";
+import AtlasElement from "./AtlasElement.astro";
+import { type GoogleMapConfig, googleMap } from "./google-map.ts";
+
+type Props = HTMLAttributes<"div"> & {
+    readonly apiKey: string;
+    readonly mapId: string;
+    readonly places: NonEmpty<MapPlace>;
+    readonly load?: GoogleMapConfig["load"];
+    readonly colorScheme: GoogleMapConfig["colorScheme"];
+};
+
+const {
+    apiKey,
+    mapId,
+    places,
+    load = "click",
+    colorScheme,
+    ...attrs
+} = Astro.props;
+
+const config: GoogleMapConfig = {
+    apiKey,
+    mapId,
+    load,
+    colorScheme,
+    frame: mapFrame(places),
+    places: places.map(({ at, label, href, pin }) => ({
+        lat: at.latitude,
+        lng: at.longitude,
+        label,
+        href,
+        pin:
+            pin === undefined
+                ? undefined
+                : {
+                      src: pin.image.src,
+                      width: pin.width,
+                      height: Math.round(
+                          (pin.width * pin.image.height) / pin.image.width
+                      ),
+                  },
+    })),
+};
+---
+
+<script src="./google-map.ts" />
+
+<AtlasElement
+    of={googleMap}
+    {...attrs}
+    data-map={JSON.stringify(config)}
+>
+    <slot />
+</AtlasElement>

package/src/astro/auto-dialog.ts

@@ -0,0 +1,72 @@
+import { CONSENT_EVENT, CONSENT_TAG, readConsent } from "./consent.ts";
+import { element } from "./element.ts";
+import { data, ref } from "./ref.ts";
+
+/** When an `<AutoDialog>` opens by itself. */
+export interface AutoOpen {
+    /** Milliseconds after load, or after the consent answer with `waitForConsent`. */
+    readonly after: number;
+    /**
+     * Once closed, stays closed for the tab (`session`) or for good (`visitor`).
+     * Omitted, it opens on every page.
+     */
+    readonly once?: "session" | "visitor";
+    /** Holds the timer until the consent banner is answered, where it asks. */
+    readonly waitForConsent?: boolean;
+    /** Defaults to `true`; `false` leaves the page usable behind it. */
+    readonly modal?: boolean;
+}
+
+const storage = (once: "session" | "visitor"): Storage =>
+    once === "session" ? sessionStorage : localStorage;
+
+/** Opens `dialog` as `options` say, until `signal` aborts. */
+export function autoOpen(
+    dialog: HTMLDialogElement,
+    { after, once, waitForConsent = false, modal = true }: AutoOpen,
+    signal: AbortSignal
+): void {
+    const key = `atlas-dialog:${dialog.id}`;
+    // Storage is blocked in some private windows: then it opens every time.
+    try {
+        if (once !== undefined && storage(once).getItem(key) !== null) return;
+    } catch {}
+
+    if (once !== undefined) {
+        dialog.addEventListener(
+            "close",
+            () => {
+                try {
+                    storage(once).setItem(key, "closed");
+                } catch {}
+            },
+            { signal }
+        );
+    }
+
+    const start = () => {
+        const timer = setTimeout(() => {
+            if (dialog.open) return;
+            if (modal) dialog.showModal();
+            else dialog.show();
+        }, after);
+        signal.addEventListener("abort", () => clearTimeout(timer));
+    };
+
+    const asking =
+        document.querySelector(CONSENT_TAG) !== null &&
+        readConsent() === undefined;
+    if (waitForConsent && asking) {
+        addEventListener(CONSENT_EVENT, start, { once: true, signal });
+    } else {
+        start();
+    }
+}
+
+export const autoDialog = element("atlas-dialog", ({ root, signal }) => {
+    autoOpen(
+        ref<HTMLDialogElement>(root, "dialog"),
+        JSON.parse(data(root, "auto")),
+        signal
+    );
+});

package/src/astro/consent-element.ts

@@ -1,5 +1,6 @@
 import { CONSENT_CATEGORIES } from "../analytics/consent-storage.ts";
 import {
+    CONSENT_TAG,
     type ConsentCategory,
     type ConsentChoices,
     everyCategory,
@@ -36,7 +37,7 @@ import { data, ref, refs } from "./ref.ts";
  * `data-consent-reopen hidden`: it stays hidden until there is an answer to
  * withdraw.
  */
-export const consentBanner = element("atlas-consent", ({ root, signal }) => {
+export const consentBanner = element(CONSENT_TAG, ({ root, signal }) => {
     const boxes = refs<HTMLInputElement>(root, "[data-consent-category]").map(
         (box) => {
             const category = data(box, "consent-category");

package/src/astro/consent.ts

@@ -86,6 +86,9 @@ export function readConsent(): ConsentRecord | undefined {
  */
 export const CONSENT_EVENT = "atlas:consent";
 
+/** The banner's tag: on the page only where this deployment asks for consent. */
+export const CONSENT_TAG = "atlas-consent";
+
 /**
  * Remembers an answer, dated now, tells Google about it, and announces it — one
  * call, so the three cannot come apart.

package/src/astro/google-map.ts

@@ -0,0 +1,135 @@
+/// <reference types="google.maps" />
+import type { MapFrame } from "../map.ts";
+import { reportDevError } from "./dev-log.ts";
+import { element } from "./element.ts";
+import { data } from "./ref.ts";
+
+/** What `GoogleMap.astro` hands the element, serialised. */
+export interface GoogleMapConfig {
+    readonly apiKey: string;
+    readonly mapId: string;
+    readonly load: "click" | "visible";
+    readonly colorScheme: google.maps.ColorSchemeString;
+    readonly frame: MapFrame;
+    readonly places: readonly {
+        readonly lat: number;
+        readonly lng: number;
+        readonly label: string;
+        readonly href?: string;
+        readonly pin?: {
+            readonly src: string;
+            readonly width: number;
+            readonly height: number;
+        };
+    }[];
+}
+
+const CALLBACK = "__atlasGoogleMaps";
+
+let loading: Promise<typeof google.maps> | undefined;
+
+/** The Maps JavaScript API, fetched once per page however many maps ask. */
+export function loadGoogleMaps(apiKey: string): Promise<typeof google.maps> {
+    loading ??= new Promise((resolve, reject) => {
+        (window as unknown as Record<string, () => void>)[CALLBACK] = () =>
+            resolve(google.maps);
+        const script = document.createElement("script");
+        script.src = `https://maps.googleapis.com/maps/api/js?${new URLSearchParams(
+            { key: apiKey, v: "weekly", loading: "async", callback: CALLBACK }
+        )}`;
+        script.async = true;
+        script.onerror = () => {
+            // So the next click tries again.
+            loading = undefined;
+            reject(new Error("the Maps JavaScript API failed to load"));
+        };
+        document.head.append(script);
+    });
+    return loading;
+}
+
+async function draw(root: HTMLElement, config: GoogleMapConfig) {
+    const maps = await loadGoogleMaps(config.apiKey);
+    const [{ Map: GoogleMapClass, InfoWindow }, { AdvancedMarkerElement }] =
+        await Promise.all([
+            maps.importLibrary("maps"),
+            maps.importLibrary("marker"),
+        ]);
+
+    const container = document.createElement("div");
+    container.style.width = "100%";
+    container.style.height = "100%";
+    root.replaceChildren(container);
+
+    const { frame } = config;
+    const map = new GoogleMapClass(container, {
+        mapId: config.mapId,
+        colorScheme: config.colorScheme,
+        ...(frame.kind === "point"
+            ? { center: frame.center, zoom: frame.zoom }
+            : {
+                  center: {
+                      lat: (frame.south + frame.north) / 2,
+                      lng: (frame.west + frame.east) / 2,
+                  },
+                  zoom: 1,
+              }),
+    });
+    if (frame.kind === "bounds") {
+        const { south, west, north, east } = frame;
+        map.fitBounds({ south, west, north, east }, 50);
+    }
+
+    const info = new InfoWindow();
+    for (const place of config.places) {
+        let content: HTMLImageElement | undefined;
+        if (place.pin !== undefined) {
+            content = document.createElement("img");
+            content.src = place.pin.src;
+            content.alt = "";
+            content.width = place.pin.width;
+            content.height = place.pin.height;
+        }
+        const marker = new AdvancedMarkerElement({
+            map,
+            position: { lat: place.lat, lng: place.lng },
+            title: place.label,
+            content,
+            gmpClickable: place.href !== undefined,
+        });
+        const { href } = place;
+        if (href === undefined) continue;
+        marker.addEventListener("gmp-click", () => {
+            const link = document.createElement("a");
+            link.href = href;
+            link.target = "_blank";
+            link.rel = "noopener";
+            link.textContent = place.label;
+            info.setContent(link);
+            info.open({ anchor: marker, map });
+        });
+    }
+}
+
+/** Internal to `GoogleMap.astro`. */
+export const googleMap = element("atlas-google-map", ({ root, signal }) => {
+    const config: GoogleMapConfig = JSON.parse(data(root, "map"));
+    const show = () => {
+        draw(root, config).catch((error) => reportDevError("GoogleMap", error));
+    };
+
+    if (config.load === "click") {
+        root.addEventListener("click", show, { once: true, signal });
+        return;
+    }
+    const observer = new IntersectionObserver(
+        (entries) => {
+            if (!entries.some((entry) => entry.isIntersecting)) return;
+            observer.disconnect();
+            show();
+        },
+        { rootMargin: "200px" }
+    );
+    observer.observe(root);
+    return () => observer.disconnect();
+});

package/src/index.ts

@@ -26,6 +26,7 @@ export {
     type ConsentDefaults,
     type ConsentState,
     consentRequired,
+    consentVendors,
     type GoogleSettings,
     type UmamiReplay,
     type UmamiSettings,
@@ -164,6 +165,7 @@ export {
     type LlmsItem,
     type LlmsSection,
 } from "./llms.ts";
+export type { MapPlace } from "./map.ts";
 export {
     type ArticleContent,
     buildMeta,

package/src/map.ts

@@ -0,0 +1,54 @@
+import { assertCoordinates, type Coordinates } from "./contact.ts";
+import type { ImageAsset } from "./image.ts";
+import type { NonEmpty } from "./types.ts";
+import type { HttpsUrl } from "./url.ts";
+
+/** A marker on a map. */
+export interface MapPlace {
+    readonly at: Coordinates;
+    /** The marker's title, and the info window's text. */
+    readonly label: string;
+    /** Opened from the info window, usually the place on Google Maps. None: no info window. */
+    readonly href?: HttpsUrl;
+    /** A custom pin, drawn `width` pixels wide. */
+    readonly pin?: { readonly image: ImageAsset; readonly width: number };
+}
+
+/** What the map shows first: one place close up, or every place in view. */
+export type MapFrame =
+    | {
+          readonly kind: "point";
+          readonly center: { readonly lat: number; readonly lng: number };
+          readonly zoom: number;
+      }
+    | {
+          readonly kind: "bounds";
+          readonly south: number;
+          readonly west: number;
+          readonly north: number;
+          readonly east: number;
+      };
+
+/** Street level: close enough to find the door. */
+const POINT_ZOOM = 15;
+
+export function mapFrame(places: NonEmpty<MapPlace>): MapFrame {
+    for (const place of places) assertCoordinates(place.at, place.label);
+
+    const latitudes = places.map((place) => place.at.latitude);
+    const longitudes = places.map((place) => place.at.longitude);
+    const south = Math.min(...latitudes);
+    const north = Math.max(...latitudes);
+    const west = Math.min(...longitudes);
+    const east = Math.max(...longitudes);
+
+    // Bounds around one point would zoom in as far as the map goes.
+    if (south === north && west === east) {
+        return {
+            kind: "point",
+            center: { lat: south, lng: west },
+            zoom: POINT_ZOOM,
+        };
+    }
+    return { kind: "bounds", south, west, north, east };
+}

package/src/site/create.ts

@@ -1,3 +1,4 @@
+import { consentVendors } from "../analytics/index.ts";
 import {
     type LocaleMeta,
     type LocalesOf,
@@ -342,6 +343,8 @@ export function createSite<
             // Nothing. The body channel exists for Tag Manager's `<noscript>`,
             // and no Google tag reaches this page.
             bodyTags: [],
+            // Umami only, which asks nobody.
+            consentVendors: [],
         };
     }
 
@@ -418,6 +421,7 @@ export function createSite<
             dir: localeMeta[locale].dir,
             tags: document.head,
             bodyTags: document.body,
+            consentVendors: consentVendors(project.analytics),
         };
     }
 

package/src/site/page.ts

@@ -65,6 +65,8 @@ export interface PageMeta {
      * both, and cannot put either in the other's place.
      */
     readonly bodyTags: MetaTag[];
+    /** The vendors that need a consent banner on this page; `Document` fails without one. */
+    readonly consentVendors: readonly string[];
 }
 
 /**