@escape-game-over/atlas 0.1.62 → 0.1.63

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.62",
+    "version": "0.1.63",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,

package/src/analytics/axon-pixel.ts

@@ -1,5 +1,4 @@
-import { warn } from "../warn.ts";
-import { UUID } from "./snap-pixel.ts";
+import { invalidId, UUID, type Uuid } from "./ids.ts";
 
 /**
  * AppLovin's Axon pixel. Marketing: it loads only once a visitor grants that.
@@ -9,17 +8,17 @@ import { UUID } from "./snap-pixel.ts";
  */
 export interface AxonPixelSettings {
     /** From the Axon dashboard: a UUID. */
-    readonly eventKey: string;
+    readonly eventKey: Uuid;
 }
 
-/** Warns about a key that is not an event key: it would report nowhere. */
+/** Fails the build on a key that is not an event key: it would report nowhere. */
 export function checkAxonPixel(
     axon: AxonPixelSettings | undefined,
     at: string
 ): void {
     if (axon === undefined || UUID.test(axon.eventKey)) return;
-    warn(
+    invalidId(
         at,
-        `Axon event key "${axon.eventKey}" is not a UUID, so it reports nowhere. Copy it from the Axon dashboard.`
+        `Axon event key "${axon.eventKey}" is not a UUID, so it would report nowhere. Copy it from the Axon dashboard.`
     );
 }

package/src/analytics/clarity.ts

@@ -1,4 +1,4 @@
-import { warn } from "../warn.ts";
+import { CLARITY_PROJECT_ID, invalidId } from "./ids.ts";
 
 /**
  * Microsoft Clarity. It has a cookieless mode, so like Google it loads for
@@ -14,16 +14,16 @@ export interface ClaritySettings {
     readonly projectId: string;
 }
 
-/** Warns about an id that is not a project id: it would report nowhere. */
+/** Fails the build on an id that is not a project id: it would report nowhere. */
 export function checkClarity(
     clarity: ClaritySettings | undefined,
     at: string
 ): void {
-    if (clarity === undefined || /^[a-z0-9]{10}$/.test(clarity.projectId)) {
+    if (clarity === undefined || CLARITY_PROJECT_ID.test(clarity.projectId)) {
         return;
     }
-    warn(
+    invalidId(
         at,
-        `Clarity project id "${clarity.projectId}" is not 10 lowercase letters and digits, so it reports nowhere. Copy it from the Clarity project's settings.`
+        `Clarity project id "${clarity.projectId}" is not 10 lowercase letters and digits, so it would report nowhere. Copy it from the Clarity project's settings.`
     );
 }

package/src/analytics/drip.ts

@@ -1,4 +1,4 @@
-import { warn } from "../warn.ts";
+import { DRIP_ACCOUNT_ID, invalidId, type NumericId } from "./ids.ts";
 
 /**
  * Drip's site tracking. Marketing: it loads only once a visitor grants that.
@@ -7,14 +7,14 @@ import { warn } from "../warn.ts";
  */
 export interface DripSettings {
     /** From Drip's Site Setup: digits, the `_dcs.account` of its snippet. */
-    readonly accountId: string;
+    readonly accountId: NumericId;
 }
 
-/** Warns about an id that is not an account id: it would report nowhere. */
+/** Fails the build on an id that is not an account id: it would report nowhere. */
 export function checkDrip(drip: DripSettings | undefined, at: string): void {
-    if (drip === undefined || /^\d+$/.test(drip.accountId)) return;
-    warn(
+    if (drip === undefined || DRIP_ACCOUNT_ID.test(drip.accountId)) return;
+    invalidId(
         at,
-        `Drip account id "${drip.accountId}" is not all digits, so it reports nowhere. Copy it from Drip's Site Setup.`
+        `Drip account id "${drip.accountId}" is not all digits, so it would report nowhere. Copy it from Drip's Site Setup.`
     );
 }

package/src/analytics/google.ts

@@ -7,6 +7,7 @@ import {
     type ConsentCategory,
 } from "./consent-storage.ts";
 import googleTag from "./google-tag.ts?raw";
+import { type GoogleTagId, invalidId, type TagManagerId } from "./ids.ts";
 import { type AnalyticsTags, literal, preconnect } from "./tags.ts";
 
 /**
@@ -108,7 +109,7 @@ export interface GoogleSettings {
      * once, for the first, and the rest are configured against it — Google's
      * documented arrangement.
      */
-    readonly tagIds?: readonly string[];
+    readonly tagIds?: readonly GoogleTagId[];
     /**
      * Tag Manager container ids — `GTM-XXXXXXX`.
      *
@@ -117,7 +118,7 @@ export interface GoogleSettings {
      * which is most of why they are worth stating — they apply to tags nobody
      * here has seen.
      */
-    readonly containerIds?: readonly string[];
+    readonly containerIds?: readonly TagManagerId[];
     /**
      * What holds before a visitor has chosen. **Denied unless stated.**
      *
@@ -371,20 +372,21 @@ export function googleScripts(
     const containers = google.containerIds ?? [];
 
     // An id in the wrong field is the silent failure here: it is configured,
-    // it is emitted, and it reports nowhere — which reads as a quiet week.
+    // it is emitted, and it reports nowhere — which reads as a quiet week. So
+    // the build fails rather than warns.
     for (const id of tags) {
         if (id.startsWith("UA-")) {
-            warn(
+            invalidId(
                 at,
                 `"${id}" is a Universal Analytics property, and those stopped processing data on 1 July 2023 (1 July 2024 for 360). It reports nowhere. The GA4 property that replaced it starts with "G-". https://support.google.com/analytics/answer/11583528`
             );
         } else if (id.startsWith("GTM-")) {
-            warn(
+            invalidId(
                 at,
                 `"${id}" is a Tag Manager container, not something gtag can configure — it belongs in containerIds.`
             );
         } else if (!GTAG_PREFIXES.some((prefix) => id.startsWith(prefix))) {
-            warn(
+            invalidId(
                 at,
                 `"${id}" does not look like anything gtag configures: those start with ${GTAG_PREFIXES.join(", ")}.`
             );
@@ -392,7 +394,7 @@ export function googleScripts(
     }
     for (const id of containers) {
         if (!id.startsWith("GTM-")) {
-            warn(
+            invalidId(
                 at,
                 `"${id}" is configured as a Tag Manager container but does not look like one — those start with "GTM-".`
             );

package/src/analytics/ids.ts

@@ -0,0 +1,41 @@
+/**
+ * What an analytics id is declared as, and the error a wrong one raises.
+ *
+ * A wrong id fails silently — configured, emitted, reporting nowhere — so the
+ * build fails instead of warning: an id is config, and there is no page worth
+ * shipping with one that is wrong.
+ */
+
+/**
+ * The shapes an id's setting is declared with. As close as a type can get
+ * without a literal to inspect: a UUID's dashes, a Google prefix, digits. The
+ * exact format is checked when a page is built, and a wrong id fails the build.
+ */
+export type Uuid = `${string}-${string}-${string}-${string}-${string}`;
+/** A `gtag` id: GA4 `G-`, Google tag `GT-`, Ads `AW-`, Floodlight `DC-`. */
+export type GoogleTagId = `${"G" | "GT" | "AW" | "DC"}-${string}`;
+/** A Tag Manager container. */
+export type TagManagerId = `GTM-${string}`;
+/** An id that is a number written out: Meta's pixels, Drip's accounts. */
+export type NumericId = `${number}`;
+
+/** The error for an id that is not what its vendor issues. */
+export function invalidId(at: string, message: string): never {
+    throw new Error(`${at}: ${message}`);
+}
+
+/** A Meta pixel id: 15 or 16 digits. */
+export const META_PIXEL_ID = /^\d{15,16}$/;
+
+/** A TikTok pixel id: 20 capital letters and digits. */
+export const TIKTOK_PIXEL_ID = /^[A-Z0-9]{20}$/;
+
+/** A Drip account id: digits. */
+export const DRIP_ACCOUNT_ID = /^\d+$/;
+
+/** A Clarity project id: 10 lowercase letters and digits. */
+export const CLARITY_PROJECT_ID = /^[a-z0-9]{10}$/;
+
+/** A UUID, as Umami, Snap and Axon issue them. */
+export const UUID =
+    /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

package/src/analytics/index.ts

@@ -38,6 +38,7 @@ export {
     type ConsentState,
     type GoogleSettings,
 } from "./google.ts";
+export type { GoogleTagId, NumericId, TagManagerId, Uuid } from "./ids.ts";
 export type { MetaPixelSettings } from "./meta-pixel.ts";
 export type { SnapPixelSettings } from "./snap-pixel.ts";
 export type { AnalyticsTags } from "./tags.ts";

package/src/analytics/meta-pixel.ts

@@ -1,5 +1,5 @@
 import type { NonEmpty } from "../types.ts";
-import { warn } from "../warn.ts";
+import { invalidId, META_PIXEL_ID, type NumericId } from "./ids.ts";
 
 /**
  * Meta's pixel. Marketing: it loads only once a visitor grants that.
@@ -10,19 +10,19 @@ import { warn } from "../warn.ts";
  */
 export interface MetaPixelSettings {
     /** From Events Manager: 15 or 16 digits. Several share one script. */
-    readonly pixelIds: NonEmpty<string>;
+    readonly pixelIds: NonEmpty<NumericId>;
 }
 
-/** Warns about an id that is not a pixel id: it would report nowhere. */
+/** Fails the build on an id that is not a pixel id: it would report nowhere. */
 export function checkMetaPixel(
     meta: MetaPixelSettings | undefined,
     at: string
 ): void {
     for (const id of meta?.pixelIds ?? []) {
-        if (!/^\d{15,16}$/.test(id)) {
-            warn(
+        if (!META_PIXEL_ID.test(id)) {
+            invalidId(
                 at,
-                `Meta pixel id "${id}" is not 15 or 16 digits, so it reports nowhere. Copy it from Events Manager.`
+                `Meta pixel id "${id}" is not 15 or 16 digits, so it would report nowhere. Copy it from Events Manager.`
             );
         }
     }

package/src/analytics/snap-pixel.ts

@@ -1,5 +1,5 @@
 import type { NonEmpty } from "../types.ts";
-import { warn } from "../warn.ts";
+import { invalidId, UUID, type Uuid } from "./ids.ts";
 
 /**
  * Snapchat's pixel. Marketing: it loads only once a visitor grants that.
@@ -9,22 +9,19 @@ import { warn } from "../warn.ts";
  */
 export interface SnapPixelSettings {
     /** From Snap's Events Manager: a UUID. */
-    readonly pixelIds: NonEmpty<string>;
+    readonly pixelIds: NonEmpty<Uuid>;
 }
 
-export const UUID =
-    /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-
-/** Warns about an id that is not a pixel id: it would report nowhere. */
+/** Fails the build on an id that is not a pixel id: it would report nowhere. */
 export function checkSnapPixel(
     snapchat: SnapPixelSettings | undefined,
     at: string
 ): void {
     for (const id of snapchat?.pixelIds ?? []) {
         if (!UUID.test(id)) {
-            warn(
+            invalidId(
                 at,
-                `Snap pixel id "${id}" is not a UUID, so it reports nowhere. Copy it from Snap's Events Manager.`
+                `Snap pixel id "${id}" is not a UUID, so it would report nowhere. Copy it from Snap's Events Manager.`
             );
         }
     }

package/src/analytics/tiktok-pixel.ts

@@ -1,5 +1,5 @@
 import type { NonEmpty } from "../types.ts";
-import { warn } from "../warn.ts";
+import { invalidId, TIKTOK_PIXEL_ID } from "./ids.ts";
 
 /**
  * TikTok's pixel. Marketing: it loads only once a visitor grants that.
@@ -13,16 +13,16 @@ export interface TikTokPixelSettings {
     readonly pixelIds: NonEmpty<string>;
 }
 
-/** Warns about an id that is not a pixel id: it would report nowhere. */
+/** Fails the build on an id that is not a pixel id: it would report nowhere. */
 export function checkTikTokPixel(
     tiktok: TikTokPixelSettings | undefined,
     at: string
 ): void {
     for (const id of tiktok?.pixelIds ?? []) {
-        if (!/^[A-Z0-9]{20}$/.test(id)) {
-            warn(
+        if (!TIKTOK_PIXEL_ID.test(id)) {
+            invalidId(
                 at,
-                `TikTok pixel id "${id}" is not 20 capital letters and digits, so it reports nowhere. Copy it from TikTok Events Manager.`
+                `TikTok pixel id "${id}" is not 20 capital letters and digits, so it would report nowhere. Copy it from TikTok Events Manager.`
             );
         }
     }

package/src/analytics/umami.ts

@@ -2,6 +2,7 @@ import type { MetaTag } from "../meta/tag.ts";
 import type { NonEmpty } from "../types.ts";
 import { type HttpsUrl, joinUrl, type UrlPath } from "../url.ts";
 import { warn } from "../warn.ts";
+import { invalidId, UUID, type Uuid } from "./ids.ts";
 import { preconnect } from "./tags.ts";
 
 /**
@@ -102,7 +103,7 @@ export interface UmamiSettings {
      * single site, and nobody notices until one venue's traffic appears to
      * double the week another launches.
      */
-    readonly websiteId: string;
+    readonly websiteId: Uuid;
     /**
      * Where the scripts are served from — `https://src.example.com`.
      *
@@ -188,7 +189,8 @@ const stated = (
     ) as Readonly<Record<string, string>>;
 
 /**
- * Warns when the `domains` list leaves out the host the site is served from.
+ * Fails the build on a website id that is not a UUID, and warns when the
+ * `domains` list leaves out the host the site is served from.
  *
  * Separate from building the scripts because the pages are not the only thing
  * that builds them — the 404 does too — and a check that ran per caller would
@@ -207,6 +209,12 @@ export function checkUmamiDomains(
     origin: HttpsUrl
 ): void {
     if (umami === undefined) return;
+    if (!UUID.test(umami.websiteId)) {
+        invalidId(
+            origin,
+            `Umami website id "${umami.websiteId}" is not a UUID, so it would record nowhere. Copy it from the Umami dashboard.`
+        );
+    }
     const site = new URL(origin).hostname;
     if (umami.domains.includes(site)) return;
 

package/src/astro/append-script.ts

@@ -1,8 +1,14 @@
-/** Fetches a vendor's script without blocking the page. */
-export function appendScript(src: string): HTMLScriptElement {
+/**
+ * Fetches a vendor's script without blocking the page: into `<head>`, or into
+ * `into` for a widget that renders where its script stands.
+ */
+export function appendScript(
+    src: string,
+    into: Element = document.head
+): HTMLScriptElement {
     const script = document.createElement("script");
     script.async = true;
     script.src = src;
-    document.head.append(script);
+    into.append(script);
     return script;
 }

package/src/astro/google-map.ts

@@ -3,6 +3,7 @@ import type { MapFrame } from "../map.ts";
 import { appendScript } from "./append-script.ts";
 import { reportDevError } from "./dev-log.ts";
 import { element } from "./element.ts";
+import { triggered } from "./load-script.ts";
 import { data } from "./ref.ts";
 
 /** What `GoogleMap.astro` hands the element, serialised. */
@@ -121,18 +122,10 @@ export const googleMap = element("atlas-google-map", ({ root, signal }) => {
         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();
+    triggered(
+        config.load === "click"
+            ? { on: "click", element: root }
+            : { on: "visible", element: root },
+        signal
+    ).then(show);
 });

package/src/astro/load-script.ts

@@ -0,0 +1,145 @@
+import { appendScript } from "./append-script.ts";
+
+/** When a script is fetched. All but `click` also wait for the page's `load`. */
+export type LoadTrigger =
+    /** At `load`. */
+    | { readonly on: "load" }
+    /** After `load`, once the browser has nothing else to do. */
+    | { readonly on: "idle" }
+    /** After `load`, `ms` later. */
+    | { readonly on: "delay"; readonly ms: number }
+    /** When `element` comes within `margin` of the viewport. */
+    | {
+          readonly on: "visible";
+          readonly element: Element;
+          readonly margin?: string;
+      }
+    /** At the visitor's first tap, click, key or scroll anywhere. */
+    | { readonly on: "interaction" }
+    /** When `element` is clicked: a visitor asking for it. */
+    | { readonly on: "click"; readonly element: Element };
+
+export interface LoadScriptOptions {
+    readonly when: LoadTrigger;
+    /** Where the script goes, for a widget that renders beside it. Defaults to `<head>`. */
+    readonly into?: Element;
+    /** Cancels a load not yet triggered. */
+    readonly signal?: AbortSignal;
+}
+
+const INTERACTIONS = ["pointerdown", "keydown", "scroll", "touchstart"];
+
+function afterLoad(signal?: AbortSignal): Promise<void> {
+    return new Promise((resolve) => {
+        if (document.readyState === "complete") resolve();
+        else addEventListener("load", () => resolve(), { once: true, signal });
+    });
+}
+
+/** Resolves when `when` fires, on its own. */
+function fires(when: LoadTrigger, signal?: AbortSignal): Promise<void> {
+    return new Promise<void>((resolve) => {
+        const done = () => {
+            if (!signal?.aborted) resolve();
+        };
+        switch (when.on) {
+            case "load":
+                done();
+                return;
+            case "idle":
+                // Not in Safari: a frame later is its nearest equivalent.
+                if (typeof requestIdleCallback === "function") {
+                    requestIdleCallback(done);
+                } else {
+                    setTimeout(done, 1);
+                }
+                return;
+            case "delay":
+                setTimeout(done, when.ms);
+                return;
+            case "visible": {
+                const observer = new IntersectionObserver(
+                    (entries) => {
+                        if (!entries.some((entry) => entry.isIntersecting)) {
+                            return;
+                        }
+                        observer.disconnect();
+                        done();
+                    },
+                    { rootMargin: when.margin ?? "200px" }
+                );
+                observer.observe(when.element);
+                signal?.addEventListener("abort", () => observer.disconnect());
+                return;
+            }
+            case "interaction": {
+                const controller = new AbortController();
+                signal?.addEventListener("abort", () => controller.abort());
+                for (const type of INTERACTIONS) {
+                    addEventListener(
+                        type,
+                        () => {
+                            controller.abort();
+                            done();
+                        },
+                        { once: true, passive: true, signal: controller.signal }
+                    );
+                }
+                return;
+            }
+            case "click":
+                when.element.addEventListener("click", done, {
+                    once: true,
+                    signal,
+                });
+                return;
+        }
+    });
+}
+
+/**
+ * Resolves when `when` fires; never, if `signal` aborts first.
+ *
+ * A click is a visitor asking, so it is answered at once. Every other trigger
+ * also waits for `load`: an interaction is listened for from the start, so an
+ * early one still counts, and the rest start counting at `load`.
+ */
+export async function triggered(
+    when: LoadTrigger,
+    signal?: AbortSignal
+): Promise<void> {
+    if (when.on === "click") return fires(when, signal);
+    if (when.on === "interaction") {
+        await Promise.all([fires(when, signal), afterLoad(signal)]);
+        return;
+    }
+    await afterLoad(signal);
+    await fires(when, signal);
+}
+
+const scripts = new Map<string, Promise<HTMLScriptElement>>();
+
+/**
+ * Fetches `src` once `when` fires, and once per page however many callers ask:
+ * each gets the same promise, which settles when the script has run. A failed
+ * fetch is forgotten, so the next caller tries again.
+ */
+export async function loadScript(
+    src: string,
+    { when, into, signal }: LoadScriptOptions
+): Promise<HTMLScriptElement> {
+    await triggered(when, signal);
+    let loading = scripts.get(src);
+    if (loading === undefined) {
+        loading = new Promise((resolve, reject) => {
+            const script = appendScript(src, into);
+            script.addEventListener("load", () => resolve(script));
+            script.addEventListener("error", () => {
+                scripts.delete(src);
+                reject(new Error(`${src} failed to load`));
+            });
+        });
+        scripts.set(src, loading);
+    }
+    return loading;
+}

package/src/index.ts

@@ -31,12 +31,16 @@ export {
     consentVendors,
     type DripSettings,
     type GoogleSettings,
+    type GoogleTagId,
     type MetaPixelSettings,
+    type NumericId,
     type SnapPixelSettings,
+    type TagManagerId,
     type TikTokPixelSettings,
     type UmamiReplay,
     type UmamiSettings,
     type UmamiTracker,
+    type Uuid,
 } from "./analytics/index.ts";
 export type {
     LanguageTag,