@c15t/nextjs 2.2.1 → 3.0.0-alpha.0

package/docs/frameworks/next/hooks/use-ssr-status.md

@@ -1,32 +0,0 @@
----
-title: useSSRStatus
-description: Check whether server-side rendered consent data was used during initialization.
-group: frameworks
----
-`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
-
-|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/frameworks/next/hooks/use-text-direction.md

@@ -1,50 +0,0 @@
----
-title: useTextDirection
-description: Manage RTL/LTR text direction based on the active language for consent UI.
-group: frameworks
----
-`useTextDirection()` determines the correct text direction (`'ltr'` or `'rtl'`) based on the provided language and sets it on the document. It wraps the `@c15t/ui` text direction utilities as a React hook.
-
-This is used internally by IAB components but is available for custom UI that needs to handle bidirectional text.
-
-```tsx
-import { useTextDirection } from '@c15t/react/hooks';
-
-function CustomConsentUI({ language }: { language: string }) {
-  const direction = useTextDirection(language);
-
-  return (
-    <div dir={direction}>
-      {/* Content renders correctly for RTL languages like Arabic and Hebrew */}
-    </div>
-  );
-}
-```
-
-## Parameters
-
-|Parameter|Type|Default|Description|
-|--|--|--|--|
-|`language`|`string \|undefined`|—|BCP 47 language tag (e.g. `'en'`, `'ar'`, `'he'`)|
-
-## Return Value
-
-|Type|Description|
-|--|--|
-|`'ltr' \|'rtl'`|The text direction for the given language|
-
-## RTL Languages
-
-The hook recognizes standard RTL languages including Arabic (`ar`), Hebrew (`he`), Persian (`fa`), and Urdu (`ur`), among others.
-
-```tsx
-import { useConsentManager } from '@c15t/nextjs';
-import { useTextDirection } from '@c15t/react/hooks';
-
-function BiDirectionalBanner() {
-  const { translationConfig } = useConsentManager();
-  const dir = useTextDirection(translationConfig.defaultLanguage);
-
-  return <div dir={dir}>...</div>;
-}
-```

package/docs/frameworks/next/hooks/use-translations.md

@@ -1,55 +0,0 @@
----
-title: useTranslations
-description: Access the current language's translations for building custom consent UI.
-group: frameworks
----
-`useTranslations()` returns the `Translations` object for the currently active language. Use it when building custom consent UI that needs translated text.
-
-```tsx
-import { useTranslations } from '@c15t/nextjs';
-
-function CustomBanner() {
-  const translations = useTranslations();
-
-  return (
-    <div>
-      <h2>{translations.cookieBanner.title}</h2>
-      <p>{translations.cookieBanner.description}</p>
-      <button>{translations.common.acceptAll}</button>
-      <button>{translations.common.rejectAll}</button>
-    </div>
-  );
-}
-```
-
-## Translation Sections
-
-The returned `Translations` object has these sections:
-
-|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.\*
-
-## With setLanguage
-
-Translations update automatically when the language changes:
-
-```tsx
-import { useConsentManager, useTranslations } from '@c15t/nextjs';
-
-function LocalizedConsent() {
-  const { setLanguage } = useConsentManager();
-  const translations = useTranslations();
-
-  return (
-    <div>
-      <p>{translations.cookieBanner.description}</p>
-      <button onClick={() => setLanguage('de')}>Deutsch</button>
-      <button onClick={() => setLanguage('fr')}>Français</button>
-    </div>
-  );
-}
-```

package/docs/frameworks/next/iab/consent-banner.md

@@ -1,91 +0,0 @@
----
-title: IABConsentBanner
-description: An IAB TCF 2.3 compliant consent banner that displays partner
-  count, purpose summaries, and legitimate interest notices.
-group: frameworks
----
-> ℹ️ **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)
-
-## Basic Usage
-
-```tsx
-import { type ReactNode } from 'react';
-import { iab } from '@c15t/iab';
-import { ConsentManagerProvider } from '@c15t/nextjs';
-import { IABConsentBanner, IABConsentDialog } from '@c15t/react/iab';
-
-export default function ConsentManager({ children }: { children: ReactNode }) {
-  return (
-    <ConsentManagerProvider
-      options={{
-        mode: 'hosted',
-        backendURL: '/api/c15t',
-        iab: iab({
-          vendors: [1, 2, 10, 25],
-          // cmpId is automatically provided by the backend when using Inth.
-          // Only set this if you have your own CMP registration.
-          // cmpId: 123,
-        }),
-      }}
-    >
-      <IABConsentBanner />
-      <IABConsentDialog />
-      {children}
-    </ConsentManagerProvider>
-  );
-}
-```
-
-> ℹ️ **Info:**
-> The banner only renders when IAB mode is enabled and the GVL (Global Vendor List) has been loaded. If iab.enabled is false or the server does not return GVL data, nothing is rendered.
-
-## Banner Content
-
-The IAB banner automatically displays:
-
-* **Title** — Heading text from IAB translations
-* **Description** — Includes the partner count (e.g., "We and our \{partnerCount} partners...")
-* **Partners link** — Clickable link that opens the vendor tab in the preference center
-* **Purpose/stack list** — Up to 5 purpose/stack names summarizing data usage, with an "and X more" overflow
-* **Legitimate interest notice** — Required IAB disclosure about legitimate interest processing
-* **Scope notice** — Service-specific scope disclosure
-
-## Buttons
-
-The banner includes three action buttons:
-
-|Button|Action|
-|--|--|
-|**Reject All**|Rejects all IAB purposes and closes the banner|
-|**Accept All**|Accepts all IAB purposes and closes the banner|
-|**Customize**|Opens the IABConsentDialog purposes tab|
-
-### Primary Button
-
-Highlight a specific button as the primary action:
-
-```tsx
-<IABConsentBanner primaryButton="accept" />
-```
-
-Options: `'reject'`, `'accept'`, `'customize'` (default: `'customize'`)
-
-## Props
-
-|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/frameworks/next/iab/consent-dialog.md

@@ -1,129 +0,0 @@
----
-title: IABConsentDialog
-description: An IAB TCF 2.3 compliant preference center with tabbed purpose and
-  vendor management.
-group: frameworks
----
-> ℹ️ **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.
-
-## Basic Usage
-
-Pair it with `IABConsentBanner` inside the provider:
-
-```tsx
-import { type ReactNode } from 'react';
-import { iab } from '@c15t/iab';
-import { ConsentManagerProvider } from '@c15t/nextjs';
-import { IABConsentBanner, IABConsentDialog } from '@c15t/react/iab';
-
-export default function ConsentManager({ children }: { children: ReactNode }) {
-  return (
-    <ConsentManagerProvider
-      options={{
-        mode: 'hosted',
-        backendURL: '/api/c15t',
-        iab: iab({
-          vendors: [1, 2, 10, 25],
-          // cmpId is automatically provided by the backend when using Inth.
-          // Only set this if you have your own CMP registration.
-          // cmpId: 123,
-        }),
-      }}
-    >
-      <IABConsentBanner />
-      <IABConsentDialog />
-      {children}
-    </ConsentManagerProvider>
-  );
-}
-```
-
-## Tabs
-
-The dialog has two tabs:
-
-### Purposes Tab
-
-Displays all IAB purposes grouped into:
-
-* **Standalone purposes** — Purpose 1 (Store and/or access information on a device) is always shown standalone per IAB TCF spec
-* **Stacks** — Groups of related purposes determined by the GVL. Each stack is expandable to show individual purpose toggles
-* **Special features** — Opt-in features like precise geolocation
-* **Essential functions** — Special purposes and features that are locked (no user toggle) because they're required for basic operation
-
-Each purpose shows:
-
-* Name and description
-* Number of vendors using this purpose
-* Consent toggle (or lock icon for essential functions)
-* Legitimate interest toggle where applicable
-* Expandable vendor list
-
-### Vendors Tab
-
-Displays all vendors from the GVL plus any custom vendors:
-
-* Search and filter vendors
-* Per-vendor consent and legitimate interest toggles
-* Vendor details: privacy policy link, cookie usage, data retention
-* Purpose and feature associations
-
-## Controlled State
-
-By default, the dialog follows `activeUI === 'dialog'` from the consent store. Use `open` for manual control:
-
-```tsx
-import { useState } from 'react';
-import { IABConsentDialog } from '@c15t/react/iab';
-
-function SettingsPage() {
-  const [open, setOpen] = useState(false);
-
-  return (
-    <>
-      <button onClick={() => setOpen(true)}>TCF Preferences</button>
-      <IABConsentDialog open={open} />
-    </>
-  );
-}
-```
-
-## Floating Trigger
-
-Add a floating button so users can re-open the dialog after dismissing the banner. IAB TCF requires the preference center to be easily resurfaceable:
-
-```tsx
-<IABConsentDialog showTrigger />
-
-{/* Custom trigger options */}
-<IABConsentDialog
-  showTrigger={{
-    icon: 'settings',
-    defaultPosition: 'bottom-left',
-    showWhen: 'after-consent',
-    size: 'sm',
-  }}
-/>
-```
-
-## Footer Actions
-
-The dialog footer provides three buttons:
-
-|Button|Action|
-|--|--|
-|**Reject All**|Rejects all purposes and vendors, closes dialog and banner|
-|**Accept All**|Accepts all purposes and vendors, closes dialog and banner|
-|**Save Settings**|Saves current selections, closes dialog and banner|
-
-## Props
-
-|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/frameworks/next/iab/use-gvl-data.md

@@ -1,21 +0,0 @@
----
-title: useGVLData (Internal)
-description: Status note for the internal GVL hook used by the built-in IAB dialog.
-group: frameworks
----
-> ⚠️ **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/frameworks/next/iframe-blocking.md

@@ -1,106 +0,0 @@
----
-title: Iframe Blocking
-description: Block embedded content (YouTube, social widgets, maps) until users
-  grant consent for the appropriate category.
-group: frameworks
----
-Embedded iframes from third parties (YouTube, Google Maps, social media widgets) can set cookies and track users without their consent. c15t provides two approaches to gate iframes behind consent:
-
-1. **`<Frame>` component** - A React component that conditionally renders children based on consent
-2. **HTML `data-category` attribute** - For raw `<iframe>` elements outside of React
-
-## Frame Component
-
-The `<Frame>` component wraps content that requires consent. Children are only mounted when the specified category has consent. When consent is not granted, a placeholder is shown instead.
-
-```tsx
-import { Frame } from '@c15t/nextjs';
-
-function YouTubeEmbed() {
-  return (
-    <Frame category="marketing">
-      <iframe
-        src="https://www.youtube.com/embed/dQw4w9WgXcQ"
-        width="560"
-        height="315"
-        allowFullScreen
-      />
-    </Frame>
-  );
-}
-```
-
-### Custom Placeholder
-
-Replace the default placeholder with your own UI:
-
-```tsx
-<Frame
-  category="marketing"
-  placeholder={
-    <div className="flex items-center justify-center h-64 bg-gray-100 rounded">
-      <p>Enable marketing cookies to watch this video.</p>
-    </div>
-  }
->
-  <iframe src="https://www.youtube.com/embed/..." />
-</Frame>
-```
-
-### Compound Components
-
-Build custom placeholder layouts using compound components:
-
-```tsx
-<Frame.Root category="marketing">
-  <Frame.Title category="marketing" />
-  <Frame.Button category="marketing" />
-</Frame.Root>
-```
-
-## HTML Attribute Approach
-
-For iframes outside of React (e.g., CMS content, server-rendered HTML), add `data-category` and use `data-src` instead of `src`:
-
-```html
-<iframe
-  data-src="https://www.youtube.com/embed/dQw4w9WgXcQ"
-  data-category="marketing"
-  width="560"
-  height="315"
-></iframe>
-```
-
-When consent for the specified category is granted, c15t automatically swaps `data-src` to `src`, loading the iframe. When consent is revoked, `src` is moved back to `data-src`.
-
-### Dynamic Iframes
-
-c15t uses a `MutationObserver` to watch for dynamically added iframes. Any iframe with `data-category` added to the DOM after initialization is automatically processed.
-
-## Initializing the Iframe Blocker
-
-The iframe blocker for HTML attributes needs to be initialized separately from the Frame component:
-
-```tsx
-import { useConsentManager } from '@c15t/nextjs';
-import { useEffect } from 'react';
-
-function IframeBlockerInit() {
-  const { initializeIframeBlocker } = useConsentManager();
-
-  useEffect(() => {
-    initializeIframeBlocker();
-  }, [initializeIframeBlocker]);
-
-  return null;
-}
-```
-
-## API Reference
-
-|Property|Value|
-|:--|:--|
-|Type Name|\`FrameProps\`|
-|Source Path|\`./packages/react/src/components/frame/types.ts\`|
-
-\*ExtractedTypeTable: Could not extract "FrameProps" from "./packages/react/src/components/frame/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/frameworks/next/internationalization.md

@@ -1,207 +0,0 @@
----
-title: Internationalization
-description: Translate consent UI into 30+ languages with built-in translations,
-  custom overrides, and automatic browser language detection.
-group: frameworks
----
-c15t ships with built-in translations for 30+ languages via the `@c15t/translations` package. Language detection happens automatically based on the browser's language preference, and you can override or extend translations for any language.
-
-In c15t v2, the preferred config shape is `i18n` with `locale`, `detectBrowserLanguage`, and `messages`.
-
-There are two ways c15t can load translations: client-side or server-side.
-
-|Server-side|Client-side|
-|--|--|
-|The best way to reduce bundle size and improve performance. We can detect the user's language based on the browser's language settings, allowing for the most accurate translations. By default, when using a [inth.com](https://inth.com) hosted instance, [these languages](https://github.com/c15t/c15t/tree/main/packages/translations/src/translations) are supported.|Bundled with the application allowing for multiple languages to be supported without the need for a backend. The more translations you have, the larger the bundle size will be, which may impact the performance of your application.|
-
-## Basic Configuration
-
-Pass custom translations via the `i18n` option:
-
-```tsx
-import { type ReactNode } from 'react';
-import { ConsentManagerProvider } from '@c15t/nextjs';
-
-export default function ConsentManager({ children }: { children: ReactNode }) {
-  return (
-    <ConsentManagerProvider
-      options={{
-        mode: 'hosted',
-        backendURL: '/api/c15t',
-        i18n: {
-          locale: 'en',
-          messages: {
-            de: {
-              cookieBanner: {
-                title: 'Datenschutzeinstellungen',
-                description: 'Wir verwenden Cookies, um Ihnen das beste Erlebnis zu bieten.',
-              },
-              common: {
-                acceptAll: 'Alle akzeptieren',
-                rejectAll: 'Alle ablehnen',
-                customize: 'Anpassen',
-                save: 'Speichern',
-              },
-            },
-          },
-        },
-      }}
-    >
-      {children}
-    </ConsentManagerProvider>
-  );
-}
-```
-
-Custom translations are deep-merged with built-in defaults - you only need to override the keys you want to change.
-
-## Translation Package Imports
-
-Use the import path that matches your use case:
-
-* `@c15t/translations`: types, utilities, and `enTranslations` only (smallest client bundle)
-* `@c15t/translations/en`: English-only translation object
-* `@c15t/translations/all`: full `baseTranslations` map for all bundled locales
-
-If you bundle translations client-side and need multiple languages, import from `@c15t/translations/all` explicitly:
-
-```tsx
-import { baseTranslations } from '@c15t/translations/all';
-
-const translations = {
-  en: baseTranslations.en,
-  de: baseTranslations.de,
-  fr: baseTranslations.fr,
-};
-```
-
-## Translation Sections
-
-The `Translations` object is organized into sections:
-
-|Section|Controls|
-|--|--|
-|`common`|Shared button labels: acceptAll, rejectAll, customize, save|
-|`cookieBanner`|Banner title and description|
-|`consentManagerDialog`|Dialog title and description|
-|`consentTypes`|Per-category title and description (keyed by AllConsentNames)|
-|`frame`|Frame placeholder title, button, loading, and error text (title and button support `{category}`)|
-|`legalLinks`|Privacy policy, cookie policy, terms of service link text|
-|`iab`|IAB TCF banner, preference center, vendor list translations|
-
-## Reading Translations
-
-Use the `useTranslations()` hook to access the current language's translations:
-
-```tsx
-import { useTranslations } from '@c15t/nextjs';
-
-function CustomBanner() {
-  const translations = useTranslations();
-
-  return (
-    <div>
-      <h2>{translations.cookieBanner.title}</h2>
-      <p>{translations.cookieBanner.description}</p>
-    </div>
-  );
-}
-```
-
-## Changing Language
-
-Switch the active language at runtime with `setLanguage()`:
-
-```tsx
-import { useConsentManager } from '@c15t/nextjs';
-
-function LanguageSwitcher() {
-  const { setLanguage } = useConsentManager();
-
-  return (
-    <select onChange={(e) => setLanguage(e.target.value)}>
-      <option value="en">English</option>
-      <option value="de">Deutsch</option>
-      <option value="fr">Fran&ccedil;ais</option>
-      <option value="es">Espa&ntilde;ol</option>
-    </select>
-  );
-}
-```
-
-`setLanguage()` re-fetches the consent banner to get server-resolved translations for the new language.
-
-## Automatic Language Detection
-
-By default, c15t detects the browser's language (`navigator.language`) and selects the closest matching translation. If custom `messages` are configured, fallback stays within your configured languages before using `locale` (or `'en'`) as the preferred fallback language.
-
-When backend policy packs use `i18n.messageProfile`, the active language pool comes only from that resolved profile.
-
-Example: if your Europe profile defines `en`, `fr`, and `de`, and your default profile defines `en`, `es`, and `pt`, a Europe visitor can resolve to `en`, `fr`, or `de`, but not `es`, `pt`, or `zh`.
-
-Use profile-local `fallbackLanguage` inside backend `i18n.messages` to choose which configured language a policy profile should fall back to when the browser asks for an unsupported locale.
-
-Disable auto-detection to always use `locale`:
-
-```tsx
-i18n: {
-  locale: 'de',
-  detectBrowserLanguage: false,
-  messages: { ... },
-}
-```
-
-If you need a policy to always use one specific language regardless of browser preference, set `policy.i18n.language` on the backend policy pack.
-
-## Custom Consent Type Labels
-
-Override the title and description for individual consent categories. Frame
-placeholders use that title anywhere their message contains `{category}`, so
-the title and action stay consistent:
-
-```tsx
-i18n: {
-  messages: {
-    en: {
-      consentTypes: {
-        measurement: {
-          title: 'Analytics & Performance',
-          description: 'Help us understand how visitors interact with our site.',
-        },
-        marketing: {
-          title: 'Advertising',
-          description: 'Used to deliver relevant ads and measure campaign effectiveness.',
-        },
-      },
-      frame: {
-        title: 'Allow {category} consent to view this content.',
-        actionButton: 'Enable {category} consent',
-        loading: 'Loading content…',
-        error: 'This content could not be loaded.',
-      },
-    },
-  },
-}
-```
-
-## Legacy `translations` Compatibility
-
-The legacy syntax is still supported in 2.0 for RC compatibility:
-
-```tsx
-// Legacy (still supported)
-translations: {
-  defaultLanguage: 'en',
-  disableAutoLanguageSwitch: true,
-  translations: { ... },
-}
-
-// Preferred in v2
-i18n: {
-  locale: 'en',
-  detectBrowserLanguage: false,
-  messages: { ... },
-}
-```
-
-If both are provided, `i18n` takes precedence.