@c15t/nextjs 2.2.1 → 3.0.0-alpha.1

package/docs/frameworks/next/components/consent-manager-provider.md

@@ -1,327 +1,77 @@
 ---
-title: ConsentManagerProvider
-description: The root provider component that initializes the consent system and
-  makes consent state available to all child components.
+title: ConsentRoot
+description: Pass server-resolved consent state and shared configuration to the
+  Next.js ConsentRoot.
 group: frameworks
 ---
-`ConsentManagerProvider` is the root component for the c15t consent system. It initializes the consent store, detects the user's jurisdiction, resolves translations, and provides consent state to all child components via React context.
 
-Every other c15t component and hook must be rendered inside this provider.
+## Mount one root
 
-## Basic Usage
+`ConsentRoot` wraps the React `ConsentProvider` and connects it to your
+Next.js configuration and server-resolved state. Mount it once; it already
+supplies the provider used by consent components and hooks.
 
-```tsx
-import { type ReactNode } from 'react';
-import { ConsentManagerProvider, ConsentBanner, ConsentDialog } from '@c15t/nextjs';
-
-export default function ConsentManager({ children }: { children: ReactNode }) {
-  return (
-    <ConsentManagerProvider
-      options={{
-        mode: 'hosted',
-        backendURL: '/api/c15t',
-        consentCategories: ['necessary', 'measurement', 'marketing'],
-      }}
-    >
-      <ConsentBanner />
-      <ConsentDialog />
-      {children}
-    </ConsentManagerProvider>
-  );
-}
-```
-
-## Options Reference
-
-|Property|Value|
-|:--|:--|
-|Type Name|\`CommonInlineStoreOptions\`|
-|Source Path|\`./packages/ui/src/theme/options.ts\`|
-
-\*ExtractedTypeTable: Could not extract "CommonInlineStoreOptions" from "./packages/ui/src/theme/options.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
-
-|Property|Value|
-|:--|:--|
-|Type Name|\`ConsentManagerContentOptions\`|
-|Source Path|\`./packages/ui/src/theme/options.ts\`|
-
-\*ExtractedTypeTable: Could not extract "ConsentManagerContentOptions" from "./packages/ui/src/theme/options.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
-
-|Property|Value|
-|:--|:--|
-|Type Name|\`UIOptions\`|
-|Source Path|\`./packages/ui/src/theme/types.ts\`|
-
-\*ExtractedTypeTable: Could not extract "UIOptions" from "./packages/ui/src/theme/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
-
-## Mode: hosted vs offline
-
-```tsx
-// Hosted mode — persists to hosted backend
-<ConsentManagerProvider
-  options={{
-    mode: 'hosted',
-    backendURL: '/api/c15t',
-  }}
->
-
-// Offline mode — local cookie storage only
-<ConsentManagerProvider
-  options={{
-    mode: 'offline',
-  }}
->
-```
-
-See [Client Modes](/docs/frameworks/next/concepts/client-modes) for a detailed comparison.
-
-## Content Security Policy
-
-c15t injects a `<style id="c15t-theme">` element for your theme tokens, and the script loader injects a `<script>` element per consented vendor. Under a nonce-based Content Security Policy, both are blocked unless they carry your nonce.
-
-Pass it once through the `nonce` option and c15t applies it to everything it injects:
-
-```tsx
-<ConsentManagerProvider
-  options={{
-    mode: 'offline',
-    nonce: yourRequestNonce,
-  }}
->
-  {children}
-</ConsentManagerProvider>
-```
-
-A `nonce` set on an individual script definition still wins, so you can override a single vendor without changing the provider.
-
-> 📝 **Note:**
-> Browsers hide the nonce content attribute once a policy is active. Inspecting the element shows no nonce="", but element.nonce still returns the value — this is expected and not a sign that c15t dropped it.
-
-### Inline style attributes
-
-The `nonce` option covers the elements c15t injects. It cannot cover inline `style="..."` attributes, which several components rely on — a nonce never authorizes a style attribute, because nonces apply to elements only.
-
-Style attributes are governed by `style-src-attr`, and when that directive is absent CSP falls back to `style-src`. A nonce-based style policy therefore blocks them:
-
-```http
-style-src 'self' 'nonce-abc123';
-```
-
-To keep the nonce requirement for stylesheets while still allowing style attributes, set `style-src-attr` explicitly:
-
-```http
-style-src 'self' 'nonce-abc123';
-style-src-attr 'unsafe-inline';
-```
-
-> ⚠️ **Warning:**
-> 'unsafe-inline' on style-src-attr permits any inline style attribute on the page. That is weaker than a nonce, but far narrower than replacing your nonce-based style-src with 'unsafe-inline', which would additionally authorize arbitrary injected \<style> elements. Note that adding 'unsafe-inline' alongside a nonce achieves nothing — a directive that specifies a nonce ignores it. If your threat model does not allow this, expect components that use inline styles to render unstyled.
-
-### Reading the nonce in the App Router
-
-Next.js does not expose the request nonce to client components, so read it in a server component and pass it down. Generate the nonce in middleware, forward it on a request header, then hand it to the provider from your layout:
-
-```ts title="middleware.ts"
-import { NextResponse, type NextRequest } from 'next/server';
-
-export function middleware(request: NextRequest) {
-  const nonce = crypto.randomUUID();
-  const isDev = process.env.NODE_ENV === 'development';
-
-  const csp = [
-    `default-src 'self'`,
-    // Next.js dev tooling (React Refresh and HMR) requires 'unsafe-eval'.
-    `script-src 'self' 'nonce-${nonce}'${isDev ? " 'unsafe-eval'" : ''}`,
-    `style-src 'self' 'nonce-${nonce}'`,
-    // Nonces cannot authorize inline style attributes — see above.
-    `style-src-attr 'unsafe-inline'`,
-  ].join('; ');
-
-  const requestHeaders = new Headers(request.headers);
-  requestHeaders.set('x-nonce', nonce);
-  requestHeaders.set('Content-Security-Policy', csp);
-
-  const response = NextResponse.next({ request: { headers: requestHeaders } });
-  response.headers.set('Content-Security-Policy', csp);
-
-  return response;
-}
-```
-
-> ⚠️ **Warning:**
-> Set the same policy on both the forwarded request headers and the response. Next.js reads the nonce for its own runtime and hydration scripts from the Content-Security-Policy request header during rendering. Setting it only on the response leaves those scripts without a nonce, and the enforced policy then blocks them, so the page never hydrates.
-
-```tsx title="app/layout.tsx"
-import { headers } from 'next/headers';
-import { ConsentManagerProvider } from '@c15t/nextjs';
-
-export default async function RootLayout({
-  children,
-}: {
-  children: React.ReactNode;
-}) {
-  const nonce = (await headers()).get('x-nonce') ?? undefined;
-
-  return (
-    <html lang="en">
-      <body>
-        <ConsentManagerProvider options={{ mode: 'offline', nonce }}>
-          {children}
-        </ConsentManagerProvider>
-      </body>
-    </html>
-  );
-}
-```
-
-## Legal Links
-
-`legalLinks` defines the URLs shown in consent UI text (banner, dialog, and widget where applicable).
-Configure only the links you want to expose.
-
-```tsx
-<ConsentManagerProvider
-  options={{
-    backendURL: 'https://your-instance.c15t.dev',
-    legalLinks: {
-      privacyPolicy: {
-        href: '/privacy',
-        target: '_self',
-      },
-      cookiePolicy: {
-        href: '/cookies',
-        target: '_self',
-      },
-      termsOfService: {
-        href: 'https://example.com/terms',
-        target: '_blank',
-        rel: 'noopener noreferrer',
-        label: 'Terms of Service',
-      },
-    },
-  }}
->
-```
-
-Notes:
-
-* Omitting a key (for example `termsOfService`) hides that link.
-* `label` overrides the translated text for that single link.
-* Use `_self` for internal pages and `_blank` + `rel="noopener noreferrer"` for external pages.
-* Control which of the configured links render in each component via the component's `legalLinks` prop.
-
-## Overrides
-
-`overrides` lets you force location/language signals instead of browser or network detection.
-This is useful for QA, local development, and preview environments.
-
-```tsx
-<ConsentManagerProvider
-  options={{
-    backendURL: 'https://your-instance.c15t.dev',
-    overrides: {
-      country: 'DE',
-      region: 'BY',
-      language: 'de-DE',
-    },
-  }}
->
-```
-
-You can also override Global Privacy Control (GPC) behavior during testing:
-
-```tsx
-<ConsentManagerProvider
-  options={{
-    backendURL: 'https://your-instance.c15t.dev',
-    overrides: {
-      gpc: true,
-    },
-  }}
->
-```
-
-> ⚠️ **Warning:**
-> Treat overrides as an environment/testing tool. Avoid hard-coding production overrides unless that behavior is intentional for your deployment.
-
-## Policy Packs
-
-In hosted mode (recommended), the backend resolves the correct policy automatically — no frontend policy config needed:
-
-```tsx
-<ConsentManagerProvider
-  options={{
-    backendURL: 'https://your-instance.c15t.dev',
-  }}
->
-```
-
-### Fallback: Offline Policies
-
-When no backend is available, `ConsentManagerProvider` accepts `offlinePolicy.policyPacks` for local policy resolution during development, testing, previews, or temporary backend outages:
-
-```tsx
-<ConsentManagerProvider
-  options={{
-    mode: 'offline',
-    offlinePolicy: {
-      i18n: {
-        defaultProfile: 'default',
-        messages: {
-          default: {
-            translations: {
-              en: { cookieBanner: { title: 'Privacy choices' } },
-            },
-          },
-          qc: {
-            fallbackLanguage: 'fr',
-            translations: {
-              en: { cookieBanner: { title: 'Quebec Privacy Settings' } },
-              fr: { cookieBanner: { title: 'Paramètres de confidentialité du Québec' } },
-            },
-          },
-        },
-      },
-      policyPacks: [
-        {
-          id: 'qc_opt_in',
-          match: { regions: [{ country: 'CA', region: 'QC' }] },
-          i18n: { messageProfile: 'qc' },
-          consent: { model: 'opt-in', expiryDays: 365 },
-          ui: { mode: 'banner' },
-        },
-        {
-          id: 'default_world',
-          match: { isDefault: true },
-          consent: { model: 'none' },
-          ui: { mode: 'none' },
-        },
-      ],
-    },
-    overrides: {
-      country: 'CA',
-      region: 'QC',
-    },
-  }}
->
-```
-
-Notes:
-
-* `offlinePolicy` is only used in `offline` mode.
-* Treat offline policies as a development/testing tool or resilience fallback, not the primary production source of truth.
-* `offlinePolicy.i18n` lets offline mode mirror hosted `messageProfile` and profile-local `fallbackLanguage` behavior.
-* Omitting `offlinePolicy.policyPacks` uses the built-in synthetic opt-in fallback banner. Hosted network fallback uses the same opt-in banner.
-* `offlinePolicy: { policyPacks: [] }` is explicit no-banner mode.
-* In hosted mode, backend `policyPacks` remain the source of truth — frontend offline policies never override a live backend decision.
-
-Read the full guide at [Policy Packs](/docs/frameworks/react/policy-packs) and the conceptual model at [Policy Packs Concept](/docs/frameworks/react/concepts/policy-packs).
+Follow [App Router](../app-router.md) or
+[Pages Router](../pages-router.md) for the complete setup.
+Keep `ConsentRoot` mounted across navigation and import the stylesheet once
+at the app root.
 
 ## Props
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`ConsentManagerProviderProps\`|
-|Source Path|\`./packages/react/src/types/consent-manager.ts\`|
-
-\*ExtractedTypeTable: Could not extract "ConsentManagerProviderProps" from "./packages/react/src/types/consent-manager.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+| Prop             | Purpose                                                                                 |
+| ---------------- | --------------------------------------------------------------------------------------- |
+| `state`          | Visitor state or its promise from `resolveConsent`; use `{}` for browser initialization |
+| `config`         | Shared configuration from `defineConsentConfig` in `c15t.config.ts`                     |
+| `backendURL`     | Overrides `config.backendURL`                                                           |
+| `scripts`        | Consent-managed script configurations                                                   |
+| `scriptLoader`   | Script-loader options                                                                   |
+| `networkBlocker` | Network-blocker options, or `false` to disable it                                       |
+| `persistence`    | Browser persistence options; defaults to `true`                                         |
+| `options`        | Provider options such as styling, callbacks and an explicit `mode` override             |
+
+## Provider options
+
+`ConsentRoot` passes `options` to its provider. Keep scripts, persistence and
+network-blocker configuration in their top-level `ConsentRoot` props.
+
+The provider owns initialization, persistence, script loading and subscriptions.
+Changing its initial mode or prefetch configuration is not a supported way to
+switch visitors or backends after mounting.
+
+| Option                | Purpose                                                         |
+| --------------------- | --------------------------------------------------------------- |
+| `mode`                | Hosted, offline or custom transport factory                     |
+| `callbacks`           | Choice, permission and error events                             |
+| `theme`, `components` | Theme tokens and component slot attributes                      |
+| `presentation`        | Prompt and preferences layout behavior                          |
+| `i18n`                | Languages and message overrides                                 |
+| `storageConfig`       | Browser record storage configuration                            |
+| `enabled`             | Set false only when intentionally bypassing 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.
+
+## Listen for consent changes
+
+`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.
+
+## When would I use ConsentProvider directly?
+
+Use `ConsentProvider` from `c15t/next` when you need to manage the runtime and
+transport yourself. For example, it accepts an externally owned `runtime`.
+Its owner must start and dispose that runtime.
+
+For standard Next.js setups, keep `ConsentRoot`. It supports
+[browser initialization](../client-side.md) as well as
+[server prefetch](../server-side.md).
+
+## Clear data when consent is denied
+
+Pass `clearOnRevocation` to `ConsentRoot`, or through the client provider's
+`options`, to declare cookies and Web Storage keys by optional consent category.
+Cleanup runs in the browser after policy resolution. The provider option is
+initial-only. See [clear on revocation](../../../integrations/clear-on-revocation.md)
+for examples, cookie scopes, and browser limits.