@c15t/nextjs 2.0.0-rc.4 → 2.0.0-rc.6

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

@@ -0,0 +1,390 @@
+---
+title: useConsentManager
+description: The primary hook for accessing consent state and actions. Returns the full consent store including all state properties and action methods.
+---
+`useConsentManager()` is the primary hook for interacting with the consent system. It returns the complete consent store state and all action methods.
+
+```tsx
+import { useConsentManager } from '@c15t/nextjs';
+
+function MyComponent() {
+  const {
+    consents,
+    model,
+    has,
+    saveConsents,
+    // ... all state and actions
+  } = useConsentManager();
+}
+```
+
+> ℹ️ **Info:**
+> Must be used within a ConsentManagerProvider. Throws an error if used outside the provider.
+
+## State Properties
+
+### StoreRuntimeState
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|branding|"c15t" \|"consent" \|"none"|Whether to show the branding|-|✅ Required|
+|consents|ConsentState|Current consent states for all consent types|-|✅ Required|
+|selectedConsents|ConsentState|Selected consents (Not Saved) - use saveConsents to save|-|✅ Required|
+|consentInfo|ConsentInfo \|null|Information about when and how consent was given|-|✅ Required|
+|activeUI|ActiveUI|Which consent UI component is currently visible.|-|✅ Required|
+|isLoadingConsentInfo|boolean|Whether consent banner information is currently being loaded|-|✅ Required|
+|hasFetchedBanner|boolean|Whether consent banner information has been successfully fetched|-|✅ Required|
+|lastBannerFetchData|Object \|undefined \|null|Last consent banner fetch data for callback replay|-|✅ Required|
+|debug|boolean|Whether debug logging is enabled|-|✅ Required|
+|consentCategories|AllConsentNames|Active consent categories|-|✅ Required|
+|locationInfo|LocationInfo \|null|Subject's location information|-|✅ Required|
+|includeNonDisplayedConsents|boolean|Whether to include non-displayed consents in operations|-|✅ Required|
+|consentTypes|ConsentType|Available consent type configurations|-|✅ Required|
+|iframeBlockerConfig|IframeBlockerConfig|Configuration for the iframe blocker|-|✅ Required|
+|loadedScripts|Record\<string, boolean>|Map of currently loaded script IDs to a boolean loaded-state|-|✅ Required|
+|scriptIdMap|Record\<string, string>|Map of anonymized script IDs to their original IDs|-|✅ Required|
+|model|Model|What type of consent model to use for the consent manager.|-|✅ Required|
+|policyBanner|PolicySurfaceState|Policy-driven UI hints for the consent banner surface.|-|✅ Required|
+|policyDialog|PolicySurfaceState|Policy-driven UI hints for the consent dialog surface.|-|✅ Required|
+|policyCategories|string\[] \|null|Active runtime policy category scope from \`/init\`.|-|✅ Required|
+|policyScopeMode|PolicyScopeMode \|null|Runtime policy scope mode from \`/init\`. Controls whether out-of-scope categories are treated as permissive at runtime.|-|✅ Required|
+|initDataSource|InitDataSource \|null|Source that provided the most recent \`/init\` payload used to hydrate runtime state.|-|✅ Required|
+|initDataSourceDetail|string \|null|Optional source detail for diagnostics (for example, cache header values).|-|✅ Required|
+|iab|IABManager \|null|IAB TCF 2.3 state and actions (null when not configured or not in IAB mode).|-|✅ Required|
+|reloadOnConsentRevoked|boolean|Whether to reload the page when consent is revoked.|-|✅ Required|
+|ssrDataUsed|boolean|Whether SSR data was successfully used for initialization.|-|✅ Required|
+|ssrSkippedReason|"no\_data" \|"fetch\_failed" \|null|Reason SSR data was skipped, if applicable.|-|✅ Required|
+
+#### `consents` ConsentState
+
+Current consent states for all consent types
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|experience|boolean|-|-|✅ Required|
+|functionality|boolean|-|-|✅ Required|
+|marketing|boolean|-|-|✅ Required|
+|measurement|boolean|-|-|✅ Required|
+|necessary|boolean|-|-|✅ Required|
+
+#### `selectedConsents` ConsentState
+
+Selected consents (Not Saved) - use saveConsents to save
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|experience|boolean|-|-|✅ Required|
+|functionality|boolean|-|-|✅ Required|
+|marketing|boolean|-|-|✅ Required|
+|measurement|boolean|-|-|✅ Required|
+|necessary|boolean|-|-|✅ Required|
+
+#### `consentInfo` ConsentInfo
+
+Information about when and how consent was given
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|time|number|The epoch timestamp of when the consent was recorded|-|✅ Required|
+|subjectId|string \|undefined|The client-generated subject ID in sub\_xxx format|-|Optional|
+|id|string \|undefined|-|-|Optional|
+|externalId|string \|undefined|The external user ID linked to this subject|-|Optional|
+|materialPolicyFingerprint|string \|undefined|Material fingerprint of the active policy when this consent was accepted.|-|Optional|
+|identityProvider|string \|undefined|The identity provider that provided the external ID|-|Optional|
+
+#### `locationInfo` LocationInfo
+
+Subject's location information
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|countryCode|string \|null|ISO country code (e.g., 'US', 'GB', 'DE')|-|✅ Required|
+|regionCode|string \|null|Region or state code within the country (e.g., 'CA', 'ENG')|-|✅ Required|
+|jurisdiction|Object \|null|Jurisdiction code (e.g. 'GDPR')|-|✅ Required|
+
+#### `consentTypes` ConsentType
+
+Available consent type configurations
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|defaultValue|boolean|Whether consent is granted by default|-|✅ Required|
+|description|string|Subject-friendly description of what this consent enables|-|✅ Required|
+|disabled|boolean \|undefined|Whether users can modify this consent setting|-|Optional|
+|display|boolean|Whether to show this consent option in the UI|-|✅ Required|
+|gdprType|number|GDPR category identifier (1-5)|-|✅ Required|
+|name|AllConsentNames|The consent category name|-|✅ Required|
+
+#### `iframeBlockerConfig` IframeBlockerConfig
+
+Configuration for the iframe blocker
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|disableAutomaticBlocking|boolean \|undefined|Whether to disable automatic iframe blocking (defaults to false)|-|Optional|
+
+#### `policyBanner` PolicySurfaceState
+
+Policy-driven UI hints for the consent banner surface.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|allowedActions|PolicyUiAction \|undefined|Allowed actions for this surface derived from backend runtime policy.|-|Optional|
+|primaryActions|PolicyUiAction \|undefined|Preferred primary action hints from backend runtime policy.|-|Optional|
+|layout|PolicyUiActionGroup \|undefined|Explicit grouped action layout hint from backend runtime policy.|-|Optional|
+|direction|PolicyUiActionDirection \|undefined|Direction hint for the grouped action layout.|-|Optional|
+|uiProfile|PolicyUiProfile \|undefined|Presentation profile hint from backend runtime policy.|-|Optional|
+|scrollLock|boolean \|undefined|Scroll lock hint from backend runtime policy.|-|Optional|
+
+#### `policyDialog` PolicySurfaceState
+
+Policy-driven UI hints for the consent dialog surface.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|allowedActions|PolicyUiAction \|undefined|Allowed actions for this surface derived from backend runtime policy.|-|Optional|
+|primaryActions|PolicyUiAction \|undefined|Preferred primary action hints from backend runtime policy.|-|Optional|
+|layout|PolicyUiActionGroup \|undefined|Explicit grouped action layout hint from backend runtime policy.|-|Optional|
+|direction|PolicyUiActionDirection \|undefined|Direction hint for the grouped action layout.|-|Optional|
+|uiProfile|PolicyUiProfile \|undefined|Presentation profile hint from backend runtime policy.|-|Optional|
+|scrollLock|boolean \|undefined|Scroll lock hint from backend runtime policy.|-|Optional|
+
+#### `iab` IABManager
+
+IAB TCF 2.3 state and actions (null when not configured or not in IAB mode).
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|config|IABConfig|IAB TCF configuration|-|✅ Required|
+|gvl|Object \|undefined \|null|Global Vendor List data (null when not yet fetched or in non-IAB region)|-|✅ Required|
+|isLoadingGVL|boolean|Whether GVL is currently being fetched|-|✅ Required|
+|nonIABVendors|NonIABVendor|Non-IAB vendors configured by the publisher|-|✅ Required|
+|tcString|string \|null|IAB TCF consent string (TC String)|-|✅ Required|
+|vendorConsents|Record\<string, boolean>|Per-vendor consent state (keyed by vendor ID)|-|✅ Required|
+|vendorLegitimateInterests|Record\<string, boolean>|Per-vendor legitimate interest state|-|✅ Required|
+|purposeConsents|Record\<number, boolean>|Per-purpose consent state (IAB purposes 1-11)|-|✅ Required|
+|purposeLegitimateInterests|Record\<number, boolean>|Per-purpose legitimate interest state|-|✅ Required|
+|specialFeatureOptIns|Record\<number, boolean>|Special feature opt-ins (e.g., precise geolocation)|-|✅ Required|
+|vendorsDisclosed|Record\<number, boolean>|Vendors disclosed to the user in the CMP UI (TCF 2.3 requirement). This tracks which vendors were shown to the user, regardless of whether consent was given. Required for TC String generation.|-|✅ Required|
+|cmpApi|CMPApi \|null|CMP API controls (manages \_\_tcfapi)|-|✅ Required|
+|preferenceCenterTab|"purposes" \|"vendors"|Active tab for the IAB preference center UI|-|✅ Required|
+|setPurposeConsent|(purposeId: number, value: boolean) => void|Sets IAB purpose consent.|-|✅ Required|
+|setPurposeLegitimateInterest|(purposeId: number, value: boolean) => void|Sets IAB purpose legitimate interest.|-|✅ Required|
+|setVendorConsent|(vendorId: string \|number, value: boolean) => void|Sets IAB vendor consent.|-|✅ Required|
+|setVendorLegitimateInterest|(vendorId: string \|number, value: boolean) => void|Sets IAB vendor legitimate interest.|-|✅ Required|
+|setSpecialFeatureOptIn|(featureId: number, value: boolean) => void|Sets special feature opt-in.|-|✅ Required|
+|setPreferenceCenterTab|(tab: "purposes" \|"vendors") => void|Sets the active tab for the IAB preference center.|-|✅ Required|
+|acceptAll|() => void|Accepts all IAB purposes, vendors, and special features.|-|✅ Required|
+|rejectAll|() => void|Rejects all IAB purposes (except necessary/Purpose 1) and vendors.|-|✅ Required|
+|save|() => Promise\<void>|Saves IAB consents and generates TC String.|-|✅ Required|
+|\_updateState|(updates: Partial\<IABState>) => void|Updates IAB state (internal use).|-|✅ Required|
+
+## Action Methods
+
+### StoreActions
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|setTranslationConfig|Object|Updates the translation configuration.|-|✅ Required|
+|setOverrides|Object \|undefined \|null|Sets the overrides for the consent manager. Automatically attempts to fetch the consent manager again with the new overrides.|-|✅ Required|
+|setLanguage|Object \|undefined \|null|Set the language override for the consent manager. This will override the language detected from the browser and re-fetch the consent banner information.|-|✅ Required|
+|identifyUser|Object|Identifies the user by setting the external ID.|-|✅ Required|
+|setSelectedConsent|(name: AllConsentNames, value: boolean) => void|Updates the selected consent state for a specific consent type.|-|✅ Required|
+|saveConsents|Object \|undefined|Saves the user's consent preferences.|-|✅ Required|
+|setConsent|(name: AllConsentNames, value: boolean) => void|Updates the consent state for a specific consent type & automatically save the consent.|-|✅ Required|
+|resetConsents|() => void|Resets all consent preferences to their default values|-|✅ Required|
+|setActiveUI|(ui: ActiveUI, options?: \{ force?: boolean \|undefined; } \|undefined) => void|Sets the active consent UI component.|-|✅ Required|
+|setConsentCategories|(types: AllConsentNames\[]) => void|Updates the active GDPR consent types.|-|✅ Required|
+|setCallback|Object \|undefined|Sets a callback for a specific consent event.|-|✅ Required|
+|setLocationInfo|Object \|null|Updates the user's location information.|-|✅ Required|
+|initConsentManager|Object \|undefined \|null|Initializes the consent manager by fetching jurisdiction, location, translations, and branding information.|-|✅ Required|
+|getDisplayedConsents|ConsentType|Retrieves the list of consent types that should be displayed|-|✅ Required|
+|hasConsented|() => boolean|Checks if the user has provided any form of consent|-|✅ Required|
+|has|Object|Evaluates whether current consent state satisfies the given condition.|-|✅ Required|
+|setScripts|Object|Sets multiple script configurations to the store.|-|✅ Required|
+|removeScript|(scriptId: string) => void|Removes a script configuration from the store.|-|✅ Required|
+|updateScripts|Object|Updates scripts based on current consent state. Loads scripts that have consent and aren't loaded yet. Unloads scripts that no longer have consent.|-|✅ Required|
+|isScriptLoaded|(scriptId: string) => boolean|Checks if a script is currently loaded.|-|✅ Required|
+|getLoadedScriptIds|() => string\[]|Gets all currently loaded script IDs.|-|✅ Required|
+|initializeIframeBlocker|() => void|Initializes the iframe blocker instance.|-|✅ Required|
+|updateIframeConsents|() => void|Updates the active consents used by the iframe blocker.|-|✅ Required|
+|destroyIframeBlocker|() => void|Destroys the iframe blocker instance and cleans up resources.|-|✅ Required|
+|initializeNetworkBlocker|() => void|Initializes the network blocker instance.|-|✅ Required|
+|updateNetworkBlockerConsents|() => void|Updates the consent snapshot used by the network blocker.|-|✅ Required|
+|setNetworkBlocker|Object \|undefined|Updates the network blocker configuration at runtime.|-|✅ Required|
+|destroyNetworkBlocker|() => void|Destroys the network blocker instance and cleans up resources.|-|✅ Required|
+|updateConsentCategories|(newCategories: AllConsentNames\[]) => void|Extends the active GDPR consent categories with any categories used by configured scripts.|-|✅ Required|
+
+#### `setTranslationConfig`
+
+Updates the translation configuration.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|translations|Record\<string, Partial\<Translations>>|-|-|✅ Required|
+|defaultLanguage|string \|undefined|-|-|Optional|
+|disableAutoLanguageSwitch|boolean \|undefined|-|-|Optional|
+
+#### `setOverrides`
+
+Sets the overrides for the consent manager. Automatically attempts to fetch the consent manager again with the new overrides.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|country|string \|undefined|Country code to forcefully set|-|Optional|
+|region|string \|undefined|Region code to forcefully set|-|Optional|
+|language|string \|undefined|Language code to forcefully set|-|Optional|
+|gpc|boolean \|undefined|Override the Global Privacy Control (GPC) signal. When \`true\`, simulates GPC being active (opt-out of marketing/measurement). When \`false\`, suppresses the real browser GPC signal. When \`undefined\`, falls back to the browser's \`navigator.globalPrivacyControl\`.|-|Optional|
+
+#### `identifyUser`
+
+Identifies the user by setting the external ID.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|id|string|Usually your own internal ID for the user from your auth provider|-|✅ Required|
+|identityProvider|string \|undefined|The identity provider of the user. Usually the name of the identity provider e.g. 'clerk', 'auth0', 'custom', etc.|-|Optional|
+
+#### `setLocationInfo`
+
+Updates the user's location information.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|countryCode|string \|null|ISO country code (e.g., 'US', 'GB', 'DE')|-|✅ Required|
+|regionCode|string \|null|Region or state code within the country (e.g., 'CA', 'ENG')|-|✅ Required|
+|jurisdiction|Object \|null|Jurisdiction code (e.g. 'GDPR')|-|✅ Required|
+
+#### `setScripts`
+
+Sets multiple script configurations to the store.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|id|string|Unique identifier for the script|-|✅ Required|
+|src|string \|undefined|URL of the script to load|-|Optional|
+|textContent|string \|undefined|Inline JavaScript code to execute|-|Optional|
+|category|HasCondition\<AllConsentNames>|Consent category or condition required to load this script|-|✅ Required|
+|callbackOnly|boolean \|undefined|Whether this is a callback-only script that doesn't need to load an external resource. When true, no script tag will be added to the DOM, only callbacks will be executed.|-|Optional|
+|persistAfterConsentRevoked|boolean \|undefined|Whether the script should persist after consent is revoked.|-|Optional|
+|alwaysLoad|boolean \|undefined|Whether the script should always load regardless of consent state. This is useful for scripts like Google Tag Manager or PostHog that manage their own consent state internally. The script will load immediately and never be unloaded based on consent changes. Note: When using this option, you are responsible for ensuring the script itself respects user consent preferences through its own consent management.|-|Optional|
+|fetchPriority|"high" \|"low" \|"auto" \|undefined|Priority hint for browser resource loading|-|Optional|
+|attributes|Record\<string, string> \|undefined|Additional attributes to add to the script element|-|Optional|
+|async|boolean \|undefined|Whether to use async loading|-|Optional|
+|defer|boolean \|undefined|Whether to defer script loading|-|Optional|
+|nonce|string \|undefined|Content Security Policy nonce|-|Optional|
+|anonymizeId|boolean \|undefined|Whether to use an anonymized ID for the script element, this helps ensure the script is not blocked by ad blockers|-|Optional|
+|target|"head" \|"body" \|undefined|Where to inject the script element in the DOM. Options: \`'head'\`: Scripts are appended to \`\<head>\` (default); \`'body'\`: Scripts are appended to \`\<body>\`|-|Optional|
+|onBeforeLoad|((info: ScriptCallbackInfo) => void) \|undefined|Callback executed before the script is loaded|-|Optional|
+|onLoad|((info: ScriptCallbackInfo) => void) \|undefined|Callback executed when the script loads successfully|-|Optional|
+|onError|((info: ScriptCallbackInfo) => void) \|undefined|Callback executed if the script fails to load|-|Optional|
+|onConsentChange|((info: ScriptCallbackInfo) => void) \|undefined|Callback executed whenever the consent store is changed. This callback only applies to scripts already loaded.|-|Optional|
+|vendorId|string \|number \|undefined|IAB TCF vendor ID - links script to a registered vendor. When in IAB mode, the script will only load if this vendor has consent. Takes precedence over \`category\` when in IAB mode. Use custom vendor IDs (string or number) to gate non-IAB vendors too.|-|Optional|
+|iabPurposes|number\[] \|undefined|IAB TCF purpose IDs this script requires consent for. When in IAB mode and no vendorId is set, the script will only load if ALL specified purposes have consent.|-|Optional|
+|iabLegIntPurposes|number\[] \|undefined|IAB TCF legitimate interest purpose IDs. These purposes can operate under legitimate interest instead of consent. The script loads if all iabPurposes have consent OR all iabLegIntPurposes have legitimate interest established.|-|Optional|
+|iabSpecialFeatures|number\[] \|undefined|IAB TCF special feature IDs this script requires. Options: 1: Use precise geolocation data; 2: Actively scan device characteristics for identification|-|Optional|
+
+#### `setNetworkBlocker`
+
+Updates the network blocker configuration at runtime.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|enabled|boolean \|undefined|Whether the network blocker is enabled.|-|Optional|
+|initialConsents|ConsentState \|undefined|The consent state snapshot that is currently used for blocking logic.|-|Optional|
+|logBlockedRequests|boolean \|undefined|Whether to automatically log blocked requests to the console.|-|Optional|
+|onRequestBlocked|((info: BlockedRequestInfo) => void) \|undefined|Callback invoked whenever a request is blocked.|-|Optional|
+|rules|NetworkBlockerRule|Domain rules that determine which requests should be blocked.|-|✅ Required|
+
+## identifyUser
+
+The `identifyUser()` method links anonymous consent records to an authenticated user. Call it after a user logs in to associate their consent preferences with their account.
+
+```tsx
+import { useConsentManager } from '@c15t/nextjs';
+
+function LoginForm() {
+  const { identifyUser } = useConsentManager();
+
+  async function handleLogin(email: string) {
+    // ... your login logic
+    const user = await api.login(email);
+
+    // Link consent to the authenticated user
+    await identifyUser({
+      id: user.id,
+      identityProvider: 'your-auth-provider', // e.g. 'clerk', 'auth0'
+    });
+  }
+
+  return (
+    <form onSubmit={(e) => {
+      e.preventDefault();
+      handleLogin(new FormData(e.currentTarget).get('email') as string);
+    }}>
+      <input name="email" type="email" placeholder="Email" />
+      <button type="submit">Log in</button>
+    </form>
+  );
+}
+```
+
+> ℹ️ **Info:**
+> identifyUser sends the user data to the c15t backend. It only works in 'c15t' mode — in 'offline' mode the call is a no-op.
+
+## Key Types
+
+<details>
+  <summary>`ConsentState`</summary>
+
+  A record mapping consent category names to their boolean values:
+
+  ```ts
+  type ConsentState = Record<AllConsentNames, boolean>;
+  // Example: { necessary: true, measurement: true, marketing: false }
+  ```
+</details>
+
+<details>
+  <summary>`ConsentInfo`</summary>
+
+  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')
+  }
+  ```
+</details>
+
+<details>
+  <summary>`LocationInfo`</summary>
+
+  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')
+  }
+  ```
+</details>
+
+<details>
+  <summary>`Model`</summary>
+
+  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
+</details>

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" \|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.