@c15t/nextjs 2.1.0 → 2.2.1

package/docs/shared/concepts/policy-packs.md

@@ -0,0 +1,225 @@
+---
+title: Policy Packs
+description: Reference page for policy packs.
+group: reference
+---
+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.
+
+## 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|
+
+## Global Privacy Control (GPC)
+
+Each policy can opt in to respecting the [Global Privacy Control](https://globalprivacycontrol.org/) signal via `consent.gpc`:
+
+```ts
+{
+  id: 'california',
+  match: { regions: [{ country: 'US', region: 'CA' }] },
+  consent: { model: 'opt-out', gpc: true },
+}
+```
+
+When `gpc: true` and the visitor's browser sends a GPC signal (`Sec-GPC: 1` header or `navigator.globalPrivacyControl`), `marketing` and `measurement` categories are automatically denied during auto-granting — honoring the user's opt-out preference.
+
+When `gpc` is `false` or omitted, the GPC signal is ignored for that policy. This is the right default for GDPR/EEA policies where consent is already opt-in and GPC is redundant.
+
+|Preset|`gpc`|Why|
+|--|--|--|
+|`californiaOptIn()`|`true`|CCPA recognizes GPC as a legal opt-out|
+|`californiaOptOut()`|`true`|CCPA recognizes GPC as a legal opt-out|
+|`europeOptIn()`|—|GDPR already requires opt-in|
+|`europeIab()`|—|TCF handles consent signals|
+|`worldNoBanner()`|—|No regulation applies|
+
+> ℹ️ **Info:**
+> The overrides.gpc option on the provider and the DevTools GPC toggle still work as a manual override for testing — they force the GPC signal on or off regardless of policy settings.
+
+## 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.

package/docs/shared/react/components/consent-banner.md

@@ -0,0 +1,242 @@
+---
+title: Consent Banner
+description: Reference page for consent banner.
+group: reference
+---
+`ConsentBanner` is a ready-to-use consent banner that appears automatically in **opt-in jurisdictions** (like GDPR) where explicit consent is required before tracking. In opt-out jurisdictions (like CCPA), the banner won't appear — users get an opt-out mechanism instead. It includes reject, accept, and customize buttons with configurable layout.
+
+## Button Layout
+
+The `layout` prop controls button arrangement. Each item is either a button ID or an array of button IDs (which groups them together):
+
+```tsx
+{/* Default: reject and accept grouped, customize separate */}
+<ConsentBanner layout={[['reject', 'accept'], 'customize']} />
+
+{/* All buttons in one group */}
+<ConsentBanner layout={[['reject', 'customize', 'accept']]} />
+
+{/* Accept first, then reject and customize grouped */}
+<ConsentBanner layout={['accept', ['reject', 'customize']]} />
+```
+
+To stack groups vertically, pair the same grouped layout with `direction="column"`:
+
+```tsx
+<ConsentBanner
+  layout={['customize', ['reject', 'accept']]}
+  direction="column"
+/>
+```
+
+## Policy-Driven UI Profile
+
+When using backend runtime policies, `policy.ui.uiProfile` can control banner action presentation:
+
+* `compact` — default desktop sizing
+* `balanced` — auto-fills compact and grouped layouts with moderate emphasis
+* `strict` — always fills action controls for explicit, high-clarity layouts
+
+## Theme-Level Button Styling
+
+Use the provider `theme` prop to control how stock consent actions look:
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    theme: {
+      consentActions: {
+        default: { mode: 'stroke' },
+        accept: { variant: 'primary', mode: 'stroke' },
+        customize: { variant: 'neutral', mode: 'ghost' },
+      },
+    },
+  }}
+>
+  <ConsentBanner />
+</ConsentManagerProvider>
+```
+
+Policy packs control grouping, ordering, and direction. The theme controls button appearance.
+
+## Styling First
+
+> ℹ️ **Info:**
+> For pure theming, stay inside the pre-built banner. Start with layout props, theme.consentActions, design tokens, and theme.slots before reaching for compound components. See Styling Overview.
+
+The stock banner maps common visual changes to the theme system:
+
+* Card background -> `theme.colors.surface`
+* Footer background -> `theme.colors.surfaceHover`
+* Card, footer, and title tweaks -> `theme.slots.consentBannerCard`, `consentBannerFooter`, and `consentBannerTitle`
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    theme: {
+      colors: {
+        surface: '#fffdf8',
+        surfaceHover: '#f6f3ee',
+      },
+      slots: {
+        consentBannerCard: 'rounded-[28px] shadow-xl',
+        consentBannerFooter: 'border-t border-black/10 px-6',
+        consentBannerTitle: 'tracking-tight',
+      },
+    },
+  }}
+>
+  <ConsentBanner />
+</ConsentManagerProvider>
+```
+
+### Primary Button
+
+Highlight specific button(s) as the primary action:
+
+```tsx
+{/* Single primary */}
+<ConsentBanner primaryButton="accept" />
+
+{/* Multiple primaries */}
+<ConsentBanner primaryButton={['accept', 'customize']} />
+```
+
+## Legal Links
+
+Control which legal links appear in the banner description:
+
+```tsx
+{/* Show all configured links (default) */}
+<ConsentBanner legalLinks={undefined} />
+
+{/* Show no links */}
+<ConsentBanner legalLinks={null} />
+
+{/* Show specific links */}
+<ConsentBanner legalLinks={['privacyPolicy', 'cookiePolicy']} />
+```
+
+> ℹ️ **Info:**
+> Legal link URLs are configured in the ConsentManagerProvider options via the legalLinks prop, not on the banner itself.
+
+## Customizing Copy
+
+Prefer provider `i18n` when you want to rename the stock banner content:
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    i18n: {
+      locale: 'en',
+      messages: {
+        en: {
+          cookieBanner: {
+            title: 'We value your privacy',
+            description: 'We use cookies to improve the site and measure performance.',
+          },
+          common: {
+            acceptAll: 'Accept all',
+            rejectAll: 'Reject all',
+            customize: 'Manage preferences',
+          },
+        },
+      },
+    },
+  }}
+>
+  <ConsentBanner />
+</ConsentManagerProvider>
+```
+
+Direct text props such as `title`, `description`, and `acceptButtonText` are still supported for one-off overrides, but `i18n` is the preferred path for copy changes.
+
+## Advanced: Compound Components
+
+Use compound components only when the stock banner structure is no longer enough and you need to rearrange existing c15t primitives while keeping policy-driven action grouping and emphasis:
+
+```tsx
+<ConsentBanner.Root>
+  <ConsentBanner.Overlay />
+  <ConsentBanner.Card>
+    <ConsentBanner.Header>
+      <ConsentBanner.Title />
+      <ConsentBanner.Description />
+    </ConsentBanner.Header>
+    <ConsentBanner.PolicyActions />
+  </ConsentBanner.Card>
+</ConsentBanner.Root>
+```
+
+* `ConsentBanner.Root` — Outermost container, provides theme context
+* `ConsentBanner.Card` — Main content card with optional focus trapping
+* `ConsentBanner.Header` — Contains title and description
+* `ConsentBanner.Title` — Heading, defaults to translation `consentBanner.title`
+* `ConsentBanner.Description` — Description text, supports `legalLinks` prop
+* `ConsentBanner.PolicyActions` — Renders policy-aware grouped actions inside the banner footer
+* `ConsentBanner.Footer` — Action buttons container
+* `ConsentBanner.FooterSubGroup` — Groups related buttons together
+* `ConsentBanner.RejectButton` — Rejects all consent
+* `ConsentBanner.CustomizeButton` — Opens the consent dialog
+* `ConsentBanner.AcceptButton` — Accepts all consent
+* `ConsentBanner.Overlay` — Optional backdrop overlay
+
+For a fixed layout that intentionally ignores policy grouping, render the footer manually:
+
+```tsx
+<ConsentBanner.Root>
+  <ConsentBanner.Card>
+    <ConsentBanner.Header>
+      <ConsentBanner.Title />
+      <ConsentBanner.Description />
+    </ConsentBanner.Header>
+    <ConsentBanner.Footer>
+      <ConsentBanner.FooterSubGroup>
+        <ConsentBanner.RejectButton />
+        <ConsentBanner.AcceptButton />
+      </ConsentBanner.FooterSubGroup>
+      <ConsentBanner.CustomizeButton />
+    </ConsentBanner.Footer>
+  </ConsentBanner.Card>
+</ConsentBanner.Root>
+```
+
+## Using `renderAction` with c15t Defaults
+
+`ConsentBanner.PolicyActions` renders stock c15t buttons and translations by default.
+
+```tsx
+<ConsentBanner.PolicyActions />
+```
+
+`renderAction` is optional. When you want custom mapping but still want the built-in c15t button behavior and copy, return the stock button compounds:
+
+```tsx
+<ConsentBanner.PolicyActions
+renderAction={(action, props) => {
+  const { key, ...buttonProps } = props
+
+  switch (action) {
+    case 'accept':
+        return <ConsentBanner.AcceptButton key={key} {...buttonProps} />
+    case 'reject':
+        return <ConsentBanner.RejectButton key={key} {...buttonProps} />
+    case 'customize':
+        return <ConsentBanner.CustomizeButton key={key} {...buttonProps} />
+  }
+}}
+/>
+```
+
+`renderAction` is still meant for stock button compounds. If you want completely custom button elements and click handling, use `useHeadlessConsentUI()` and render `banner.actionGroups` manually instead of `ConsentBanner.PolicyActions`.
+
+If you only need styling changes, stay with tokens and slots instead of rebuilding the banner layout.
+
+## Props
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`ConsentBannerProps\`|
+|Source Path|\`./packages/react/src/components/consent-banner/consent-banner.tsx\`|
+
+\*ExtractedTypeTable: Could not extract "ConsentBannerProps" from "./packages/react/src/components/consent-banner/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/components/consent-dialog-link.md

@@ -0,0 +1,45 @@
+---
+title: Consent Dialog Link
+description: Reference page for consent dialog link.
+group: reference
+---
+`ConsentDialogLink` is an inline trigger for opening the consent dialog from places like site footers, legal pages, or account settings. It is unstyled by default, so it inherits your app's typography and link/button styles.
+
+## Footer Link (unstyled by default)
+
+```tsx
+<footer>
+  <ConsentDialogLink>
+    Your privacy settings
+  </ConsentDialogLink>
+</footer>
+```
+
+## Render as an Anchor
+
+Use `asChild` to keep semantic anchor markup while still opening the dialog:
+
+```tsx
+<ConsentDialogLink asChild>
+  <a href="#privacy-settings">Manage Preferences</a>
+</ConsentDialogLink>
+```
+
+## Optional Styling Control
+
+The component defaults to `noStyle={true}`. Set it to `false` if you want c15t button styles:
+
+```tsx
+<ConsentDialogLink noStyle={false}>
+  Privacy Settings
+</ConsentDialogLink>
+```
+
+## Props
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`ConsentDialogLinkProps\`|
+|Source Path|\`./packages/react/src/components/consent-preferences-link/consent-preferences-link.tsx\`|
+
+\*ExtractedTypeTable: Could not extract "ConsentDialogLinkProps" from "./packages/react/src/components/consent-preferences-link/consent-preferences-link.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/components/consent-dialog-trigger.md

@@ -0,0 +1,185 @@
+---
+title: Consent Dialog Trigger
+description: Reference page for consent dialog trigger.
+group: reference
+---
+`ConsentDialogTrigger` is a floating button that opens the consent dialog when clicked. Users can drag it to any corner of the screen, and the position persists across sessions. Use it to give users a persistent way to manage their privacy settings.
+
+## Icon Options
+
+```tsx
+{/* Built-in icons */}
+<ConsentDialogTrigger icon="branding" />    {/* c15t logo (default) */}
+<ConsentDialogTrigger icon="fingerprint" /> {/* Privacy icon */}
+<ConsentDialogTrigger icon="settings" />    {/* Gear icon */}
+
+{/* Custom icon */}
+<ConsentDialogTrigger icon={<MyCustomIcon />} />
+```
+
+## Configurable Toolbar
+
+Use the separate `ConsentDialogTriggerToolbar` when you want to place app-owned controls beside the privacy trigger. It always renders exactly one built-in action that opens consent preferences, so `actions` only contains controls your app owns.
+
+```tsx
+<ConsentDialogTriggerToolbar
+  ariaLabel="Site controls"
+  actions={[
+    {
+      id: 'theme',
+      label: isDark ? 'Switch to light theme' : 'Switch to dark theme',
+      icon: isDark ? <SunIcon /> : <MoonIcon />,
+      pressed: isDark,
+      onSelect: toggleColorScheme,
+    },
+    {
+      id: 'support',
+      label: 'Open support chat',
+      icon: <ChatIcon />,
+      onSelect: openSupportChat,
+    },
+  ]}
+  preferences={{
+    icon: 'fingerprint',
+    label: 'Manage privacy settings',
+  }}
+/>
+```
+
+Each custom action requires a stable `id`, accessible `label`, `icon`, and `onSelect` callback. Use `pressed` for toggle actions and `disabled` for unavailable actions. Your app remains responsible for state, integrations, and changing the icon or label. The preferences action automatically moves to the edge nearest the toolbar's snapped corner while custom actions keep their configured order.
+
+Toolbars are horizontal by default. Set `orientation="vertical"` to stack the actions and enable Up/Down arrow-key navigation:
+
+```tsx
+<ConsentDialogTriggerToolbar
+  orientation="vertical"
+  actions={toolbarActions}
+/>
+```
+
+### Toolbar Styling
+
+The toolbar follows the standard styling precedence: internal CSS module styles, provider theme slots, then direct component overrides. Use `className` and `style` on the toolbar, or on an individual action, and use `noStyle` for a fully custom implementation.
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    theme: {
+      slots: {
+        consentDialogTriggerToolbar: 'my-toolbar',
+        consentDialogTriggerToolbarItem: 'my-toolbar-item',
+        consentDialogTriggerToolbarIcon: 'my-toolbar-icon',
+      },
+    },
+  }}
+>
+  <ConsentDialogTriggerToolbar
+    className="fixed-toolbar"
+    style={{ '--cdtt-offset': '24px' }}
+    actions={[
+      {
+        id: 'support',
+        label: 'Open support chat',
+        icon: <ChatIcon />,
+        onSelect: openSupportChat,
+        className: 'support-action',
+      },
+    ]}
+  />
+</ConsentManagerProvider>
+```
+
+Available toolbar theme slots are `consentDialogTriggerToolbar`, `consentDialogTriggerToolbarItem`, and `consentDialogTriggerToolbarIcon`.
+
+With `noStyle`, use `data-corner`, `data-dragging`, and `data-snapping` on the toolbar to style its current position and interaction state.
+
+## Visibility
+
+Control when the trigger is visible:
+
+```tsx
+{/* Always visible (default) */}
+<ConsentDialogTrigger showWhen="always" />
+
+{/* Only after user has made a consent choice */}
+<ConsentDialogTrigger showWhen="after-consent" />
+
+{/* Hidden (control visibility programmatically) */}
+<ConsentDialogTrigger showWhen="never" />
+```
+
+## Position
+
+Set the default corner and control persistence:
+
+```tsx
+<ConsentDialogTrigger
+  defaultPosition="bottom-left"
+  persistPosition={true} // Remembers user's drag position
+  onPositionChange={(position) => console.log('Moved to:', position)}
+/>
+```
+
+## Size
+
+```tsx
+<ConsentDialogTrigger size="sm" /> {/* Small */}
+<ConsentDialogTrigger size="md" /> {/* Medium (default) */}
+<ConsentDialogTrigger size="lg" /> {/* Large */}
+```
+
+## Compound Components
+
+Build fully custom trigger layouts using sub-components:
+
+```tsx
+<ConsentDialogTrigger.Root defaultPosition="bottom-right">
+  <ConsentDialogTrigger.Button size="md">
+    <ConsentDialogTrigger.Icon icon="settings" />
+    <ConsentDialogTrigger.Text>Privacy</ConsentDialogTrigger.Text>
+  </ConsentDialogTrigger.Button>
+</ConsentDialogTrigger.Root>
+```
+
+* `ConsentDialogTrigger.Root` — Portal wrapper with drag handling and position persistence
+* `ConsentDialogTrigger.Button` — Draggable button element with size variants
+* `ConsentDialogTrigger.Icon` — Icon display (branding, fingerprint, settings, or custom)
+* `ConsentDialogTrigger.Text` — Optional text label
+
+## Props
+
+### ConsentDialogTrigger
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`ConsentDialogTriggerProps\`|
+|Source Path|\`./packages/react/src/components/consent-dialog-trigger/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "ConsentDialogTriggerProps" from "./packages/react/src/components/consent-dialog-trigger/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+### ConsentDialogTriggerToolbar
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`ConsentDialogTriggerToolbarProps\`|
+|Source Path|\`./packages/react/src/components/consent-dialog-trigger/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "ConsentDialogTriggerToolbarProps" from "./packages/react/src/components/consent-dialog-trigger/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+### Toolbar Actions
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`ConsentDialogTriggerToolbarAction\`|
+|Source Path|\`./packages/react/src/components/consent-dialog-trigger/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "ConsentDialogTriggerToolbarAction" from "./packages/react/src/components/consent-dialog-trigger/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+### Preferences Action
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`ConsentDialogTriggerToolbarPreferences\`|
+|Source Path|\`./packages/react/src/components/consent-dialog-trigger/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "ConsentDialogTriggerToolbarPreferences" from "./packages/react/src/components/consent-dialog-trigger/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*