@c15t/react 3.0.0-alpha.3 → 3.0.0-alpha.4

package/docs/frameworks/react/components/consent-provider.md

@@ -0,0 +1,126 @@
+---
+title: ConsentProvider
+description: Mount ConsentProvider in a React app and configure its backend,
+  scripts, storage, blocking and presentation options.
+group: frameworks
+---
+
+## Mount one provider
+
+`ConsentProvider` creates the consent runtime, loads the policy, stores the
+visitor's choice and loads consent-gated scripts. Render one provider at the
+root of your app and put the banner, dialog and a preferences link inside it.
+The [quickstart](../quickstart.md) does this in
+`src/consent.tsx`:
+
+```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>
+);
+```
+
+`hosted({ url })` points the provider at your Inth backend. Replace
+`https://your-project.inth.app` with the URL from your Inth project. The
+Next.js and TanStack Start adapters export `ConsentRoot` instead, which wraps
+this provider and passes it server-resolved state.
+
+## Provider options
+
+Keep the provider mounted across client navigation. It reads `mode`,
+`prefetch`, `persistence`, `clearOnRevocation` and the module options once,
+when it mounts. Remount the provider to change them.
+
+| Option                        | Purpose                                                                                                                               |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `mode`                        | Required. `hosted({ url })` for a backend, `offline()` for local policies, or `custom()` for your own transport                       |
+| `prefetch`                    | Server-resolved state, or a promise of it, from a framework adapter's server helper                                                   |
+| `scripts`                     | Consent-gated vendor scripts. See [scripts and embeds](../scripts.md)                                                                 |
+| `vendors`                     | Vendors listed under their category with their own switch. See [vendor consent](../vendor-consent.md)                                 |
+| `scriptLoader`                | Options for the script loader module                                                                                                  |
+| `networkBlocker`              | Rules that hold `fetch` and `XMLHttpRequest` calls until their category is allowed, or `false`                                        |
+| `iframeBlocker`               | Gates DOM iframes that carry `data-category`. On by default; `false` turns it off                                                     |
+| `persistence`                 | Stores the visitor's choice in a cookie and localStorage. On by default                                                               |
+| `storageConfig`               | Storage key and cookie settings for the stored choice                                                                                 |
+| `clearOnRevocation`           | Cookies and storage keys to delete when a category is denied                                                                          |
+| `reloadOnConsentRevoked`      | Reload the page after the visitor turns off a granted category or vendor. Defaults to `true`                                          |
+| `consentCategories`           | Categories the preference dialog offers alongside those your scripts use, within the policy's scope                                   |
+| `overrides`                   | Force the country, region or language the policy is resolved for, for testing                                                         |
+| `user`                        | Link consent records to a signed-in user                                                                                              |
+| `callbacks`                   | Choice, permission and error events                                                                                                   |
+| `i18n`                        | Languages and message overrides                                                                                                       |
+| `legalLinks`                  | Privacy policy and other links shown in the banner and dialog                                                                         |
+| `theme`                       | `consentActions` and slot styles. Tokens go through `ConsentTheme`; see [customize](../customize.md)                                  |
+| `components`                  | Slot attributes per component part                                                                                                    |
+| `presentation`                | Banner and dialog shape, position and blocking                                                                                        |
+| `experiment`                  | A/B test of `presentation`, read once at mount. See [banner experiments](../../../guides/banner-experiments.md)                       |
+| `colorScheme`                 | `'light'`, `'dark'`, `'system'`, or `null` to leave the `c15t-dark` class alone                                                       |
+| `noStyle`, `disableAnimation` | Drop the built-in styles, or turn off animations                                                                                      |
+| `preloadDialog`               | When the deferred `ConsentDialog` starts loading: `'idle'` (default) or `'intent'`; see [ConsentDialog](./consent-dialog.md#behavior) |
+| `nonce`                       | Content Security Policy nonce for script elements c15t inserts                                                                        |
+| `enabled`                     | Set `false` only when you deliberately bypass consent enforcement                                                                     |
+
+`enabled: false` grants categories and allows gated loading while suppressing
+consent UI. It is not a way to fix failed initialization or hide a banner in
+production.
+
+## Observe changes without inventing choices
+
+`onChoiceRecorded` reports explicit accept, reject and save actions.
+`onPermissionsChanged` also covers changes caused by policy, expiry or privacy
+signals. Hydration and notice dismissal do not become explicit choices.
+
+An externally owned runtime can be passed through `runtime`. Its owner must
+start and dispose it. A provider borrowing that runtime must not initialize or
+dispose a second copy. Passing a different `runtime` moves the provider and its
+hooks to the new runtime's kernel and unsubscribes them from the previous one.
+The previous runtime keeps running until its owner disposes it. Switch the
+provider to another runtime, or unmount it, before disposing the runtime it
+renders. Changing between a borrowed runtime and a provider-created one still
+requires remounting the provider. IAB actions taken before its handle is ready
+wait for that handle. If the provider unmounts or switches runtimes first, a
+pending `save()` rejects with an `AbortError` instead of waiting indefinitely.
+See [how consent works](../../../concepts/how-consent-works.md#a-permission-is-not-a-recorded-choice) and
+[choose your setup](../../../concepts/choose-your-setup.md).
+
+## Reload after revocation
+
+Removing a script cannot stop code that already ran. A vendor's listeners,
+timers and widgets keep working until the page unloads. When an accept, reject
+or save turns off a category or vendor that was granted, the provider reloads
+the page once the save request settles, so the next page runs only permitted
+code. `onBeforeConsentRevocationReload` runs just before the reload.
+
+Otherwise, expiry, policy changes and privacy signals do not reload the page. Set
+`reloadOnConsentRevoked: false` only when every gated vendor stops itself on
+revocation, for example through its own opt-out API.
+
+## Clear data when consent is denied
+
+Set `options.clearOnRevocation` to declare cookies, localStorage keys, and
+sessionStorage keys by optional consent category. Cleanup waits for policy
+resolution, then clears denied categories and later allowed-to-denied
+transitions. This option is initial-only. See
+[clear on revocation](../clear-on-revocation.md) for examples,
+cookie scopes, and browser limits.

package/docs/frameworks/react/components/consent-widget.md

@@ -8,7 +8,7 @@ group: frameworks
 ## Embed the preference center inline
 
 `ConsentWidget` renders the preference center in the page flow instead of in
-a modal: the category switches and the Reject all, Accept all and Save
+a modal: the category switches and the Reject All, Accept All and Save Settings
 actions, without a title, backdrop or portal. Use it on a privacy or
 settings page where the visitor expects the controls to be part of the
 content. Render it anywhere inside the `ConsentProvider` from your
@@ -19,16 +19,16 @@ banner's Customize button and preference links still have a dialog to open.
 import { ConsentWidget } from 'c15t/react';
 
 export function PrivacyPage() {
-  return (
-    <main>
-      <h1>Privacy</h1>
-      <p>Choose which optional categories this site may use.</p>
-      <section aria-labelledby="cookie-preferences">
-        <h2 id="cookie-preferences">Cookie preferences</h2>
-        <ConsentWidget />
-      </section>
-    </main>
-  );
+	return (
+		<main>
+			<h1>Privacy</h1>
+			<p>Choose which optional categories this site may use.</p>
+			<section aria-labelledby="cookie-preferences">
+				<h2 id="cookie-preferences">Cookie preferences</h2>
+				<ConsentWidget />
+			</section>
+		</main>
+	);
 }
 ```
 
@@ -49,13 +49,16 @@ or dialog by itself.
 
 The widget is the preference center without the modal around it: an
 accordion with one row per category, each with a switch, followed by the
-Reject all, Accept all and Save actions. `ConsentDialog` renders this same
+Reject All, Accept All and Save Settings actions. `ConsentDialog` renders this same
 widget inside its card. Standalone, the widget renders in place, takes part
 in server rendering, and does not touch the active surface, so it suits a
 privacy page or an account settings screen.
 
 The rows are `necessary` plus the categories in the active policy's scope,
-narrowed to the provider `options.consentCategories` when that list is non-empty.
+narrowed to the categories the provider declares: `options.consentCategories`
+and the categories of its scripts, network rules, vendors and discovered
+frames. When nothing is declared, a permissive policy shows only `necessary`
+and a strict one its whole scope.
 The `necessary` switch is on and disabled. Row titles and descriptions come
 from `consentTypes.<category>.title` and `.description`; the action labels
 from `common.rejectAll`, `common.acceptAll` and `common.save`. One row is
@@ -68,8 +71,8 @@ until Save. The draft seeds each category from the recorded choice; without
 one it uses `presentation.preferences.defaults` from the provider options,
 and without that it is on under an opt-out rule and on only for the rule's
 preselected categories under an opt-in rule. Save records the displayed
-categories, then reseeds the draft from the new record. Accept all and
-Reject all record immediately without a separate Save. A save answers a
+categories, then reseeds the draft from the new record. Accept All and
+Reject All record immediately without a separate Save. A save answers a
 choice prompt, so an open choice banner closes; it does not dismiss a
 `notice` prompt, which keeps its own acknowledgement record. Unsaved toggles
 are lost when the widget unmounts.
@@ -102,18 +105,18 @@ only; the category stays granted and its other vendors keep loading. While
 the category is off in the draft the vendor switches are disabled, with the
 hint "Turn on this category to choose vendors." A vendor declared
 `disabled`, or one that only falls under `necessary`, is listed without a
-switch. Accept all and Reject all clear every vendor denial, including one
+switch. Accept All and Reject All clear every vendor denial, including one
 staged but not yet saved. Under an `iab` policy no vendor rows render.
 Vendors that are only referenced by a script slug, without a name and
 privacy policy URL, still gate loading but are not listed, and so does a
 vendor whose condition negates a category, since no category row can
 host it. See
-[granular consent](../../../integrations/granular-consent.md).
+[vendor consent](../vendor-consent.md).
 
 ### Actions
 
-The preference center always renders Reject all, Accept all and Save, with
-Save as the primary action. `presentation.preferences.layout`,
+The preference center always renders Reject All, Accept All and Save Settings, with
+Save Settings as the primary action. `presentation.preferences.layout`,
 `primaryActions`, `direction` and `uiProfile` in the provider options
 reorder and restyle them; a layout that omits one of the three has it
 restored. Customize and dismiss actions never render here.
@@ -201,7 +204,7 @@ it. `c15t/react/components/consent-widget` exports the widget without that
 deferral, plus each part as a named export.
 
 The compound parts import from `c15t/react` as properties of `ConsentWidget`.
-See [Styling](../styling/overview.md) for slots and tokens.
+See [customize](../customize.md) for slots and tokens.
 
 ## Verify
 

package/docs/frameworks/react/components/dev-tools.md

@@ -1,7 +1,7 @@
 ---
 title: DevTools
-description: A development tool for inspecting consent state, geolocation,
-  loaded scripts, and consent events in real time.
+description: Inspect consent state, location, loaded scripts and consent events
+  in a React app during development with the c15t DevTools panel.
 group: frameworks
 ---
 
@@ -12,42 +12,44 @@ group: frameworks
 
 ## Installation
 
-No extra package is required for a framework adapter. The adapter and its
-engine are included with the `c15t` package and the dedicated
-`@c15t/svelte` adapter. Install `@c15t/dev-tools` directly only
-when you need the imperative `createDevTools({ kernel })` API.
+No extra package is required. The React adapter and its engine are included
+with the `c15t` package. Install `@c15t/dev-tools` directly only when you
+need the imperative `createDevTools({ kernel })` API.
 
-## Usage
+## Render DevTools in development builds
 
-This example uses Vite's `import.meta.env.DEV` build-time flag. For another
-bundler, use its development flag instead. For example, webpack projects can
-use a configured `process.env.NODE_ENV === 'development'` replacement;
-`process` is not a browser global.
+Render `DevTools` inside `ConsentProvider`. This example loads it only in
+development with Vite's `import.meta.env.DEV` flag, so production bundles never
+download it. For another bundler, use its development flag instead; for
+example, webpack projects can use a configured
+`process.env.NODE_ENV === 'development'` replacement, since `process` is not a
+browser global.
 
-```tsx
-import { lazy, Suspense, type ReactNode } from 'react';
-import { ConsentProvider, hosted } from 'c15t/react';
-
-const DevTools =
-  import.meta.env.DEV
-    ? lazy(() =>
-        import('c15t/react/devtools').then(({ DevTools }) => ({ default: DevTools })),
-      )
-    : () => null;
+```tsx title="src/consent-devtools.tsx"
+import { lazy, Suspense } from 'react';
 
-export function ConsentManager({ children }: { children: ReactNode }) {
-  return (
-    <ConsentProvider options={{ mode: hosted({ url: 'https://your-instance.c15t.dev' }) }}>
-      {children}
-      <Suspense fallback={null}>
-        <DevTools />
-      </Suspense>
-    </ConsentProvider>
-  );
+const DevTools = import.meta.env.DEV
+	? lazy(() =>
+			import('c15t/react/devtools').then(({ DevTools }) => ({
+				default: DevTools,
+			}))
+		)
+	: null;
+
+export function ConsentDevTools() {
+	return DevTools ? (
+		<Suspense fallback={null}>
+			<DevTools />
+		</Suspense>
+	) : null;
 }
 ```
 
-Import the adapter from `c15t/react/devtools` when you use the umbrella package, or `c15t/react/devtools` when you install the React package directly. `@c15t/dev-tools` exports the imperative engine, not the React component.
+Render `<ConsentDevTools />` inside the provider from your
+[quickstart](../quickstart.md), next to the banner. Import the
+component from `c15t/react/devtools` when you installed the `c15t` package, or
+from `@c15t/react/devtools` when you installed `@c15t/react` directly.
+`@c15t/dev-tools` exports the imperative engine, not the React component.
 
 If the CLI cannot identify your bundler's development flag, it generates
 `const DevTools = false` with a setup comment. Replace `false` with your
@@ -69,14 +71,16 @@ DevTools disabled instead of assuming browser globals or loading it in productio
 `position` accepts any corner: `top-left`, `top-right`, `bottom-left`, or
 `bottom-right`. Set `defaultOpen` to open the initial panel and `defaultTab`
 to choose that panel. `maxEvents` limits captured kernel and script events.
-Set `disabled` to prevent mounting without removing the component.
+Set `disabled` to prevent mounting without removing the component. The
+panel renders inside a shadow root by default, so page CSS does not reach
+it. `shadow={false}` mounts it in the light DOM with its stylesheet in
+`<head>`.
 
 ## Panels
 
 Accept and reject apply only to categories displayed by the provider, leaving
-hidden consent values unchanged. `necessary` always remains enabled. Svelte
-and Vue adapters use their provider's displayed categories; the kernel and
-React adapter use the current policy categories by default.
+hidden consent values unchanged. `necessary` always remains enabled. The
+React adapter uses the current policy categories by default.
 
 For an imperative integration with a narrower UI, pass
 `getConsentCategories: () => ['necessary', 'measurement']` to
@@ -168,55 +172,6 @@ For custom inspection tools, `getIABControls(kernel)` and
 The getter returns undefined before module initialization and after disposal.
 A snapshot without an attached IAB module is read-only in DevTools.
 
-## Vue and Svelte
-
-Vue imports `ConsentDevTools` from `c15t/vue/devtools`.
-Render it in the app where the c15t plugin provides
-the kernel. In Nuxt, the configured c15t module provides that context.
-
-```vue
-<script setup lang="ts">
-import { defineAsyncComponent } from 'vue';
-
-const DevTools = import.meta.env.DEV
-  ? defineAsyncComponent(() => import('c15t/vue/devtools'))
-  : null;
-</script>
-
-<template>
-  <DevTools v-if="DevTools" position="bottom-right" />
-</template>
-```
-
-In Nuxt, use `import.meta.dev` instead of `import.meta.env.DEV`.
-Svelte imports the adapter from `@c15t/svelte/devtools` and renders it
-inside `ConsentManagerProvider`.
-
-```svelte
-<script lang="ts">
-  import { ConsentManagerProvider, offline } from '@c15t/svelte';
-
-  const devTools = import.meta.env.DEV
-    ? import('@c15t/svelte/devtools')
-    : null;
-</script>
-
-<ConsentManagerProvider options={{ mode: offline() }}>
-  {#if devTools}
-    {#await devTools then { ConsentDevTools }}
-      <ConsentDevTools position="bottom-right" />
-    {/await}
-  {/if}
-</ConsentManagerProvider>
-```
-
-Both adapters accept `position`, `defaultOpen`, `defaultTab`, `maxEvents`,
-`shadow` (`false` renders into the page instead of a shadow root),
-and `getConsentCategories`. Changing these presentation options recreates
-the panel and clears its event history. They do not accept React's `disabled`
-prop; conditionally render them instead. Unmounting removes the panel and
-subscriptions without changing consent.
-
 ## TanStack Devtools
 
 Each embedded panel owns its event history and subscriptions. Unmounting it
@@ -257,6 +212,19 @@ export function AppDevtools() {
 
 In a Next.js app, import `c15tDevtools` from `c15t/next/devtools` instead. Scoped installs use `@c15t/react/devtools` and `@c15t/nextjs/devtools`.
 
+The c15t panel follows the TanStack Devtools light or dark theme, not your app's consent theme. If you write the plugin entry yourself, use a render function and pass the theme to `C15tTanStackDevtoolsPanel`:
+
+```tsx
+import { C15tTanStackDevtoolsPanel } from 'c15t/react/devtools';
+
+const c15tPlugin = {
+  name: 'Consent',
+  render: (_element: HTMLElement, { theme }: { theme: 'light' | 'dark' }) => (
+    <C15tTanStackDevtoolsPanel theme={theme} />
+  ),
+};
+```
+
 ## Props
 
 | Property | Type                | Description                                 | Default | Required |

package/docs/frameworks/react/components.md

@@ -0,0 +1,105 @@
+---
+title: Components
+description: Every c15t component a React app imports from c15t/react, what each
+  renders, where each one mounts, and which to start with.
+group: frameworks
+---
+
+## Component reference
+
+`c15t/react` exports the provider, the consent UI and the hooks from one
+import path. Every component except `ConsentProvider` and `ConsentTheme`
+reads the runtime the provider creates, so render them inside
+`ConsentProvider`.
+
+| Component                             | Renders                                                                                                           | Reference                                                      |
+| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `ConsentProvider`                     | The consent runtime, which loads the policy, stores the choice and loads scripts. No markup of its own            | [ConsentProvider](./components/consent-provider.md)            |
+| `ConsentBanner`                       | The banner, when the visitor's policy asks for one                                                                | [ConsentBanner](./components/consent-banner.md)                |
+| `ConsentDialog`                       | The preference center as a modal                                                                                  | [ConsentDialog](./components/consent-dialog.md)                |
+| `ConsentWidget`                       | The preference center inline in a page, for a privacy route                                                       | [ConsentWidget](./components/consent-widget.md)                |
+| `ConsentDialogLink`                   | An unstyled button that opens the dialog, for your footer                                                         | [ConsentDialogLink](./components/consent-dialog-link.md)       |
+| `ConsentDialogTrigger`                | A floating, draggable button that opens the dialog. `ConsentDialogTriggerToolbar` adds your own actions beside it | [ConsentDialogTrigger](./components/consent-dialog-trigger.md) |
+| `ConsentGate`                         | Its children while a category is allowed, a placeholder otherwise                                                 | [ConsentGate](./components/consent-gate.md)                    |
+| `ConsentTheme`                        | A `<style>` element with your theme tokens                                                                        | [Customize](./customize.md)                                    |
+| `DevTools` from `c15t/react/devtools` | A development panel for consent state, scripts and events                                                         | [DevTools](./components/dev-tools.md)                          |
+
+Mount one `ConsentProvider` at the root of the app and keep it mounted across
+client navigation. The provider reads `mode` and its module options once,
+when it mounts.
+
+## Start with the provider, banner and dialog
+
+Most apps start with four components. `ConsentProvider` holds the runtime,
+`ConsentBanner` and `ConsentDialog` ask for a choice, and a
+`ConsentDialogLink` lets visitors reopen their preferences. The [quickstart](./quickstart.md) puts them in
+one file:
+
+```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>
+);
+```
+
+Add `ConsentWidget`, `ConsentDialogTrigger` or `ConsentGate` later, where a
+page needs them. Keep `ConsentDialog` mounted even when you add a widget,
+because the banner's Customize button and every dialog link open it.
+
+## Server-rendered React apps
+
+React Router framework mode, Remix and other server-rendered React apps use the
+same components. `ConsentProvider` renders on the server without touching
+browser APIs, and the banner mounts after hydration, once the browser has
+resolved the policy. [Rendering](./rendering.md#react-router-remix-and-other-server-rendered-apps)
+explains the trade-off.
+
+## IAB TCF components
+
+Import `IABProvider`, `IABConsentBanner` and `IABConsentDialog` from
+`c15t/react/iab`, render them inside `ConsentProvider` next to
+`ConsentBanner` and `ConsentDialog`, and load `c15t/react/iab/styles.css`. The stock banner and dialog stay closed
+under an IAB policy. See
+[IAB TCF](./iab.md).
+
+## Other entry points
+
+| Import                                                                                                                                                                                  | Exports                        | Use                                                                                                      |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------- |
+| `c15t/react/consent-banner`, `c15t/react/consent-dialog`, `c15t/react/consent-widget`, `c15t/react/consent-dialog-link`, `c15t/react/consent-dialog-trigger`, `c15t/react/consent-gate` | One component each             | A module that needs one component without the rest of the adapter                                        |
+| `c15t/react/headless`                                                                                                                                                                   | Headless hooks                 | Your own banner and dialog markup. See [headless](./headless.md)                                         |
+| `c15t/react/server`                                                                                                                                                                     | `fetchSSRData` and its helpers | Resolve `/init` in a server loader. See [rendering](./rendering.md#skip-the-browsers-first-init-request) |
+| `c15t/react/devtools`                                                                                                                                                                   | `DevTools`                     | Development only                                                                                         |
+
+## Check the components
+
+Load the app in a private window under a policy that asks for a choice:
+
+1. The banner shows, and DevTools Network has no requests to your vendors'
+   hosts.
+2. Click the footer's `ConsentDialogLink`. The dialog opens with every optional
+   category off.
+3. Allow one category and save. Its vendor requests appear, and a
+   `ConsentGate` for that category mounts its children.
+4. Reload. The banner stays closed, and the link still reopens the dialog.