@escape-game-over/atlas 0.1.39 → 0.1.41

package/docs/client-scripts.md

@@ -51,7 +51,9 @@ answer is two, one per category: `analytics` (Google's `analytics_storage`) and
 markup marks its buttons `data-consent="grant"` and `data-consent="deny"` for
 everything at once, and `data-consent="save"` for the answer its checkboxes
 give — `data-consent-category="analytics"` and `"marketing"`, never ticked by
-default. The control that brings it back is `data-consent-reopen hidden`.
+default. Those can wait in a `data-consent-choices hidden` panel that a
+`data-consent-choose` button shows and hides, keeping its `aria-expanded` in
+step. The control that brings it back is `data-consent-reopen hidden`.
 
 `Document` ships one more: scroll restoration, on unless `restoreScroll={false}`.
 WebKit restores a page's position only at `load`, after every image, so a page

package/package.json

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

package/src/astro/attribution.ts

@@ -0,0 +1,114 @@
+/**
+ * Where a visit came from, for a lead form to report: the campaign tags it
+ * landed with, and the Google Ads click behind it.
+ *
+ * A lead is the one record that outlives the visit — an email, a row in a
+ * sheet — so it is where a conversion import has to find the click, and where
+ * anyone asking "which campaign brought this?" will look.
+ *
+ * The two are kept differently, on purpose:
+ *
+ * - **Campaign tags** (`utm_*`) are labels a campaign shares with everyone who
+ *   clicked it, not an identifier. They are kept for the tab in
+ *   `sessionStorage`, so a visitor who lands on one page and fills a form on
+ *   another still reports them. `rememberCampaign()` on every page does that.
+ * - **The ad click id** (`gclid`, `gbraid`, `wbraid`) identifies one click, and
+ *   is never stored here. Google keeps it under the visitor's consent: on the
+ *   URL while marketing is denied — `urlPassthrough` in `GoogleSettings` — and
+ *   in its own `_gcl_aw` cookie once granted. `adClick()` reads it from there.
+ */
+
+/** The campaign tags a link can carry. */
+export type CampaignTag =
+    | "utm_source"
+    | "utm_medium"
+    | "utm_campaign"
+    | "utm_term"
+    | "utm_content";
+
+const CAMPAIGN_TAGS: readonly CampaignTag[] = [
+    "utm_source",
+    "utm_medium",
+    "utm_campaign",
+    "utm_term",
+    "utm_content",
+];
+
+/** The ids Google Ads puts on a landing URL. */
+export type AdClickId = "gclid" | "gbraid" | "wbraid";
+
+const AD_CLICK_IDS: readonly AdClickId[] = ["gclid", "gbraid", "wbraid"];
+
+export type Campaign = Partial<Record<CampaignTag, string>>;
+export type AdClick = Partial<Record<AdClickId, string>>;
+
+/** The `sessionStorage` key the tags are kept under. */
+const KEY = "atlas-campaign";
+
+/** The given parameters present on this page's URL. */
+function fromUrl<K extends string>(
+    names: readonly K[]
+): Partial<Record<K, string>> {
+    const params = new URLSearchParams(location.search);
+    const found: Partial<Record<K, string>> = {};
+    for (const name of names) {
+        const value = params.get(name);
+        if (value) found[name] = value;
+    }
+    return found;
+}
+
+/** Keeps this page's campaign tags for the tab, if it has any. */
+export function rememberCampaign(): void {
+    const landed = fromUrl(CAMPAIGN_TAGS);
+    if (Object.keys(landed).length === 0) return;
+    try {
+        sessionStorage.setItem(KEY, JSON.stringify(landed));
+    } catch {
+        // Storage refused: the tags still count on the page they arrived on.
+    }
+}
+
+/** The tags on this page's URL, else the ones the visit landed with. */
+export function campaign(): Campaign {
+    const here = fromUrl(CAMPAIGN_TAGS);
+    if (Object.keys(here).length > 0) return here;
+    try {
+        const kept: unknown = JSON.parse(sessionStorage.getItem(KEY) ?? "{}");
+        if (typeof kept !== "object" || kept === null) return {};
+        const found: Campaign = {};
+        for (const tag of CAMPAIGN_TAGS) {
+            const value = (kept as Record<string, unknown>)[tag];
+            if (typeof value === "string" && value !== "") found[tag] = value;
+        }
+        return found;
+    } catch {
+        return {};
+    }
+}
+
+/**
+ * A cookie's value. `document.cookie` is always `name=value; name=value`, so a
+ * split reads it — `cookieStore.get` would too, but is async and newer than
+ * the Safari still in use.
+ */
+function cookie(name: string): string | undefined {
+    const prefix = `${name}=`;
+    return document.cookie
+        .split("; ")
+        .find((pair) => pair.startsWith(prefix))
+        ?.slice(prefix.length);
+}
+
+/**
+ * The Google Ads click behind this visit: from the URL, else `gclid` from
+ * Google's `_gcl_aw` cookie, whose value is `GCL.<time>.<gclid>`.
+ */
+export function adClick(): AdClick {
+    const click = fromUrl(AD_CLICK_IDS);
+    if (click.gclid === undefined) {
+        const gclid = cookie("_gcl_aw")?.split(".").slice(2).join(".");
+        if (gclid) click.gclid = gclid;
+    }
+    return click;
+}

package/src/astro/client.ts

@@ -9,8 +9,12 @@
  * import, so a component's contract can be imported from frontmatter too.
  */
 
+export * from "./attribution.ts";
 export * from "./background-video.ts";
 export * from "./carousel.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";
 export {
     type Connect,
     type ElementContext,

package/src/astro/consent-element.ts

@@ -7,7 +7,7 @@ import {
     recordConsent,
 } from "./consent.ts";
 import { element } from "./element.ts";
-import { data, refs } from "./ref.ts";
+import { data, ref, refs } from "./ref.ts";
 
 /**
  * The banner's behaviour. Its own module, and not re-exported from `client.ts`,
@@ -25,6 +25,13 @@ import { data, refs } from "./ref.ts";
  * The checkboxes are never ticked by default; they show an answer already
  * given, and nothing else.
  *
+ * To keep them out of sight until asked for, put them in a
+ * `data-consent-choices hidden` panel and add a `data-consent-choose` button:
+ * it shows and hides the panel, and keeps its own `aria-expanded` in step. The
+ * panel can sit anywhere in the banner — below the buttons, not only inside
+ * the control, which is what a `<details>` would force. It starts closed each
+ * time the banner is shown.
+ *
  * The control that brings it back — usually in the footer — is
  * `data-consent-reopen hidden`: it stays hidden until there is an answer to
  * withdraw.
@@ -53,12 +60,31 @@ export const consentBanner = element("atlas-consent", ({ root, signal }) => {
         };
     };
 
+    const toggles = refs<HTMLButtonElement>(root, "[data-consent-choose]");
+    const panel =
+        toggles.length > 0 ? ref(root, "[data-consent-choices]") : undefined;
+
+    const expand = (open: boolean): void => {
+        if (panel === undefined) return;
+        panel.hidden = !open;
+        for (const toggle of toggles) {
+            toggle.setAttribute("aria-expanded", String(open));
+        }
+    };
+
+    for (const toggle of toggles) {
+        toggle.addEventListener("click", () => expand(panel?.hidden === true), {
+            signal,
+        });
+    }
+
     const show = (): void => {
         // Only an answer already given ticks a box.
         const stored = readConsent();
         for (const { box, category } of boxes) {
             box.checked = stored?.[category] === "granted";
         }
+        expand(false);
         root.hidden = false;
     };