@c15t/nextjs 2.1.0 → 2.2.1

package/docs/shared/react/guides/building-headless-components.md

@@ -0,0 +1,110 @@
+---
+title: Building Headless Components
+description: Reference page for building headless components.
+group: reference
+---
+Building custom consent UI is easier now because c15t exposes multiple layers of policy-aware primitives instead of forcing you to reconstruct banner rules by hand.
+
+Think of customization as a ladder:
+
+* stock component props for the shortest path
+* `ConsentBanner.PolicyActions` and `ConsentWidget.PolicyActions` when you want custom structure but still want c15t to resolve policy-aware actions
+* `useHeadlessConsentUI()` when you need fully manual action rendering, custom controls, or non-standard flow
+
+> ⚠️ **Warning:**
+> Headless is the last step in the customization ladder. Use this guide only when pre-built components, tokens, slots, compound components, and noStyle are no longer sufficient.
+
+The headless stack underneath that is:
+
+* `useHeadlessConsentUI()` for policy-aware banner/dialog actions, ordering, layout, and primary actions hints
+* `@c15t/ui/utils` for the pure policy-action helpers that framework packages build on
+* `useConsentManager()` for runtime state, categories, selected consent state, and policy metadata
+* `useTranslations()` for the resolved copy
+* `offlinePolicy.policyPacks` for offline previews that behave like backend policy resolution
+
+The split is intentional: `@c15t/ui` owns pure policy-action resolution, while the framework hooks own visibility, consent mutations, and reactive state.
+
+> ℹ️ **Info:**
+> This guide is about building your own components while still respecting resolved policy-pack behavior. For the general headless overview, see Headless Mode.
+
+## Choose the Smallest Layer That Solves the Job
+
+Start with the smallest API surface that still gives you the behavior you need:
+
+* Stay with stock components when you only need theming, spacing, copy, or legal-link changes
+* Use `ConsentBanner.PolicyActions` or `ConsentWidget.PolicyActions` when you want a custom compound-component layout but still want grouped actions, ordering, and primary emphasis to come from policy
+* Add `renderAction` when the grouping is still correct but you want to remap actions to stock c15t button compounds
+* Reach for `useHeadlessConsentUI()` only when you need custom button elements, need to map `actionGroups` yourself, wire non-button controls, or coordinate the consent UI with a more custom state machine
+
+This order matters because every step down the ladder gives you more control, but also makes it easier for your UI to drift away from the resolved policy if you stop using the provided state.
+
+## Before You Build Headless UI
+
+Do not use headless mode for problems that are still inside the stock component model:
+
+* Use `layout`, `direction`, `primaryButton`, and `legalLinks` before you rebuild banner markup
+* Use `theme.consentActions` before you swap out stock actions
+* Use tokens such as `colors.surface` and `colors.surfaceHover` before raw CSS overrides
+* Use slots such as `consentBannerCard`, `consentBannerFooter`, and `consentDialogCard` before compound components
+* Use `ConsentManagerProvider.options.i18n` before rebuilding UI just to change text
+
+A good rule: if the stock banner or dialog structure is still correct, you probably do not need headless mode.
+
+## What the Headless Tooling Gives You
+
+The main win is that your custom UI can stay aligned with policy packs without duplicating policy logic in your components.
+
+`useHeadlessConsentUI()` already resolves:
+
+* which actions are allowed
+* the order those actions should render in
+* grouped actions from policy `layout`
+* layout `direction` (`row` or `column`)
+* the primary actions
+* UI profile and scroll-lock hints
+* whether the banner or dialog should currently be visible
+
+The hook also gives you the policy-aware action helpers you are expected to call:
+
+* `performBannerAction('accept' | 'reject')`
+* `performDialogAction('accept' | 'reject')`
+* `saveCustomPreferences()` for the dialog `customize` action
+* `openDialog()`, `openBanner()`, and `closeUI()` for surface visibility
+
+That means your component mostly focuses on markup and design-system concerns instead of re-implementing policy interpretation.
+
+For most compound-component layouts, start with `ConsentBanner.PolicyActions` or `ConsentWidget.PolicyActions`. They render stock c15t buttons and translations by default, and `renderAction` is only needed when you want to override which stock compound renders for each action. Reach for manual `actionGroups` mapping when you need action rendering that no longer fits the stock button compounds.
+
+## What Headless Is Not For
+
+Headless mode is not the recommended path for:
+
+* changing the banner footer background
+* rounding the stock banner card
+* restyling stock banner or dialog buttons
+* changing consent copy
+
+Those should stay in the pre-built stack with tokens, slots, `theme.consentActions`, and provider `i18n`.
+
+## What a Policy-Aware Headless Component Should Respect
+
+When you build custom banner or dialog components, make sure they use:
+
+* `activeUI` or `banner.isVisible` / `dialog.isVisible` for visibility
+* `allowedActions`, `actionGroups`, and `primaryActions` instead of hard-coding buttons
+* `primaryActions` for visual emphasis
+* `consentCategories` when deciding which category toggles to render
+* `policyDecision` when you want to debug why a specific UI state was chosen
+
+If you ignore those values, your custom UI can drift away from the resolved policy pack even though the underlying consent engine is configured correctly.
+
+## Validation and Testing
+
+If you are building a reusable headless component library, validate your rendered UI against the resolved runtime policy in tests.
+
+The core package exposes:
+
+* `getEffectivePolicy(initData)` to read the resolved policy from `/init`
+* `validateUIAgainstPolicy({ policy, state })` to detect mismatches such as wrong actions, layout, or mode
+
+This is useful when your design system renders custom button arrangements and you want tests to catch policy drift early.

package/docs/shared/react/guides/callbacks.md

@@ -0,0 +1,89 @@
+---
+title: Callbacks
+description: Reference page for callbacks.
+group: reference
+---
+Callbacks let you run custom code at key points in the consent lifecycle. Define them in the provider or runtime `callbacks` option, or register them dynamically after initialization.
+
+For analytics SDKs and other change-only integrations, prefer `subscribeToConsentChanges()` or `onConsentChanged`. Use `onConsentSet` when you want the broader lifecycle signal, including initialization, automatic defaults, and replay-aware registration.
+
+## Choose the Right Surface
+
+|Surface|Replays when registered late?|Fires on init / hydration / auto-grants?|Best for|
+|--|--|--|--|
+|`onBannerFetched`|Yes, via `setCallback('onBannerFetched', ...)` after init|Yes|Logging resolved policy, location, and translations|
+|`onConsentSet`|Yes, via `setCallback('onConsentSet', ...)`|Yes|Broad lifecycle hooks, debugging, and integrations that want the latest full state regardless of how it was reached|
+|`onConsentChanged`|No|No|Declarative change-only integrations|
+|`subscribeToConsentChanges()`|No|No|Canonical change-only subscriptions after mount|
+
+> ℹ️ **Info:**
+> Script.onConsentChange is a script-scoped lifecycle hook. It is not the global consent change API for analytics SDKs or other app-wide integrations.
+
+## Available Callbacks
+
+### `onBannerFetched`
+
+Called when the consent banner data is fetched from the backend (or loaded from SSR data). The payload includes jurisdiction info, location data, and resolved translations.
+
+```tsx
+onBannerFetched: ({ jurisdiction, location, translations }) => {
+  // jurisdiction: 'GDPR' | 'CCPA' | { code: 'GDPR', message: '...' } | ...
+  // location: { countryCode: 'DE', regionCode: 'BY' }
+  // translations: { language: 'de', translations: {...} }
+}
+```
+
+### `onConsentSet`
+
+Called whenever c15t broadly settles consent state: store initialization, automatic defaults during init, explicit saves, and replay via `setCallback('onConsentSet', ...)`.
+
+```tsx
+onConsentSet: ({ preferences }) => {
+  // preferences: { necessary: true, measurement: true, marketing: false, ... }
+  console.log('Latest consent state:', preferences);
+}
+```
+
+### `onConsentChanged`
+
+Called only after an explicit `saveConsents()` or `setConsent()` that actually changes the saved consent state. It never fires on store creation, hydration, automatic grants, unchanged saves, or `setCallback('onConsentChanged', ...)`.
+
+```tsx
+onConsentChanged: ({
+  preferences,
+  previousPreferences,
+  allowedCategories,
+  deniedCategories,
+  previousAllowedCategories,
+  previousDeniedCategories,
+}) => {
+  analytics.syncConsent({
+    allowedCategories,
+    deniedCategories,
+    previousAllowedCategories,
+    previousDeniedCategories,
+  });
+}
+```
+
+### `onError`
+
+Called when an error occurs during consent operations (e.g., API request failure). If no `onError` callback is provided, errors are logged to `console.error`.
+
+```tsx
+onError: ({ error }) => {
+  // error: string describing what went wrong
+  Sentry.captureMessage(`Consent error: ${error}`);
+}
+```
+
+### `onBeforeConsentRevocationReload`
+
+Called synchronously before the page reloads due to consent revocation. This is your last chance to run cleanup before the reload. Keep this callback fast - avoid async operations.
+
+```tsx
+onBeforeConsentRevocationReload: ({ preferences }) => {
+  // Flush any pending data
+  navigator.sendBeacon('/api/flush', JSON.stringify({ session: sessionId }));
+}
+```

package/docs/shared/react/guides/headless.md

@@ -0,0 +1,31 @@
+---
+title: Headless
+description: Reference page for headless.
+group: reference
+---
+c15t's headless mode means using the hooks (`useConsentManager`, `useTranslations`, etc.) without any pre-built UI components. This gives you complete control over the consent experience.
+
+Before you go headless, walk the customization ladder in order:
+
+1. **Pre-built components** - Use provider options, component props, tokens, slots, and `theme.consentActions`
+2. **Compound components** - Rearrange c15t primitives when the markup order must change
+3. **`noStyle`** - Keep c15t structure but replace its styling
+4. **Headless** - Use only hooks and build the entire UI yourself
+
+## When to Go Headless
+
+Go headless when:
+
+* Your design system requires complete control over markup
+* You need a consent flow that doesn't fit the banner/dialog pattern
+* You want to embed consent choices inline rather than as overlays
+
+Use a lower-power tool instead when:
+
+* The component structure works but the styling doesn't -> use tokens, slots, or `noStyle`
+* You only need to rearrange existing c15t parts -> use compound components
+* You want to change copy -> use `ConsentManagerProvider.options.i18n`
+* You only need to restyle stock actions -> use `theme.consentActions`
+
+> ⚠️ **Warning:**
+> Headless mode is not the first answer for pure theming. If you are still trying to debug why a banner footer color did not change, stay in the styling system and verify the token-to-component mapping before you rebuild the UI.

package/docs/shared/react/guides/iframe-blocking.md

@@ -0,0 +1,65 @@
+---
+title: Iframe Blocking
+description: Reference page for iframe blocking.
+group: reference
+---
+Embedded iframes from third parties (YouTube, Google Maps, social media widgets) can set cookies and track users without their consent. c15t provides two approaches to gate iframes behind consent:
+
+1. **`<Frame>` component** - A React component that conditionally renders children based on consent
+2. **HTML `data-category` attribute** - For raw `<iframe>` elements outside of React
+
+### Custom Placeholder
+
+Replace the default placeholder with your own UI:
+
+```tsx
+<Frame
+  category="marketing"
+  placeholder={
+    <div className="flex items-center justify-center h-64 bg-gray-100 rounded">
+      <p>Enable marketing cookies to watch this video.</p>
+    </div>
+  }
+>
+  <iframe src="https://www.youtube.com/embed/..." />
+</Frame>
+```
+
+### Compound Components
+
+Build custom placeholder layouts using compound components:
+
+```tsx
+<Frame.Root category="marketing">
+  <Frame.Title category="marketing" />
+  <Frame.Button category="marketing" />
+</Frame.Root>
+```
+
+## HTML Attribute Approach
+
+For iframes outside of React (e.g., CMS content, server-rendered HTML), add `data-category` and use `data-src` instead of `src`:
+
+```html
+<iframe
+  data-src="https://www.youtube.com/embed/dQw4w9WgXcQ"
+  data-category="marketing"
+  width="560"
+  height="315"
+></iframe>
+```
+
+When consent for the specified category is granted, c15t automatically swaps `data-src` to `src`, loading the iframe. When consent is revoked, `src` is moved back to `data-src`.
+
+### Dynamic Iframes
+
+c15t uses a `MutationObserver` to watch for dynamically added iframes. Any iframe with `data-category` added to the DOM after initialization is automatically processed.
+
+## API Reference
+
+|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.\*

package/docs/shared/react/guides/internationalization.md

@@ -0,0 +1,123 @@
+---
+title: Internationalization
+description: Reference page for internationalization.
+group: reference
+---
+c15t ships with built-in translations for 30+ languages via the `@c15t/translations` package. Language detection happens automatically based on the browser's language preference, and you can override or extend translations for any language.
+
+In c15t v2, the preferred config shape is `i18n` with `locale`, `detectBrowserLanguage`, and `messages`.
+
+There are two ways c15t can load translations: client-side or server-side.
+
+|Server-side|Client-side|
+|--|--|
+|The best way to reduce bundle size and improve performance. We can detect the user's language based on the browser's language settings, allowing for the most accurate translations. By default, when using a [inth.com](https://inth.com) hosted instance, [these languages](https://github.com/c15t/c15t/tree/main/packages/translations/src/translations) are supported.|Bundled with the application allowing for multiple languages to be supported without the need for a backend. The more translations you have, the larger the bundle size will be, which may impact the performance of your application.|
+
+## Translation Package Imports
+
+Use the import path that matches your use case:
+
+* `@c15t/translations`: types, utilities, and `enTranslations` only (smallest client bundle)
+* `@c15t/translations/en`: English-only translation object
+* `@c15t/translations/all`: full `baseTranslations` map for all bundled locales
+
+If you bundle translations client-side and need multiple languages, import from `@c15t/translations/all` explicitly:
+
+```tsx
+import { baseTranslations } from '@c15t/translations/all';
+
+const translations = {
+  en: baseTranslations.en,
+  de: baseTranslations.de,
+  fr: baseTranslations.fr,
+};
+```
+
+## Translation Sections
+
+The `Translations` object is organized into sections:
+
+|Section|Controls|
+|--|--|
+|`common`|Shared button labels: acceptAll, rejectAll, customize, save|
+|`cookieBanner`|Banner title and description|
+|`consentManagerDialog`|Dialog title and description|
+|`consentTypes`|Per-category title and description (keyed by AllConsentNames)|
+|`frame`|Frame placeholder title, button, loading, and error text (title and button support `{category}`)|
+|`legalLinks`|Privacy policy, cookie policy, terms of service link text|
+|`iab`|IAB TCF banner, preference center, vendor list translations|
+
+## Automatic Language Detection
+
+By default, c15t detects the browser's language (`navigator.language`) and selects the closest matching translation. If custom `messages` are configured, fallback stays within your configured languages before using `locale` (or `'en'`) as the preferred fallback language.
+
+When backend policy packs use `i18n.messageProfile`, the active language pool comes only from that resolved profile.
+
+Example: if your Europe profile defines `en`, `fr`, and `de`, and your default profile defines `en`, `es`, and `pt`, a Europe visitor can resolve to `en`, `fr`, or `de`, but not `es`, `pt`, or `zh`.
+
+Use profile-local `fallbackLanguage` inside backend `i18n.messages` to choose which configured language a policy profile should fall back to when the browser asks for an unsupported locale.
+
+Disable auto-detection to always use `locale`:
+
+```tsx
+i18n: {
+  locale: 'de',
+  detectBrowserLanguage: false,
+  messages: { ... },
+}
+```
+
+If you need a policy to always use one specific language regardless of browser preference, set `policy.i18n.language` on the backend policy pack.
+
+## Custom Consent Type Labels
+
+Override the title and description for individual consent categories. Frame
+placeholders use that title anywhere their message contains `{category}`, so
+the title and action stay consistent:
+
+```tsx
+i18n: {
+  messages: {
+    en: {
+      consentTypes: {
+        measurement: {
+          title: 'Analytics & Performance',
+          description: 'Help us understand how visitors interact with our site.',
+        },
+        marketing: {
+          title: 'Advertising',
+          description: 'Used to deliver relevant ads and measure campaign effectiveness.',
+        },
+      },
+      frame: {
+        title: 'Allow {category} consent to view this content.',
+        actionButton: 'Enable {category} consent',
+        loading: 'Loading content…',
+        error: 'This content could not be loaded.',
+      },
+    },
+  },
+}
+```
+
+## Legacy `translations` Compatibility
+
+The legacy syntax is still supported in 2.0 for RC compatibility:
+
+```tsx
+// Legacy (still supported)
+translations: {
+  defaultLanguage: 'en',
+  disableAutoLanguageSwitch: true,
+  translations: { ... },
+}
+
+// Preferred in v2
+i18n: {
+  locale: 'en',
+  detectBrowserLanguage: false,
+  messages: { ... },
+}
+```
+
+If both are provided, `i18n` takes precedence.

package/docs/shared/react/guides/network-blocker.md

@@ -0,0 +1,72 @@
+---
+title: Network Blocker
+description: Reference page for network blocker.
+group: reference
+---
+The network blocker intercepts outgoing `fetch` and `XMLHttpRequest` calls and blocks them based on consent state and domain rules. This catches tracking requests that happen outside of script loading - for example, beacon calls, API requests to analytics endpoints, or pixel fires from already-loaded scripts.
+
+## Rule Matching
+
+Rules match requests using three criteria:
+
+### Domain matching
+
+The `domain` field matches the request hostname. Subdomains are automatically included - a rule for `google-analytics.com` also matches `www.google-analytics.com` and `stats.google-analytics.com`.
+
+### Path matching
+
+The optional `pathIncludes` field requires the request URL path to contain the specified substring. This lets you target specific endpoints without blocking the entire domain.
+
+### Method matching
+
+The optional `methods` array restricts the rule to specific HTTP methods. If omitted, the rule applies to all methods.
+
+## Consent Conditions
+
+Like the script loader, `category` accepts a `HasCondition`:
+
+```tsx
+// Simple
+{ category: 'measurement' }
+
+// Must have both
+{ category: { and: ['measurement', 'marketing'] } }
+
+// Must have either
+{ category: { or: ['measurement', 'marketing'] } }
+```
+
+## Monitoring Blocked Requests
+
+### Console logging
+
+Blocked requests are logged to the console by default. Disable with `logBlockedRequests: false`.
+
+### Callback
+
+Use `onRequestBlocked` to handle blocked requests programmatically:
+
+```tsx
+networkBlocker: {
+  rules: [...],
+  onRequestBlocked: ({ method, url, rule }) => {
+    console.log(`Blocked ${method} ${url} (rule: ${rule?.id})`);
+  },
+}
+```
+
+## API Reference
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`NetworkBlockerRule\`|
+|Source Path|\`./packages/core/src/libs/network-blocker/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "NetworkBlockerRule" from "./packages/core/src/libs/network-blocker/types.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|\`NetworkBlockerConfig\`|
+|Source Path|\`./packages/core/src/libs/network-blocker/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "NetworkBlockerConfig" from "./packages/core/src/libs/network-blocker/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/guides/optimization.md

@@ -0,0 +1,44 @@
+---
+title: Optimization
+description: Reference page for optimization.
+group: reference
+---
+Use this guide when you care about banner visibility speed, route static-ness, and reducing backend round-trip cost.
+
+Why this helps:
+
+* Same-origin requests avoid extra DNS/TLS setup in many deployments
+* Ad blockers are less likely to block your init endpoint
+* You can change backend infrastructure without touching client code
+
+In production benchmarks with a same-origin rewrite, prefetching strategies show measurable improvement over client-only init:
+
+|Strategy|Scripts loaded|Data request starts|Banner visible|
+|--|--|--|--|
+|Client-only (no prefetch)|baseline|baseline|baseline|
+|Browser prefetch|\~1.3x faster|\~2.6x earlier|\~1.25x faster|
+|Server prefetch|\~2x faster|before page loads|\~1.9x faster|
+
+## Keep The Provider Mounted Across Navigation
+
+Mount the consent provider at the app root so route transitions do not remount it.
+
+Why this helps:
+
+* Avoids re-running init work on client-side navigation
+* Prevents extra callback churn from remount cycles
+* Keeps banner/dialog state stable between route transitions
+
+## Animation Performance
+
+The default motion tokens are tuned for speed-first product UI:
+
+|Token|Duration|Used for|
+|--|--|--|
+|`fast`|80ms|Banner slide + overlay, card scale, button hover, widget entry/exit|
+|`normal`|150ms|Accordion, switch toggle|
+|`slow`|200ms|Dialog trigger snap, tab indicator|
+
+These defaults follow the principle that product UI should be fast and purposeful — animations exist for spatial continuity, not decoration. In benchmarks, animation duration contributes a constant floor to "data fetched → banner visible" timing. The default tokens sit at the lower end of standard UI ranges (80-200ms) to minimize that floor.
+
+If you must use a cross-origin backend URL, add preconnect so the browser starts DNS/TLS early: