@c15t/react 3.0.0-alpha.1 → 3.0.0-alpha.11

package/docs/frameworks/react/iab.md

@@ -0,0 +1,278 @@
+---
+title: IAB TCF
+description: Mount the IAB TCF banner and dialog inside a React ConsentProvider
+  and configure the CMP ID, policy and vendor data.
+group: frameworks
+---
+
+## Prepare the IAB configuration
+
+Use the IAB integration when your application needs the Transparency and Consent
+Framework. Configure an IAB policy, the correct CMP identity and vendor data for
+your deployment. A demo CMP ID is not a production configuration.
+
+A CMP ID is assigned to a company when it registers as a CMP with IAB Europe
+([register.consensu.org/CMP](https://register.consensu.org/CMP)). Every TC
+String names the CMP that wrote it, so an ID you did not register attributes
+your users' consent records to someone else. Omitting it leaves the add-on
+unmounted: no `__tcfapi`, and no TC String written.
+
+Install `@c15t/iab` alongside your framework adapter, then mount the IAB
+components inside an existing consent provider connected to Inth.
+
+Import the components from `c15t/react/iab` and render them inside your
+existing `ConsentProvider` from `c15t/react`.
+
+The IAB banner and dialog render their own styles by default. Leave the
+provider's `styles` option enabled and render the components without a CSS
+import:
+
+```tsx title="src/iab-consent.tsx"
+import {
+	IABProvider,
+	IABConsentBanner,
+	IABConsentDialog,
+} from 'c15t/react/iab';
+
+export const IABConsent = ({ cmpId }: { cmpId: number }) => (
+	<IABProvider cmpId={cmpId}>
+		<IABConsentBanner />
+		<IABConsentDialog />
+	</IABProvider>
+);
+```
+
+Supply the CMP ID from your deployment's IAB configuration. Keep a persistent
+preferences entry point through the surrounding consent provider.
+
+## Resolve the policy before rendering
+
+IAB components remain hidden until an applicable policy resolves. Forcing a
+dialog open does not create a policy or vendor list. Inspect resolution and the
+Global Vendor List response before changing rendering conditions.
+
+IAB presentation follows `presentation.prompt.blocking` and
+`presentation.preferences.blocking`. A blocking dialog needs focus management,
+scroll locking and a backdrop together.
+
+## Mount IABProvider for every IAB policy
+
+IAB is opt-in. The standard `ConsentBanner` and `ConsentDialog` do not
+handle the IAB model, so when a visitor's policy uses it, the backend
+sends its vendor list and the app has no `IABProvider`, they throw an
+`IABUnavailableError` (code `C15T_IAB_UNAVAILABLE`):
+`c15t: this visitor's policy uses IAB TCF, but no <IABProvider> is mounted`.
+The error happens during render, on the server and in the browser, so
+your error boundary or the framework's error overlay shows it. Render `IABProvider` from
+`c15t/react/iab` for those visitors, or remove the `iab` model from the
+policy.
+
+## When the dialog loads
+
+`IABConsentDialog` loads its code on demand, so the first page load
+carries the banner without the preference center. The code downloads at
+the first of:
+
+* The browser's first idle period after the page's `load` event, while
+  the IAB banner is shown.
+* Hover or focus on the banner's Customize button or partners link.
+* The dialog opening.
+
+A visitor who opens the dialog before the download finishes waits for
+it. `open={true}` and `showTrigger` load it on mount, under a model the
+dialog's `models` prop lists. Under another model, `showTrigger` loads
+only the trigger. Set
+`preloadDialog: 'intent'` in the consent provider options to skip the
+idle download. Idle loading is also skipped with Save-Data on, on `2g`
+and `slow-2g` connections, and while offline.
+
+## Verify vendor and purpose choices
+
+Test category choices alongside vendor, purpose, legitimate-interest and special
+feature controls used by your integration. Confirm the TC String and `__tcfapi`
+reflect the saved state, and verify the vendor's actual requests. A category-only
+banner test does not establish that the IAB flow works.
+
+## Load an external stylesheet
+
+With Tailwind CSS 3, or when you want to put c15t in a named cascade layer,
+import `c15t/react/styles.css` and then `c15t/react/iab/styles.css` at your
+global stylesheet entry. The IAB stylesheet holds the IAB rules and uses the
+base stylesheet's tokens. Set `styles: false` so the components use those
+stylesheets:
+
+```tsx title="src/consent.tsx (partial)"
+import 'c15t/react/styles.css';
+import 'c15t/react/iab/styles.css';
+
+// In the ConsentProvider options:
+styles: false,
+```
+
+Tailwind CSS 3 also needs the
+[PostCSS plugin](../../customization/tailwind.md#set-up-tailwind-css-3).
+
+## Restrict how vendors use a purpose
+
+Publisher restrictions override a vendor's declared use of one purpose. Pass
+them to `IABProvider` as `publisherRestrictions`. The vendor IDs below are
+placeholders; use vendors from your list whose declarations allow each
+restriction.
+
+```tsx title="src/iab-consent.tsx"
+import {
+	IABProvider,
+	IABConsentBanner,
+	IABConsentDialog,
+} from 'c15t/react/iab';
+
+const publisherRestrictions = [
+	// Vendors 10 and 755 may not use purpose 4.
+	{ purposeId: 4, restrictionType: 0 as const, vendorIds: [10, 755] },
+	// Vendor 755 must use legitimate interest for purpose 7.
+	{ purposeId: 7, restrictionType: 2 as const, vendorIds: [755] },
+];
+
+export const IABConsent = ({ cmpId }: { cmpId: number }) => (
+	<IABProvider cmpId={cmpId} publisherRestrictions={publisherRestrictions}>
+		<IABConsentBanner />
+		<IABConsentDialog />
+	</IABProvider>
+);
+```
+
+Each restriction type has a requirement that depends on the vendor list:
+
+| `restrictionType` | Meaning                                | Allowed when the vendor                                                         |
+| ----------------- | -------------------------------------- | ------------------------------------------------------------------------------- |
+| `0`               | Purpose not allowed on any legal basis | declares the purpose for consent or legitimate interest                         |
+| `1`               | Consent required                       | declares the purpose for legitimate interest and lists it in `flexiblePurposes` |
+| `2`               | Legitimate interest required           | declares the purpose for consent and lists it in `flexiblePurposes`             |
+
+Type `2` is never allowed for purposes 1, 3, 4, 5 and 6, which TCF allows
+only with consent. TCF allows restrictions only in service-specific TC strings.
+c15t always writes those, so the deprecated `isServiceSpecific` option has no
+effect on restrictions.
+c15t copies the restrictions when the CMP starts, so changing your array
+afterwards has no effect.
+
+c15t checks restrictions when the vendor list loads and again before each TC
+String is encoded. Unsupported restrictions include type `3`, which the spec
+reserves, a vendor or purpose missing from the list, and a vendor with two
+restriction types for one purpose. They are never dropped. Loading IAB
+settings, saving and generating a TC String all reject with a
+`PublisherRestrictionError` exported by `@c15t/iab`. On a `createIAB` handle
+these are `whenReady()`, `save()` and `generateTCString()`. No TC String is
+written and no consent is recorded. Retrying `whenReady()` does not fetch
+another vendor list. The error lasts until a new vendor list is set up: with an
+explicit `gvl` option that never happens, so saving keeps failing even if the
+kernel later holds a different list. When the CMP follows the kernel's list
+instead, a replacement list is checked again and saving works once it accepts
+the restrictions. When a replacement vendor list makes a restriction
+unsupported, c15t also clears the TC authority confirmed under the previous
+list, so gated scripts stop until the configuration is fixed. Whenever c15t
+withdraws the authority it confirmed, it also removes the TC String from the
+`euconsent-v2` cookie and localStorage entry. Because the check reads the
+current vendor list, a vendor that stops declaring a purpose or its flexibility
+makes a restriction invalid. Narrow a `vendors` allowlist and your restrictions
+together.
+
+Saved TC Strings carry the restrictions in their `PubRestrictions` section, and
+`__tcfapi('getTCData')` reports them as `publisher.restrictions`, keyed by
+purpose ID, then vendor ID. A stored TC String whose restrictions differ from
+the current configuration is not restored. If the visitor's stored choice is
+otherwise current, the banner opens again, as it does after a policy change,
+and closes once the visitor saves. IAB gates that depend on the TC String stay
+denied until then. c15t also removes the superseded TC String from the
+`euconsent-v2` cookie and localStorage entry, so vendors reading standard
+storage do not pick it up. An unchanged configuration restores the stored TC
+String without asking.
+When reading a string written under TCF policy version 2 or 3, c15t accepts
+type `2` for purposes 3 to 6, which those versions allowed. Strings c15t
+writes always follow the current policy.
+
+The React, Vue, Svelte and `@c15t/browser/iab` preference centres list each
+vendor under the legal basis the restrictions leave it. A vendor whose purpose
+now requires legitimate interest gets an objection control instead of a
+consent toggle, and a prohibited purpose no longer lists the vendor. A
+purpose whose vendors all use legitimate interest has no consent switch,
+because turning one off would change nothing the vendors rely on; its
+objection control is the opt-out. Such a purpose does not decide its c15t
+category: the category follows the purposes in it that the visitor can
+consent to. Legitimate interest never grants a category on its own. If none of
+a category's purposes has a consent basis, nothing can consent to them, Accept
+All included, so the category stays denied. See
+[categories under an IAB policy](../../concepts/consent-state.md#categories-under-an-iab-policy).
+Stack switches
+cover only the purposes some vendor processes on consent. Display-model rows
+expose this as `hasConsentBasis`. Custom preference UIs can call
+`applyPublisherRestrictionsToGVL` from `@c15t/iab/headless`, or pass
+`publisherRestrictions` to `processGVLForDialog`, to get the same vendor
+declarations. The configured restrictions are on the kernel's IAB state as
+`publisherRestrictions`.
+
+Consent-gated scripts, network rules and iframes with a `vendorId` also apply
+the confirmed restrictions for that vendor:
+
+* Type `0` blocks a target that declares the purpose in `iabPurposes` or
+  `iabLegIntPurposes`.
+* Type `1` makes a purpose declared in `iabLegIntPurposes` require purpose and
+  vendor consent. Legitimate interest no longer satisfies it.
+* Type `2` makes a purpose declared in `iabPurposes` require purpose and vendor
+  legitimate interest. Consent no longer satisfies it.
+
+Types `1` and `2` block the target when the vendor list does not mark the
+purpose as flexible for that vendor. Targets without a `vendorId` ignore
+restrictions. A target that uses only legitimate interest once restrictions
+apply is not blocked by a refused category, since it needs no consent; its
+legitimate interest signals and the visitor's objection decide. GPC and strict
+scope still block it, and the category stays refused for scripts that depend on
+it. Accept All grants the vendor signal a restriction moves a purpose to,
+including legitimate interest for a vendor that declares none. Legitimate
+interest a restriction introduces applies until the visitor objects: the
+preference centres show it as allowed, and saving without touching it encodes
+it as allowed. `introducedLegitimateInterest` from `@c15t/iab/headless` lists
+those purposes and vendors for custom preference UIs.
+
+## How the preference centre shows features
+
+The stock IAB preference centres in React, Next.js, Vue, Svelte, Astro and the
+script tag follow TCF 2.4 and Policies v5.0.b. Special purposes stay in their
+locked section with a lock icon, because the visitor cannot object to them.
+
+Features get their own section after the special purposes. It shows the IAB
+standard text for features from the Global Vendor List's
+`standardTexts.features`. If the list has no standard text, it shows the
+`iab.preferenceCenter.features.description` translation. Each feature lists
+its name, description, illustrations and the vendors that use it. The section has no switch, lock or vendor toggle, because
+TCF forbids showing features next to a control that cannot be disabled.
+
+The feature section follows the theme's spacing and typography tokens.
+Its disclosure arrows are decorative and stay out of the accessibility tree.
+
+A custom preference UI gets the same rows from
+`resolveIABDialogDisplayModel` in `@c15t/iab/headless`. `essentialRows` holds
+the special purposes only. `featureRows` holds the features, with
+`locked: false` and `toggle: 'none'`, so render them without a control.
+`featuresStandardText` is the standard text, or `null` when you should use the
+translation.
+
+Each vendor's privacy policy and legitimate interest links come from its
+`urls[]` entry in the Global Vendor List. The stock preference centres pick
+the entry for the language the banner shows, then English. A custom UI gets
+the same links from `resolveIABVendorUrls(vendor, language)` in
+`@c15t/iab/headless`, or from `policyUrl` and `legitimateInterestUrl` on the
+vendors `processGVLForDialog` returns when you pass it `language`. Vendor lists
+older than GVL v3 have a single `policyUrl` field, which c15t still reads.
+
+## Consent scope
+
+c15t stores TCF choices per site and browser, which the TCF calls
+service-specific scope. It does not sync TC strings across devices, and every
+TC string it writes has `IsServiceSpecific` set to `1`.
+
+Do not use `/consent/check` or your own account data to skip the TCF banner on
+another device. That turns the choice into multi-device scope, which the TCF
+requires you to disclose in the first layer, and c15t does not show that
+disclosure. The `isServiceSpecific` option is deprecated. c15t ignores it and
+logs a warning when you pass `false`.

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.