@c15t/react 3.0.0-alpha.0 → 3.0.0-alpha.10

package/docs/integrations/google-maps.md

@@ -1,6 +1,9 @@
 ---
 title: Google Maps
-description: Prevent a map iframe from mounting before the required permission.
+description: Gate a Google Maps iframe embed with c15t v3 so the map loads only
+  after the visitor allows its consent category, in Next.js, TanStack Start,
+  React, Nuxt, Vue, Astro, Svelte, SvelteKit, HTML or JavaScript.
+icon: google-maps
 group: integrations
 ---
 
@@ -11,7 +14,8 @@ application; this example uses functionality permission.
 
 ```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 embedURL =
+	'https://www.google.com/maps/embed?pb=YOUR_EMBED_PARAMETERS';
 export const embedTitle = 'Map showing our office location';
 export const embedAspectRatio = '4 / 3';
 ```
@@ -22,7 +26,7 @@ address and a directions link outside the consent-gated embed.
 ## Add the embed to your framework
 
 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
+your framework. Keep the existing [consent setup](https://v3.c15t.com/docs/frameworks), its policy
 and preferences UI. These examples do not create a second consent provider.
 
 **Next.js**
@@ -32,12 +36,12 @@ Render this component inside your existing consent boundary or provider.
 ```tsx title="src/consent-embed.tsx"
 'use client';
 
-import { Frame } from 'c15t/next';
+import { ConsentGate } from 'c15t/next';
 import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';
 
 export function ConsentEmbed() {
   return (
-    <Frame category={embedCategory}>
+    <ConsentGate category={embedCategory}>
       <iframe
         src={embedURL}
         title={embedTitle}
@@ -45,12 +49,12 @@ export function ConsentEmbed() {
         allowFullScreen
         style={{ width: '100%', aspectRatio: embedAspectRatio, minHeight: 200, border: 0 }}
       />
-    </Frame>
+    </ConsentGate>
   );
 }
 ```
 
-`Frame` keeps the iframe absent while permission is denied and removes it
+`ConsentGate` keeps the iframe absent while permission is denied and removes it
 on revocation. Keep your existing consent styles and preferences dialog.
 
 **TanStack Start**
@@ -58,12 +62,12 @@ on revocation. Keep your existing consent styles and preferences dialog.
 Render this component inside your existing consent boundary or provider.
 
 ```tsx title="src/consent-embed.tsx"
-import { Frame } from 'c15t/tanstack-start';
+import { ConsentGate } from 'c15t/tanstack-start';
 import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';
 
 export function ConsentEmbed() {
   return (
-    <Frame category={embedCategory}>
+    <ConsentGate category={embedCategory}>
       <iframe
         src={embedURL}
         title={embedTitle}
@@ -71,12 +75,12 @@ export function ConsentEmbed() {
         allowFullScreen
         style={{ width: '100%', aspectRatio: embedAspectRatio, minHeight: 200, border: 0 }}
       />
-    </Frame>
+    </ConsentGate>
   );
 }
 ```
 
-`Frame` keeps the iframe absent while permission is denied and removes it
+`ConsentGate` keeps the iframe absent while permission is denied and removes it
 on revocation. Keep your existing consent styles and preferences dialog.
 
 **React**
@@ -84,12 +88,12 @@ on revocation. Keep your existing consent styles and preferences dialog.
 Render this component inside your existing consent boundary or provider.
 
 ```tsx title="src/consent-embed.tsx"
-import { Frame } from 'c15t/react';
+import { ConsentGate } from 'c15t/react';
 import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';
 
 export function ConsentEmbed() {
   return (
-    <Frame category={embedCategory}>
+    <ConsentGate category={embedCategory}>
       <iframe
         src={embedURL}
         title={embedTitle}
@@ -97,74 +101,75 @@ export function ConsentEmbed() {
         allowFullScreen
         style={{ width: '100%', aspectRatio: embedAspectRatio, minHeight: 200, border: 0 }}
       />
-    </Frame>
+    </ConsentGate>
   );
 }
 ```
 
-`Frame` keeps the iframe absent while permission is denied and removes it
+`ConsentGate` 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.
+The Nuxt module registers `ConsentGate` and `ConsentDialogLink`, so
+this component imports only the embed configuration.
 
 ```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>
+  <ConsentGate :category="embedCategory">
+    <iframe
+      :src="embedURL"
+      :title="embedTitle"
+      loading="lazy"
+      allowfullscreen
+      :style="{ width: '100%', aspectRatio: embedAspectRatio, minHeight: '200px', border: 0 }"
+    />
+    <template #placeholder>
+      <p>Allow {{ embedCategory }} to load this content.</p>
+      <ConsentDialogLink>Open privacy settings</ConsentDialogLink>
+    </template>
+  </ConsentGate>
 </template>
 ```
 
-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.
+`ConsentGate` keeps the iframe out of the server HTML and the DOM while
+permission is denied, and removes it on revocation. See
+[Nuxt scripts and embeds](https://v3.c15t.com/docs/frameworks/nuxt/scripts).
 
 **Vue**
 
-Use the reactive snapshot from the existing consent runtime. The c15t Vue plugin must already be installed on this app.
+Render this component inside the app that installed the c15t Vue plugin.
 
 ```vue title="src/ConsentEmbed.vue"
 <script setup lang="ts">
-import { useConsentSnapshot, useConsentActiveUI } from 'c15t/vue/vue-plugin';
+import { ConsentDialogLink, ConsentGate } 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>
+  <ConsentGate :category="embedCategory">
+    <iframe
+      :src="embedURL"
+      :title="embedTitle"
+      loading="lazy"
+      allowfullscreen
+      :style="{ width: '100%', aspectRatio: embedAspectRatio, minHeight: '200px', border: 0 }"
+    />
+    <template #placeholder>
+      <p>Allow {{ embedCategory }} to load this content.</p>
+      <ConsentDialogLink>Open privacy settings</ConsentDialogLink>
+    </template>
+  </ConsentGate>
 </template>
 ```
 
-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.
+`ConsentGate` keeps the iframe out of the DOM while permission is denied,
+and removes it on revocation. See
+[Vue scripts and embeds](https://v3.c15t.com/docs/frameworks/vue/scripts).
 
 **Astro**
 
@@ -175,7 +180,7 @@ Add this component to pages using your consent-enabled base layout:
 <c15t-consent-embed style="display: block"></c15t-consent-embed>
 
 <script>
-  import { getConsentClient } from '@c15t/astro/client';
+  import { getConsentClient } from 'c15t/astro/client';
   import { mountConsentEmbed } from '../consent-embed';
 
   class ConsentEmbed extends HTMLElement {
@@ -217,16 +222,16 @@ runtime for this embed.
 
 **Svelte**
 
-Render this component inside the existing `ConsentManagerProvider`.
+Render this component inside the existing `ConsentProvider`.
 The provider from your quickstart supplies its consent state.
 
 ```svelte title="src/ConsentEmbed.svelte"
 <script lang="ts">
-  import { Frame } from '@c15t/svelte';
+  import { ConsentGate } from '@c15t/svelte';
   import { embedCategory, embedURL, embedTitle, embedAspectRatio } from './embed-config';
 </script>
 
-<Frame category={embedCategory}>
+<ConsentGate category={embedCategory}>
   <iframe
     src={embedURL}
     title={embedTitle}
@@ -237,25 +242,25 @@ The provider from your quickstart supplies its consent state.
     style:min-height="200px"
     style:border="0"
   ></iframe>
-</Frame>
+</ConsentGate>
 ```
 
-The Svelte `Frame` waits until the browser is mounted and the category is
+The Svelte `ConsentGate` 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.
+Render this component inside the existing `ConsentRoot`.
+Keep the SvelteKit root and its server-resolved state unchanged.
 
 ```svelte title="src/lib/ConsentEmbed.svelte"
 <script lang="ts">
-  import { Frame } from '@c15t/svelte';
+  import { ConsentGate } from '@c15t/svelte';
   import { embedCategory, embedURL, embedTitle, embedAspectRatio } from '../embed-config';
 </script>
 
-<Frame category={embedCategory}>
+<ConsentGate category={embedCategory}>
   <iframe
     src={embedURL}
     title={embedTitle}
@@ -266,23 +271,44 @@ Keep the SvelteKit root provider and its server prefetch unchanged.
     style:min-height="200px"
     style:border="0"
   ></iframe>
-</Frame>
+</ConsentGate>
 ```
 
-The Svelte `Frame` waits until the browser is mounted and the category is
+The Svelte `ConsentGate` waits until the browser is mounted and the category is
 allowed. Its default placeholder opens preferences. Revocation removes the
 iframe.
 
+**HTML**
+
+The c15t script tag gates iframes that name a category. Put the embed's URL
+in `data-src` instead of `src`, using the values from the configuration on
+this page:
+
+```html
+<iframe
+  data-src="https://www.youtube-nocookie.com/embed/VIDEO_ID?playsinline=1"
+  data-category="measurement"
+  title="Product video"
+  loading="lazy"
+  allowfullscreen
+></iframe>
+```
+
+c15t sets `src` once the category is allowed and removes it on revocation.
+Without `src` the iframe loads nothing, so hide it with CSS and show a link
+to `#c15t-preferences` in its place. See
+[HTML embeds](https://v3.c15t.com/docs/frameworks/html/embeds).
+
 **JavaScript**
 
-Use the shared browser helper below with your existing kernel. Put an
+Use the shared browser helper below with your existing client. Put an
 empty container where the embed should appear:
 
 ```html
 <div id="consent-embed"></div>
 ```
 
-In your browser entry point, after creating the kernel:
+In your browser entry point, after `init()`:
 
 ```ts
 import { mountConsentEmbed } from './consent-embed';
@@ -290,13 +316,16 @@ import { mountConsentEmbed } from './consent-embed';
 const container = document.querySelector<HTMLElement>('#consent-embed');
 if (!container) throw new Error('Missing consent embed container');
 
-const disposeEmbed = mountConsentEmbed(container, kernel, openPreferences);
+const disposeEmbed = mountConsentEmbed(container, consent.kernel, () =>
+  consent.openDialog(),
+);
 ```
 
-`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.
+`consent` is the client from `init()` in your quickstart. With
+`createConsentRuntime`, pass `runtime.kernel` and your own function that
+opens preferences. Call `disposeEmbed()` when the page or component is
+destroyed. Iframe markup with `data-src` and `data-category` also works
+without the helper, because both setups gate iframes by default.
 
 ## Browser helper for Astro and JavaScript
 
@@ -305,51 +334,56 @@ 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';
+import {
+	embedCategory,
+	embedURL,
+	embedTitle,
+	embedAspectRatio,
+} from './embed-config';
 
 type EmbedKernel = {
-  getSnapshot: () => {
-    effectivePermissions: Record<typeof embedCategory, boolean>;
-  };
-  subscribe: (listener: () => void) => () => void;
+	getSnapshot: () => {
+		effectivePermissions: Record<typeof embedCategory, boolean>;
+	};
+	subscribe: (listener: () => void) => () => void;
 };
 
 export function mountConsentEmbed(
-  container: HTMLElement,
-  kernel: EmbedKernel,
-  openPreferences: () => void,
+	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();
-  };
+	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();
+	};
 }
 ```