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

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

@@ -0,0 +1,141 @@
+---
+title: Network blocker
+description: Hold fetch and XMLHttpRequest calls to tracking domains in a Svelte
+  app until their consent category is allowed, with the provider's
+  networkBlocker option.
+group: frameworks
+---
+
+## When to use the network blocker
+
+The network blocker stops `fetch` and `XMLHttpRequest` calls to domains you
+list until their consent category is allowed. Use it as a backstop for
+tracking calls from code that is already on the page, such as your own
+analytics wrapper or an SDK you import. It is off until you configure it.
+
+Load vendor SDKs through the provider's `scripts` prop first; see
+[scripts](./scripts.md). A script that never loads sends nothing, which is
+stronger than blocking its requests one by one.
+
+## Configure the rules
+
+Write the configuration in its own module:
+
+```ts title="src/lib/network-blocker.ts"
+import type { UseNetworkBlockerOptions } from '@c15t/svelte';
+
+// Pass as `networkBlocker={networkBlocker}` on ConsentManagerProvider.
+export const networkBlocker: UseNetworkBlockerOptions = {
+	onRequestBlocked: ({ method, url }) => {
+		console.info('Blocked until consent', method, url);
+	},
+	rules: [
+		{
+			category: 'measurement',
+			domain: 'google-analytics.com',
+			id: 'google-analytics',
+		},
+		{
+			category: 'marketing',
+			domain: 'connect.facebook.net',
+			id: 'meta-pixel',
+			pathIncludes: '/signals',
+		},
+	],
+};
+```
+
+Pass it to the provider:
+
+```svelte
+<ConsentManagerProvider {mode} {scripts} {networkBlocker}>
+```
+
+The provider reads `networkBlocker` once, when it is created. Remount the
+provider to change the rules.
+
+## 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
+
+A blocked `fetch` resolves to a response with status `451` and the status
+text `Request blocked by consent`, and nothing is sent. A blocked
+`XMLHttpRequest` is aborted and fires an `error` event. Requests that match no
+rule are not delayed. With `logBlockedRequests` on, the default, each blocked
+request is logged with `console.warn`; `onRequestBlocked` receives
+`{ method, url, rule }`.
+
+## When blocking starts
+
+The provider starts holding matching requests when it is created in the
+browser, before its children run their own code. The blocker module loads
+when the provider mounts and then decides each held request:
+
+* While the policy is still loading, a matching request waits instead of
+  failing. When the policy arrives, with the visitor's stored choice applied,
+  the request is sent if its category is allowed and blocked otherwise.
+* If the policy fails to load, optional categories stay denied and the
+  waiting requests are blocked.
+* A synchronous XHR cannot wait. Before the blocker module loads, a matching
+  one throws a `NetworkError` from `send()`.
+
+When the visitor allows a category later, new requests to its domains go
+through. Requests blocked earlier are not replayed.
+
+## What it cannot stop
+
+The blocker sees only `fetch` and `XMLHttpRequest` calls made after the
+provider is created in the browser. It cannot stop:
+
+* Scripts that run before the provider, such as tags in `index.html` or
+  `app.html` and code at the top level of modules that load first.
+* Code that kept its own reference to `fetch` or `XMLHttpRequest` from before
+  the provider was created.
+* `navigator.sendBeacon`, `WebSocket`, `EventSource`, and requests made by
+  `<img>`, `<script>` and `<iframe>` elements, web workers and service
+  workers.
+* Requests your server makes, such as from a SvelteKit `load` or endpoint.
+
+Keep tracking calls out of that window. Send them from event handlers or
+effects, not at a module's top level, and check
+`getConsentManager().has('measurement')` before you call a vendor from your
+own code.
+
+## Verify the blocker
+
+Open DevTools, clear site data for your origin and reload:
+
+1. Before you choose, requests matching a rule do not reach the network, and
+   the console logs each blocked request.
+2. Allow the rule's category. New matching requests appear in the Network
+   panel.
+3. Reject, reload and confirm they stay blocked.
+
+`fetch('https://www.google-analytics.com/g/collect')` in the console returns a
+response with status `451` while measurement is denied.

package/docs/frameworks/svelte/scripts.md

@@ -0,0 +1,144 @@
+---
+title: Scripts
+description: Load vendor scripts, iframes and network requests in a Svelte app
+  only after the visitor allows their consent category, and stop them when
+  consent is withdrawn.
+group: frameworks
+---
+
+## Register scripts on the provider
+
+Pass the array from `src/scripts.ts` to `ConsentManagerProvider` as the
+`scripts` prop. The [quickstart](https://c15t.com/docs/frameworks/svelte/quickstart) sets up
+this file:
+
+```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' }),
+];
+```
+
+Replace the placeholder PostHog project key and X Pixel ID with your own.
+
+The provider loads the script loader as a separate chunk, shared with the
+[network blocker](./network-blocker.md), and only when `scripts` is not empty or
+the blocker has rules, so an app with neither never downloads it. A
+single-page app has no server render to link the chunk from, so the browser
+requests it after your app's JavaScript has run. A SvelteKit app can preload
+it from the server-rendered page; the SvelteKit scripts guide shows how.
+
+## How registered scripts load
+
+The provider's `scripts` prop takes an array of script configurations. Each
+has a category. The loader adds a script to the page when its category becomes
+allowed and removes it when the category is withdrawn. Nothing optional loads
+while the policy is still resolving, or when it fails.
+
+Helpers in `@c15t/integrations`, such as `posthog()` from `@c15t/integrations/posthog`,
+return a configuration with the right category and the vendor's own consent
+calls. [Integrations](../../integrations/overview.md) lists every helper. For an
+SDK without a helper, write a configuration with an `id`, `category` and `src`
+as shown in [building integrations](../../integrations/building-integrations.md).
+
+Remove the vendor's original `<script>` tag, `app.html` snippet or SDK import
+before you register it. A banner does not block code that loads some other
+way, and a vendor loaded twice sends events twice.
+
+The `scripts` array is read when the provider is created. Build it once, at
+the top level of the component, not inside an effect.
+
+## Script options
+
+Helpers set these for you. For a script without a helper, write the object
+yourself:
+
+| Option                                                              | Default  | Behavior                                                                                                                            |
+| ------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `id`                                                                | required | A unique name. The loader uses it to add and remove the script once.                                                                |
+| `category`                                                          | required | The category or condition, such as `'measurement'` or `{ and: ['measurement', 'marketing'] }`, that must be allowed.                |
+| `src` or `textContent`                                              | none     | The script's URL, or inline code.                                                                                                   |
+| `callbackOnly`                                                      | `false`  | Adds no `<script>` element and only runs the callbacks. Use it to switch an SDK you load yourself on and off.                       |
+| `alwaysLoad`                                                        | `false`  | Loads at once, whatever the consent state. Only for scripts that apply consent themselves, such as a tag manager with Consent Mode. |
+| `persistAfterConsentRevoked`                                        | `false`  | Keeps the element after withdrawal instead of removing it.                                                                          |
+| `target`                                                            | `'head'` | Where the element goes: `'head'` or `'body'`.                                                                                       |
+| `async`, `defer`, `fetchPriority`, `attributes`, `nonce`            | none     | Set on the `<script>` element.                                                                                                      |
+| `anonymizeId`                                                       | `true`   | Gives the element a random `id`, so ad blockers do not match it by name.                                                            |
+| `vendor`                                                            | none     | Also waits for this vendor to be allowed, for vendor-level consent outside IAB.                                                     |
+| `onBeforeLoad`, `onLoad`, `onError`, `onConsentChange`, `onDispose` | none     | Lifecycle callbacks. See [callbacks](https://c15t.com/docs/frameworks/svelte/callbacks#script-callbacks).                           |
+
+## Gate embeds
+
+Iframes are not scripts. Wrap them in `ConsentGate`, which keeps the iframe
+out of the DOM until its category is allowed:
+
+```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>
+```
+
+For iframes from a CMS or Markdown, which you cannot wrap, use the iframe
+blocker's `data-category` and `data-src` attributes. [Embeds](./embeds.md) covers
+both.
+
+## Block requests from code already on the page
+
+The provider's `networkBlocker` option holds `fetch` and `XMLHttpRequest`
+calls to the domains you list until their category is allowed. It is a
+backstop for code you cannot move into `scripts`. [Network blocker](./network-blocker.md)
+covers the rules and what it cannot stop.
+
+## What happens when consent is withdrawn
+
+Removing a script tag cannot stop code that already ran. So when a save
+withdraws a category that was granted, the provider reloads the page after the
+save request, and the new page starts with only the permitted code. Set
+`reloadOnConsentRevoked: false` on the provider if you handle withdrawal
+yourself, for example through a vendor's own opt-out call in
+`onConsentChange`.
+
+`ConsentGate` content unmounts without a reload. To delete first-party cookies
+a vendor set, configure `clearOnRevocation`; see
+[clearing data on revocation](https://c15t.com/docs/frameworks/svelte/clear-on-revocation).
+
+## Let visitors turn off one vendor
+
+A visitor can allow marketing and still switch off one vendor in it. Pass
+`vendors` to the provider; helpers from `@c15t/integrations` already carry their
+vendor slug. See [vendor consent](https://c15t.com/docs/frameworks/svelte/vendor-consent).
+
+## Verify vendor loading
+
+Open DevTools, clear site data for your origin and reload:
+
+1. With the banner showing, the Network panel has no requests to your vendors,
+   and gated iframes are absent from the Elements panel.
+2. Allow one category in preferences. Only that category's vendors load, and
+   its iframes appear.
+3. Reject, reload, and confirm the vendor requests stay absent.
+4. Withdraw a category you allowed. The page reloads and its vendors no longer
+   load.
+
+[Verify consent](../../guides/verify-consent.md) covers automated checks.

package/docs/frameworks/sveltekit/embeds.md

@@ -0,0 +1,103 @@
+---
+title: Embeds
+description: Keep YouTube videos, maps and other iframes out of SvelteKit server
+  HTML and the browser until their consent category is allowed.
+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/sveltekit/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`.
+
+## Embeds in server HTML
+
+`ConsentGate` renders an empty wrapper on the server, so a gated embed is
+never in the server HTML, whatever the visitor chose. It appears in the
+browser after hydration. An iframe with `data-category` and `data-src` is in
+the server HTML without `src`, so it loads nothing until the iframe blocker
+starts in the browser and finds its category allowed.

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

@@ -0,0 +1,159 @@
+---
+title: Network blocker
+description: Hold browser fetch and XMLHttpRequest calls to tracking domains in
+  a SvelteKit app until their consent category is allowed, with the
+  networkBlocker option.
+group: frameworks
+---
+
+## When to use the network blocker
+
+The network blocker stops `fetch` and `XMLHttpRequest` calls to domains you
+list until their consent category is allowed. Use it as a backstop for
+tracking calls from code that is already on the page, such as your own
+analytics wrapper or an SDK you import. It is off until you configure it.
+
+Load vendor SDKs through the provider's `scripts` prop first; see
+[scripts](./scripts.md). A script that never loads sends nothing, which is
+stronger than blocking its requests one by one.
+
+## Configure the rules
+
+Write the configuration in its own module:
+
+```ts title="src/lib/network-blocker.ts"
+import type { UseNetworkBlockerOptions } from '@c15t/svelte';
+
+// Pass as `networkBlocker={networkBlocker}` on ConsentManagerProvider.
+export const networkBlocker: UseNetworkBlockerOptions = {
+	onRequestBlocked: ({ method, url }) => {
+		console.info('Blocked until consent', method, url);
+	},
+	rules: [
+		{
+			category: 'measurement',
+			domain: 'google-analytics.com',
+			id: 'google-analytics',
+		},
+		{
+			category: 'marketing',
+			domain: 'connect.facebook.net',
+			id: 'meta-pixel',
+			pathIncludes: '/signals',
+		},
+	],
+};
+```
+
+Pass it to the provider:
+
+```svelte
+<ConsentManagerProvider {mode} {scripts} {networkBlocker}>
+```
+
+The provider reads `networkBlocker` once, when it is created. Remount the
+provider to change the rules.
+
+## 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
+
+A blocked `fetch` resolves to a response with status `451` and the status
+text `Request blocked by consent`, and nothing is sent. A blocked
+`XMLHttpRequest` is aborted and fires an `error` event. Requests that match no
+rule are not delayed. With `logBlockedRequests` on, the default, each blocked
+request is logged with `console.warn`; `onRequestBlocked` receives
+`{ method, url, rule }`.
+
+## When blocking starts
+
+The provider starts holding matching requests when it is created in the
+browser, before its children run their own code. The blocker module loads
+when the provider mounts and then decides each held request:
+
+* While the policy is still loading, a matching request waits instead of
+  failing. When the policy arrives, with the visitor's stored choice applied,
+  the request is sent if its category is allowed and blocked otherwise.
+* If the policy fails to load, optional categories stay denied and the
+  waiting requests are blocked.
+* A synchronous XHR cannot wait. Before the blocker module loads, a matching
+  one throws a `NetworkError` from `send()`.
+
+When the visitor allows a category later, new requests to its domains go
+through. Requests blocked earlier are not replayed.
+
+## What it cannot stop
+
+The blocker sees only `fetch` and `XMLHttpRequest` calls made after the
+provider is created in the browser. It cannot stop:
+
+* Scripts that run before the provider, such as tags in `index.html` or
+  `app.html` and code at the top level of modules that load first.
+* Code that kept its own reference to `fetch` or `XMLHttpRequest` from before
+  the provider was created.
+* `navigator.sendBeacon`, `WebSocket`, `EventSource`, and requests made by
+  `<img>`, `<script>` and `<iframe>` elements, web workers and service
+  workers.
+* Requests your server makes, such as from a SvelteKit `load` or endpoint.
+
+Keep tracking calls out of that window. Send them from event handlers or
+effects, not at a module's top level, and check
+`getConsentManager().has('measurement')` before you call a vendor from your
+own code.
+
+## Verify the blocker
+
+Open DevTools, clear site data for your origin and reload:
+
+1. Before you choose, requests matching a rule do not reach the network, and
+   the console logs each blocked request.
+2. Allow the rule's category. New matching requests appear in the Network
+   panel.
+3. Reject, reload and confirm they stay blocked.
+
+`fetch('https://www.google-analytics.com/g/collect')` in the console returns a
+response with status `451` while measurement is denied.
+
+## Preload the blocker
+
+The blocker shares a separate chunk with the script loader. The chunk loads
+only on pages with `networkBlocker` rules or `scripts`, and matching requests
+wait until it has loaded. Add the `c15tPreload()` Vite plugin so `c15tHandle`
+links the chunk from the page's `<head>` and the browser fetches it with the
+app's own code.
+[Preload the script loader](./scripts.md#preload-the-script-loader) shows the
+setup.
+
+## Server requests are not blocked
+
+The network blocker runs in the browser. A `fetch` in a SvelteKit `load`,
+`+server.ts` or `hooks.server.ts` is never blocked, even when the visitor has
+denied the category. If server code sends data to a vendor, check the
+visitor's stored choice yourself before it does; `event.locals.c15t.config`
+from [`c15tHandle`](https://c15t.com/docs/frameworks/sveltekit/server-api#c15thandle) holds it.