@c15t/nextjs 2.1.0 → 2.2.1

package/docs/shared/react/components/consent-dialog.md

@@ -0,0 +1,119 @@
+---
+title: Consent Dialog
+description: Reference page for consent dialog.
+group: reference
+---
+`ConsentDialog` is a modal that shows toggles for each consent category. In **opt-in jurisdictions**, it typically opens when users click "Customize" on `ConsentBanner`. It can also be controlled programmatically for use on settings pages regardless of jurisdiction.
+
+## Floating Trigger
+
+Add a floating button that lets users re-open the dialog after dismissing the banner:
+
+```tsx
+{/* Default trigger */}
+<ConsentDialog showTrigger />
+
+{/* Custom trigger */}
+<ConsentDialog
+  showTrigger={{
+    icon: 'settings',
+    defaultPosition: 'bottom-left',
+    showWhen: 'after-consent',
+    size: 'sm',
+  }}
+/>
+```
+
+## Branding
+
+Hide the c15t branding tag:
+
+```tsx
+<ConsentDialog hideBranding />
+```
+
+## Styling First
+
+> ℹ️ **Info:**
+> If you are only changing visuals, stay with the stock dialog and use the theme system first. Start with tokens and slots such as consentDialogCard, consentWidgetFooter, and consentDialogTag. See Styling Overview.
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    theme: {
+      colors: {
+        surface: '#fffdf8',
+        surfaceHover: '#f6f3ee',
+      },
+      slots: {
+        consentDialogCard: 'rounded-[32px] shadow-xl',
+        consentDialogHeader: 'gap-3',
+        consentWidgetFooter: 'gap-3 pt-6',
+        consentDialogTag: 'shadow-none',
+      },
+    },
+  }}
+>
+  <ConsentDialog />
+</ConsentManagerProvider>
+```
+
+Dialog copy should be changed through `ConsentManagerProvider.options.i18n`, not by rebuilding the dialog structure.
+
+## Advanced: Compound Components
+
+Use compound components only when you need custom dialog markup while still keeping c15t primitives and policy-aware footer actions:
+
+```tsx
+<ConsentDialog.Root>
+  <ConsentDialog.Overlay />
+  <ConsentDialog.Card>
+    <ConsentDialog.Header>
+      <ConsentDialog.HeaderTitle />
+      <ConsentDialog.HeaderDescription />
+    </ConsentDialog.Header>
+    <ConsentDialog.Content>
+      <ConsentWidget.Root>
+        <ConsentWidget.Accordion type="single">
+          <ConsentWidget.AccordionItems />
+        </ConsentWidget.Accordion>
+        <ConsentWidget.PolicyActions />
+      </ConsentWidget.Root>
+    </ConsentDialog.Content>
+    <ConsentDialog.Footer />
+  </ConsentDialog.Card>
+</ConsentDialog.Root>
+```
+
+* `ConsentDialog.Root` — Portal container with focus trap, scroll lock, and animation
+* `ConsentDialog.Card` — Main dialog card
+* `ConsentDialog.Header` — Contains title and description
+* `ConsentDialog.HeaderTitle` — Dialog title
+* `ConsentDialog.HeaderDescription` — Description with optional `legalLinks`
+* `ConsentDialog.Content` — Main content area (typically contains `ConsentWidget`)
+* `ConsentDialog.Footer` — Footer with optional branding (`hideBranding` prop)
+* `ConsentDialog.Overlay` — Backdrop overlay
+* `ConsentWidget.PolicyActions` — Renders policy-aware grouped dialog actions
+
+For a quick pre-composed layout, use the shorthand card:
+
+```tsx
+<ConsentDialog.Root>
+  <ConsentDialog.ConsentCustomizationCard />
+</ConsentDialog.Root>
+```
+
+`ConsentWidget.PolicyActions` uses stock c15t widget buttons and translations by default. Pass `renderAction` only when you need to customize the action mapping, and return stock widget button compounds if you want to preserve built-in behavior and copy.
+
+For fully manual control over dialog action rendering, use `useHeadlessConsentUI()` and map `dialog.actionGroups` yourself.
+
+If the stock dialog structure still works, prefer tokens, slots, and provider configuration instead.
+
+## Props
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`ConsentDialogProps\`|
+|Source Path|\`./packages/react/src/components/consent-dialog/consent-dialog.tsx\`|
+
+\*ExtractedTypeTable: Could not extract "ConsentDialogProps" from "./packages/react/src/components/consent-dialog/consent-dialog.tsx" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*

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

@@ -0,0 +1,225 @@
+---
+title: Consent Manager Provider
+description: Reference page for consent manager provider.
+group: reference
+---
+`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.
+
+## 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.\*
+
+## 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.
+
+## 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).
+
+## 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.\*

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

@@ -0,0 +1,121 @@
+---
+title: Consent Widget
+description: Reference page for consent widget.
+group: reference
+---
+`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.
+
+## 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
+
+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>
+```
+
+* `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.
+
+```tsx
+<ConsentWidget.PolicyActions />
+```
+
+`renderAction` is optional. Return the stock button compounds when you want custom mapping while preserving built-in c15t behavior and copy:
+
+```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} />
+  }
+}}
+/>
+```
+
+`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.\*

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

@@ -0,0 +1,81 @@
+---
+title: Dev Tools
+description: Reference page for dev tools.
+group: reference
+---
+`DevTools` is a floating panel that shows the internal state of the consent manager. Use it during development to inspect consent values, geolocation results, loaded scripts, and debug consent flows. Also exported as `C15TDevTools` if you need to avoid naming conflicts with other devtools.
+
+> ⚠️ **Warning:**
+> DevTools should only be included in development builds. The component renders nothing to the React tree - it injects directly into document.body.
+
+## Installation
+
+DevTools lives in a separate package to keep it out of production bundles:
+
+```bash
+bun add -D @c15t/dev-tools
+```
+
+## Configuration
+
+```tsx
+<DevTools
+  position="bottom-right"  // 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
+  defaultOpen={false}       // Start with panel open
+  namespace="c15tStore"     // Store namespace to connect to
+  disabled={false}          // Disable without removing from tree
+/>
+```
+
+## Panels
+
+|Panel|What it shows|
+|--|--|
+|**Consents**|Current consent state for all categories|
+|**Location**|Detected jurisdiction, country, region, and consent model|
+|**Scripts**|Configured scripts and their load status|
+|**IAB**|IAB TCF state (when enabled) - TC string, vendor consents, purposes|
+|**Events**|Timeline of consent events and state changes|
+|**Actions**|Buttons to trigger consent actions (accept all, reject all, reset)|
+
+## TanStack Devtools
+
+`@c15t/dev-tools/tanstack` exposes a panel component and plugin factory that match TanStack Devtools' plugin API, so c15t can sit beside Query and Router without a custom mount adapter:
+
+```tsx
+import * as React from 'react';
+import { useRouter } from '@tanstack/react-router';
+import { TanStackDevtools } from '@tanstack/react-devtools';
+import { ReactQueryDevtoolsPanel } from '@tanstack/react-query-devtools';
+import { TanStackRouterDevtoolsPanel } from '@tanstack/react-router-devtools';
+import { c15tDevtools } from '@c15t/dev-tools/tanstack';
+
+export function AppDevtools() {
+  const router = useRouter();
+
+  return (
+    <TanStackDevtools
+      plugins={[
+        {
+          name: 'TanStack Query',
+          render: <ReactQueryDevtoolsPanel />,
+        },
+        {
+          name: 'TanStack Router',
+          render: <TanStackRouterDevtoolsPanel router={router} />,
+        },
+        c15tDevtools(),
+      ]}
+    />
+  );
+}
+```
+
+## Props
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`C15TDevToolsProps\`|
+|Source Path|\`./packages/dev-tools/src/react.ts\`|
+
+\*ExtractedTypeTable: Could not extract "C15TDevToolsProps" from "./packages/dev-tools/src/react.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*

package/docs/shared/react/components/frame.md

@@ -0,0 +1,52 @@
+---
+title: Frame
+description: Reference page for frame.
+group: reference
+---
+`Frame` conditionally renders its children based on consent state. When consent for the specified category is not granted, a placeholder is shown instead. Children are not mounted at all until consent is given, preventing any network requests or script execution.
+
+## Custom Placeholder
+
+Replace the default placeholder:
+
+```tsx
+<Frame
+  category="experience"
+  placeholder={
+    <div className="rounded-lg border p-8 text-center">
+      <p>This content requires experience cookies.</p>
+      <p>Please enable them in your privacy settings.</p>
+    </div>
+  }
+>
+  <InteractiveWidget />
+</Frame>
+```
+
+## Compound Components
+
+Build fully custom placeholder layouts:
+
+```tsx
+<Frame.Root category="marketing">
+  <Frame.Title category="marketing" />
+  <Frame.Button category="marketing" />
+</Frame.Root>
+```
+
+* `Frame.Root` - Container with default placeholder styling
+* `Frame.Title` - Displays a consent-request message with the category name
+* `Frame.Button` - Button that opens the consent dialog for the specified category
+
+## Automatic Category Registration
+
+When `Frame` mounts, it automatically adds its `category` to the active `consentCategories` list. This means you don't need to explicitly list the category in your provider's `consentCategories` option - if a `Frame` component uses it, it will be registered.
+
+## Props
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`FrameProps\`|
+|Source Path|\`./packages/react/src/components/frame/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "FrameProps" from "./packages/react/src/components/frame/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*