@c15t/react 2.0.4 → 2.2.0-canary-20260727202135

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:

package/docs/shared/react/guides/policy-packs.md

@@ -0,0 +1,173 @@
+---
+title: Policy Packs
+description: Reference page for policy packs.
+group: reference
+---
+Policy packs configure how c15t handles regional consent — which model (opt-in, opt-out, none), which categories, and what UI to show. The backend resolves the right policy automatically based on the visitor's location.
+
+**For most apps, you just need a `ConsentManagerProvider` pointing at your backend with presets configured there.** The frontend receives the resolved policy via the `/init` response — no client-side policy config required.
+
+When a backend isn't available — local development, static previews, Storybook, automated tests, or as a resilience fallback during a temporary outage — you can pass policies directly to the provider via `offlinePolicy.policyPacks` and c15t resolves them locally.
+
+> ℹ️ **Info:**
+> For QA and testing, use the c15t DevTools to simulate different regions and policy responses against your real backend, rather than switching to offline mode.
+
+## Hosted Mode (Recommended)
+
+When using inth.com or a self-hosted backend, the provider connects automatically. No policy configuration is needed on the frontend:
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    backendURL: 'https://your-instance.c15t.dev',
+  }}
+>
+  <ConsentBanner />
+  <ConsentDialog />
+  {children}
+</ConsentManagerProvider>
+```
+
+The backend resolves the correct policy based on the visitor's geo data and returns it in the `/init` response. Configure your presets on the backend side.
+
+## Offline Presets (Development and Fallback)
+
+Use offline presets mainly for local development, Storybook, deterministic tests, or temporary backend outages:
+
+```tsx
+import { policyPackPresets } from '@c15t/react';
+
+offlinePolicy: {
+  i18n: {
+    defaultProfile: 'default',
+    messages: {
+      default: {
+        translations: {
+          en: { cookieBanner: { title: 'Privacy choices' } },
+        },
+      },
+      eu: {
+        fallbackLanguage: 'en',
+        translations: {
+          en: { cookieBanner: { title: 'EU GDPR Consent' } },
+          fr: { cookieBanner: { title: 'Consentement RGPD' } },
+          de: { cookieBanner: { title: 'GDPR-Einwilligung' } },
+        },
+      },
+    },
+  },
+  policyPacks: [
+    {
+      ...policyPackPresets.europeOptIn(),
+      i18n: { messageProfile: 'eu' },
+    },
+    policyPackPresets.californiaOptOut(),
+    policyPackPresets.worldNoBanner(),
+  ],
+}
+```
+
+Available presets:
+
+|Preset|Model|Matches|
+|--|--|--|
+|`europeOptIn()`|`opt-in`|EEA + UK countries + geo fallback|
+|`europeIab()`|`iab`|EEA + UK countries + geo fallback (TCF 2.3)|
+|`californiaOptOut()`|`opt-out`|US-CA region|
+|`quebecOptIn()`|`opt-in`|CA-QC region|
+|`worldNoBanner()`|`none`|default fallback|
+
+## Provider Shape
+
+Configure packs through `offlinePolicy.policyPacks`. Add `offlinePolicy.i18n`
+when you want local previews or fallback behavior to mirror hosted policy-profile language behavior:
+
+```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',
+          match: { isDefault: true },
+          consent: { model: 'none' },
+          ui: { mode: 'none' },
+        },
+      ],
+    },
+    overrides: { country: 'CA', region: 'QC' },
+  }}
+>
+```
+
+With that setup, offline mode resolves language the same way as hosted mode:
+
+* the active policy profile defines the allowed language set
+* each profile can define its own `fallbackLanguage`
+* built-in translations only fill missing keys for the selected language
+
+## Fallback Behavior
+
+|Configuration|Result|
+|--|--|
+|`offlinePolicy.policyPacks` omitted|Synthetic opt-in fallback banner (also used for hosted network fallback)|
+|`offlinePolicy: { policyPacks: [] }`|Explicit no-banner mode|
+|Non-empty pack, no match, no default|Explicit no-banner mode|
+
+Omitting the option gives you a safe opt-in default for local development and outage scenarios. Providing it tells c15t you want deterministic preview or fallback behavior exactly as configured.
+
+## QA and Debugging
+
+The best way to test regional consent behavior is with the [c15t DevTools](/docs/frameworks/react/dev-tools). The DevTools Policy panel lets you simulate different countries, regions, and GPC signals against your real backend — no code changes needed.
+
+For deeper inspection:
+
+* Read `policy` and `policyDecision` from `useConsentManager()` to see the resolved config
+* Open the DevTools Policy panel to inspect matcher resolution and fingerprints
+* Compare your frontend preview with the backend `/init` response before shipping
+
+If you need fully deterministic resolution without a backend during testing or preview work (for example, in automated tests or Storybook), pair `offlinePolicy.policyPacks` with `overrides`:
+
+```tsx
+options={{
+  mode: 'offline',
+  offlinePolicy: {
+    policyPacks: [
+      policyPackPresets.europeOptIn(),
+      policyPackPresets.californiaOptOut(),
+      policyPackPresets.worldNoBanner(),
+    ],
+  },
+  overrides: {
+    country: 'US',
+    region: 'CA',
+    language: 'en-US',
+    gpc: true, // Simulate Global Privacy Control
+  },
+}}
+```