@c15t/nextjs 2.1.0 → 2.2.1

package/docs/shared/react/hooks/use-consent-manager/location-info.md

@@ -0,0 +1,96 @@
+---
+title: Location Info
+description: Reference page for location info.
+group: reference
+---
+## locationInfo
+
+The `locationInfo` state contains the user's detected geographic information:
+
+```tsx
+const { locationInfo } = useConsentManager();
+
+if (locationInfo) {
+  console.log(locationInfo.jurisdiction); // 'GDPR', 'CCPA', etc.
+  console.log(locationInfo.countryCode);  // 'DE', 'US', etc.
+  console.log(locationInfo.regionCode);   // 'BY', 'CA', etc.
+}
+```
+
+`locationInfo` is `null` until the backend responds with geolocation data (or in offline mode if no overrides are set).
+
+## Jurisdiction Codes
+
+|Code|Region|Consent Model|
+|--|--|--|
+|`GDPR`|European Union|opt-in|
+|`UK_GDPR`|United Kingdom|opt-in|
+|`CH`|Switzerland|opt-in|
+|`BR`|Brazil (LGPD)|opt-in|
+|`APPI`|Japan|opt-in|
+|`PIPA`|South Korea|opt-in|
+|`PIPEDA`|Canada (excl. Quebec)|opt-out|
+|`QC_LAW25`|Quebec, Canada|opt-in|
+|`CCPA`|California, USA|opt-out|
+|`AU`|Australia|opt-out|
+|`NONE`|No jurisdiction|null model|
+
+## setOverrides()
+
+Override detected values for testing or manual configuration. This triggers a re-fetch of consent banner data with the new values:
+
+```tsx
+const { setOverrides } = useConsentManager();
+
+// Override country (triggers jurisdiction detection)
+await setOverrides({ country: 'DE' });
+
+// Override language
+await setOverrides({ language: 'de' });
+
+// Override both
+await setOverrides({ country: 'US', region: 'CA', language: 'es' });
+```
+
+## setLocationInfo()
+
+Directly set location info without triggering a re-fetch:
+
+```tsx
+const { setLocationInfo } = useConsentManager();
+
+setLocationInfo({
+  jurisdiction: 'GDPR',
+  countryCode: 'DE',
+  regionCode: 'BY',
+});
+```
+
+## Testing Different Jurisdictions
+
+A development-only component for testing consent behavior across jurisdictions:
+
+```tsx
+function JurisdictionTester() {
+  const { setOverrides, model, locationInfo } = useConsentManager();
+
+  const testCases = [
+    { label: 'GDPR', country: 'DE' },
+    { label: 'CCPA', country: 'US', region: 'CA' },
+    { label: 'PIPEDA', country: 'CA', region: undefined },
+    { label: 'QC_LAW25', country: 'CA', region: 'QC' },
+    { label: 'NONE', country: 'US', region: 'TX' },
+  ];
+
+  return (
+    <div>
+      <p>Current: {locationInfo?.jurisdiction ?? 'none'} → model: {model}</p>
+      {testCases.map((tc) => (
+        <button key={tc.label} onClick={() => setOverrides({ country: tc.country, region: tc.region })}>
+          Test as {tc.label}
+        </button>
+      ))}
+    </div>
+  );
+}
+```

package/docs/shared/react/hooks/use-consent-manager/overview.md

@@ -0,0 +1,74 @@
+---
+title: Overview
+description: Reference page for overview.
+group: reference
+---
+> ⚠️ **Warning:**
+> Must be used within a ConsentManagerProvider. Throws an error if used outside the provider.
+
+## State Properties
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`StoreRuntimeState\`|
+|Source Path|\`./packages/core/src/store/type.ts\`|
+
+\*ExtractedTypeTable: Could not extract "StoreRuntimeState" from "./packages/core/src/store/type.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+## Action Methods
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`StoreActions\`|
+|Source Path|\`./packages/core/src/store/type.ts\`|
+
+\*ExtractedTypeTable: Could not extract "StoreActions" from "./packages/core/src/store/type.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+## Key Types
+
+### ConsentState
+
+A record mapping consent category names to their boolean values:
+
+```ts
+type ConsentState = Record<AllConsentNames, boolean>;
+// Example: { necessary: true, measurement: true, marketing: false }
+```
+
+### ConsentInfo
+
+Metadata about when and how consent was recorded:
+
+```ts
+interface ConsentInfo {
+  time: number;                    // Epoch timestamp when consent was recorded
+  subjectId?: string;              // Client-generated subject ID (sub_xxx format)
+  externalId?: string;             // External user ID linked via identifyUser()
+  identityProvider?: string;       // Identity provider (e.g. 'clerk', 'auth0')
+}
+```
+
+### LocationInfo
+
+Detected geographic location from the c15t backend:
+
+```ts
+interface LocationInfo {
+  countryCode: string;     // ISO 3166-1 alpha-2 (e.g. 'DE')
+  regionCode: string;      // Region/state code (e.g. 'BY')
+  jurisdiction: string;    // Applicable jurisdiction (e.g. 'GDPR', 'CCPA')
+}
+```
+
+### Model
+
+The active consent model:
+
+```ts
+type Model = 'opt-in' | 'opt-out' | 'iab' | null;
+```
+
+* `'opt-in'` — Explicit consent required before tracking (GDPR)
+* `'opt-out'` — Tracking allowed by default, user can opt out (CCPA)
+* `'iab'` — IAB TCF 2.3 compliance mode
+* `null` — No jurisdiction detected yet

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

@@ -0,0 +1,93 @@
+---
+title: Setting Consent
+description: Reference page for setting consent.
+group: reference
+---
+## 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/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.