@c15t/nextjs 2.2.1 → 3.0.0-alpha.0

package/docs/frameworks/next/concepts/policy-packs.md

@@ -1,230 +0,0 @@
----
-title: Policy Packs
-description: How c15t resolves regional consent policies and what a policy pack controls.
-group: frameworks
----
-Different countries need different consent experiences. Policy packs let you define those rules once — c15t picks the right one automatically based on where the visitor is.
-
-A policy pack is an ordered array of policies. Each policy targets a region or country and controls the consent model, which categories are in scope, what UI is shown, and how consent is recorded.
-
-There are three ways to configure policy packs:
-
-1. **inth.com (recommended)** — use [inth.com](https://inth.com) as your hosted backend. Configure packs visually in the dashboard or via API — no code changes required. Works with any frontend, including static sites.
-2. **Self-hosted backend** — define packs in code via `policyPacks` and resolve them from real request geo data. Full control over policy logic and storage.
-3. **Offline fallback** — pass the same policy shapes to the frontend via `offlinePolicy.policyPacks`. Use this mainly for local development, demos, deterministic testing, or resilience when the backend is temporarily unreachable. If you omit `offlinePolicy.policyPacks`, c15t falls back to a synthetic worldwide opt-in banner instead of no-banner mode.
-
-In both hosted and self-hosted modes, the **backend is always the source of truth**. Offline packs are a preview or fallback layer and never override a live backend decision.
-
-## Quickstart
-
-The fastest way to get started is with the built-in presets:
-
-```ts
-import { policyPackPresets } from 'c15t';
-
-const policies = [
-  policyPackPresets.europeOptIn(),    // GDPR opt-in banner
-  policyPackPresets.californiaOptOut(), // CCPA opt-out banner
-  policyPackPresets.worldNoBanner(),          // No banner elsewhere
-];
-```
-
-|Preset|Model|UI|Matches|
-|--|--|--|--|
-|`europeOptIn()`|`opt-in`|banner|EEA + UK countries + geo fallback|
-|`europeIab()`|`iab`|banner|EEA + UK countries + geo fallback (TCF 2.3)|
-|`californiaOptOut()`|`opt-out`|none|US-CA region|
-|`quebecOptIn()`|`opt-in`|banner|CA-QC region|
-|`worldNoBanner()`|`none`|none|default fallback|
-
-Most apps only need these presets — pick the ones that match your regions, pass them to your backend config or provider, and you're done. Customize individual fields or write fully custom policies when you need more control.
-
-For banner/dialog actions, policy packs can also control grouped button arrangement:
-
-```ts
-ui: {
-  mode: 'banner',
-  banner: {
-    allowedActions: ['reject', 'accept', 'customize'],
-    layout: [['reject', 'accept'], 'customize'],
-    direction: 'row',
-    primaryActions: ['accept', 'customize'],
-  },
-}
-```
-
-That expresses arrangement only. Button appearance like `stroke`, `filled`, or `ghost` lives in the UI theme.
-
-## What Users See
-
-Each policy combination produces a different consent experience:
-
-|Policy Config|User Experience|
-|--|--|
-|`model: 'opt-in'`, `ui.mode: 'banner'`|Banner appears, nothing loads until the user consents|
-|`model: 'opt-out'`, `ui.mode: 'none'`|No banner, everything loads immediately — user opts out via a "Do Not Sell" link|
-|`model: 'none'`, `ui.mode: 'none'`|No banner, all categories auto-granted silently|
-|`model: 'opt-in'`, `ui.mode: 'dialog'`|Full-screen dialog, nothing loads until the user consents|
-|`model: 'iab'`, `ui.mode: 'banner'`|IAB TCF 2.3 banner with vendor-level controls|
-
-## How Policy Resolution Works
-
-When a visitor arrives, c15t walks the policy pack in priority order:
-
-1. **Match by region** — checks for a policy targeting the specific region (e.g., US-CA, CA-QC)
-2. **Match by country** — if no region match, checks for a country-level policy (e.g., US, DE)
-3. **Fallback (geo failure)** — if geo-location failed (no country detected), uses the policy marked with `match.fallback`
-4. **Fall back to default** — if nothing matches, uses the policy marked as the default
-5. **No match, no default** — resolves to no-banner mode (silent, no consent UI)
-
-Within the same matcher type, the first policy in the array wins. Pack order matters when two policies target the same country or region.
-
-The **fallback** step is distinct from **default**: `isDefault` is a catch-all for known locations that don't match any specific policy ("rest of world"), while `fallback` is a safety net for unknown locations when geo-headers are missing ("assume strictest"). The `europeOptIn()` and `europeIab()` presets include `fallback: true` by default so EU-level consent applies when geo fails.
-
-> ⚠️ **Warning:**
-> Only one default and one fallback policy are allowed. Use inspectPolicies() to surface overlapping matchers and other warnings before deployment.
-
-Inspect the resolved policy from any client component:
-
-```tsx
-'use client';
-
-import { useConsentManager } from '@c15t/nextjs';
-
-export function PolicyDebug() {
-  const { locationInfo, model, policy, policyDecision } = useConsentManager();
-
-  return (
-    <pre>
-      {JSON.stringify(
-        {
-          country: locationInfo?.countryCode,
-          region: locationInfo?.regionCode,
-          model,
-          policyId: policy?.id,
-          matchedBy: policyDecision?.matchedBy,
-          fingerprint: policyDecision?.fingerprint,
-        },
-        null,
-        2
-      )}
-    </pre>
-  );
-}
-```
-
-## Common Patterns
-
-**The 80% case** — strict in Europe, light in California, silent everywhere else:
-
-```ts
-const policies = [
-  {
-    id: 'eu',
-    match: { countries: ['DE', 'FR', 'IT'] },
-    consent: { model: 'opt-in', categories: ['necessary', 'measurement', 'marketing'] },
-    ui: { mode: 'banner' },
-  },
-  {
-    id: 'ca',
-    match: { regions: [{ country: 'US', region: 'CA' }] },
-    consent: { model: 'opt-out', gpc: true },
-    ui: { mode: 'none' },
-  },
-  {
-    id: 'default',
-    match: { isDefault: true },
-    consent: { model: 'none' },
-    ui: { mode: 'none' },
-  },
-];
-```
-
-**Region overrides country** — stricter rules for California than the rest of the US:
-
-```ts
-const policies = [
-  {
-    id: 'us_ca',
-    match: { regions: [{ country: 'US', region: 'CA' }] },
-    consent: { model: 'opt-in', scopeMode: 'strict' },
-    ui: { mode: 'banner' },
-  },
-  {
-    id: 'us',
-    match: { countries: ['US'] },
-    consent: { model: 'opt-out' },
-    ui: { mode: 'banner' },
-  },
-];
-// US-CA → us_ca (region match wins)
-// US-NY → us (country match)
-```
-
-**Different wording per region** — use `i18n.messageProfile` to vary copy without changing the consent model:
-
-```ts
-const c15t = c15tInstance({
-  i18n: {
-    defaultProfile: 'default',
-    messages: {
-      default: {
-        translations: {
-          en: { cookieBanner: { title: 'Privacy choices' } },
-          es: { cookieBanner: { title: 'Tus opciones de privacidad' } },
-        },
-      },
-      eu: {
-        fallbackLanguage: 'en',
-        translations: {
-          en: { cookieBanner: { title: 'EU GDPR Consent' } },
-          fr: { cookieBanner: { title: 'Consentement RGPD' } },
-          de: { cookieBanner: { title: 'GDPR-Einwilligung' } },
-        },
-      },
-    },
-  },
-  policyPacks: [
-    {
-      id: 'eu',
-      match: { countries: ['DE', 'FR', 'IT'] },
-      i18n: { messageProfile: 'eu' },
-      consent: { model: 'opt-in' },
-      ui: { mode: 'banner' },
-    },
-  ],
-});
-```
-
-In that setup, the `eu` policy uses only the `eu` language set. So Europe can
-resolve to `en`, `fr`, or `de`, but not to `es` or any other locale defined
-only in `default`. If the browser asks for an unsupported locale, c15t falls
-back to the `eu` profile's `fallbackLanguage`.
-
-## Re-Prompting on Policy Change
-
-When you change a policy in a way that affects consent semantics — like adding a category, changing the consent model, or modifying allowed actions — c15t automatically re-prompts returning users.
-
-This works through the **material policy fingerprint**: a hash of only the consent-affecting fields (model, categories, scope, allowed actions, grouped action layout, direction, proof settings). Presentation-only changes like copy, button styling, or scroll lock do not trigger re-prompts.
-
-|Change|Re-prompts?|
-|--|--|
-|Add a consent category|Yes|
-|Change `model` from `opt-out` to `opt-in`|Yes|
-|Remove an `allowedAction`|Yes|
-|Change `uiProfile` or button styling|No|
-|Update translation copy|No|
-|Change `scrollLock`|No|
-
-## Design Guidelines
-
-* **Start from presets.** Use `policyPackPresets` to get running, then customize for your needs.
-* **Keep packs small.** A handful of regional policies is better than dozens of tiny fragments.
-* **Think risk, not geography.** Geography is just a matcher — the real question is what consent behavior each region needs.
-* **Always include a default.** Unless "no banner for unmatched traffic" is intentional.
-* **Set a fallback for geo failures.** Mark your strictest policy with `match.fallback=true` so users in unknown locations still see a consent banner. The `europeOptIn()` and `europeIab()` presets do this automatically.
-* **Keep policy IDs stable.** They appear in debugging output, snapshots, and audit records.
-* **Use `inspectPolicies()` before deploying.** It catches overlapping matchers, missing defaults, and IAB misconfigurations.
-
-> ℹ️ **Info:**
-> For provider setup, see the Next.js policy pack guide. For backend configuration, see the self-host guide.

package/docs/frameworks/next/hooks/use-color-scheme.md

@@ -1,41 +0,0 @@
----
-title: useColorScheme
-description: Manage light/dark mode preferences for consent components.
-group: frameworks
----
-`useColorScheme()` manages the color scheme preference for c15t components. It sets up the appropriate CSS class and media query listeners.
-
-```tsx
-import { useColorScheme } from '@c15t/nextjs';
-
-function ThemeManager() {
-  useColorScheme('system'); // Follow system preference
-}
-```
-
-## Parameters
-
-|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|
-|`undefined`|No-op|
-
-## Provider-Level Configuration
-
-You can also set the color scheme on the provider without using this hook:
-
-```tsx
-<ConsentManagerProvider
-  options={{
-    colorScheme: 'system',
-    // ...
-  }}
->
-```
-
-## System Preference Detection
-
-When set to `'system'`, the hook listens for changes to the `prefers-color-scheme` media query and updates automatically when the user changes their OS theme.

package/docs/frameworks/next/hooks/use-consent-manager/checking-consent.md

@@ -1,96 +0,0 @@
----
-title: Checking Consent
-description: Use has() for flexible consent checks with AND, OR, and NOT logic.
-  Check if any consent exists with hasConsented().
-group: frameworks
----
-## has(condition)
-
-The `has()` method evaluates whether the current consent state satisfies a condition. It supports simple category checks and complex logical expressions.
-
-### Simple Check
-
-```tsx
-const { has } = useConsentManager();
-
-if (has('measurement')) {
-  // User has granted measurement consent
-}
-```
-
-### AND Logic
-
-All conditions must be true:
-
-```tsx
-has({ and: ['measurement', 'marketing'] })
-// true only if BOTH measurement AND marketing are granted
-```
-
-### OR Logic
-
-At least one condition must be true:
-
-```tsx
-has({ or: ['measurement', 'marketing'] })
-// true if EITHER measurement OR marketing is granted
-```
-
-### NOT Logic
-
-Negates a condition:
-
-```tsx
-has({ not: 'marketing' })
-// true if marketing consent is NOT granted
-```
-
-### Nested Conditions
-
-Combine operators for complex logic:
-
-```tsx
-has({
-  and: [
-    'necessary',
-    { or: ['measurement', 'marketing'] },
-    { not: 'functionality' },
-  ],
-})
-// true if: necessary AND (measurement OR marketing) AND NOT functionality
-```
-
-### HasCondition Type
-
-```ts
-type HasCondition<CategoryType> =
-  | CategoryType                                    // "measurement"
-  | { and: HasCondition[] | HasCondition }          // { and: ["a", "b"] }
-  | { or: HasCondition[] | HasCondition }           // { or: ["a", "b"] }
-  | { not: HasCondition }                           // { not: "a" }
-```
-
-## hasConsented()
-
-Returns `true` if the user has made any consent choice (accepted, rejected, or customized). Returns `false` if no consent has been recorded yet.
-
-```tsx
-const { hasConsented } = useConsentManager();
-
-if (hasConsented()) {
-  // User has previously made a consent choice
-} else {
-  // First visit — no consent recorded
-}
-```
-
-## getDisplayedConsents()
-
-Returns the consent types that should be displayed in the UI (based on active `consentCategories` and each type's `display` property):
-
-```tsx
-const { getDisplayedConsents } = useConsentManager();
-
-const visibleCategories = getDisplayedConsents();
-// Returns ConsentType[] with name, description, defaultValue, etc.
-```

package/docs/frameworks/next/hooks/use-consent-manager/location-info.md

@@ -1,97 +0,0 @@
----
-title: Location Info
-description: Access detected jurisdiction, country, and region. Override
-  geolocation for testing.
-group: frameworks
----
-## 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/frameworks/next/hooks/use-consent-manager/setting-consent.md

@@ -1,94 +0,0 @@
----
-title: Setting Consent
-description: Save, update, and reset consent preferences with setConsent(),
-  setSelectedConsent(), and saveConsents().
-group: frameworks
----
-## 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/frameworks/next/hooks/use-draggable.md

@@ -1,59 +0,0 @@
----
-title: useDraggable
-description: Make an element draggable between viewport corners with snapping,
-  persistence, and animation support.
-group: frameworks
----
-`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/frameworks/next/hooks/use-focus-trap.md

@@ -1,42 +0,0 @@
----
-title: useFocusTrap
-description: Trap keyboard focus within a container for accessible modal dialogs.
-group: frameworks
----
-`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/frameworks/next/hooks/use-reduced-motion.md

@@ -1,37 +0,0 @@
----
-title: useReducedMotion
-description: Detect the user's prefers-reduced-motion OS setting and reactively
-  disable animations.
-group: frameworks
----
-`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.