@c15t/react 2.0.4 → 2.2.0-canary-20260727202135

package/docs/shared/react/hooks/use-draggable.md

@@ -0,0 +1,30 @@
+---
+title: Use Draggable
+description: Reference page for use draggable.
+group: reference
+---
+## 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/shared/react/hooks/use-focus-trap.md

@@ -0,0 +1,20 @@
+---
+title: Use Focus Trap
+description: Reference page for use focus trap.
+group: reference
+---
+## 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/shared/react/hooks/use-reduced-motion.md

@@ -0,0 +1,33 @@
+---
+title: Use Reduced Motion
+description: Reference page for use reduced motion.
+group: reference
+---
+`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|

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

@@ -0,0 +1,16 @@
+---
+title: Use SSR Status
+description: Reference page for use ssr status.
+group: reference
+---
+## Return Value
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`SSRStatus\`|
+|Source Path|\`./packages/react/src/hooks/use-ssr-status.ts\`|
+
+\*ExtractedTypeTable: Could not extract "SSRStatus" from "./packages/react/src/hooks/use-ssr-status.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+> ℹ️ **Info:**
+> Must be used within a ConsentManagerProvider. Throws if used outside the provider context.

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

@@ -0,0 +1,38 @@
+---
+title: Use Text Direction
+description: Reference page for use text direction.
+group: reference
+---
+`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.

package/docs/shared/react/hooks/use-translations.md

@@ -0,0 +1,15 @@
+---
+title: Use Translations
+description: Reference page for use translations.
+group: reference
+---
+## Translation Sections
+
+The returned `Translations` object has these sections:
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`Translations\`|
+|Source Path|\`./packages/translations/src/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "Translations" from "./packages/translations/src/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/iab/consent-banner.md

@@ -0,0 +1,60 @@
+---
+title: Consent Banner
+description: Reference page for consent banner.
+group: reference
+---
+> ℹ️ **Info:**
+> c15t's IAB TCF support can be used in production. Use Inth for a hosted, IAB TCF-certified CMP setup with a managed CMP ID, or register your own CMP with IAB Europe and configure your own CMP ID.
+
+`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)
+
+> ℹ️ **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
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`IABConsentBannerProps\`|
+|Source Path|\`./packages/react/src/components/iab-consent-banner/iab-consent-banner.tsx\`|
+
+\*ExtractedTypeTable: Could not extract "IABConsentBannerProps" from "./packages/react/src/components/iab-consent-banner/iab-consent-banner.tsx" 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/iab/consent-dialog.md

@@ -0,0 +1,76 @@
+---
+title: Consent Dialog
+description: Reference page for consent dialog.
+group: reference
+---
+> ℹ️ **Info:**
+> c15t's IAB TCF support can be used in production. Use Inth for a hosted, IAB TCF-certified CMP setup with a managed CMP ID, or register your own CMP with IAB Europe and configure your own CMP ID.
+
+`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.
+
+## 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
+
+## 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
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`IABConsentDialogProps\`|
+|Source Path|\`./packages/react/src/components/iab-consent-dialog/iab-consent-dialog.tsx\`|
+
+\*ExtractedTypeTable: Could not extract "IABConsentDialogProps" from "./packages/react/src/components/iab-consent-dialog/iab-consent-dialog.tsx" 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/iab/overview.md

@@ -0,0 +1,80 @@
+---
+title: Overview
+description: Reference page for overview.
+group: reference
+---
+## 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](https://inth.com), c15t's hosted platform, is IAB TCF certified. When you use Inth as your backend with c15t's prebuilt IAB UI, the correct CMP ID is automatically provided to your client via the `/init` endpoint — no client-side configuration needed.
+
+If you self-host the c15t backend or want to operate as your own CMP, register your own CMP with IAB Europe and configure your CMP ID on the backend via `advanced.iab.cmpId` or on the client via the `iab.cmpId` option. Registering your own CMP may also involve IAB Europe fees, so check IAB Europe's current CMP registration terms and pricing before choosing this route. A valid (non-zero) CMP ID is required for IAB TCF compliance.
+
+> ⚠️ **Warning:**
+> If you heavily customize or build your own IAB banner or dialog instead of using the default IABConsentBanner and IABConsentDialog components, you cannot use Inth'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.
+
+## IAB Configuration Options
+
+Configure IAB mode with `iab({ ... })` from `@c15t/iab`. The factory enables the addon and injects the runtime module automatically. The user-facing options are:
+
+|Option|Type|Description|
+|--|--|--|
+|`cmpId`|`number`|CMP ID registered with IAB Europe. Automatically provided by the backend when using Inth with the prebuilt IAB UI. Only set this if you have your own CMP registration.|
+|`vendors`|`number[]`|IAB vendor IDs that your site works with|
+|`customVendors`|`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|

package/docs/shared/react/iab/use-gvl-data.md

@@ -0,0 +1,21 @@
+---
+title: Use GVL Data
+description: Reference page for use gvl data.
+group: reference
+---
+> ⚠️ **Warning:**
+> c15t's IAB TCF support can be used in production through Inth or with your own registered CMP ID. useGVLData() is different: it remains an internal hook and is not part of the supported public API.
+
+`useGVLData()` currently powers the built-in `IABConsentDialog`, but it is **not part of the public package surface**.
+
+Older docs showed it as a public hook. That is no longer accurate.
+
+If you need supported customization points today:
+
+* Use `IABConsentBanner` and `IABConsentDialog` from `@c15t/react/iab` for the supported prebuilt UI
+* Use `useHeadlessIABConsentUI()` from `@c15t/react/iab` when you need lower-level control over banner/dialog state and actions
+
+> ⚠️ **Warning:**
+> Until useGVLData() is exported as public API, avoid importing it from deep internal paths. Those paths are not covered by semver guarantees and can change without notice.
+
+When a public GVL-focused hook becomes part of the supported API, this page should document that public surface instead of the internal dialog hook.

package/docs/shared/react/styling/classnames.md

@@ -0,0 +1,93 @@
+---
+title: Classnames
+description: Reference page for classnames.
+group: reference
+---
+## Prefer Slots for Stock Components
+
+There is no single top-level `className` contract across every pre-built consent component.
+
+For the stock `ConsentBanner`, `ConsentDialog`, and `ConsentWidget`, prefer `theme.slots` first. That keeps the markup intact and lets you target the exact part you need.
+
+## Per-Slot className
+
+Target individual component parts via the theme's `slots` object. Each slot accepts a string (className) or an object with `className` and `style`:
+
+```tsx
+const theme = {
+  slots: {
+    consentBannerTitle: 'text-xl font-semibold',
+    consentBannerDescription: 'text-sm text-gray-600',
+    consentBannerFooter: 'flex gap-3',
+    buttonPrimary: 'rounded-full px-6',
+  },
+} satisfies Theme;
+```
+
+## Combining with CSS Modules
+
+```tsx
+import styles from './consent.module.css';
+
+const theme = {
+  slots: {
+    consentBannerCard: styles.bannerCard,
+    consentBannerTitle: styles.bannerTitle,
+    buttonPrimary: styles.primaryButton,
+  },
+} satisfies Theme;
+```
+
+```css title="consent.module.css"
+.bannerCard {
+  backdrop-filter: blur(12px);
+  background: rgba(255, 255, 255, 0.9);
+}
+
+.bannerTitle {
+  font-size: 1.25rem;
+  font-weight: 700;
+}
+
+.primaryButton {
+  border-radius: 9999px;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+```
+
+## When to Use Raw className
+
+Use raw className-level styling when:
+
+* your styling system is already class-driven
+* tokens are too broad for the change
+* slots already identify the correct element
+
+If the request is "make the banner footer darker", prefer `theme.colors.surfaceHover` first. If the request is "add a border and spacing only to the footer", prefer `theme.slots.consentBannerFooter`.
+
+## Advanced: `noStyle`
+
+Use `noStyle` only when you want to remove defaults and style from scratch while still keeping c15t's component structure:
+
+```tsx
+{/* Remove all styles from a specific component */}
+<ConsentBanner noStyle />
+
+{/* Remove all styles globally */}
+<ConsentManagerProvider options={{ noStyle: true, ... }}>
+```
+
+You can also set `noStyle` per-slot:
+
+```tsx
+const theme = {
+  slots: {
+    consentBannerCard: { noStyle: true, className: 'my-custom-card' },
+  },
+} satisfies Theme;
+```
+
+Treat `noStyle` as an advanced escape hatch. Do not jump to it just because a token or slot needs debugging.
+
+For full custom markup and behavior, continue to [Headless Mode](../headless).

package/docs/shared/react/styling/color-scheme.md

@@ -0,0 +1,35 @@
+---
+title: Color Scheme
+description: Reference page for color scheme.
+group: reference
+---
+c15t supports light and dark mode through the theme's `colors` and `dark` token groups. The active color scheme is determined by one of three methods:
+
+1. **Explicit setting** via the `colorScheme` option
+2. **CSS class detection** - c15t checks for `.dark` on the document element
+3. **System preference** - matches `prefers-color-scheme` media query
+
+|Value|Behavior|
+|--|--|
+|`'light'`|Force light mode|
+|`'dark'`|Force dark mode|
+|`'system'`|Follow `prefers-color-scheme` media query|
+|`null`|Disable - c15t won't manage color scheme|
+
+## How Dark Mode Works
+
+When dark mode is active, c15t applies the `dark` token values as CSS variable overrides. Only tokens specified in `dark` are overridden - unset tokens fall back to the `colors` values. This also applies to `textOnPrimary`: if you omit it, c15t derives a readable foreground from the active `primary` color in that scheme.
+
+```tsx
+const theme = {
+  colors: {
+    surface: '#ffffff',     // Light mode
+    text: '#1f2937',        // Light mode
+  },
+  dark: {
+    surface: '#1f2937',     // Dark mode override
+    text: '#f9fafb',        // Dark mode override
+    // primary is NOT set - inherits from colors.primary
+  },
+} satisfies Theme;
+```

package/docs/shared/react/styling/css-variables.md

@@ -0,0 +1,53 @@
+---
+title: CSS Variables
+description: Reference page for css variables.
+group: reference
+---
+Every theme token is converted to a `--c15t-*` CSS custom property at runtime. You can override these variables in your stylesheet without using the JavaScript theme API.
+
+## Variable Reference
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`ThemeCSSVariables\`|
+|Source Path|\`./packages/ui/src/theme/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "ThemeCSSVariables" from "./packages/ui/src/theme/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+## Overriding Variables
+
+Override in your stylesheet:
+
+```css
+:root {
+  --c15t-primary: #8b5cf6;
+  --c15t-surface: #fafafa;
+  --c15t-radius-md: 1rem;
+}
+
+/* Dark mode overrides */
+.dark,
+.c15t-dark {
+  --c15t-primary: #a78bfa;
+  --c15t-surface: #18181b;
+  --c15t-text: #fafafa;
+}
+```
+
+## Scoped Overrides
+
+Target specific components by scoping variables:
+
+```tsx
+<div className="checkout-consent">
+  <ConsentBanner />
+</div>
+```
+
+```css
+/* Only affect c15t components inside .checkout-consent */
+.checkout-consent {
+  --c15t-surface: #f0f9ff;
+  --c15t-radius-lg: 1.5rem;
+}
+```