@c15t/nextjs 2.0.0-rc.4 → 2.0.0-rc.6

package/docs/internationalization.md

@@ -0,0 +1,197 @@
+---
+title: Internationalization
+description: Translate consent UI into 30+ languages with built-in translations, custom overrides, and automatic browser language detection.
+---
+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 [consent.io](https://consent.io) 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.|
+
+## Basic Configuration
+
+Pass custom translations via the `i18n` option:
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/nextjs';
+
+export default function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        i18n: {
+          locale: 'en',
+          messages: {
+            de: {
+              cookieBanner: {
+                title: 'Datenschutzeinstellungen',
+                description: 'Wir verwenden Cookies, um Ihnen das beste Erlebnis zu bieten.',
+              },
+              common: {
+                acceptAll: 'Alle akzeptieren',
+                rejectAll: 'Alle ablehnen',
+                customize: 'Anpassen',
+                save: 'Speichern',
+              },
+            },
+          },
+        },
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+Custom translations are deep-merged with built-in defaults - you only need to override the keys you want to change.
+
+## 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 and button text (supports `{category}` placeholder)|
+|`legalLinks`|Privacy policy, cookie policy, terms of service link text|
+|`iab`|IAB TCF banner, preference center, vendor list translations|
+
+## Reading Translations
+
+Use the `useTranslations()` hook to access the current language's translations:
+
+```tsx
+import { useTranslations } from '@c15t/nextjs';
+
+function CustomBanner() {
+  const translations = useTranslations();
+
+  return (
+    <div>
+      <h2>{translations.cookieBanner.title}</h2>
+      <p>{translations.cookieBanner.description}</p>
+    </div>
+  );
+}
+```
+
+## Changing Language
+
+Switch the active language at runtime with `setLanguage()`:
+
+```tsx
+import { useConsentManager } from '@c15t/nextjs';
+
+function LanguageSwitcher() {
+  const { setLanguage } = useConsentManager();
+
+  return (
+    <select onChange={(e) => setLanguage(e.target.value)}>
+      <option value="en">English</option>
+      <option value="de">Deutsch</option>
+      <option value="fr">Fran&ccedil;ais</option>
+      <option value="es">Espa&ntilde;ol</option>
+    </select>
+  );
+}
+```
+
+`setLanguage()` re-fetches the consent banner to get server-resolved translations for the new language.
+
+## 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:
+
+```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.',
+        },
+      },
+    },
+  },
+}
+```
+
+## 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/network-blocker.md

@@ -0,0 +1,178 @@
+---
+title: Network Blocker
+description: Block outgoing network requests to third-party domains until the user grants consent for the appropriate category.
+---
+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.
+
+## Configuration
+
+Add `networkBlocker` to your provider options:
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/nextjs';
+
+export function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        networkBlocker: {
+          rules: [
+            {
+              id: 'google-analytics',
+              domain: 'google-analytics.com',
+              category: 'measurement',
+            },
+            {
+              id: 'facebook-pixel',
+              domain: 'facebook.com',
+              pathIncludes: '/tr',
+              category: 'marketing',
+            },
+            {
+              id: 'analytics-post',
+              domain: 'analytics.example.com',
+              methods: ['POST'],
+              category: 'measurement',
+            },
+          ],
+        },
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+## 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})`);
+  },
+}
+```
+
+## Runtime Updates
+
+Update the network blocker configuration at runtime:
+
+```tsx
+import { useConsentManager } from '@c15t/nextjs';
+
+function NetworkBlockerManager() {
+  const { setNetworkBlocker } = useConsentManager();
+
+  const addRule = () => {
+    setNetworkBlocker({
+      rules: [
+        {
+          id: 'new-tracker',
+          domain: 'tracker.example.com',
+          category: 'marketing',
+        },
+      ],
+    });
+  };
+}
+```
+
+## API Reference
+
+### NetworkBlockerRule
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|id|string \|undefined|Optional identifier for the rule. Useful for debugging and logging.|-|Optional|
+|domain|string|Domain that this rule applies to.|-|✅ Required|
+|pathIncludes|string \|undefined|Optional path substring that must be present in the request path for the rule to apply.|-|Optional|
+|methods|string\[] \|undefined|Optional list of HTTP methods that this rule applies to. If omitted, the rule applies to all methods.|-|Optional|
+|category|HasCondition\<AllConsentNames>|Consent condition that must be satisfied to allow the request. When this condition is not satisfied, matching requests will be blocked.|-|✅ Required|
+
+### NetworkBlockerConfig
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|enabled|boolean \|undefined|Whether the network blocker is enabled.|-|Optional|
+|initialConsents|ConsentState \|undefined|The consent state snapshot that is currently used for blocking logic.|-|Optional|
+|logBlockedRequests|boolean \|undefined|Whether to automatically log blocked requests to the console.|-|Optional|
+|onRequestBlocked|Object \|undefined|Callback invoked whenever a request is blocked.|-|Optional|
+|rules|NetworkBlockerRule|Domain rules that determine which requests should be blocked.|-|✅ Required|
+
+#### `initialConsents` ConsentState
+
+The consent state snapshot that is currently used for blocking logic.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|experience|boolean|-|-|✅ Required|
+|functionality|boolean|-|-|✅ Required|
+|marketing|boolean|-|-|✅ Required|
+|measurement|boolean|-|-|✅ Required|
+|necessary|boolean|-|-|✅ Required|
+
+#### `onRequestBlocked`
+
+Callback invoked whenever a request is blocked.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|method|string|The HTTP method of the blocked request (e.g. GET, POST).|-|✅ Required|
+|url|string|The URL of the blocked request.|-|✅ Required|
+|rule|NetworkBlockerRule \|undefined|The rule that caused the request to be blocked, if available. Can be undefined when the blocker configuration changed between evaluation and logging.|-|Optional|
+
+#### `rules` NetworkBlockerRule
+
+Domain rules that determine which requests should be blocked.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|id|string \|undefined|Optional identifier for the rule. Useful for debugging and logging.|-|Optional|
+|domain|string|Domain that this rule applies to.|-|✅ Required|
+|pathIncludes|string \|undefined|Optional path substring that must be present in the request path for the rule to apply.|-|Optional|
+|methods|string\[] \|undefined|Optional list of HTTP methods that this rule applies to. If omitted, the rule applies to all methods.|-|Optional|
+|category|HasCondition\<AllConsentNames>|Consent condition that must be satisfied to allow the request. When this condition is not satisfied, matching requests will be blocked.|-|✅ Required|

package/docs/optimization.md

@@ -0,0 +1,156 @@
+---
+title: Optimization
+description: Improve c15t startup performance in Next.js with rewrites, static prefetching, and rendering tradeoffs.
+lastModified: 2026-03-17
+---
+Use this guide when you care about banner visibility speed, route static-ness, and reducing backend round-trip cost.
+
+## 1) Prefer Same-Origin Rewrites
+
+Proxy c15t requests through your Next.js app so the browser calls your own origin instead of a third-party domain.
+
+```ts title="next.config.ts"
+import type { NextConfig } from 'next';
+
+const config: NextConfig = {
+  async rewrites() {
+    return [
+      {
+        source: '/api/c15t/:path*',
+        destination: `${process.env.NEXT_PUBLIC_C15T_URL}/:path*`,
+      },
+    ];
+  },
+};
+
+export default config;
+```
+
+Then use:
+
+```tsx
+<ConsentManagerProvider options={{ backendURL: '/api/c15t', mode: 'hosted' }}>
+```
+
+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
+
+> ℹ️ **Info:**
+> Set NEXT\_PUBLIC\_C15T\_URL in .env to your backend URL, for example https\://your-instance.c15t.dev.
+>
+> ℹ️ **Info:**
+> Use rewrites for browser-side calls (ConsentManagerProvider, C15tPrefetch). For server-side fetchInitialData(), prefer a direct backend URL (for example https\://your-instance.c15t.dev) to avoid an extra server proxy hop.
+
+## 2) Pick The Right Data Strategy
+
+|Goal|Strategy|Tradeoff|
+|--|--|--|
+|Keep routes fully static|`C15tPrefetch` + `getPrefetchedInitialData()`|Still client-side fetch, but starts earlier|
+|Fastest first banner on dynamic routes|`fetchInitialData()` in a Server Component (do not await)|Route becomes dynamic because of `next/headers`|
+|Simplest setup|Client-only init (no prefetch)|Banner appears later on slow networks|
+
+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|
+
+### Static Routes: Start Fetch Early In The Browser
+
+Use `C15tPrefetch` in your layout and consume the same Promise in the provider.
+
+```tsx title="app/layout.tsx"
+import { C15tPrefetch } from '@c15t/nextjs';
+import { ConsentManager } from '@/components/consent-manager';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <C15tPrefetch
+          backendURL="/api/c15t"
+          overrides={{ country: 'DE', region: 'BE', language: 'de' }}
+        />
+      </head>
+      <body>
+        <ConsentManager>{children}</ConsentManager>
+      </body>
+    </html>
+  );
+}
+```
+
+```tsx title="components/consent-manager/provider.tsx"
+'use client';
+
+import {
+  ConsentManagerProvider,
+  ConsentBanner,
+  ConsentDialog,
+  getPrefetchedInitialData,
+} from '@c15t/nextjs';
+
+export default function ConsentManagerClient({ children }: { children: React.ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        ssrData: getPrefetchedInitialData({
+          backendURL: '/api/c15t',
+          overrides: { country: 'DE', region: 'BE', language: 'de' },
+        }),
+      }}
+    >
+      <ConsentBanner />
+      <ConsentDialog />
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+> ℹ️ **Info:**
+> C15tPrefetch uses Next.js beforeInteractive script loading, so the /init request can start before hydration. In App Router streaming output, this may appear as Next.js script bootstrap data (for example self.\_\_next\_s.push(...)) instead of a literal \<head>\<script> tag.
+>
+> ℹ️ **Info:**
+> If you use overrides or custom credentials in C15tPrefetch, pass the same values to getPrefetchedInitialData(...) so it resolves the matching prefetched request.
+
+## 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.
+
+To customize motion durations and easing, see [Styling](/docs/frameworks/next/styling/overview).
+
+## Reduce Network Overhead
+
+If you must use a cross-origin backend URL, add preconnect so the browser starts DNS/TLS early:
+
+```tsx title="app/layout.tsx"
+<head>
+  <link rel="preconnect" href="https://your-instance.c15t.dev" crossOrigin="" />
+</head>
+```