@escape-game-over/atlas 0.1.50 → 0.1.53

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.50",
+    "version": "0.1.53",
     "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/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

@@ -13,6 +13,9 @@
  * A site with a lead form passes `rememberCampaign`, so the `utm_*` tags a
  * visit landed with survive to the page the form is on; see `attribution.ts`.
  *
+ * It sends a reader arriving from elsewhere to the page in the language they
+ * last chose; see `RememberLocale.astro`. `rememberLocale={false}` turns it off.
+ *
  * `fonts={site.fonts}` writes the `@font-face` rules and preloads for the
  * faces `siteFonts(site)` registered in the Astro config.
  *
@@ -29,6 +32,7 @@ import type { Fonts } from "../fonts.ts";
 import type { PageMeta } from "../site/index.ts";
 import MetaTags from "./MetaTags.astro";
 import RememberCampaign from "./RememberCampaign.astro";
+import RememberLocale from "./RememberLocale.astro";
 import ScrollRestore from "./ScrollRestore.astro";
 
 interface Props {
@@ -41,6 +45,8 @@ interface Props {
     readonly restoreScroll?: boolean;
     /** Off unless stated: a site with no lead form has nothing to keep them for. */
     readonly rememberCampaign?: boolean;
+    /** Defaults to `true`. */
+    readonly rememberLocale?: boolean;
 }
 
 const {
@@ -50,6 +56,7 @@ const {
     body,
     restoreScroll = true,
     rememberCampaign = false,
+    rememberLocale = true,
 } = Astro.props;
 ---
 
@@ -62,9 +69,13 @@ const {
     <head>
         <slot name="head-start" />
         <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}>

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/RememberLocale.astro

@@ -0,0 +1,23 @@
+---
+/**
+ * Opens a page in the language its reader chose, however they reached it.
+ *
+ * The choice is the locale of the last page reached from inside the site, so
+ * using the language switcher makes it and a shared link does not. Arriving
+ * from anywhere else, a reader is sent to this page in their chosen locale when
+ * the head lists an alternate for it. Crawlers keep no storage, so they are
+ * never sent anywhere.
+ *
+ * Rendered by `Document` after the head tags, whose alternates it reads.
+ * Inline and blocking, so the wrong language is never painted.
+ */
+import { inlineScript } from "./inline-script.ts";
+import source from "./remember-locale.ts?raw";
+
+const code = await inlineScript(source);
+---
+
+<script
+    is:inline
+    set:html={code}
+/>

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/astro/remember-locale.ts

@@ -0,0 +1,35 @@
+// The body of `RememberLocale.astro`'s inline script. A classic script: no
+// imports or exports, and the block keeps its names out of the global scope.
+{
+    const KEY = "atlas-locale";
+    const current = document.documentElement.lang;
+
+    const remember = () => {
+        // Came from this site: the visitor is browsing, or just switched
+        // language. Either way, this locale is their choice.
+        if (document.referrer.startsWith(`${location.origin}/`)) {
+            localStorage.setItem(KEY, current);
+            return;
+        }
+
+        const chosen = localStorage.getItem(KEY);
+        if (chosen === null || chosen === current) return;
+
+        // No alternate means this page is not built in that locale.
+        const alternate = document.querySelector<HTMLLinkElement>(
+            `link[rel="alternate"][hreflang="${CSS.escape(chosen)}"]`
+        );
+        if (alternate === null) return;
+
+        // Path only: alternates carry the production origin, not a preview's.
+        location.replace(
+            new URL(alternate.href).pathname + location.search + location.hash
+        );
+    };
+
+    try {
+        remember();
+    } catch {
+        // Storage is blocked in some private windows.
+    }
+}

package/src/index.ts

@@ -164,6 +164,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 };
+}