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

package/docs/hooks/use-consent-manager/setting-consent.md

@@ -0,0 +1,92 @@
+---
+title: Setting Consent
+description: Save, update, and reset consent preferences with setConsent(), setSelectedConsent(), and saveConsents().
+---
+## saveConsents(type)
+
+The primary way to persist consent. Accepts one of three strategies:
+
+```tsx
+const { saveConsents } = useConsentManager();
+
+// Accept all - sets every active category to true
+await saveConsents('all');
+
+// Reject all - only necessary stays true, everything else false
+await saveConsents('necessary');
+
+// Save current selections - persists whatever the user toggled
+await saveConsents('custom');
+```
+
+**What happens when you call saveConsents:**
+
+1. Consent state is updated in the store
+2. UI closes (activeUI → 'none')
+3. Consent is saved to localStorage and cookie
+4. If consent was revoked and `reloadOnConsentRevoked` is true, the page reloads
+5. Otherwise, scripts/iframes/network blocker are updated
+6. Consent is synced to the backend API
+
+## setConsent(name, value)
+
+Updates a single consent category AND automatically saves it. Use this for simple one-off consent changes:
+
+```tsx
+const { setConsent } = useConsentManager();
+
+// Grant measurement consent immediately
+setConsent('measurement', true);
+
+// Revoke marketing consent immediately
+setConsent('marketing', false);
+```
+
+## setSelectedConsent(name, value)
+
+Updates the selection state without saving. This is what dialog toggles use - the user can flip toggles without committing until they click "Save":
+
+```tsx
+const { setSelectedConsent, saveConsents } = useConsentManager();
+
+// User toggles measurement on
+setSelectedConsent('measurement', true);
+
+// User toggles marketing off
+setSelectedConsent('marketing', false);
+
+// User clicks "Save" - now it persists
+await saveConsents('custom');
+```
+
+## resetConsents()
+
+Resets all consent preferences to their default values and clears stored consent:
+
+```tsx
+const { resetConsents } = useConsentManager();
+
+resetConsents();
+// All consents back to defaults, consent info cleared
+```
+
+## Accept All / Reject All Patterns
+
+Common patterns for banner buttons:
+
+```tsx
+function ConsentActions() {
+  const { saveConsents } = useConsentManager();
+
+  return (
+    <div>
+      <button onClick={() => saveConsents('necessary')}>
+        Reject All
+      </button>
+      <button onClick={() => saveConsents('all')}>
+        Accept All
+      </button>
+    </div>
+  );
+}
+```

package/docs/hooks/use-draggable.md

@@ -0,0 +1,57 @@
+---
+title: useDraggable
+description: Make an element draggable between viewport corners with snapping, persistence, and animation support.
+---
+`useDraggable()` provides drag-to-corner functionality. Used internally by `ConsentDialogTrigger`, this hook lets you build custom draggable elements that snap to viewport corners.
+
+```tsx
+import { useDraggable } from '@c15t/nextjs';
+
+function DraggableButton() {
+  const { corner, isDragging, handlers, dragStyle } = useDraggable({
+    defaultPosition: 'bottom-right',
+    persistPosition: true,
+  });
+
+  return (
+    <button
+      {...handlers}
+      style={{
+        ...dragStyle,
+        position: 'fixed',
+        // Position based on corner
+        ...(corner.includes('bottom') ? { bottom: 16 } : { top: 16 }),
+        ...(corner.includes('right') ? { right: 16 } : { left: 16 }),
+      }}
+    >
+      {isDragging ? 'Dragging...' : 'Drag me'}
+    </button>
+  );
+}
+```
+
+## Options
+
+|Option|Type|Default|Description|
+|--|--|--|--|
+|`defaultPosition`|`CornerPosition`|`'bottom-right'`|Initial corner position|
+|`persistPosition`|`boolean`|`true`|Save position to localStorage|
+|`onPositionChange`|`(position: CornerPosition) => void`|-|Callback on position change|
+
+## Return Value
+
+|Property|Type|Description||||
+|--|--|--|--|--|--|
+|`corner`|`CornerPosition`|Current corner: `'top-left'`|`'top-right'`|`'bottom-left'`|`'bottom-right'`|
+|`isDragging`|`boolean`|Whether the element is being dragged||||
+|`isSnapping`|`boolean`|Whether the element is animating to a new corner||||
+|`wasDragged`|`() => boolean`|Whether the last interaction was a drag (vs click)||||
+|`handlers`|`object`|Pointer event handlers to spread onto the element||||
+|`dragStyle`|`CSSProperties`|Transform style for drag offset||||
+
+## Behavior
+
+* Drag starts on pointer down (left click / single touch)
+* Movement threshold of 5px distinguishes drag from click
+* On pointer up, element snaps to the nearest corner based on drag direction and velocity
+* Position persists to localStorage by default

package/docs/hooks/use-focus-trap.md

@@ -0,0 +1,41 @@
+---
+title: useFocusTrap
+description: Trap keyboard focus within a container for accessible modal dialogs.
+---
+`useFocusTrap()` keeps keyboard focus within a container element while active. This is essential for accessibility - when a modal dialog is open, Tab and Shift+Tab should cycle through focusable elements inside the dialog, not escape to the page behind it.
+
+```tsx
+import { useFocusTrap } from '@c15t/nextjs';
+import { useRef } from 'react';
+
+function AccessibleModal({ isOpen }: { isOpen: boolean }) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  useFocusTrap(isOpen, containerRef);
+
+  if (!isOpen) return null;
+
+  return (
+    <div ref={containerRef} role="dialog" aria-modal="true">
+      <h2>Modal Title</h2>
+      <button>Action</button>
+      <button>Close</button>
+    </div>
+  );
+}
+```
+
+## Parameters
+
+|Parameter|Type|Description|
+|--|--|--|
+|`shouldTrap`|`boolean`|Whether focus should be trapped|
+|`containerRef`|`RefObject<HTMLElement \|null> \|null`|Ref to the container element|
+
+## Behavior
+
+* **Tab**: Moves focus to the next focusable element. Wraps to the first element when reaching the end.
+* **Shift+Tab**: Moves focus to the previous focusable element. Wraps to the last element when reaching the start.
+* Focus is restored to the previously focused element when the trap is deactivated.
+
+> ℹ️ **Info:**
+> ConsentBanner and ConsentDialog use useFocusTrap internally when trapFocus is enabled (default: true). You only need this hook when building custom consent UI.

package/docs/hooks/use-reduced-motion.md

@@ -0,0 +1,35 @@
+---
+title: useReducedMotion
+description: Detect the user's prefers-reduced-motion OS setting and reactively disable animations.
+---
+`useReducedMotion()` reads the `prefers-reduced-motion: reduce` media query and reactively updates when the user's preference changes. Use it to conditionally skip animations for users who have enabled reduced motion in their OS accessibility settings.
+
+The hook returns `false` during SSR to avoid hydration mismatches, then updates to the actual preference on the client.
+
+```tsx
+import { useReducedMotion } from '@c15t/react/hooks';
+
+function AnimatedBanner() {
+  const prefersReducedMotion = useReducedMotion();
+
+  return (
+    <div
+      style={{
+        transition: prefersReducedMotion ? 'none' : 'opacity 300ms ease',
+        opacity: 1,
+      }}
+    >
+      Consent banner content
+    </div>
+  );
+}
+```
+
+## Return Value
+
+|Type|Description|
+|--|--|
+|`boolean`|`true` if the user prefers reduced motion, `false` otherwise|
+
+> ℹ️ **Info:**
+> c15t's built-in components already respect prefers-reduced-motion internally. This hook is primarily useful when building custom UI with the headless approach.

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/nextjs';
+
+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/nextjs';
+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/nextjs';
+
+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/nextjs';
+
+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,94 @@
+---
+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 { iab } from '@c15t/iab';
+import { ConsentManagerProvider } from '@c15t/nextjs';
+import { IABConsentBanner, IABConsentDialog } from '@c15t/react/iab';
+
+export default function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        iab: iab({
+          vendors: [1, 2, 10, 25],
+          // cmpId is automatically provided by the backend when using consent.io.
+          // Only set this if you have your own CMP registration.
+          // cmpId: 123,
+        }),
+      }}
+    >
+      <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,134 @@
+---
+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 { iab } from '@c15t/iab';
+import { ConsentManagerProvider } from '@c15t/nextjs';
+import { IABConsentBanner, IABConsentDialog } from '@c15t/react/iab';
+
+export default function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        iab: iab({
+          vendors: [1, 2, 10, 25],
+          // cmpId is automatically provided by the backend when using consent.io.
+          // Only set this if you have your own CMP registration.
+          // cmpId: 123,
+        }),
+      }}
+    >
+      <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|