@c15t/react 2.2.0 → 3.0.0-alpha.0

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

@@ -1,270 +1,62 @@
 ---
-title: ConsentManagerProvider
-description: The root provider component that initializes the consent system and
-  makes consent state available to all child components.
+title: ConsentProvider
+description: Configure the v3 consent runtime and share its state with child components.
 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.
-
-## Basic Usage
+## Mount one provider
 
 ```tsx
-import { type ReactNode } from 'react';
-import { ConsentManagerProvider, ConsentBanner, ConsentDialog } from '@c15t/react';
+import type { ReactNode } from 'react';
+import { ConsentProvider, ConsentBanner, ConsentDialog, ConsentDialogLink, hosted } from 'c15t/react';
+
+const mode = hosted({ url: 'https://your-project.inth.app' });
 
-export default function ConsentManager({ children }: { children: ReactNode }) {
+export function Consent({ children }: { children: ReactNode }) {
   return (
-    <ConsentManagerProvider
-      options={{
-        mode: 'hosted',
-        backendURL: 'https://your-instance.c15t.dev',
-        consentCategories: ['necessary', 'measurement', 'marketing'],
-      }}
-    >
+    <ConsentProvider options={{ mode }}>
+      {children}
       <ConsentBanner />
       <ConsentDialog />
-      {children}
-    </ConsentManagerProvider>
+      <ConsentDialogLink>Privacy settings</ConsentDialogLink>
+    </ConsentProvider>
   );
 }
 ```
 
-## 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: 'https://your-instance.c15t.dev',
-  }}
->
-
-// Offline mode — local cookie storage only
-<ConsentManagerProvider
-  options={{
-    mode: 'offline',
-  }}
->
-```
-
-See [Client Modes](/docs/frameworks/react/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:
+Replace the URL with your Inth project endpoint. Import the adapter stylesheet
+once at the app root. In Next.js this component needs a client boundary; prefer
+the framework's `ConsentRoot` when passing server-resolved state.
 
-```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.
-
-## 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',
-    },
-  }}
->
-```
+## Provider responsibilities
 
-Notes:
+The provider owns initialization, persistence, configured script loading and
+subscriptions. Keep it mounted across client navigation. Its initial mode and
+prefetch configuration belong to the runtime's creation, not a per-render
+mechanism for switching visitors or backends.
 
-* `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.
+| Option                | Purpose                                                         |
+| --------------------- | --------------------------------------------------------------- |
+| `mode`                | Hosted, offline or custom transport factory                     |
+| `scripts`             | Consent-managed script configurations                           |
+| `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 |
 
-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).
+`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.
 
-## Props
+## Observe changes without inventing choices
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`ConsentManagerProviderProps\`|
-|Source Path|\`./packages/react/src/types/consent-manager.ts\`|
+`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.
 
-\*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.\*
+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. See [consent state](../../../guides/consent-state.md) and
+[deployment modes](../../../guides/deployment-modes.md).

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

@@ -1,138 +1,174 @@
 ---
 title: ConsentWidget
-description: An inline consent management widget for embedding in settings or
-  privacy pages. Shows category toggles with accordion layout.
+description: Embed the c15t preference center inline with ConsentWidget on a
+  React privacy page, with draft toggles that record a choice only on Save.
 group: frameworks
 ---
-`ConsentWidget` is a standalone, inline consent management widget. Unlike `ConsentDialog` (which is a modal), the widget embeds directly in your page layout - ideal for privacy settings pages, account preferences, or any page where users should be able to manage consent without a modal overlay.
 
-## Basic Usage
+## Embed the preference center inline
 
-```tsx
-import { ConsentWidget } from '@c15t/react';
+`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
+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
+[quickstart](../quickstart.md); keep `ConsentDialog` mounted as well so the
+banner's Customize button and preference links still have a dialog to open.
+
+```tsx title="src/pages/privacy.tsx"
+import { ConsentWidget } from 'c15t/react';
 
-export function PrivacySettingsPage() {
+export function PrivacyPage() {
   return (
-    <>
-      <h1>Privacy Settings</h1>
-      <p>Manage your cookie preferences below.</p>
-      <ConsentWidget />
-    </>
+    <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>
   );
 }
 ```
 
-## Configuration
-
-```tsx
-<ConsentWidget
-  hideBranding
-  legalLinks={['privacyPolicy', 'cookiePolicy']}
-  noStyle={false}
-  disableAnimation={false}
-/>
-```
-
-## Accordion Behavior
-
-Each consent category is rendered as an expandable accordion item. Clicking the category header expands it to show a description and any associated services. Users can toggle individual categories on or off using the switch control. The `necessary` category is always enabled and cannot be toggled.
-
-## Styling First
-
-> ℹ️ **Info:**
-> Most widget customization should stay in the stock component. Use theme tokens and slots such as consentWidgetAccordion, consentWidgetFooter, consentWidgetFooterSubGroup, and toggle before reaching for compound components. See Styling Overview.
-
-```tsx
-<ConsentManagerProvider
-  options={{
-    theme: {
-      colors: {
-        surface: '#fffdf8',
-        surfaceHover: '#f6f3ee',
-      },
-      slots: {
-        consentWidgetAccordion: 'rounded-3xl border border-black/10',
-        consentWidgetFooter: 'border-t border-black/10 px-6',
-        consentWidgetFooterSubGroup: 'gap-3',
-        toggle: 'shadow-sm',
-      },
-    },
-  }}
->
-  <ConsentWidget />
-</ConsentManagerProvider>
-```
-
-Use `consentWidgetFooter` for styling the whole action area, such as border and padding. Use `consentWidgetFooterSubGroup` for spacing or alignment inside nested button groups.
-
-Widget copy should be changed through `ConsentManagerProvider.options.i18n` so the inline UI stays aligned with the rest of the consent experience.
-
-## Advanced: Compound Components
+The widget uses the provider's policy, translations and transport. It does
+not need a second `ConsentProvider`, and it does not open or close the banner
+or dialog by itself.
 
-Use compound components only when you need to rearrange the widget's existing primitives while keeping policy-aware action grouping:
-
-```tsx
-<ConsentWidget.Root>
-  <ConsentWidget.Accordion type="multiple">
-    <ConsentWidget.AccordionItems />
-  </ConsentWidget.Accordion>
-  <ConsentWidget.PolicyActions />
-</ConsentWidget.Root>
-```
+## Props
 
-* `ConsentWidget.Root` — Theme context provider
-* `ConsentWidget.Accordion` — Radix-based accordion root
-* `ConsentWidget.AccordionItems` — Auto-generates toggle items from consent config
-* `ConsentWidget.AccordionItem` — Individual category item
-* `ConsentWidget.AccordionTrigger` — Clickable header for each item
-* `ConsentWidget.AccordionContent` — Collapsible content area
-* `ConsentWidget.AccordionArrow` — Expand/collapse indicator
-* `ConsentWidget.Switch` — Category toggle switch
-* `ConsentWidget.PolicyActions` — Renders grouped policy-aware actions
-* `ConsentWidget.Footer` — Footer container
-* `ConsentWidget.FooterSubGroup` — Groups related buttons
-* `ConsentWidget.AcceptAllButton` — Accepts all consent
-* `ConsentWidget.RejectButton` — Rejects all consent
-* `ConsentWidget.SaveButton` — Saves custom selections
-
-## Using `renderAction` with c15t Defaults
-
-`ConsentWidget.PolicyActions` renders stock c15t buttons and translations by default.
+| Prop               | Type      | Default    | Description                                                                                                 |
+| ------------------ | --------- | ---------- | ----------------------------------------------------------------------------------------------------------- |
+| `hideBranding`     | `boolean` | `true`     | A standalone widget hides the "Secured by" tag. Pass `false` to show it.                                    |
+| `uiSource`         | `string`  | `'widget'` | Source identifier recorded with saves made from this widget. Inside `ConsentDialog` it inherits `'dialog'`. |
+| `disableAnimation` | `boolean` | `false`    | Skips animations in the widget's parts.                                                                     |
+| `noStyle`          | `boolean` | `false`    | Removes the built-in styling from every part.                                                               |
+
+## Behavior
+
+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
+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.
+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
+expanded at a time.
+
+### Draft and save
+
+Switches edit a draft, not the visitor's permissions. Nothing is recorded
+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
+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.
+
+When the policy changes in a way that affects the choice while the draft has
+unsaved toggles, the widget shows an alert, "The privacy policy changed.
+Review the current choices before saving.", with a Review choices button
+that resets the draft. Save is refused until then. A draft without unsaved
+toggles reseeds silently.
+
+A saved grant that the current policy or a privacy signal such as Global
+Privacy Control overrides shows a note under its row: "Your saved choice is
+restricted by the current privacy settings." The switch still reflects the
+saved value; the effective permission is off.
+
+### Actions
+
+The preference center always renders Reject all, Accept all and Save, with
+Save 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.
+
+### When consent is not owed
+
+Without a resolved policy rule the widget renders nothing and appears as
+soon as a rule resolves, without a remount. A rule with `model: 'none'` and
+an empty `rights` list renders nothing; a `none` rule that lists any right,
+such as `['disclosure']`, renders the widget and Save completes without
+writing a consent record.
+
+For a fully custom preference center, `useConsentDraft()` returns the same
+draft: `values`, `displayedCategories`, `isDirty`, `isStale`, `set`,
+`update`, `acceptAll`, `rejectAll`, `save` and `reset`.
+
+`useConsentDraft` and `ConsentDraftProvider` import from `c15t/react`.
+
+## Accessibility
+
+Each row is a disclosure: a button that expands the category description
+and a switch beside it, so a visitor can read the description without
+changing the choice. Each switch has the category title as its accessible
+name. The policy-change alert uses `role="alert"`, and a restriction note is
+an `output` element linked to its switch through `aria-describedby`. The
+root's `dir` attribute follows the active language.
+
+## Composition
+
+Every part is available as `ConsentWidget.<Part>`. `Root` provides the
+draft and accepts `noStyle`, `disableAnimation` and `uiSource`. `Accordion`
+and `AccordionItems` render the stock rows; `AccordionItem`,
+`AccordionTrigger`, `AccordionTriggerInner`, `AccordionContent`,
+`AccordionArrow` and `Switch` build your own. `PolicyActions` renders the
+resolved actions in `Footer` and `FooterSubGroup` and accepts `renderAction`
+to replace one button; `AcceptAllButton`, `RejectButton`, `SaveButton` and
+`CustomizeButton` are the individual buttons.
+
+`Accordion` is controlled: pass `value` and `onValueChange`, or no
+category description ever opens. The stock `ConsentWidget` holds that state
+for you. In this component, `ConsentWidget` comes from the same import as
+the example at the top of the page:
 
 ```tsx
-<ConsentWidget.PolicyActions />
-```
+import { useState } from 'react';
 
-`renderAction` is optional. Return the stock button compounds when you want custom mapping while preserving built-in c15t behavior and copy:
+export function PreferenceCenter() {
+  const [open, setOpen] = useState<string[]>([]);
 
-```tsx
-<ConsentWidget.PolicyActions
-renderAction={(action, props) => {
-  const { key, ...buttonProps } = props
-
-  switch (action) {
-    case 'accept':
-        return <ConsentWidget.AcceptAllButton key={key} {...buttonProps} />
-    case 'reject':
-        return <ConsentWidget.RejectButton key={key} {...buttonProps} />
-    case 'customize':
-        return <ConsentWidget.SaveButton key={key} {...buttonProps} />
-  }
-}}
-/>
+  return (
+    <ConsentWidget.Root>
+      <ConsentWidget.Accordion
+        value={open}
+        onValueChange={(next) => setOpen(Array.isArray(next) ? next : [next])}
+      >
+        <ConsentWidget.AccordionItems />
+      </ConsentWidget.Accordion>
+      <ConsentWidget.PolicyActions />
+    </ConsentWidget.Root>
+  );
+}
 ```
 
-`renderAction` is still meant for stock button compounds. If you want completely custom button elements and handlers, use `useHeadlessConsentUI()` and render `dialog.actionGroups` manually instead of `ConsentWidget.PolicyActions`.
-
-For a fixed footer layout, render `ConsentWidget.Footer` and `ConsentWidget.FooterSubGroup` manually instead of using `ConsentWidget.PolicyActions`.
-
-If the stock widget structure is already correct, stay with tokens and slots instead of rebuilding the layout.
-
-## Props
-
-|Property|Value|
-|:--|:--|
-|Type Name|\`ConsentWidgetProps\`|
-|Source Path|\`./packages/react/src/components/consent-widget/types.ts\`|
-
-\*ExtractedTypeTable: Could not extract "ConsentWidgetProps" from "./packages/react/src/components/consent-widget/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+Provider component slots for the stock structure are `manager.root`,
+`manager.footer`, `manager.actionGroup`, `accordion.root`,
+`accordion.triggerRow`, `accordion.title`, `accordion.control`,
+`accordion-item.root`, `accordion-item.trigger`, `accordion-item.content`
+and `tag.manager`.
+
+The compound parts import from `c15t/react` as properties of `ConsentWidget`.
+See [Styling](../styling/overview.md) for slots and tokens.
+
+## Verify
+
+Visit the page with the widget. Use a displayed optional category whose permission is
+not restricted by policy or privacy signals such as GPC. One row per displayed
+category appears, with `necessary` on and disabled. Turn that category on:
+`useConsent('<category>')`
+elsewhere on the page still reports the old value. Choose Save: it now
+reports `true`. An open choice banner closes when the save answers its
+prompt; a notice banner stays open until acknowledged. Reload the page: the
+switch keeps the saved value. Without a saved choice or configured draft
+defaults, optional switches start on under an opt-out rule.