@escape-game-over/atlas 0.1.59 → 0.1.60

package/package.json

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

package/src/analytics/axon-pixel.ts

@@ -1,7 +1,12 @@
 import { warn } from "../warn.ts";
 import { UUID } from "./snap-pixel.ts";
 
-/** AppLovin's Axon pixel. Marketing: it loads only once a visitor grants that. */
+/**
+ * AppLovin's Axon pixel. Marketing: it loads only once a visitor grants that.
+ *
+ * @see https://support.applovin.com/en/growth/promoting-your-websites/axon-pixel-integration/axon-pixel-native-js
+ * @see https://support.applovin.com/en/growth/promoting-your-websites/axon-pixel-integration/events-and-objects
+ */
 export interface AxonPixelSettings {
     /** From the Axon dashboard: a UUID. */
     readonly eventKey: string;

package/src/analytics/clarity.ts

@@ -0,0 +1,29 @@
+import { warn } from "../warn.ts";
+
+/**
+ * Microsoft Clarity. It has a cookieless mode, so like Google it loads for
+ * every visitor: without consent it records each page view on its own and sets
+ * no cookie, and the visitor's answer switches its cookies on or off.
+ *
+ * @see https://learn.microsoft.com/en-us/clarity/setup-and-installation/clarity-setup
+ * @see https://learn.microsoft.com/en-us/clarity/setup-and-installation/consent-mode
+ * @see https://learn.microsoft.com/en-us/clarity/setup-and-installation/clarity-consent-api-v2
+ */
+export interface ClaritySettings {
+    /** From the Clarity project's settings: 10 lowercase letters and digits. */
+    readonly projectId: string;
+}
+
+/** Warns about 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)) {
+        return;
+    }
+    warn(
+        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.`
+    );
+}

package/src/analytics/drip.ts

@@ -1,6 +1,10 @@
 import { warn } from "../warn.ts";
 
-/** Drip's site tracking. Marketing: it loads only once a visitor grants that. */
+/**
+ * Drip's site tracking. Marketing: it loads only once a visitor grants that.
+ *
+ * @see https://help.drip.com/hc/en-us/articles/4424702539789-Install-Your-JavaScript-Snippet
+ */
 export interface DripSettings {
     /** From Drip's Site Setup: digits, the `_dcs.account` of its snippet. */
     readonly accountId: string;

package/src/analytics/index.ts

@@ -1,6 +1,7 @@
 import type { MetaTag } from "../meta/tag.ts";
 import type { HttpsUrl } from "../url.ts";
 import { type AxonPixelSettings, checkAxonPixel } from "./axon-pixel.ts";
+import { type ClaritySettings, checkClarity } from "./clarity.ts";
 import { checkDrip, type DripSettings } from "./drip.ts";
 import { type GoogleSettings, googleEmits, googleScripts } from "./google.ts";
 import { checkMetaPixel, type MetaPixelSettings } from "./meta-pixel.ts";
@@ -29,6 +30,7 @@ import {
  */
 
 export type { AxonPixelSettings } from "./axon-pixel.ts";
+export type { ClaritySettings } from "./clarity.ts";
 export type { DripSettings } from "./drip.ts";
 export {
     CONSENT_UPDATE_GLOBAL,
@@ -60,6 +62,8 @@ export interface AnalyticsSettings {
     readonly axon?: AxonPixelSettings;
     /** Loaded by `ConsentBanner`, after marketing is granted. */
     readonly drip?: DripSettings;
+    /** Loaded by `ConsentBanner` for every visitor, cookieless until analytics is granted. */
+    readonly clarity?: ClaritySettings;
 }
 
 /**
@@ -85,6 +89,7 @@ export function analyticsScripts(
     checkSnapPixel(analytics.snapchat, origin);
     checkAxonPixel(analytics.axon, origin);
     checkDrip(analytics.drip, origin);
+    checkClarity(analytics.clarity, origin);
     const google = googleScripts(analytics.google, origin);
     return {
         head: [...google.head, ...umamiScripts(analytics.umami)],
@@ -133,6 +138,9 @@ export function consentVendors(
         axon: analytics.axon !== undefined,
         // No consent mode at all.
         drip: analytics.drip !== undefined,
+        // Cookieless without consent, but the answer is what switches its
+        // cookies on, so it needs the banner.
+        clarity: analytics.clarity !== undefined,
     };
 
     return (Object.keys(VENDORS) as (keyof AnalyticsSettings)[]).filter(

package/src/analytics/meta-pixel.ts

@@ -1,7 +1,13 @@
 import type { NonEmpty } from "../types.ts";
 import { warn } from "../warn.ts";
 
-/** Meta's pixel. Marketing: it loads only once a visitor grants that. */
+/**
+ * Meta's pixel. Marketing: it loads only once a visitor grants that.
+ *
+ * @see https://developers.facebook.com/docs/meta-pixel/get-started
+ * @see https://developers.facebook.com/docs/meta-pixel/reference
+ * @see https://developers.facebook.com/docs/meta-pixel/implementation/gdpr
+ */
 export interface MetaPixelSettings {
     /** From Events Manager: 15 or 16 digits. Several share one script. */
     readonly pixelIds: NonEmpty<string>;

package/src/analytics/snap-pixel.ts

@@ -1,7 +1,12 @@
 import type { NonEmpty } from "../types.ts";
 import { warn } from "../warn.ts";
 
-/** Snapchat's pixel. Marketing: it loads only once a visitor grants that. */
+/**
+ * Snapchat's pixel. Marketing: it loads only once a visitor grants that.
+ *
+ * @see https://businesshelp.snapchat.com/s/article/pixel-direct-implementation
+ * @see https://forbusiness.snapchat.com/en-US/blog/the-snap-pixel-how-it-works-and-how-to-install-it
+ */
 export interface SnapPixelSettings {
     /** From Snap's Events Manager: a UUID. */
     readonly pixelIds: NonEmpty<string>;

package/src/analytics/tiktok-pixel.ts

@@ -1,7 +1,13 @@
 import type { NonEmpty } from "../types.ts";
 import { warn } from "../warn.ts";
 
-/** TikTok's pixel. Marketing: it loads only once a visitor grants that. */
+/**
+ * TikTok's pixel. Marketing: it loads only once a visitor grants that.
+ *
+ * @see https://ads.tiktok.com/help/article/get-started-pixel
+ * @see https://ads.tiktok.com/help/article/standard-events-parameters
+ * @see https://ads.tiktok.com/help/article/how-to-use-cookies-with-tiktok-pixel
+ */
 export interface TikTokPixelSettings {
     /** From TikTok Events Manager: 20 capital letters and digits. */
     readonly pixelIds: NonEmpty<string>;

package/src/astro/Clarity.astro

@@ -0,0 +1,18 @@
+---
+/** Internal to `ConsentBanner.astro`, so Clarity's script ships only where it is configured. */
+import type { ClaritySettings } from "../analytics/clarity.ts";
+import AtlasElement from "./AtlasElement.astro";
+import { clarityElement } from "./clarity.ts";
+
+interface Props {
+    readonly settings: ClaritySettings;
+}
+---
+
+<script src="./clarity.ts" />
+
+<AtlasElement
+    of={clarityElement}
+    data-project-id={Astro.props.settings.projectId}
+    hidden
+/>

package/src/astro/ConsentBanner.astro

@@ -5,12 +5,13 @@
  * buttons.
  *
  * Renders nothing — and ships no script — when this site's analytics need no
- * permission. Also loads the vendors that wait for consent, such as the Meta, TikTok, Snap and Axon pixels and Drip. Otherwise the banner starts hidden and shows only to a visitor
+ * permission. Also loads the vendors that wait for consent, such as the Meta, TikTok, Snap and Axon pixels, Drip and Clarity. Otherwise the banner starts hidden and shows only to a visitor
  * 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";
 import AxonPixel from "./AxonPixel.astro";
+import Clarity from "./Clarity.astro";
 import ConsentElement from "./ConsentElement.astro";
 import Drip from "./Drip.astro";
 import MetaPixel from "./MetaPixel.astro";
@@ -34,5 +35,6 @@ const { analytics, ...attrs } = Astro.props;
         {analytics?.snapchat && <SnapPixel settings={analytics.snapchat} />}
         {analytics?.axon && <AxonPixel settings={analytics.axon} />}
         {analytics?.drip && <Drip settings={analytics.drip} />}
+        {analytics?.clarity && <Clarity settings={analytics.clarity} />}
     </>
 )}

package/src/astro/GoogleMap.astro

@@ -11,6 +11,11 @@
  *
  * Give the element its size; the map fills it.
  *
+ * @see https://developers.google.com/maps/documentation/javascript/load-maps-js-api
+ * @see https://developers.google.com/maps/documentation/javascript/advanced-markers/overview
+ * @see https://developers.google.com/maps/documentation/get-map-id
+ * @see https://developers.google.com/maps/billing-and-pricing/pricing
+ *
  * ```astro
  * <GoogleMap apiKey={key} mapId={id} colorScheme="DARK" places={[{ at, label, href }]} class="block h-96">
  *     <button type="button">Show map</button>

package/src/astro/clarity-event.ts

@@ -0,0 +1,15 @@
+/** What `clarity.ts` defines once the page has loaded. */
+interface ClarityWindow {
+    clarity?: (...args: unknown[]) => void;
+}
+
+/**
+ * Marks the current Clarity recording with a named event — a form sent, a
+ * booking opened — so recordings can be filtered by it.
+ *
+ * Sent with or without consent: Clarity records either way, and without it
+ * sets no cookie. Dropped before Clarity loads, or where it is not configured.
+ */
+export function clarityEvent(name: string): void {
+    (window as unknown as ClarityWindow).clarity?.("event", name);
+}

package/src/astro/clarity.ts

@@ -0,0 +1,60 @@
+import { appendScript } from "./append-script.ts";
+import type { ConsentChoices } from "./consent.ts";
+import { withConsent } from "./consent-gate.ts";
+import { element } from "./element.ts";
+import { data } from "./ref.ts";
+
+/** Clarity's `clarity`: a queue until its script arrives and replays it. */
+interface Clarity {
+    (...args: unknown[]): void;
+    q?: unknown[];
+}
+
+interface ClarityWindow {
+    clarity?: Clarity;
+}
+
+/** Clarity's own base code, as it defines `clarity` before the script loads. */
+function defineClarity(): Clarity {
+    const global = window as unknown as ClarityWindow;
+    if (global.clarity !== undefined) return global.clarity;
+    // `arguments` is the list of whatever a call passed, which every regular
+    // `function` gets without declaring it (an arrow function does not). The
+    // queue stores that object rather than an array because Clarity's official
+    // snippet does: it is the shape Clarity promises its script will replay.
+    const clarity = function () {
+        // biome-ignore lint/complexity/noArguments: see above.
+        const args = arguments;
+        clarity.q ??= [];
+        clarity.q.push(args);
+    } as Clarity;
+    global.clarity = clarity;
+    return clarity;
+}
+
+/** Clarity's consent call, in its own spelling. */
+const consentv2 = (choices: ConsentChoices) => ({
+    ad_Storage: choices.marketing,
+    analytics_Storage: choices.analytics,
+});
+
+/**
+ * Loads Clarity with the answer so far, then passes on every answer. Stated
+ * even when denied: a Clarity project set to use cookies by default would
+ * otherwise set them before anyone was asked.
+ */
+export function clarity(projectId: string, signal?: AbortSignal): void {
+    let loaded = false;
+    withConsent((choices) => {
+        const queue = defineClarity();
+        queue("consentv2", consentv2(choices));
+        if (loaded) return;
+        loaded = true;
+        appendScript(`https://www.clarity.ms/tag/${projectId}`);
+    }, signal);
+}
+
+/** Internal to `Clarity.astro`. */
+export const clarityElement = element("atlas-clarity", ({ root, signal }) => {
+    clarity(data(root, "project-id"), signal);
+});

package/src/astro/client.ts

@@ -13,6 +13,7 @@ export * from "./attribution.ts";
 export * from "./axon-event.ts";
 export * from "./background-video.ts";
 export * from "./carousel.ts";
+export * from "./clarity-event.ts";
 // Reading only: a form that reports what the visitor agreed to. Recording an
 // answer stays with the banner.
 export { type ConsentRecord, readConsent } from "./consent.ts";

package/src/astro/consent-gate.ts

@@ -46,3 +46,24 @@ export function whenGranted(
         { signal }
     );
 }
+
+/**
+ * For a vendor with a cookieless mode, which loads whatever the answer: after
+ * `load`, `apply` gets the answer so far (everything denied until one is
+ * given), then every answer given on this page.
+ */
+export function withConsent(
+    apply: (choices: ConsentChoices) => void,
+    signal?: AbortSignal
+): void {
+    const start = () => {
+        apply(readConsent() ?? { analytics: "denied", marketing: "denied" });
+        addEventListener(
+            CONSENT_EVENT,
+            (event) => apply((event as CustomEvent<ConsentChoices>).detail),
+            { signal }
+        );
+    };
+    if (document.readyState === "complete") start();
+    else addEventListener("load", start, { once: true, signal });
+}

package/src/index.ts

@@ -23,6 +23,7 @@ export {
     type AnalyticsSettings,
     type AnalyticsTags,
     type AxonPixelSettings,
+    type ClaritySettings,
     CONSENT_UPDATE_GLOBAL,
     type ConsentDefaults,
     type ConsentState,