@c15t/react 2.2.1 → 3.0.0-alpha.0

package/docs/frameworks/react/network-blocker.md

@@ -1,140 +0,0 @@
----
-title: Network Blocker
-description: Block outgoing network requests to third-party domains until the
-  user grants consent for the appropriate category.
-group: frameworks
----
-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/react';
-
-export function ConsentManager({ children }: { children: ReactNode }) {
-  return (
-    <ConsentManagerProvider
-      options={{
-        mode: 'hosted',
-        backendURL: 'https://your-instance.c15t.dev',
-        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/react';
-
-function NetworkBlockerManager() {
-  const { setNetworkBlocker } = useConsentManager();
-
-  const addRule = () => {
-    setNetworkBlocker({
-      rules: [
-        {
-          id: 'new-tracker',
-          domain: 'tracker.example.com',
-          category: 'marketing',
-        },
-      ],
-    });
-  };
-}
-```
-
-## 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/frameworks/react/optimization.md

@@ -1,148 +0,0 @@
----
-title: Optimization
-description: Improve c15t startup performance in React with prefetching, proxy
-  rewrites, and rendering tradeoffs.
-group: frameworks
----
-Use this guide when you care about banner visibility speed, route static-ness, and reducing backend round-trip cost.
-
-## Start Here
-
-Apply the optimizations in this order:
-
-|Situation|Use|Why|Tradeoff|
-|--|--|--|--|
-|Any production app using hosted mode|Same-origin `/api/c15t` proxy|Lowers browser startup overhead and keeps the backend origin out of client config|Requires framework or platform proxy setup|
-|Banner speed matters on cold loads|`buildPrefetchScript()`|Starts `/init` before your app hydrates|Still a browser-side fetch, not SSR|
-|Your app navigates client-side|Keep the provider mounted at the app root|Avoids remounting and re-running init work|Requires provider placement discipline|
-|You cannot proxy and must stay cross-origin|`<link rel="preconnect">`|Starts DNS/TLS work earlier|Smaller gain than same-origin proxying|
-|You are using Next.js and want SSR or static-route-specific guidance|Next.js optimization docs|Covers `C15tPrefetch`, `fetchInitialData()`, and rendering tradeoffs|Next-specific|
-
-> ℹ️ **Info:**
-> Treat same-origin proxying as the baseline optimization. The others are situational layers you add when startup timing or route behavior justifies them.
-
-## 1) Prefer Same-Origin Proxy
-
-Proxy c15t requests through your app server so the browser calls your own origin instead of a third-party domain.
-
-How you configure this depends on your framework — Vite has `server.proxy`, Remix has resource routes, and most deployment platforms support rewrite rules.
-
-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
-
-If you can only do one optimization, do this one first.
-
-## 2) Prefetch Init Data Early
-
-Use `buildPrefetchScript()` from the `c15t` core package to start the `/init` request before your app hydrates. Inject the script as early as possible in your HTML `<head>`.
-
-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|
-
-Use this when:
-
-* The app is client-rendered
-* You want a faster first banner without introducing SSR complexity
-* You control the HTML template or document `<head>`
-
-### Inline Script Prefetch
-
-```tsx
-import { buildPrefetchScript } from 'c15t';
-
-const prefetchScript = buildPrefetchScript({
-  backendURL: '/api/c15t',
-});
-
-// In your HTML template or root component:
-<head>
-  <script dangerouslySetInnerHTML={{ __html: prefetchScript }} />
-</head>
-```
-
-Then initialize your provider normally. Matching prefetched data is consumed automatically by the runtime during first store initialization:
-
-```tsx
-import {
-  ConsentManagerProvider,
-  ConsentBanner,
-  ConsentDialog,
-} from '@c15t/react';
-
-export default function App({ children }: { children: React.ReactNode }) {
-  return (
-    <ConsentManagerProvider
-      options={{
-        mode: 'hosted',
-        backendURL: '/api/c15t',
-      }}
-    >
-      <ConsentBanner />
-      <ConsentDialog />
-      {children}
-    </ConsentManagerProvider>
-  );
-}
-```
-
-> ℹ️ **Info:**
-> If overrides.gpc conflicts with the browser's ambient GPC signal, the prefetched entry is not reused and c15t falls back to a normal client /init.
-
-## 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
-
-Mount `ConsentManagerProvider` as high in the tree as possible so route transitions do not recreate it.
-
-## 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/react/styling/overview).
-
-## Reduce Network Overhead
-
-If your browser must call a cross-origin backend URL directly, add `preconnect` so the browser can warm up the connection earlier. This is a fallback optimization when same-origin proxying is not possible.
-
-If you must use a cross-origin backend URL, add preconnect so the browser starts DNS/TLS early:
-
-```tsx
-<head>
-  <link rel="preconnect" href="https://your-instance.c15t.dev" crossOrigin="" />
-</head>
-```
-
-## Next.js-Specific SSR And Static Routes
-
-This page is intentionally React-generic. If you are using Next.js and need SSR or static-route-specific guidance:
-
-* See [Next.js Optimization](/docs/frameworks/next/optimization) for the static-vs-dynamic decision guide
-* See [Next.js Server-Side Data Fetching](/docs/frameworks/next/server-side) for `fetchInitialData()`

package/docs/frameworks/react/policy-packs.md

@@ -1,242 +0,0 @@
----
-title: Policy Packs
-description: Configure regional consent policies in React — hosted mode,
-  presets, and offline fallback.
-group: frameworks
----
-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|
-
-## React Example (Hosted)
-
-Point the provider at your backend — policy resolution happens server-side:
-
-```tsx
-import type { ReactNode } from 'react';
-import {
-  ConsentBanner,
-  ConsentDialog,
-  ConsentManagerProvider,
-} from '@c15t/react';
-
-export function ConsentManager({ children }: { children: ReactNode }) {
-  return (
-    <ConsentManagerProvider
-      options={{
-        backendURL: 'https://your-instance.c15t.dev',
-      }}
-    >
-      <ConsentBanner />
-      <ConsentDialog />
-      {children}
-    </ConsentManagerProvider>
-  );
-}
-```
-
-## Offline / Fallback
-
-For local development, previews, automated tests, or when the backend is temporarily unreachable, pass policies directly:
-
-```tsx
-import type { ReactNode } from 'react';
-import {
-  ConsentBanner,
-  ConsentDialog,
-  ConsentManagerProvider,
-  policyPackPresets,
-} from '@c15t/react';
-
-export function ConsentManager({ children }: { children: ReactNode }) {
-  return (
-    <ConsentManagerProvider
-      options={{
-        mode: 'offline',
-        offlinePolicy: {
-          policyPacks: [
-            policyPackPresets.europeOptIn(),
-            policyPackPresets.californiaOptOut(),
-            policyPackPresets.worldNoBanner(),
-          ],
-        },
-        overrides: {
-          country: 'DE', // Preview as a German visitor
-        },
-      }}
-    >
-      <ConsentBanner />
-      <ConsentDialog />
-      {children}
-    </ConsentManagerProvider>
-  );
-}
-```
-
-## 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
-  },
-}}
-```
-
-> ℹ️ **Info:**
-> For the full concept model (matchers, scope modes, re-prompting), see Policy Packs concepts. For backend setup, see the self-host guide.

package/docs/frameworks/react/server-side.md

@@ -1,158 +0,0 @@
----
-title: Server-Side Utilities
-description: Fetch consent data on the server for SSR hydration — eliminate the
-  loading flash and improve performance.
-group: frameworks
----
-The `@c15t/react/server` module provides utilities for fetching consent data on the server before rendering. This enables SSR hydration — consent state is available immediately on page load without a client-side fetch, eliminating the consent banner flash.
-
-> ℹ️ **Info:**
-> SSR hydration is part of the initialization flow. When SSR data is available, the client skips the API fetch entirely.
-
-```ts
-import {
-  fetchSSRData,
-  extractRelevantHeaders,
-  normalizeBackendURL,
-  validateBackendURL,
-} from '@c15t/react/server';
-```
-
-> ℹ️ **Info:**
-> If you're using Next.js, the @c15t/nextjs package wraps these utilities with automatic header resolution. See the Next.js docs for framework-specific usage.
-
-## fetchSSRData
-
-The primary function for fetching consent data on the server. It calls the c15t backend's `/init` endpoint with the user's request headers and returns the initial consent data.
-
-```ts
-import { fetchSSRData } from '@c15t/react/server';
-
-// In your server handler / page loader
-const ssrData = await fetchSSRData({
-  backendURL: 'https://your-instance.c15t.dev',
-  headers: request.headers,
-  debug: true,
-});
-```
-
-### Options
-
-|Property|Value|
-|:--|:--|
-|Type Name|\`FetchSSRDataOptions\`|
-|Source Path|\`./packages/react/src/server/types.ts\`|
-
-\*ExtractedTypeTable: Could not extract "FetchSSRDataOptions" from "./packages/react/src/server/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
-
-### Return Value
-
-Returns `SSRInitialData | undefined`. The data includes the init response (jurisdiction, translations, consent model) and GVL data when IAB is configured.
-
-### Passing SSR Data to the Provider
-
-Pass the result as a Promise to the provider's `ssrData` option:
-
-```tsx
-import { type ReactNode } from 'react';
-import { ConsentManagerProvider, ConsentBanner, ConsentDialog } from '@c15t/react';
-import { fetchSSRData } from '@c15t/react/server';
-
-// Server component or page loader
-async function getSSRData(headers: Headers) {
-  return fetchSSRData({
-    backendURL: 'https://your-instance.c15t.dev',
-    headers,
-  });
-}
-
-export default function ConsentManager({
-  children,
-  ssrData,
-}: {
-  children: ReactNode;
-  ssrData: Promise<any>;
-}) {
-  return (
-    <ConsentManagerProvider
-      options={{
-        mode: 'hosted',
-        backendURL: 'https://your-instance.c15t.dev',
-        ssrData,
-      }}
-    >
-      <ConsentBanner />
-      <ConsentDialog />
-      {children}
-    </ConsentManagerProvider>
-  );
-}
-```
-
-## extractRelevantHeaders
-
-Extracts geo-location and forwarding headers from the incoming request. Supports headers from Cloudflare, Vercel, AWS CloudFront, and generic proxies.
-
-```ts
-import { extractRelevantHeaders } from '@c15t/react/server';
-
-const relevant = extractRelevantHeaders(request.headers);
-// Returns: { 'cf-ipcountry': 'DE', 'accept-language': 'de-DE', ... }
-```
-
-### Recognized Headers
-
-|Header|Source|Contains|
-|--|--|--|
-|`cf-ipcountry`|Cloudflare|Country code|
-|`x-vercel-ip-country`|Vercel|Country code|
-|`x-amz-cf-ipcountry`|AWS CloudFront|Country code|
-|`x-vercel-ip-country-region`|Vercel|Region code|
-|`accept-language`|Browser|Language preference|
-|`x-forwarded-host`|Proxy|Original host|
-|`x-forwarded-for`|Proxy|Client IP|
-
-## normalizeBackendURL
-
-Resolves a backend URL to an absolute URL. Absolute URLs are returned as-is. Relative URLs (starting with `/`) are resolved using the request's `Host` or `Referer` headers.
-
-```ts
-import { normalizeBackendURL } from '@c15t/react/server';
-
-// Absolute — returned as-is
-normalizeBackendURL('https://api.example.com/', headers);
-// → 'https://api.example.com'
-
-// Relative — resolved from headers
-normalizeBackendURL('/api/consent', headers);
-// → 'https://example.com/api/consent'
-```
-
-## validateBackendURL
-
-Validates and normalizes a URL without resolving relative paths. Useful for configuration validation.
-
-```ts
-import { validateBackendURL } from '@c15t/react/server';
-
-validateBackendURL('https://api.example.com/');
-// → { isAbsolute: true, normalizedURL: 'https://api.example.com' }
-
-validateBackendURL('/api/consent/');
-// → { isAbsolute: false, normalizedURL: '/api/consent' }
-```
-
-## Debugging SSR
-
-Use the [useSSRStatus](/docs/frameworks/react/hooks/use-ssr-status) hook on the client to verify SSR data was consumed:
-
-```tsx
-import { useSSRStatus } from '@c15t/react';
-
-function DebugSSR() {
-  const { ssrDataUsed, ssrSkippedReason } = useSSRStatus();
-
-  if (ssrDataUsed) return <span>SSR hydration successful</span>;
-  return <span>SSR skipped: {ssrSkippedReason ?? 'unknown'}</span>;
-}
-```