@escape-game-over/atlas 0.1.53 → 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.53",
+    "version": "0.1.54",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,

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/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>
@@ -81,6 +90,7 @@ const {
     <body {...body}>
         <MetaTags tags={meta.bodyTags} />
         <slot />
+        <slot name="consent" />
         {restoreScroll && <ScrollRestore />}
         {rememberCampaign && <RememberCampaign />}
     </body>

package/src/index.ts

@@ -26,6 +26,7 @@ export {
     type ConsentDefaults,
     type ConsentState,
     consentRequired,
+    consentVendors,
     type GoogleSettings,
     type UmamiReplay,
     type UmamiSettings,

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[];
 }
 
 /**