@c15t/scripts 2.2.0 → 3.0.0-alpha.0

package/docs/integrations/google-maps.md

@@ -1,263 +1,384 @@
 ---
 title: Google Maps
-description: Render Google Maps only after consent with one shared Maps
-  JavaScript API loader and independently managed map instances.
-icon: google-maps
+description: Prevent a map iframe from mounting before the required permission.
 group: integrations
 ---
-`GoogleMap` is a renderable integration for React and Next.js. It keeps the
-Google Maps JavaScript API off the page until the configured consent category is
-allowed, then loads the SDK once and creates a map for each mounted component.
 
-Unlike the helpers from `@c15t/scripts`, `GoogleMap` owns both the consent-aware
-script lifecycle and the visible map container.
+## Configure the map
 
-> ℹ️ **Info:**
-> The browser must receive a Google Maps API key, so the key is visible to site visitors. Keep it out of source control, use a key created for browser use, and restrict it by website and API in Google Cloud.
+Copy the map's iframe embed URL. Choose the category matching its use in your
+application; this example uses functionality permission.
 
-## Integrate with c15t
+```ts title="src/embed-config.ts"
+export const embedCategory = 'functionality' as const;
+export const embedURL = 'https://www.google.com/maps/embed?pb=YOUR_EMBED_PARAMETERS';
+export const embedTitle = 'Map showing our office location';
+export const embedAspectRatio = '4 / 3';
+```
 
-`GoogleMap` must render inside a `ConsentManagerProvider`. Complete the
-[React quickstart](/docs/frameworks/react/quickstart) or
-[Next.js quickstart](/docs/frameworks/next/quickstart) first.
+Replace the example URL with the complete embed URL for your map. Keep the
+address and a directions link outside the consent-gated embed.
 
-**React**
+## Add the embed to your framework
 
-```tsx
-import { GoogleMap } from '@c15t/react';
+Create `src/embed-config.ts` using the configuration on this page, then select
+your framework. Keep the existing [consent setup](https://c15t.com/docs/frameworks), its policy
+and preferences UI. These examples do not create a second consent provider.
 
-const apiKey = import.meta.env.VITE_GOOGLE_MAPS_API_KEY;
+**Next.js**
 
-export function StoreMap() {
-  if (!apiKey) {
-    return <p>Google Maps is not configured.</p>;
-  }
+Render this component inside your existing consent boundary or provider.
 
+```tsx title="src/consent-embed.tsx"
+'use client';
+
+import { Frame } from 'c15t/next';
+import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';
+
+export function ConsentEmbed() {
   return (
-    <GoogleMap
-      apiKey={apiKey}
-      authReferrerPolicy="origin"
-      center={{ lat: 40.7128, lng: -74.006 }}
-      consentCategory="measurement"
-      style={{ height: 400 }}
-      zoom={12}
-    />
+    <Frame category={embedCategory}>
+      <iframe
+        src={embedURL}
+        title={embedTitle}
+        loading="lazy"
+        allowFullScreen
+        style={{ width: '100%', aspectRatio: embedAspectRatio, minHeight: 200, border: 0 }}
+      />
+    </Frame>
   );
 }
 ```
 
-**Next.js**
-
-```tsx
-'use client';
+`Frame` keeps the iframe absent while permission is denied and removes it
+on revocation. Keep your existing consent styles and preferences dialog.
 
-import { GoogleMap } from '@c15t/nextjs';
+**TanStack Start**
 
-const apiKey = process.env.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY;
+Render this component inside your existing consent boundary or provider.
 
-export function StoreMap() {
-  if (!apiKey) {
-    return <p>Google Maps is not configured.</p>;
-  }
+```tsx title="src/consent-embed.tsx"
+import { Frame } from 'c15t/tanstack-start';
+import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';
 
+export function ConsentEmbed() {
   return (
-    <GoogleMap
-      apiKey={apiKey}
-      authReferrerPolicy="origin"
-      center={{ lat: 40.7128, lng: -74.006 }}
-      consentCategory="measurement"
-      style={{ height: 400 }}
-      zoom={12}
-    />
+    <Frame category={embedCategory}>
+      <iframe
+        src={embedURL}
+        title={embedTitle}
+        loading="lazy"
+        allowFullScreen
+        style={{ width: '100%', aspectRatio: embedAspectRatio, minHeight: 200, border: 0 }}
+      />
+    </Frame>
   );
 }
 ```
 
-`measurement` is a common choice for an interactive map, but the correct
-category depends on why your application uses Google Maps and the policy shown
-to your users.
-
-## How c15t loads it
-
-* **Before consent:** no Maps JavaScript API script is requested and no map
-  instance is created.
-* **After consent:** c15t registers one shared SDK loader and waits for Google's
-  callback before constructing the map.
-* **Multiple maps:** components with the same `scriptId` reuse the SDK while
-  keeping separate map instances.
-* **On revocation or unmount:** the component clears the map instance and its
-  listeners. The page-level SDK registration is retained after its first load
-  because Google supports one loader per page.
-* **Existing SDK:** if another part of the application already loaded a
-  compatible Google Maps global, the component adopts it instead of adding a
-  duplicate script.
-* **Visible states:** the blocked, loading, and error states are accessible and
-  use the active c15t translations by default.
-
-Keep one `scriptId` and one loader configuration across the page. Override the
-default `scriptId` only to coordinate with a known c15t script registration, not
-to load a second Maps SDK configuration. If two maps register conflicting
-loader options, c15t reports the conflict and tells you to align the key,
-language, region, libraries, and other loader options. A different `scriptId`
-does not make a second Google loader safe.
-
-## Configure the map
-
-Pass `center`, `zoom`, `mapId`, and `options` as you would when constructing a
-Google map:
-
-```tsx
-<GoogleMap
-  apiKey={apiKey}
-  center={{ lat: 51.5072, lng: -0.1276 }}
-  consentCategory="measurement"
-  mapId="YOUR_MAP_ID"
-  options={{
-    disableDefaultUI: true,
-    gestureHandling: 'cooperative',
-  }}
-  zoom={11}
-/>
-```
-
-Changes to `center`, `zoom`, and updateable `options` are applied to the existing
-map. Changing `mapId` recreates it because Google treats that value as
-construction-time configuration.
-
-The component has a default height of `320px`. Override `style.height` or apply
-a class with an explicit height when your layout needs another size.
-
-### Loader options
-
-The direct Maps JavaScript API loader options are available as component props:
+`Frame` keeps the iframe absent while permission is denied and removes it
+on revocation. Keep your existing consent styles and preferences dialog.
 
-* `libraries`
-* `language`
-* `region`
-* `version`
-* `authReferrerPolicy`
-* `mapIds`
-* `channel`
-* `solutionChannel`
-* `nonce`
+**React**
 
-`mapIds` preloads map ID configuration; `mapId` selects the map ID for the
-component instance.
+Render this component inside your existing consent boundary or provider.
 
-## Handle loading and errors
+```tsx title="src/consent-embed.tsx"
+import { Frame } from 'c15t/react';
+import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';
 
-The built-in loading and error states use `frame.loading` and `frame.error` from
-your c15t messages. The consent placeholder uses the localized consent-type
-title in both its message and button—for example, an `Analytics` title produces
-“Enable Analytics consent.”
+export function ConsentEmbed() {
+  return (
+    <Frame category={embedCategory}>
+      <iframe
+        src={embedURL}
+        title={embedTitle}
+        loading="lazy"
+        allowFullScreen
+        style={{ width: '100%', aspectRatio: embedAspectRatio, minHeight: 200, border: 0 }}
+      />
+    </Frame>
+  );
+}
+```
 
-Use the fallback props when you need integration-specific content and `onError`
-for reporting:
+`Frame` keeps the iframe absent while permission is denied and removes it
+on revocation. Keep your existing consent styles and preferences dialog.
+
+**Nuxt**
+
+Use the reactive snapshot from the existing consent runtime. The Nuxt module auto-imports the consent composables.
+
+```vue title="app/components/ConsentEmbed.vue"
+<script setup lang="ts">
+import { embedCategory, embedURL, embedTitle, embedAspectRatio } from '../../src/embed-config';
+
+const snapshot = useConsentSnapshot();
+const activeUI = useConsentActiveUI();
+</script>
+
+<template>
+  <iframe
+    v-if="snapshot.effectivePermissions[embedCategory]"
+    :src="embedURL"
+    :title="embedTitle"
+    loading="lazy"
+    allowfullscreen
+    :style="{ width: '100%', aspectRatio: embedAspectRatio, minHeight: '200px', border: 0 }"
+  />
+  <button v-else type="button" @click="activeUI = 'manager'">
+    Open privacy settings to view this content
+  </button>
+</template>
+```
 
-```tsx
-import { Frame, GoogleMap } from '@c15t/react';
+Use `v-if` so a denied iframe is removed from the DOM. Hiding an existing
+iframe with `v-show` or CSS does not prevent its requests.
+
+**Vue**
+
+Use the reactive snapshot from the existing consent runtime. The c15t Vue plugin must already be installed on this app.
+
+```vue title="src/ConsentEmbed.vue"
+<script setup lang="ts">
+import { useConsentSnapshot, useConsentActiveUI } from 'c15t/vue/vue-plugin';
+import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';
+
+const snapshot = useConsentSnapshot();
+const activeUI = useConsentActiveUI();
+</script>
+
+<template>
+  <iframe
+    v-if="snapshot.effectivePermissions[embedCategory]"
+    :src="embedURL"
+    :title="embedTitle"
+    loading="lazy"
+    allowfullscreen
+    :style="{ width: '100%', aspectRatio: embedAspectRatio, minHeight: '200px', border: 0 }"
+  />
+  <button v-else type="button" @click="activeUI = 'manager'">
+    Open privacy settings to view this content
+  </button>
+</template>
+```
 
-function reportMapError(error: Error) {
-  // Send the error to your observability provider.
-}
+Use `v-if` so a denied iframe is removed from the DOM. Hiding an existing
+iframe with `v-show` or CSS does not prevent its requests.
+
+**Astro**
+
+Use the shared browser helper below with Astro's existing page runtime.
+Add this component to pages using your consent-enabled base layout:
+
+```astro title="src/components/ConsentEmbed.astro"
+<c15t-consent-embed style="display: block"></c15t-consent-embed>
+
+<script>
+  import { getConsentClient } from '@c15t/astro/client';
+  import { mountConsentEmbed } from '../consent-embed';
+
+  class ConsentEmbed extends HTMLElement {
+    dispose?: () => void;
+
+    connect = () => {
+      if (this.dispose) return;
+      const client = getConsentClient();
+      if (!client) return;
+      this.dispose = mountConsentEmbed(
+        this,
+        client.runtime.kernel,
+        () => { void client.openDialog(); },
+      );
+    };
+
+    connectedCallback() {
+      document.addEventListener('DOMContentLoaded', this.connect, { once: true });
+      this.connect();
+    }
+
+    disconnectedCallback() {
+      document.removeEventListener('DOMContentLoaded', this.connect);
+      this.dispose?.();
+      this.dispose = undefined;
+    }
+  }
 
-<GoogleMap
-  apiKey={apiKey}
-  center={{ lat: 40.7128, lng: -74.006 }}
-  consentCategory="measurement"
-  loadingFallback={<p>Loading map…</p>}
-  errorFallback={<p>The map could not be loaded.</p>}
-  onError={reportMapError}
-  placeholder={
-    <Frame.Root>
-      <Frame.Title>Allow measurement consent to view this map.</Frame.Title>
-      <Frame.Button category="measurement" />
-    </Frame.Root>
+  if (!customElements.get('c15t-consent-embed')) {
+    customElements.define('c15t-consent-embed', ConsentEmbed);
   }
-/>
+</script>
 ```
 
-`onError` covers loader failures, timeouts, map-constructor failures, and
-Google's global authentication failure callback. Authentication failures
-usually indicate an invalid key, missing billing, a disabled API, or a referrer
-that is not allowed.
-
-If you provide a custom `placeholder`, include `Frame.Button` or another way to
-reopen consent preferences or grant the required category.
-
-### Retry a failed map
+The first mount waits for the page's module scripts, including c15t's boot
+script. Later `ClientRouter` mounts reuse the existing runtime. Removing the
+component unsubscribes and removes the iframe. Do not create another consent
+runtime for this embed.
+
+**Svelte**
+
+Render this component inside the existing `ConsentManagerProvider`.
+The provider from your quickstart supplies its consent state.
+
+```svelte title="src/ConsentEmbed.svelte"
+<script lang="ts">
+  import { Frame } from '@c15t/svelte';
+  import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';
+</script>
+
+<Frame category={embedCategory}>
+  <iframe
+    src={embedURL}
+    title={embedTitle}
+    loading="lazy"
+    allowfullscreen
+    style:width="100%"
+    style:aspect-ratio={embedAspectRatio}
+    style:min-height="200px"
+    style:border="0"
+  ></iframe>
+</Frame>
+```
 
-Increment `retryKey` to retry the same map after a loader, authentication, or
-constructor failure:
+The Svelte `Frame` waits until the browser is mounted and the category is
+allowed. Its default placeholder opens preferences. Revocation removes the
+iframe.
+
+**SvelteKit**
+
+Render this component inside the existing `ConsentManagerProvider`.
+Keep the SvelteKit root provider and its server prefetch unchanged.
+
+```svelte title="src/lib/ConsentEmbed.svelte"
+<script lang="ts">
+  import { Frame } from '@c15t/svelte';
+  import { embedCategory, embedURL, embedTitle, embedAspectRatio } from '../embed-config';
+</script>
+
+<Frame category={embedCategory}>
+  <iframe
+    src={embedURL}
+    title={embedTitle}
+    loading="lazy"
+    allowfullscreen
+    style:width="100%"
+    style:aspect-ratio={embedAspectRatio}
+    style:min-height="200px"
+    style:border="0"
+  ></iframe>
+</Frame>
+```
 
-```tsx
-import { GoogleMap } from '@c15t/react';
-import { useState } from 'react';
+The Svelte `Frame` waits until the browser is mounted and the category is
+allowed. Its default placeholder opens preferences. Revocation removes the
+iframe.
 
-function RetryableMap({ apiKey }: { apiKey: string }) {
-  const [retryKey, setRetryKey] = useState(0);
+**JavaScript**
 
-  return (
-    <>
-      <GoogleMap
-        apiKey={apiKey}
-        center={{ lat: 40.7128, lng: -74.006 }}
-        retryKey={retryKey}
-      />
+Use the shared browser helper below with your existing kernel. Put an
+empty container where the embed should appear:
 
-      <button type="button" onClick={() => setRetryKey((key) => key + 1)}>
-        Retry map
-      </button>
-    </>
-  );
-}
+```html
+<div id="consent-embed"></div>
 ```
 
-Changing `retryKey` clears the failed attempt and retries with the same
-`scriptId`. A successful page-level SDK registration remains shared and is not
-loaded again.
+In your browser entry point, after creating the kernel:
 
-## Secure the browser key
+```ts
+import { mountConsentEmbed } from './consent-embed';
 
-For production:
+const container = document.querySelector<HTMLElement>('#consent-embed');
+if (!container) throw new Error('Missing consent embed container');
 
-1. Create a key specifically for the browser application.
-2. Apply a **Websites** application restriction for every allowed development
-   and production origin.
-3. Restrict the key to the **Maps JavaScript API** and any additional APIs used
-   by requested libraries.
-4. Keep the value in an untracked environment file and expose it through the
-   browser environment variable required by your framework.
-5. Monitor key usage and rotate the key if you see unexpected traffic.
+const disposeEmbed = mountConsentEmbed(container, kernel, openPreferences);
+```
 
-When `authReferrerPolicy="origin"` is set, configure origin-level website
-restrictions without URL paths.
+`kernel` is the instance from your quickstart. `openPreferences` is your
+application's function for showing its consent preferences UI. Call
+`disposeEmbed()` when the page or component is destroyed. The helper observes
+both the current snapshot and later changes.
+
+## Browser helper for Astro and JavaScript
+
+Only the Astro and JavaScript examples need this helper. It creates the iframe
+when permission allows it, keeps an existing player mounted across unrelated
+snapshot updates, and removes it on revocation.
+
+```ts title="src/consent-embed.ts"
+import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';
+
+type EmbedKernel = {
+  getSnapshot: () => {
+    effectivePermissions: Record<typeof embedCategory, boolean>;
+  };
+  subscribe: (listener: () => void) => () => void;
+};
+
+export function mountConsentEmbed(
+  container: HTMLElement,
+  kernel: EmbedKernel,
+  openPreferences: () => void,
+) {
+  const render = () => {
+    if (kernel.getSnapshot().effectivePermissions[embedCategory]) {
+      if (container.querySelector('iframe')) return;
+      const frame = document.createElement('iframe');
+      frame.src = embedURL;
+      frame.title = embedTitle;
+      frame.loading = 'lazy';
+      frame.allowFullscreen = true;
+      Object.assign(frame.style, {
+        width: '100%',
+        aspectRatio: embedAspectRatio,
+        minHeight: '200px',
+        border: '0',
+      });
+      container.replaceChildren(frame);
+    } else {
+      if (container.querySelector('button')) return;
+      const button = document.createElement('button');
+      button.type = 'button';
+      button.textContent = 'Open privacy settings to view this content';
+      button.onclick = openPreferences;
+      container.replaceChildren(button);
+    }
+  };
+
+  render();
+  const unsubscribe = kernel.subscribe(render);
+  return () => {
+    unsubscribe();
+    container.replaceChildren();
+  };
+}
+```
 
-* [Google Maps Platform security guidance](https://developers.google.com/maps/api-security-best-practices)
-* [Maps JavaScript API loader options](https://developers.google.com/maps/documentation/javascript/load-maps-js-api)
-* [Maps Demo Key for local prototypes](https://developers.google.com/maps/documentation/javascript/demo-key)
+Keep a transcript, address or other useful alternative outside the embed.
+`loading="lazy"` is a performance hint; the consent condition controls whether
+the iframe exists at all. A denied category may be fixed by policy, so opening
+preferences does not guarantee that the visitor can grant it.
 
-## Verify setup
+## Gate existing iframe markup
 
-1. Clear saved consent and reload the page.
-2. Confirm no request to `maps.googleapis.com/maps/api/js` occurs before the
-   configured category is allowed.
-3. Grant consent and confirm the map reaches its ready state.
-4. Render two maps with the same `scriptId` and confirm only one loader script is
-   added.
-5. Revoke consent and confirm each map instance is removed.
-6. Test a rejected key or referrer and confirm `errorFallback` and `onError`
-   receive the failure.
-7. Fix the rejected configuration, change `retryKey`, and confirm the map can
-   recover without changing `scriptId`.
+For markup that uses `data-category` and `data-src`, the
+`createIframeBlocker` module from `c15t/modules/iframe-blocker` promotes
+`data-src` only when the category has consent and the URL resolves to HTTP or
+HTTPS. Relative URLs resolve against the iframe document's base URL.
+Malformed URLs and other schemes, including `javascript:`, `data:` and `blob:`,
+remain in `data-src` without loading. Correct the URL and call
+`processAllIframes()` to retry.
 
-## Types
+Keep the initial URL in `data-src`, without `src`, so the browser cannot load
+it before the blocker runs. The module does not sanitize arbitrary HTML or
+modify iframes without `data-category`.
 
-### GoogleMapProps
+## Verify before and after permission
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`GoogleMapProps\`|
-|Source Path|\`./packages/react/src/components/integrations/google-map.tsx\`|
+On a fresh opt-in session, inspect Network and confirm the iframe has not
+requested the map. Grant the category and confirm the map mounts. Revoke it and
+check the frame returns to its blocked state. Keep useful fallback information,
+such as the address and directions link, available outside the map.
 
-\*ExtractedTypeTable: Could not extract "GoogleMapProps" from "./packages/react/src/components/integrations/google-map.tsx" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+For a JavaScript Maps SDK instead of an iframe, register a category-gated script
+and manage the widget's cleanup. Do not use this iframe recipe as evidence that
+an independently loaded Maps SDK is blocked.