@c15t/react 2.0.0-rc.1 → 2.0.0-rc.10

package/docs/hooks/use-ssr-status.md

@@ -0,0 +1,31 @@
+---
+title: useSSRStatus
+description: Check whether server-side rendered consent data was used during initialization.
+---
+`useSSRStatus()` returns information about whether SSR data was used for consent manager initialization. This is primarily useful for debugging SSR data flow in Next.js or other server-rendering frameworks.
+
+```tsx
+import { useSSRStatus } from '@c15t/react';
+
+function DebugSSR() {
+  const { ssrDataUsed, ssrSkippedReason } = useSSRStatus();
+
+  if (ssrDataUsed) {
+    return <span>Consent initialized from SSR data</span>;
+  }
+
+  return <span>SSR skipped: {ssrSkippedReason ?? 'unknown'}</span>;
+}
+```
+
+## Return Value
+
+### SSRStatus
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|ssrDataUsed|boolean|Whether SSR data was used for initialization. \`true\` if SSR data was provided and successfully consumed, \`false\` otherwise.|-|✅ Required|
+|ssrSkippedReason|"no\_data" \|"fetch\_failed" \|"context\_mismatch" \|null|Reason SSR data was skipped, or \`null\` if used successfully.|-|✅ Required|
+
+> ℹ️ **Info:**
+> Must be used within a ConsentManagerProvider. Throws if used outside the provider context.

package/docs/hooks/use-text-direction.md

@@ -0,0 +1,49 @@
+---
+title: useTextDirection
+description: Manage RTL/LTR text direction based on the active language for consent UI.
+---
+`useTextDirection()` determines the correct text direction (`'ltr'` or `'rtl'`) based on the provided language and sets it on the document. It wraps the `@c15t/ui` text direction utilities as a React hook.
+
+This is used internally by IAB components but is available for custom UI that needs to handle bidirectional text.
+
+```tsx
+import { useTextDirection } from '@c15t/react/hooks';
+
+function CustomConsentUI({ language }: { language: string }) {
+  const direction = useTextDirection(language);
+
+  return (
+    <div dir={direction}>
+      {/* Content renders correctly for RTL languages like Arabic and Hebrew */}
+    </div>
+  );
+}
+```
+
+## Parameters
+
+|Parameter|Type|Default|Description|
+|--|--|--|--|
+|`language`|`string \|undefined`|—|BCP 47 language tag (e.g. `'en'`, `'ar'`, `'he'`)|
+
+## Return Value
+
+|Type|Description|
+|--|--|
+|`'ltr' \|'rtl'`|The text direction for the given language|
+
+## RTL Languages
+
+The hook recognizes standard RTL languages including Arabic (`ar`), Hebrew (`he`), Persian (`fa`), and Urdu (`ur`), among others.
+
+```tsx
+import { useConsentManager } from '@c15t/react';
+import { useTextDirection } from '@c15t/react/hooks';
+
+function BiDirectionalBanner() {
+  const { translationConfig } = useConsentManager();
+  const dir = useTextDirection(translationConfig.defaultLanguage);
+
+  return <div dir={dir}>...</div>;
+}
+```

package/docs/hooks/use-translations.md

@@ -0,0 +1,118 @@
+---
+title: useTranslations
+description: Access the current language's translations for building custom consent UI.
+---
+`useTranslations()` returns the `Translations` object for the currently active language. Use it when building custom consent UI that needs translated text.
+
+```tsx
+import { useTranslations } from '@c15t/react';
+
+function CustomBanner() {
+  const translations = useTranslations();
+
+  return (
+    <div>
+      <h2>{translations.cookieBanner.title}</h2>
+      <p>{translations.cookieBanner.description}</p>
+      <button>{translations.common.acceptAll}</button>
+      <button>{translations.common.rejectAll}</button>
+    </div>
+  );
+}
+```
+
+## Translation Sections
+
+The returned `Translations` object has these sections:
+
+### Translations
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|common|CommonTranslations|-|-|✅ Required|
+|cookieBanner|CookieBannerTranslations|-|-|✅ Required|
+|consentManagerDialog|ConsentManagerDialogTranslations|-|-|✅ Required|
+|consentTypes|Object \|undefined|-|-|✅ Required|
+|frame|FrameTranslations \|undefined|-|-|Optional|
+|legalLinks|LegalLinksTranslations \|undefined|-|-|Optional|
+|iab|Object \|undefined|-|-|Optional|
+
+#### `common` CommonTranslations
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|acceptAll|string \|undefined|-|-|✅ Required|
+|rejectAll|string \|undefined|-|-|✅ Required|
+|customize|string \|undefined|-|-|✅ Required|
+|save|string \|undefined|-|-|✅ Required|
+|close|string \|undefined|-|-|✅ Required|
+|securedBy|string \|undefined|-|-|✅ Required|
+
+#### `cookieBanner` CookieBannerTranslations
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|title|string \|undefined|-|-|✅ Required|
+|description|string \|undefined|-|-|✅ Required|
+
+#### `consentManagerDialog` ConsentManagerDialogTranslations
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|title|string \|undefined|-|-|✅ Required|
+|description|string \|undefined|-|-|✅ Required|
+
+#### `consentTypes`
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|experience|ConsentTypeTranslations \|undefined|-|-|✅ Required|
+|functionality|ConsentTypeTranslations \|undefined|-|-|✅ Required|
+|marketing|ConsentTypeTranslations \|undefined|-|-|✅ Required|
+|measurement|ConsentTypeTranslations \|undefined|-|-|✅ Required|
+|necessary|ConsentTypeTranslations \|undefined|-|-|✅ Required|
+
+#### `frame` FrameTranslations
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|title|string \|undefined|You can use the \{category} placeholder to dynamically insert the consent category name.|-|✅ Required|
+|actionButton|string \|undefined|You can use the \{category} placeholder to dynamically insert the consent category name.|-|✅ Required|
+|policyBlocked|string \|undefined|Message shown when the frame category is blocked by active policy scope.|-|✅ Required|
+
+#### `legalLinks` LegalLinksTranslations
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|privacyPolicy|string \|undefined|-|-|✅ Required|
+|cookiePolicy|string \|undefined|-|-|✅ Required|
+|termsOfService|string \|undefined|-|-|✅ Required|
+
+#### `iab`
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|banner|DeepPartial\<IABBannerTranslations> \|undefined|-|-|✅ Required|
+|preferenceCenter|DeepPartial\<IABPreferenceCenterTranslations> \|undefined|-|-|✅ Required|
+|common|DeepPartial\<IABCommonTranslations> \|undefined|-|-|✅ Required|
+
+## With setLanguage
+
+Translations update automatically when the language changes:
+
+```tsx
+import { useConsentManager, useTranslations } from '@c15t/react';
+
+function LocalizedConsent() {
+  const { setLanguage } = useConsentManager();
+  const translations = useTranslations();
+
+  return (
+    <div>
+      <p>{translations.cookieBanner.description}</p>
+      <button onClick={() => setLanguage('de')}>Deutsch</button>
+      <button onClick={() => setLanguage('fr')}>Français</button>
+    </div>
+  );
+}
+```

package/docs/iab/consent-banner.md

@@ -0,0 +1,92 @@
+---
+title: IABConsentBanner
+description: An IAB TCF 2.3 compliant consent banner that displays partner count, purpose summaries, and legitimate interest notices.
+---
+> ❌ **Error:**
+> c15t is not yet IAB certified. The IAB TCF components are under active development and should not be used in production. APIs and behavior may change before certification is achieved.
+
+`IABConsentBanner` is a pre-built consent banner that follows the [IAB Transparency & Consent Framework (TCF) 2.3](https://iabeurope.eu/tcf-2-0/) specification. It renders when the consent model is set to `'iab'` and includes required disclosures like partner count, purpose summaries, and legitimate interest notices.
+
+Use this component instead of `ConsentBanner` when you need IAB TCF compliance for programmatic advertising in EU jurisdictions.
+
+## When to Use
+
+* Your site participates in the IAB TCF ecosystem (ad exchanges, SSPs, DSPs)
+* You need to disclose vendor partnerships and data processing purposes per IAB requirements
+* The detected jurisdiction requires IAB TCF compliance (typically EU/EEA)
+
+## Basic Usage
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/react';
+import { IABConsentBanner, IABConsentDialog } from '@c15t/react/iab';
+
+export default function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: 'https://your-instance.c15t.dev',
+        iab: {
+          enabled: true,
+          cmpId: 123,
+          vendors: [1, 2, 10, 25],
+        },
+      }}
+    >
+      <IABConsentBanner />
+      <IABConsentDialog />
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+> ℹ️ **Info:**
+> The banner only renders when IAB mode is enabled and the GVL (Global Vendor List) has been loaded. If iab.enabled is false or the server does not return GVL data, nothing is rendered.
+
+## Banner Content
+
+The IAB banner automatically displays:
+
+* **Title** — Heading text from IAB translations
+* **Description** — Includes the partner count (e.g., "We and our \{partnerCount} partners...")
+* **Partners link** — Clickable link that opens the vendor tab in the preference center
+* **Purpose/stack list** — Up to 5 purpose/stack names summarizing data usage, with an "and X more" overflow
+* **Legitimate interest notice** — Required IAB disclosure about legitimate interest processing
+* **Scope notice** — Service-specific scope disclosure
+
+## Buttons
+
+The banner includes three action buttons:
+
+|Button|Action|
+|--|--|
+|**Reject All**|Rejects all IAB purposes and closes the banner|
+|**Accept All**|Accepts all IAB purposes and closes the banner|
+|**Customize**|Opens the IABConsentDialog purposes tab|
+
+### Primary Button
+
+Highlight a specific button as the primary action:
+
+```tsx
+<IABConsentBanner primaryButton="accept" />
+```
+
+Options: `'reject'`, `'accept'`, `'customize'` (default: `'customize'`)
+
+## Props
+
+### IABConsentBannerProps
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|noStyle|boolean \|undefined|When true, removes all default styling from the component.|false|Optional|
+|disableAnimation|boolean \|undefined|When true, disables entrance/exit animations.|false|Optional|
+|scrollLock|boolean \|undefined|When true, locks page scroll when the banner is visible.|true|Optional|
+|trapFocus|boolean \|undefined|When true, traps keyboard focus within the banner.|true|Optional|
+|primaryButton|"reject" \|"accept" \|"customize" \|undefined|Specifies which button should be highlighted as primary.|'customize'|Optional|
+|models|Model \|undefined|Which consent models this banner responds to.|\['iab']|Optional|
+|uiSource|string \|undefined|Override the UI source identifier sent with consent API calls.|'iab\_banner'|Optional|

package/docs/iab/consent-dialog.md

@@ -0,0 +1,132 @@
+---
+title: IABConsentDialog
+description: An IAB TCF 2.3 compliant preference center with tabbed purpose and vendor management.
+---
+> ❌ **Error:**
+> c15t is not yet IAB certified. The IAB TCF components are under active development and should not be used in production. APIs and behavior may change before certification is achieved.
+
+`IABConsentDialog` is an IAB TCF 2.3 compliant consent dialog that provides a tabbed interface for managing purpose consent and vendor preferences. It includes purpose grouping via stacks, individual purpose/vendor toggles, special purpose and feature disclosures, and legitimate interest handling.
+
+## Basic Usage
+
+Pair it with `IABConsentBanner` inside the provider:
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/react';
+import { IABConsentBanner, IABConsentDialog } from '@c15t/react/iab';
+
+export default function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: 'https://your-instance.c15t.dev',
+        iab: {
+          enabled: true,
+          cmpId: 123,
+          vendors: [1, 2, 10, 25],
+        },
+      }}
+    >
+      <IABConsentBanner />
+      <IABConsentDialog />
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+## Tabs
+
+The dialog has two tabs:
+
+### Purposes Tab
+
+Displays all IAB purposes grouped into:
+
+* **Standalone purposes** — Purpose 1 (Store and/or access information on a device) is always shown standalone per IAB TCF spec
+* **Stacks** — Groups of related purposes determined by the GVL. Each stack is expandable to show individual purpose toggles
+* **Special features** — Opt-in features like precise geolocation
+* **Essential functions** — Special purposes and features that are locked (no user toggle) because they're required for basic operation
+
+Each purpose shows:
+
+* Name and description
+* Number of vendors using this purpose
+* Consent toggle (or lock icon for essential functions)
+* Legitimate interest toggle where applicable
+* Expandable vendor list
+
+### Vendors Tab
+
+Displays all vendors from the GVL plus any custom vendors:
+
+* Search and filter vendors
+* Per-vendor consent and legitimate interest toggles
+* Vendor details: privacy policy link, cookie usage, data retention
+* Purpose and feature associations
+
+## Controlled State
+
+By default, the dialog follows `activeUI === 'dialog'` from the consent store. Use `open` for manual control:
+
+```tsx
+import { useState } from 'react';
+import { IABConsentDialog } from '@c15t/react/iab';
+
+function SettingsPage() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <button onClick={() => setOpen(true)}>TCF Preferences</button>
+      <IABConsentDialog open={open} />
+    </>
+  );
+}
+```
+
+## Floating Trigger
+
+Add a floating button so users can re-open the dialog after dismissing the banner. IAB TCF requires the preference center to be easily resurfaceable:
+
+```tsx
+<IABConsentDialog showTrigger />
+
+{/* Custom trigger options */}
+<IABConsentDialog
+  showTrigger={{
+    icon: 'settings',
+    defaultPosition: 'bottom-left',
+    showWhen: 'after-consent',
+    size: 'sm',
+  }}
+/>
+```
+
+## Footer Actions
+
+The dialog footer provides three buttons:
+
+|Button|Action|
+|--|--|
+|**Reject All**|Rejects all purposes and vendors, closes dialog and banner|
+|**Accept All**|Accepts all purposes and vendors, closes dialog and banner|
+|**Save Settings**|Saves current selections, closes dialog and banner|
+
+## Props
+
+### IABConsentDialogProps
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|open|boolean \|undefined|Control the open state. If omitted, follows activeUI === 'dialog' from context.|-|Optional|
+|noStyle|boolean \|undefined|When true, removes all default styling.|false|Optional|
+|disableAnimation|boolean \|undefined|When true, disables entrance/exit animations.|false|Optional|
+|scrollLock|boolean \|undefined|When true, locks page scroll when the dialog is visible.|true|Optional|
+|trapFocus|boolean \|undefined|When true, traps keyboard focus within the dialog.|true|Optional|
+|hideBranding|boolean \|undefined|When true, hides the branding in the footer.|false|Optional|
+|showTrigger|ConsentDialogTriggerProps \|undefined|Show a floating trigger button to resurface the consent dialog. IAB TCF requires the consent dialog to be easily resurfaceable. Options: \`true\` - Show trigger with default settings; \`false\` - Hide trigger (default); \`ConsentDialogTriggerProps\` - Show trigger with custom props|false|Optional|
+|models|Model \|undefined|Which consent models this dialog responds to.|\['iab']|Optional|
+|uiSource|string \|undefined|Override the UI source identifier sent with consent API calls.|'iab\_dialog'|Optional|

package/docs/iab/overview.md

@@ -0,0 +1,125 @@
+---
+title: IAB TCF 2.3
+description: Implement IAB Transparency & Consent Framework 2.3 compliance for programmatic advertising in EU/EEA jurisdictions.
+---
+## What is IAB TCF?
+
+The [IAB Transparency & Consent Framework (TCF)](https://iabeurope.eu/tcf-2-0/) is a standardized protocol for communicating user consent choices to ad tech vendors in the programmatic advertising ecosystem. TCF 2.3 is the current version and is widely adopted across the EU/EEA.
+
+When your site participates in the IAB ecosystem (ad exchanges, SSPs, DSPs, DMPs), you need to:
+
+* Disclose which vendors process user data and for what purposes
+* Collect granular consent for each IAB-defined purpose
+* Generate a **TC String** — a standardized encoding of consent choices that ad tech vendors can read
+* Expose the `__tcfapi` CMP stub for vendor scripts to query consent status
+
+## CMP Registration
+
+[inth.com](https://inth.com) is pending validation as an IAB Europe-registered CMP for c15t. Once approved, when you use inth.com as your backend, the correct CMP ID will be automatically provided to your client via the `/init` endpoint — no client-side configuration needed.
+
+If you self-host the c15t backend and have your own CMP registration with IAB Europe, you can configure your CMP ID on the backend via `advanced.iab.cmpId` or on the client via the `iab.cmpId` option. A valid (non-zero) CMP ID is required for IAB TCF compliance.
+
+> ℹ️ **Info:**
+> If you heavily customize or build your own IAB banner or dialog (rather than using the default IABConsentBanner and IABConsentDialog components), you cannot use inth.com's CMP ID. You must register your own CMP with IAB Europe and use your own CMP ID.
+
+## How c15t Implements TCF
+
+c15t provides a complete IAB TCF 2.3 CMP (Consent Management Platform) implementation:
+
+1. **Global Vendor List (GVL)** — Automatically fetched from the c15t backend. Contains the official IAB vendor registry with purposes, features, and stacks.
+2. **IABConsentBanner** — A pre-built banner showing partner count, purpose summaries, and legitimate interest notices.
+3. **IABConsentDialog** — A tabbed preference center for granular purpose and vendor consent management.
+4. **TC String generation** — Consent choices are encoded into the standard TC String format.
+5. **`__tcfapi` stub** — The standard CMP API is exposed on `window` so vendor scripts can query consent.
+
+If you use the prebuilt styled IAB UI, add your framework's `iab/styles.css` entrypoint alongside the base c15t stylesheet. IAB CSS is published separately so apps that do not render IAB surfaces do not ship those component rules.
+
+## Quick Setup
+
+If you use the prebuilt styled IAB UI, import the IAB stylesheet alongside the base stylesheet in your global CSS entrypoint:
+
+```css title="src/index.css"
+@import "@c15t/react/styles.css";
+@import "@c15t/react/iab/styles.css";
+```
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/react';
+import { IABConsentBanner, IABConsentDialog } from '@c15t/react/iab';
+
+export default function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: 'https://your-instance.c15t.dev',
+        iab: {
+          enabled: true,
+          vendors: [1, 2, 10, 25],  // IAB vendor IDs you work with
+          // cmpId is automatically provided by the backend (inth.com).
+          // Only set this if you have your own CMP registration with IAB Europe.
+          // cmpId: 123,
+        },
+      }}
+    >
+      <IABConsentBanner />
+      <IABConsentDialog showTrigger />
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+## IAB Configuration Options
+
+The `iab` option on the provider accepts:
+
+|Option|Type|Description|
+|--|--|--|
+|`enabled`|`boolean`|Enable IAB TCF mode|
+|`cmpId`|`number`|CMP ID registered with IAB Europe. Automatically provided by the backend when using inth.com. Only set this if you have your own CMP registration.|
+|`vendors`|`number[]`|IAB vendor IDs that your site works with|
+|`nonIABVendors`|`NonIABVendor[]`|Custom vendors not in the IAB registry|
+
+## Key Concepts
+
+### Purposes
+
+IAB defines 11 standard purposes for data processing (e.g., "Store and/or access information on a device", "Select basic ads", "Measure ad performance"). Each purpose can be consented to individually.
+
+### Stacks
+
+Purposes are grouped into **stacks** by the GVL for a simplified UI presentation. For example, "Advertising based on limited data" might group purposes 2, 7, and 10 together.
+
+### Special Features
+
+Features like precise geolocation or device scanning that require explicit opt-in beyond standard consent.
+
+### Legitimate Interest
+
+Some purposes can be processed under legitimate interest rather than consent. Users can object to legitimate interest processing per-vendor.
+
+### Vendors
+
+Each vendor in the GVL declares which purposes it uses, whether via consent or legitimate interest. The preference center lets users toggle consent per-vendor.
+
+## Standard vs IAB Components
+
+|Feature|ConsentBanner / ConsentDialog|IABConsentBanner / IABConsentDialog|
+|--|--|--|
+|Consent model|opt-in / opt-out|IAB TCF 2.3|
+|Granularity|Category-level (measurement, marketing, etc.)|Purpose-level + vendor-level|
+|Vendor management|No|Yes (full GVL integration)|
+|TC String|No|Yes|
+|`__tcfapi`|No|Yes|
+|Legitimate interest|No|Yes|
+|Use when|General GDPR/CCPA compliance|Programmatic advertising in EU/EEA|
+
+## Components
+
+|Component|Description|
+|--|--|
+|[IABConsentBanner](/docs/frameworks/react/iab/consent-banner)|TCF-compliant banner with partner disclosure|
+|[IABConsentDialog](/docs/frameworks/react/iab/consent-dialog)|Tabbed preference center for purposes and vendors|
+|[useGVLData](/docs/frameworks/react/iab/use-gvl-data)|Hook for building custom IAB UI|