@c15t/nextjs 2.0.0-rc.1 → 2.0.0-rc.12

package/docs/components/consent-banner.md

@@ -0,0 +1,269 @@
+---
+title: ConsentBanner
+description: A pre-built consent banner that appears when user consent is needed. Supports policy-aware layout, theming, and advanced composition when markup must change.
+---
+`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.
+
+## Basic Usage
+
+```tsx
+import { ConsentManagerProvider, ConsentBanner } from '@c15t/nextjs';
+
+export function ConsentManager() {
+  return (
+    <ConsentManagerProvider options={{ mode: 'hosted', backendURL: '/api/c15t' }}>
+      <ConsentBanner />
+    </ConsentManagerProvider>
+  );
+}
+```
+
+## 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
+
+### ConsentBannerProps
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|noStyle|boolean \|undefined|When true, removes all default styling from the component|false|Optional|
+|title|ReactNode|Content to display as the banner's title|undefined|Optional|
+|description|ReactNode|Content to display as the banner's description|undefined|Optional|
+|rejectButtonText|ReactNode|Content to display on the reject button|undefined|Optional|
+|customizeButtonText|ReactNode|Content to display on the customize button|undefined|Optional|
+|acceptButtonText|ReactNode|Content to display on the accept button|undefined|Optional|
+|scrollLock|boolean \|undefined|When true, the consent banner will lock the scroll of the page|false|Optional|
+|trapFocus|boolean \|undefined|When true, the consent banner will trap focus|true|Optional|
+|disableAnimation|boolean \|undefined|When true, disables the entrance/exit animations|false|Optional|
+|legalLinks|(keyof LegalLinksTranslations)\[] \|null \|undefined|Controls which legal links to display. Options: \`undefined\` (default): Shows all available legal links; \`null\`: Explicitly hides all legal links; Array of keys: Shows only the specified legal links|-|Optional|
+|hideBranding|boolean \|undefined|When true, hides the branding tag on the banner.|false|Optional|
+|layout|ConsentBannerLayout \|undefined|Defines the layout of buttons in the footer. Allows reordering and grouping of buttons.|-|Optional|
+|direction|PolicyUiActionDirection \|undefined|Defines how footer button groups flow.|-|Optional|
+|primaryButton|ConsentBannerButton \|undefined|Specifies which button(s) should be highlighted as the primary action.|-|Optional|
+|models|Model \|undefined|Which consent models this banner responds to.|\['opt-in']|Optional|
+|uiSource|string \|undefined|Override the UI source identifier sent with consent API calls.|'banner'|Optional|

package/docs/components/consent-dialog-link.md

@@ -0,0 +1,59 @@
+---
+title: ConsentDialogLink
+description: An inline trigger for opening the consent dialog from footers, legal pages, and account settings.
+---
+`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.
+
+## Basic Usage
+
+```tsx
+import { ConsentDialogLink } from '@c15t/nextjs/components/consent-dialog-link';
+
+export function SiteFooter() {
+  return (
+    <footer>
+      <ConsentDialogLink>
+        Your privacy settings
+      </ConsentDialogLink>
+    </footer>
+  );
+}
+```
+
+## 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
+
+### ConsentDialogLinkProps
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|children|ReactNode|Custom trigger content, for example "Your privacy settings" or "Manage preferences".|-|✅ Required|

package/docs/components/consent-dialog-trigger.md

@@ -0,0 +1,103 @@
+---
+title: ConsentDialogTrigger
+description: A floating, draggable button that lets users re-open the consent dialog at any time.
+---
+`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.
+
+## Basic Usage
+
+Use standalone or via the `showTrigger` prop on `ConsentDialog`:
+
+```tsx
+import { ConsentDialogTrigger } from '@c15t/nextjs';
+
+// Standalone
+<ConsentDialogTrigger />
+
+// Via ConsentDialog
+<ConsentDialog showTrigger />
+```
+
+For inline footer links (instead of a floating button), use [`ConsentDialogLink`](/docs/frameworks/next/components/consent-dialog-link).
+
+## 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 />} />
+```
+
+## 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
+
+### ConsentDialogTriggerProps
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|icon|TriggerIcon|Icon to display in the trigger button.|'branding'|Optional|
+|defaultPosition|CornerPosition \|undefined|Default corner position for the trigger. User can drag to any corner and the position will be remembered.|'bottom-right'|Optional|
+|persistPosition|boolean \|undefined|Whether to persist the user's position preference in localStorage.|true|Optional|
+|ariaLabel|string \|undefined|Accessible label for the trigger button.|'Open privacy settings'|Optional|
+|className|string \|undefined|Additional CSS class names.|-|Optional|
+|noStyle|boolean \|undefined|When true, removes default styling.|false|Optional|
+|showWhen|TriggerVisibility \|undefined|Controls when the trigger is visible.|'always'|Optional|
+|size|TriggerSize \|undefined|Size of the trigger button.|'md'|Optional|
+|onClick|(() => void) \|undefined|Callback fired when the trigger is clicked (before opening dialog).|-|Optional|
+|onPositionChange|((position: CornerPosition) => void) \|undefined|Callback fired when the corner position changes.|-|Optional|

package/docs/components/consent-dialog.md

@@ -0,0 +1,177 @@
+---
+title: ConsentDialog
+description: A modal dialog where users can toggle individual consent categories.
+---
+`ConsentDialog` is a modal that shows toggles for each consent category. In **opt-in jurisdictions**, it typically opens when users click "Customize" on `ConsentBanner`. It can also be controlled programmatically for use on settings pages regardless of jurisdiction.
+
+## Basic Usage
+
+```tsx
+import { ConsentManagerProvider, ConsentBanner, ConsentDialog } from '@c15t/nextjs';
+
+export function ConsentManager() {
+  return (
+    <ConsentManagerProvider options={{ mode: 'hosted', backendURL: '/api/c15t' }}>
+      <ConsentBanner />
+      <ConsentDialog />
+    </ConsentManagerProvider>
+  );
+}
+```
+
+## Controlled State
+
+By default, the dialog follows `activeUI === 'dialog'` from the consent store. Use the `open` prop for manual control:
+
+```tsx
+import { useState } from 'react';
+
+function SettingsPage() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <button onClick={() => setOpen(true)}>Privacy Settings</button>
+      <ConsentDialog open={open} />
+    </>
+  );
+}
+```
+
+Or use the hook to open it programmatically:
+
+```tsx
+import { useConsentManager } from '@c15t/nextjs';
+
+function PrivacyLink() {
+  const { setActiveUI } = useConsentManager();
+
+  return (
+    <button onClick={() => setActiveUI('dialog')}>
+      Manage cookies
+    </button>
+  );
+}
+```
+
+## Floating Trigger
+
+Add a floating button that lets users re-open the dialog after dismissing the banner:
+
+```tsx
+{/* Default trigger */}
+<ConsentDialog showTrigger />
+
+{/* Custom trigger */}
+<ConsentDialog
+  showTrigger={{
+    icon: 'settings',
+    defaultPosition: 'bottom-left',
+    showWhen: 'after-consent',
+    size: 'sm',
+  }}
+/>
+```
+
+## Branding
+
+Hide the c15t branding tag:
+
+```tsx
+<ConsentDialog hideBranding />
+```
+
+## Styling First
+
+> ℹ️ **Info:**
+> If you are only changing visuals, stay with the stock dialog and use the theme system first. Start with tokens and slots such as consentDialogCard, consentWidgetFooter, and consentDialogTag. See Styling Overview.
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    theme: {
+      colors: {
+        surface: '#fffdf8',
+        surfaceHover: '#f6f3ee',
+      },
+      slots: {
+        consentDialogCard: 'rounded-[32px] shadow-xl',
+        consentDialogHeader: 'gap-3',
+        consentWidgetFooter: 'gap-3 pt-6',
+        consentDialogTag: 'shadow-none',
+      },
+    },
+  }}
+>
+  <ConsentDialog />
+</ConsentManagerProvider>
+```
+
+Dialog copy should be changed through `ConsentManagerProvider.options.i18n`, not by rebuilding the dialog structure.
+
+## Advanced: Compound Components
+
+Use compound components only when you need custom dialog markup while still keeping c15t primitives and policy-aware footer actions:
+
+```tsx
+<ConsentDialog.Root>
+  <ConsentDialog.Overlay />
+  <ConsentDialog.Card>
+    <ConsentDialog.Header>
+      <ConsentDialog.HeaderTitle />
+      <ConsentDialog.HeaderDescription />
+    </ConsentDialog.Header>
+    <ConsentDialog.Content>
+      <ConsentWidget.Root>
+        <ConsentWidget.Accordion type="single">
+          <ConsentWidget.AccordionItems />
+        </ConsentWidget.Accordion>
+        <ConsentWidget.PolicyActions />
+      </ConsentWidget.Root>
+    </ConsentDialog.Content>
+    <ConsentDialog.Footer />
+  </ConsentDialog.Card>
+</ConsentDialog.Root>
+```
+
+* `ConsentDialog.Root` — Portal container with focus trap, scroll lock, and animation
+* `ConsentDialog.Card` — Main dialog card
+* `ConsentDialog.Header` — Contains title and description
+* `ConsentDialog.HeaderTitle` — Dialog title
+* `ConsentDialog.HeaderDescription` — Description with optional `legalLinks`
+* `ConsentDialog.Content` — Main content area (typically contains `ConsentWidget`)
+* `ConsentDialog.Footer` — Footer with optional branding (`hideBranding` prop)
+* `ConsentDialog.Overlay` — Backdrop overlay
+* `ConsentWidget.PolicyActions` — Renders policy-aware grouped dialog actions
+
+For a quick pre-composed layout, use the shorthand card:
+
+```tsx
+<ConsentDialog.Root>
+  <ConsentDialog.ConsentCustomizationCard />
+</ConsentDialog.Root>
+```
+
+`ConsentWidget.PolicyActions` uses stock c15t widget buttons and translations by default. Pass `renderAction` only when you need to customize the action mapping, and return stock widget button compounds if you want to preserve built-in behavior and copy.
+
+For fully manual control over dialog action rendering, use `useHeadlessConsentUI()` and map `dialog.actionGroups` yourself.
+
+If the stock dialog structure still works, prefer tokens, slots, and provider configuration instead.
+
+## Props
+
+### ConsentDialogProps
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|theme|undefined|Theme configuration override (deprecated)|-|Optional|
+|disableAnimation|boolean \|undefined|Disables all animations when true|-|Optional|
+|noStyle|boolean \|undefined|Removes default styles when true|-|Optional|
+|scrollLock|boolean \|undefined|Locks the scroll when true|-|Optional|
+|trapFocus|boolean \|undefined|Traps keyboard focus within a dialog when true|-|Optional|
+|open|boolean \|undefined|Control the open state. If omitted the dialog follows \`useConsentManager().activeUI === 'dialog'\`.|-|Optional|
+|legalLinks|(keyof LegalLinksTranslations)\[] \|null \|undefined|Controls which legal links to display. Options: \`undefined\` (default): Shows all available legal links; \`null\`: Explicitly hides all legal links; Array of keys: Shows only the specified legal links|-|Optional|
+|hideBranding|boolean \|undefined|Controls whether to hide the branding in the dialog footer.|-|Optional|
+|showTrigger|ConsentDialogTriggerProps \|undefined|Show a floating trigger button to resurface the consent dialog. Useful for allowing users to re-open the dialog after dismissing. Options: \`true\` - Show trigger with default settings; \`false\` - Hide trigger (default); \`ConsentDialogTriggerProps\` - Show trigger with custom props|false|Optional|
+|models|Model \|undefined|Which consent models this dialog responds to.|\['opt-in', 'opt-out']|Optional|
+|uiSource|string \|undefined|Override the UI source identifier sent with consent API calls.|'dialog'|Optional|