@c15t/scripts 3.0.0-alpha.2 → 3.0.0-alpha.4

package/docs/frameworks/nuxt/network-blocker.md

@@ -0,0 +1,97 @@
+---
+title: Network blocker
+description: Hold fetch and XMLHttpRequest calls in a Nuxt app until their
+  consent category is allowed, with rules in the c15t module options.
+group: frameworks
+---
+
+## Add rules
+
+The network blocker stops `fetch` and `XMLHttpRequest` calls in the browser
+that match a rule until the rule's category is allowed. Use it as a backstop
+for tracking calls your own code or a vendor SDK makes. Load vendor SDKs
+through [`scripts`](./scripts.md) first, so they do not run
+at all before consent.
+
+Rules are plain data, so they can go in the module options:
+
+```ts title="nuxt.config.ts"
+export default defineNuxtConfig({
+	c15t: {
+		networkBlocker: {
+			rules: [{ category: 'measurement', domain: 'google-analytics.com' }],
+		},
+	},
+});
+```
+
+Module options reach the browser as JSON, so the `onRequestBlocked` callback
+goes under the `c15t` key of `app/app.config.ts`. Rules you set there are
+added to the rules from `nuxt.config.ts`:
+
+```ts title="app/app.config.ts"
+export default defineAppConfig({
+	c15t: {
+		networkBlocker: {
+			onRequestBlocked: (info) => console.info('Blocked', info.url),
+			rules: [],
+		},
+	},
+});
+```
+
+## Match requests with rules
+
+Each rule names a `domain` and the consent `category` a request needs. The
+domain also matches its subdomains, so `google-analytics.com` covers
+`www.google-analytics.com`. `pathIncludes` narrows a rule to paths that
+contain a substring, and `methods` narrows it to HTTP methods. `category`
+also takes conditions such as `{ and: ['measurement', 'marketing'] }`.
+
+Add `vendor` with a vendor ID to also block the request while the visitor has
+turned that vendor off. Rules for IAB TCF vendors use `vendorId` and the
+`iabPurposes` fields instead.
+
+| Option               | Default  | Purpose                                                                             |
+| -------------------- | -------- | ----------------------------------------------------------------------------------- |
+| `rules`              | Required | The rules above.                                                                    |
+| `enabled`            | `true`   | `false` keeps the rules but stops blocking.                                         |
+| `logBlockedRequests` | `true`   | Logs each blocked request with `console.warn`.                                      |
+| `onRequestBlocked`   | Unset    | `app.config.ts` only. Called with `{ method, url, rule }` for each blocked request. |
+
+## What a blocked request looks like
+
+A blocked `fetch` resolves to a `451` response with the status text
+`Request blocked by consent`, and nothing is sent. A blocked XHR is aborted
+and fires an `error` event. Requests that match no rule are not delayed.
+
+## When blocking starts
+
+The blocker runs in the browser only. It starts holding matching requests
+when the c15t plugin runs, before your app hydrates. While consent is
+unknown, a matching request waits instead of failing. Once the policy and the
+stored choice apply, a waiting request is sent if consent allows it and
+blocked otherwise. With `manifest: 'server'`, the policy arrives with the
+page, so waiting requests are decided as soon as the app mounts.
+
+Requests your server makes during server rendering, such as `useFetch` on the
+server, are not blocked. Check `useConsent()` before you call a vendor from
+server code.
+
+## What it cannot stop
+
+The blocker sees only browser `fetch` and `XMLHttpRequest` calls made after
+the c15t plugin runs. It cannot stop:
+
+* Scripts you add to the page head with `useHead` or `app.head`, and Nuxt
+  plugins that run before the c15t plugin.
+* Code that saved its own reference to `fetch` before the plugin ran.
+* `navigator.sendBeacon`, `WebSocket`, `EventSource`, and requests from
+  `<img>`, `<script>` and `<iframe>` elements, web workers and service
+  workers.
+
+## Verify
+
+Open the Network tab, clear site data and reload. Requests that match a rule
+do not appear until you allow their category, and the console lists each
+blocked request. Reject, reload, and check that they still do not appear.

package/docs/frameworks/nuxt/scripts.md

@@ -0,0 +1,89 @@
+---
+title: Scripts
+description: Load vendor scripts by consent category in a Nuxt app with the c15t
+  Nuxt module, and what happens when a visitor withdraws consent.
+group: frameworks
+---
+
+## Register vendor scripts
+
+A banner does not stop a script you load with a `<script>` tag, `useHead` or a
+vendor's Nuxt module. Remove those loaders and register the vendor with c15t
+instead, so c15t loads it only while its category is allowed.
+
+Create the script configuration with the helpers from `@c15t/integrations`:
+
+```ts title="app/consent-scripts.ts"
+import { posthog } from '@c15t/integrations/posthog';
+import { xPixel } from '@c15t/integrations/x-pixel';
+
+export const scripts = [
+	posthog({
+		id: 'phc_your_project_key',
+		initOptions: { cookieless_mode: 'never' },
+		loadMode: 'after-consent',
+		region: 'eu',
+	}),
+	xPixel({ pixelId: 'your-pixel-id' }),
+];
+```
+
+Register it under the `c15t` key in `app/app.config.ts`:
+
+```ts title="app/app.config.ts"
+import { scripts } from './consent-scripts';
+
+export default defineAppConfig({ c15t: { scripts } });
+```
+
+The module starts one script loader in the browser after hydration, once it
+has applied the visitor's stored choice and privacy signals. Do not also call
+`createScriptLoader` yourself, or each script loads twice.
+
+`scripts` must go in `app.config.ts`. Module options in `nuxt.config.ts`
+reach the browser as JSON, which drops the functions inside each script.
+
+Every vendor guide under [integrations](../../integrations/overview.md) gives the
+helper and options for that vendor.
+
+## Embeds and other requests
+
+Scripts cover vendor code c15t loads for you. For the rest:
+
+* [Embeds](./embeds.md) gates iframes with `ConsentGate` or
+  the iframe blocker.
+* [Network blocker](./network-blocker.md) holds `fetch` and
+  XHR calls that match a rule until their category is allowed.
+
+## When a visitor withdraws consent
+
+Removing a script tag cannot stop code that already ran. When a save turns off
+a category or vendor that was allowed, c15t reloads the page so the new
+document starts with only permitted code. Set `reloadOnConsentRevoked: false`
+to handle revocation yourself, or use the
+[`onBeforeConsentRevocationReload` callback](https://c15t.com/docs/frameworks/nuxt/callbacks#before-a-revocation-reload)
+to run code before the reload.
+
+`clearOnRevocation` deletes first-party cookies and storage keys that belong to
+a category when it is withdrawn. It is plain data, so it can go in
+`nuxt.config.ts`. See [clear on revocation](https://c15t.com/docs/frameworks/nuxt/clear-on-revocation).
+
+## Let visitors turn off one vendor
+
+A visitor can allow marketing and still switch off one vendor in it. Declare
+the vendors in the `vendors` option; helpers from `@c15t/integrations` already carry
+their vendor slug. See [vendor consent](https://c15t.com/docs/frameworks/nuxt/vendor-consent).
+
+## Content Security Policy
+
+Allow each vendor's script host in your `script-src` directive. The module's
+`nonce` option is fixed when the app builds, so prefer the host allowlist.
+See [Content Security Policy](https://c15t.com/docs/frameworks/nuxt/content-security-policy).
+
+## Verify gating
+
+In a private window, open the Network tab and load a page under a policy that
+asks for consent. Requests to your vendors are absent.
+Allow one category and save, and only that category's vendors load. Withdraw
+it, and the page reloads without loading the vendor again.
+[Verify consent](../../guides/verify-consent.md) has the full checklist.

package/docs/frameworks/react/embeds.md

@@ -0,0 +1,89 @@
+---
+title: Embeds
+description: Keep YouTube videos, maps and other iframes out of a React page
+  until their consent category is allowed, with ConsentGate or the iframe
+  blocker in ConsentProvider.
+group: frameworks
+---
+
+## Pick a method
+
+| Method             | Use it when                                                                                              |
+| ------------------ | -------------------------------------------------------------------------------------------------------- |
+| `ConsentGate`      | You render the iframe in a React component and want a placeholder until the visitor allows its category. |
+| The iframe blocker | The iframe comes from markup you do not render with React, such as CMS or Markdown content.              |
+
+Both keep the iframe's `src` out of the page until the category is allowed, so
+the embed's host receives no request before consent.
+
+## Gate an embed with ConsentGate
+
+Wrap the iframe in `ConsentGate` anywhere inside `ConsentProvider`:
+
+```tsx title="src/video-embed.tsx"
+import { ConsentDialogLink, ConsentGate } from 'c15t/react';
+
+export const VideoEmbed = () => (
+	<ConsentGate
+		category="measurement"
+		placeholder={
+			<div className="placeholder">
+				<p>Allow measurement to load this YouTube video.</p>
+				<ConsentDialogLink>Choose video permissions</ConsentDialogLink>
+			</div>
+		}
+	>
+		<iframe
+			title="YouTube video"
+			sandbox="allow-scripts allow-same-origin allow-presentation"
+			src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y?playsinline=1"
+			allow="encrypted-media; picture-in-picture"
+			allowFullScreen
+		/>
+	</ConsentGate>
+);
+```
+
+The iframe is absent from the page until the visitor allows measurement. The
+`placeholder` shows a message and a
+[`ConsentDialogLink`](https://c15t.com/docs/frameworks/react/components/consent-dialog-link)
+until then. When the visitor withdraws measurement, React removes the iframe.
+
+Pick the category that matches what the embed does. The example uses
+measurement for YouTube because its player measures views. A map or chat
+widget usually belongs under functionality or experience.
+[ConsentGate](https://c15t.com/docs/frameworks/react/components/consent-gate) documents the
+built-in placeholder and every prop.
+
+## Gate an iframe with the iframe blocker
+
+`ConsentProvider` runs the iframe blocker by default. Give an iframe
+`data-src` instead of `src`, and a `data-category`:
+
+```html title="Markup from your CMS"
+<iframe
+  data-src="https://www.google.com/maps/embed?pb=YOUR_EMBED_ID"
+  data-category="functionality"
+  title="Store map"
+></iframe>
+```
+
+c15t sets `src` from `data-src` when the category is allowed and removes `src`
+when the category is withdrawn. It watches the page, so iframes added later
+are handled too. Add `data-vendor` with a vendor ID to also block the iframe
+while the visitor has turned that vendor off.
+
+To turn the blocker off, set `iframeBlocker: false` in the provider `options`.
+
+## Verify the embeds
+
+Open the production build in a private window with DevTools open, under a
+policy that asks for consent.
+
+1. No iframe has a `src` pointing at `youtube-nocookie.com` or
+   `google.com/maps`, and the Network panel shows no request to them.
+2. Allow the embed's category and save. The iframe loads.
+3. Withdraw the category and save. The page reloads without the embed.
+
+The [YouTube](../../integrations/youtube.md) and
+[Google Maps](../../integrations/google-maps.md) guides cover sizing and titles.

package/docs/frameworks/react/network-blocker.md

@@ -0,0 +1,140 @@
+---
+title: Network blocker
+description: Hold fetch and XMLHttpRequest calls in a React app until their
+  consent category is allowed, with networkBlocker rules in the ConsentProvider
+  options.
+group: frameworks
+---
+
+## Add rules
+
+Some SDKs are already on the page and send beacons or API calls of their own.
+Add `networkBlocker` rules to the provider options to stop `fetch` and
+`XMLHttpRequest` calls to those domains until the category is allowed. Load
+vendor SDKs through [`scripts`](./scripts.md) first, so they
+do not run at all before consent.
+
+This partial example adds the option next to the existing `mode` and
+`scripts`:
+
+```tsx title="src/consent.tsx"
+const networkBlocker = {
+	rules: [
+		{
+			id: 'google-analytics',
+			domain: 'google-analytics.com',
+			category: 'measurement',
+		},
+		{
+			id: 'meta-pixel',
+			domain: 'facebook.com',
+			pathIncludes: '/tr',
+			category: 'marketing',
+		},
+	],
+};
+
+<ConsentProvider options={{ mode, scripts, networkBlocker }}>
+```
+
+## Match requests with rules
+
+Each rule names a `domain` and the consent `category` a request needs. The
+domain also matches its subdomains: `google-analytics.com` covers
+`www.google-analytics.com`. `pathIncludes` narrows the rule to paths that
+contain a substring, and `methods` narrows it to HTTP methods. A request is
+blocked when a matching rule's condition is not met by the visitor's
+effective permissions.
+
+`category` takes the same conditions as scripts:
+
+```ts
+{ category: 'measurement' }
+{ category: { and: ['measurement', 'marketing'] } }
+{ category: { or: ['measurement', 'marketing'] } }
+```
+
+Add `vendor` to also block the request while the visitor has turned that
+vendor off. IAB TCF rules use `vendorId` and the `iab*` purpose fields
+instead.
+
+| Option               | Default  | Purpose                                                      |
+| -------------------- | -------- | ------------------------------------------------------------ |
+| `rules`              | required | Rules described above                                        |
+| `enabled`            | `true`   | Set `false` to keep the rules but stop blocking              |
+| `logBlockedRequests` | `true`   | Log each blocked request with `console.warn`                 |
+| `onRequestBlocked`   | none     | Called with `{ method, url, rule }` for each blocked request |
+
+## What a blocked request looks like
+
+The blocker wraps `window.fetch` and `XMLHttpRequest`. A blocked `fetch`
+resolves to a `451` response with the status text
+`Request blocked by consent`, and nothing is sent. A blocked XHR is aborted
+and fires an `error` event. Requests that match no rule are not delayed.
+
+## When blocking starts
+
+The provider holds matching requests from its first render in the browser,
+before any of its children render or run effects. That covers requests from
+child components, including their mount effects, and from effects in
+components rendered next to the provider. The blocker module itself loads
+after mount and decides each held request. Apps without `networkBlocker` do
+not download it.
+
+The standalone `useNetworkBlocker` hook works the same way from the first
+render of the component that calls it. That render patches `fetch` and
+`XMLHttpRequest`. If React throws the render away and never commits it, the
+hold ends after 10 seconds. Nothing checked consent for the requests it held,
+so they fail the way the blocker fails a blocked request: a 451 response for
+`fetch`, a failed XHR. The same happens when the component unmounts before
+the blocker loads.
+
+While consent is unknown, a matching request that would be blocked waits
+instead of failing. Consent is unknown until the policy has loaded, which is
+also when a returning visitor's stored choice takes effect. The request is
+then sent if the choice allows it and blocked otherwise. If the policy fails
+to load, optional categories stay denied and waiting requests are blocked.
+If the policy request never finishes, they keep waiting and are never sent.
+
+A synchronous XHR cannot wait. Before the blocker module has loaded, a
+matching one throws a `NetworkError` from `send()`. After that, one that
+consent does not allow yet is blocked.
+
+## What the network blocker cannot stop
+
+The blocker only sees requests made after the provider starts rendering in
+the browser, through `fetch` or `XMLHttpRequest`. It cannot stop:
+
+* Code that runs before the provider renders: inline scripts in the HTML,
+  third-party tags in `<head>`, scripts loaded before hydration (such as
+  `next/script` with `beforeInteractive`), and client modules that evaluate
+  earlier. Webpack builds evaluate a route's client component modules when
+  its chunk loads, so their top-level code runs first. Turbopack evaluates a
+  client component module when its first element renders, which inside the
+  provider is after blocking starts.
+* Code that saved its own reference to `fetch` or `XMLHttpRequest` before the
+  provider rendered.
+* `navigator.sendBeacon`, `WebSocket`, `EventSource`, and requests made by
+  `<img>`, `<script>` or `<iframe>` elements, web workers and service
+  workers.
+* With the standalone `useNetworkBlocker` hook instead of the provider
+  option, requests sent before the component that calls it renders.
+  Blocking starts in that component's first render, not the provider's.
+
+Keep tracking calls out of that window:
+
+* Send them from an effect or an event handler, never at module top level.
+* Load vendor SDKs through `scripts` instead of a `<script>` tag or
+  `next/script`, so they wait for consent before they run at all.
+* Check `useConsent('measurement')` (or the category you need) before you
+  call a vendor from your own code, and treat the blocker as a backstop.
+
+## Verify the blocked requests
+
+Open DevTools Network in a private window, under a policy that asks for
+consent.
+
+1. Before a choice, requests matching a rule are absent, and the console logs
+   each blocked request.
+2. Allow the rule's category and save. Matching requests go out.
+3. Reject, reload, and check that they stay absent.

package/docs/frameworks/react/scripts.md

@@ -0,0 +1,115 @@
+---
+title: Scripts
+description: Load vendor scripts by consent category in a React app with
+  ConsentProvider, and clear stored data or reload the page when a visitor
+  withdraws consent.
+group: frameworks
+---
+
+## Register vendor scripts
+
+Pass vendor loaders to `ConsentProvider` through `options.scripts`. The
+provider loads each script when its category is allowed and removes it when
+the category is denied. The [quickstart](https://c15t.com/docs/frameworks/react/quickstart)
+registers PostHog and X Pixel this way:
+
+```ts title="src/scripts.ts"
+import { posthog } from '@c15t/integrations/posthog';
+import { xPixel } from '@c15t/integrations/x-pixel';
+
+export const scripts = [
+	posthog({
+		id: 'phc_your_project_key',
+		initOptions: { cookieless_mode: 'never' },
+		loadMode: 'after-consent',
+	}),
+	xPixel({ pixelId: 'your-pixel-id' }),
+];
+```
+
+The provider in `src/consent.tsx` receives them:
+
+```tsx title="src/consent.tsx"
+import {
+	ConsentBanner,
+	ConsentDialog,
+	ConsentDialogLink,
+	ConsentProvider,
+	hosted,
+} from 'c15t/react';
+import type { ReactNode } from 'react';
+
+import { scripts } from './scripts';
+
+import 'c15t/react/styles.css';
+
+const mode = hosted({ url: 'https://your-project.inth.app' });
+
+export const Consent = ({ children }: { children: ReactNode }) => (
+	<ConsentProvider options={{ mode, scripts }}>
+		{children}
+		<ConsentBanner />
+		<ConsentDialog />
+		<footer>
+			<ConsentDialogLink>Privacy settings</ConsentDialogLink>
+		</footer>
+	</ConsentProvider>
+);
+```
+
+Each helper from `@c15t/integrations` sets its own category and a stable `id`.
+Remove every other loader for the same vendor, such as a `<script>` tag in
+`index.html` or an SDK you initialize at module level, so the vendor loads
+once and only through c15t. [Integrations](../../integrations/overview.md) lists
+every helper, and [building integrations](../../integrations/building-integrations.md)
+covers a vendor without one.
+
+## What happens when consent changes
+
+* **Allowed.** The script loads, or its SDK is started, the first time its
+  category is allowed.
+* **Denied later.** The provider removes the script element. Code that already
+  ran keeps running, so after the visitor turns off a category they had
+  allowed, the provider reloads the page once the save finishes. Set
+  `reloadOnConsentRevoked: false` only if every gated vendor stops itself.
+* **`alwaysLoad` helpers.** Some integrations, such as Google Consent Mode,
+  load before consent and pass the visitor's choice to the vendor. Read the
+  vendor's guide; a category on a script does not always mean zero requests.
+
+## Embeds and other requests
+
+Scripts cover vendor code c15t loads for you. For the rest:
+
+* [Embeds](./embeds.md) keeps iframes out of the page with
+  `ConsentGate` or the iframe blocker.
+* [Network blocker](./network-blocker.md) holds `fetch` and
+  XHR calls that match a rule until their category is allowed.
+
+## Clear stored data after revocation
+
+Removing a script does not delete the cookies or storage entries it wrote. Add
+`clearOnRevocation` to the provider options to delete the entries you list for
+each category when it is denied. The option is read once, when the provider
+mounts. [Clear on revocation](https://c15t.com/docs/frameworks/react/clear-on-revocation) covers
+configuration and browser limits.
+
+## Let visitors turn off one vendor
+
+A visitor can allow marketing and still switch off one vendor in it. Pass
+`vendors` to the provider options. Helpers from `@c15t/integrations` already carry
+their vendor slug. See [vendor consent](https://c15t.com/docs/frameworks/react/vendor-consent).
+
+To send your own events only to allowed integrations, see
+[send events only to allowed integrations](../../integrations/overview.md#send-events-only-to-allowed-integrations).
+
+## Check the scripts
+
+Open DevTools Network in a private window, filter by each vendor's domain and
+reload.
+
+1. Before a choice under an opt-in policy, no vendor script loads.
+2. Allow one category. Only that category's vendors load.
+3. Turn the category off. The page reloads and the vendor stays absent.
+4. Reload again. The rejection holds.
+
+[Verify consent](../../guides/verify-consent.md) has the full checklist.

package/docs/frameworks/svelte/embeds.md

@@ -0,0 +1,96 @@
+---
+title: Embeds
+description: Keep YouTube videos, maps and other iframes out of a Svelte page
+  until their consent category is allowed, with ConsentGate or the iframe
+  blocker.
+group: frameworks
+---
+
+## Pick a way to gate the embed
+
+A YouTube video, a map or a social post in an iframe contacts its vendor as
+soon as it loads. c15t offers two ways to keep it from loading before
+consent:
+
+| Your markup                                              | Use                                                    | Placeholder                   |
+| -------------------------------------------------------- | ------------------------------------------------------ | ----------------------------- |
+| A Svelte component you write                             | `ConsentGate` around the iframe                        | Built in, or your own snippet |
+| HTML you do not control, such as CMS or Markdown content | The iframe blocker with `data-category` and `data-src` | None; the iframe stays empty  |
+
+Both use the visitor's effective permission for one category, and both
+remove the embed again when the visitor withdraws that category.
+
+## Wrap the iframe in ConsentGate
+
+```svelte title="src/YouTubeEmbed.svelte"
+<script lang="ts">
+	import { ConsentDialogLink, ConsentGate } from '@c15t/svelte';
+</script>
+
+<!-- The iframe mounts only while measurement is allowed. -->
+<ConsentGate category="measurement">
+	{#snippet placeholder()}<div class="placeholder">
+			<p>Allow measurement to load this YouTube video.</p>
+			<ConsentDialogLink>Choose video permissions</ConsentDialogLink>
+		</div>{/snippet}
+	<iframe
+		title="YouTube video"
+		src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y?playsinline=1"
+		allow="encrypted-media; picture-in-picture"
+		allowfullscreen
+	></iframe>
+</ConsentGate>
+```
+
+The iframe is absent from the DOM until measurement is allowed, so the
+browser never requests it. The placeholder snippet replaces the built-in one
+and includes a `ConsentDialogLink`, so a visitor can allow the category from
+the embed's own spot. Keep `ConsentDialog` mounted for that link.
+[ConsentGate](https://c15t.com/docs/frameworks/svelte/components/consent-gate) lists its props.
+
+Pick the category the vendor's embed needs. YouTube and maps usually fit
+`measurement` or `marketing`; check what each vendor sets.
+
+## Gate iframes you do not render
+
+The provider's iframe blocker is on by default. It watches the page for
+iframes with a `data-category` attribute:
+
+```html
+<iframe
+  title="Store locations"
+  data-category="functionality"
+  data-src="https://www.google.com/maps/embed?pb=..."
+></iframe>
+```
+
+* While the category is denied, the iframe has no `src`, so it loads nothing.
+* When the category is allowed, the blocker copies `data-src` to `src`.
+  Only `http` and `https` URLs are used.
+* When the category is withdrawn, the blocker removes `src` again.
+
+Iframes without `data-category` or `data-vendor` are never touched. Put
+`data-src` in the HTML instead of `src`; an iframe that arrives with `src`
+already starts loading before the blocker sees it. Add `data-vendor` with a
+vendor slug to also keep the iframe empty while the visitor has that vendor
+turned off.
+
+The blocker has no placeholder. Style the empty iframe, or place a note and a
+`ConsentDialogLink` next to it.
+
+Pass `iframeBlocker={false}` on the provider to turn the blocker off.
+
+## Vendor guides
+
+The [YouTube](../../integrations/youtube.md) and
+[Google Maps](../../integrations/google-maps.md) guides have ready embed
+configurations. [Integrations](../../integrations/overview.md) lists the rest.
+
+## Verify the embeds
+
+Clear site data and reload with DevTools open:
+
+1. The Network panel has no request to the embed's host, and the Elements
+   panel shows the placeholder or an iframe without `src`.
+2. Allow the category in preferences. The embed loads without a page reload.
+3. Withdraw the category. The embed disappears, or its iframe loses `src`.