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

package/docs/styling/overview.md

@@ -0,0 +1,312 @@
+---
+title: Styling Overview
+description: Five approaches for theming consent components — design tokens, component slots, CSS variables, className, and noStyle mode.
+---
+c15t's theming system gives you multiple levels of control, from high-level design tokens to complete style removal.
+
+The flow:
+
+1. **Define** tokens (colors, spacing, radius, etc.) in JavaScript
+2. Tokens are **injected** as CSS custom properties (`--c15t-*`) at runtime
+3. Components **consume** these variables in their default styles
+4. You **override** at any level: tokens, slots, CSS variables, or raw classNames
+
+## Styling Approaches
+
+|Approach|Control|Use When|
+|--|--|--|
+|**Tokens**|High|Changing global colors, typography, spacing, radius, shadows, or motion|
+|**Slots**|Medium|Targeting specific component parts (e.g., the banner title, dialog footer)|
+|**CSS Variables**|Medium|Overriding `--c15t-*` variables from external CSS|
+|**className**|Medium|Passing class names to components or slots|
+|**noStyle**|Full|Removing all default styles, building from scratch|
+
+## Quick Start
+
+```tsx
+import { type Theme, ConsentManagerProvider, ConsentBanner, ConsentDialog } from '@c15t/nextjs';
+
+const theme = {
+  colors: {
+    primary: '#6366f1',
+    primaryHover: '#4f46e5',
+  },
+  radius: {
+    md: '0.75rem',
+    lg: '1rem',
+  },
+  slots: {
+    consentBannerTitle: 'text-xl font-semibold',
+    buttonPrimary: 'rounded-full',
+  },
+} satisfies Theme;
+
+export function ConsentManager({ children }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        theme,
+      }}
+    >
+      <ConsentBanner />
+      <ConsentDialog />
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+## Styling Paths
+
+### 1. Design tokens
+
+Set global values for colors, typography, spacing, radius, shadows, and motion:
+
+```tsx
+options={{ theme: { colors: { primary: '#6366f1' } } }}
+```
+
+### 2. Component slots
+
+Target specific component parts via the `slots` object:
+
+```tsx
+options={{ theme: { slots: { consentBannerTitle: 'text-2xl font-bold' } } }}
+```
+
+### 3. CSS variables
+
+Override `--c15t-*` custom properties in your stylesheet.
+
+### 4. className prop
+
+Pass className directly to components:
+
+```tsx
+<ConsentBanner className="my-custom-banner" />
+```
+
+### 5. noStyle prop
+
+Strip all default styles and build from scratch (best paired with [Headless Mode](../headless)):
+
+```tsx
+<ConsentBanner noStyle />
+```
+
+## Common Styling Tasks
+
+### Change brand color globally
+
+```tsx
+options={{ theme: { colors: { primary: '#0ea5e9', primaryHover: '#0284c7' } } }}
+```
+
+### Make the banner card more compact
+
+```tsx
+options={{ theme: { spacing: { md: '0.75rem', lg: '1rem' } } }}
+```
+
+### Round primary/secondary buttons
+
+```tsx
+options={{ theme: { slots: { buttonPrimary: 'rounded-full', buttonSecondary: 'rounded-full' } } }}
+```
+
+### Change consent action button styles semantically
+
+```tsx
+options={{
+  theme: {
+    consentActions: {
+      default: { mode: 'stroke' },
+      accept: { variant: 'primary', mode: 'stroke' },
+      customize: { variant: 'neutral', mode: 'ghost' },
+    },
+  },
+}}
+```
+
+Use `theme.consentActions` when you want to change the stock banner/dialog button treatment without rewriting the component layout. Policy packs still control action arrangement and primary-action hints. The theme controls whether those actions render as `stroke`, `filled`, `ghost`, or `lighter`.
+
+### Enable dark mode safely
+
+```tsx
+options={{
+  colorScheme: 'system',
+  theme: {
+    colors: { surface: '#ffffff', text: '#1f2937' },
+    dark: { surface: '#111827', text: '#f9fafb' },
+  },
+}}
+```
+
+> ⚠️ **Warning:**
+> noStyle: true removes layout and visual defaults. Use it only when you want full control.Use either tokens/slots or raw CSS variable overrides intentionally to avoid conflicting style sources.For dark mode, c15t supports .dark and .c15t-dark.
+
+## API Reference
+
+### Theme
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|colors|ColorTokens \|undefined|Color palette for light mode.|-|Optional|
+|dark|ColorTokens \|undefined|Dark mode color overrides.|-|Optional|
+|typography|TypographyTokens \|undefined|Typography settings for text elements.|-|Optional|
+|spacing|SpacingTokens \|undefined|Spacing scale for internal padding and margins.|-|Optional|
+|radius|RadiusTokens \|undefined|Border radius scale for rounded corners.|-|Optional|
+|shadows|ShadowTokens \|undefined|Box shadow scale for depth and elevation.|-|Optional|
+|motion|MotionTokens \|undefined|Animation and transition timing.|-|Optional|
+|consentActions|Object \|undefined|Semantic button styling for consent actions.|-|Optional|
+|slots|ComponentSlots \|undefined|Component-specific style overrides.|-|Optional|
+
+#### `colors` ColorTokens
+
+Color palette for light mode.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|primary|string \|undefined|Primary brand/accent color for interactive elements.|-|Optional|
+|primaryHover|string \|undefined|Hover/active state for primary elements.|-|Optional|
+|surface|string \|undefined|Main background color for panels and containers.|-|Optional|
+|surfaceHover|string \|undefined|Hover state for surface elements.|-|Optional|
+|border|string \|undefined|Border color for containers and inputs.|-|Optional|
+|borderHover|string \|undefined|Hover state for bordered elements.|-|Optional|
+|text|string \|undefined|Primary text color for headings and body.|-|Optional|
+|textMuted|string \|undefined|Muted text color for secondary content.|-|Optional|
+|textOnPrimary|string \|undefined|Text color for content on primary background.|-|Optional|
+|overlay|string \|undefined|Overlay color for modal backdrops.|-|Optional|
+|switchTrack|string \|undefined|Toggle track color (off state).|-|Optional|
+|switchTrackActive|string \|undefined|Toggle track color (on state).|-|Optional|
+|switchThumb|string \|undefined|Toggle thumb color.|-|Optional|
+
+#### `dark` ColorTokens
+
+Dark mode color overrides.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|primary|string \|undefined|Primary brand/accent color for interactive elements.|-|Optional|
+|primaryHover|string \|undefined|Hover/active state for primary elements.|-|Optional|
+|surface|string \|undefined|Main background color for panels and containers.|-|Optional|
+|surfaceHover|string \|undefined|Hover state for surface elements.|-|Optional|
+|border|string \|undefined|Border color for containers and inputs.|-|Optional|
+|borderHover|string \|undefined|Hover state for bordered elements.|-|Optional|
+|text|string \|undefined|Primary text color for headings and body.|-|Optional|
+|textMuted|string \|undefined|Muted text color for secondary content.|-|Optional|
+|textOnPrimary|string \|undefined|Text color for content on primary background.|-|Optional|
+|overlay|string \|undefined|Overlay color for modal backdrops.|-|Optional|
+|switchTrack|string \|undefined|Toggle track color (off state).|-|Optional|
+|switchTrackActive|string \|undefined|Toggle track color (on state).|-|Optional|
+|switchThumb|string \|undefined|Toggle thumb color.|-|Optional|
+
+#### `typography` TypographyTokens
+
+Typography settings for text elements.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|fontFamily|string \|undefined|Font family for all components.|-|Optional|
+|fontSize|Object \|undefined|Font sizes for text hierarchy.|-|Optional|
+|fontWeight|Object \|undefined|Font weights for emphasis.|-|Optional|
+|lineHeight|Object \|undefined|Line heights for readability.|-|Optional|
+
+#### `spacing` SpacingTokens
+
+Spacing scale for internal padding and margins.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|xs|string \|undefined|@default '0.25rem' (4px)|-|Optional|
+|sm|string \|undefined|@default '0.5rem' (8px)|-|Optional|
+|md|string \|undefined|@default '1rem' (16px)|-|Optional|
+|lg|string \|undefined|@default '1.5rem' (24px)|-|Optional|
+|xl|string \|undefined|@default '2rem' (32px)|-|Optional|
+
+#### `radius` RadiusTokens
+
+Border radius scale for rounded corners.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|sm|string \|undefined|@default '0.25rem' (4px)|-|Optional|
+|md|string \|undefined|@default '0.5rem' (8px)|-|Optional|
+|lg|string \|undefined|@default '0.75rem' (12px)|-|Optional|
+|full|string \|undefined|@default '9999px'|-|Optional|
+
+#### `shadows` ShadowTokens
+
+Box shadow scale for depth and elevation.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|sm|string \|undefined|@default '0 1px 2px hsla(0, 0%, 0%, 0.05)'|-|Optional|
+|md|string \|undefined|@default '0 4px 12px hsla(0, 0%, 0%, 0.08)'|-|Optional|
+|lg|string \|undefined|@default '0 8px 24px hsla(0, 0%, 0%, 0.12)'|-|Optional|
+
+#### `motion` MotionTokens
+
+Animation and transition timing.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|duration|Object \|undefined|Duration presets for transitions.|-|Optional|
+|easing|string \|undefined|Default CSS easing function for general animation curves.|-|Optional|
+|easingOut|string \|undefined|CSS easing function for enter/exit animations. Use for modals, tooltips, dropdowns, and any element entering or exiting.|-|Optional|
+|easingInOut|string \|undefined|CSS easing function for on-screen movement. Use when elements already on screen need to move or morph.|-|Optional|
+|easingSpring|string \|undefined|CSS easing function with spring-like overshoot. Use for playful, bouncy animations.|-|Optional|
+
+#### `consentActions`
+
+Semantic button styling for consent actions.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|default|ConsentActionStyle \|undefined|-|-|Optional|
+|accept|ConsentActionStyle \|undefined|-|-|Optional|
+|reject|ConsentActionStyle \|undefined|-|-|Optional|
+|customize|ConsentActionStyle \|undefined|-|-|Optional|
+
+#### `slots` ComponentSlots
+
+Component-specific style overrides.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|consentBanner|SlotStyle \|undefined|Root wrapper for the consent banner portal content.|-|Optional|
+|consentBannerCard|SlotStyle \|undefined|Main card container for banner content and actions.|-|Optional|
+|consentBannerHeader|SlotStyle \|undefined|Header region containing title and description.|-|Optional|
+|consentBannerTitle|SlotStyle \|undefined|Banner title text element.|-|Optional|
+|consentBannerDescription|SlotStyle \|undefined|Banner description text element.|-|Optional|
+|consentBannerFooter|SlotStyle \|undefined|Footer container for banner action buttons.|-|Optional|
+|consentBannerFooterSubGroup|SlotStyle \|undefined|Nested button group inside the banner footer.|-|Optional|
+|consentBannerOverlay|SlotStyle \|undefined|Backdrop overlay rendered behind the banner when enabled.|-|Optional|
+|consentDialog|SlotStyle \|undefined|Root wrapper for the consent dialog modal.|-|Optional|
+|consentDialogCard|SlotStyle \|undefined|Main dialog card container.|-|Optional|
+|consentDialogHeader|SlotStyle \|undefined|Dialog header region containing title and description.|-|Optional|
+|consentDialogTitle|SlotStyle \|undefined|Dialog title text element.|-|Optional|
+|consentDialogDescription|SlotStyle \|undefined|Dialog description text element.|-|Optional|
+|consentDialogContent|SlotStyle \|undefined|Dialog content region (typically holds ConsentWidget).|-|Optional|
+|consentDialogFooter|SlotStyle \|undefined|Dialog footer container with actions/branding.|-|Optional|
+|consentDialogOverlay|SlotStyle \|undefined|Backdrop overlay rendered behind the dialog.|-|Optional|
+|consentWidget|SlotStyle \|undefined|Root wrapper for the consent widget/preferences panel.|-|Optional|
+|consentWidgetAccordion|SlotStyle \|undefined|Accordion region listing consent categories.|-|Optional|
+|consentWidgetFooter|SlotStyle \|undefined|Footer area for widget actions and links.|-|Optional|
+|consentWidgetBranding|SlotStyle \|undefined|Branding element rendered in the widget footer.|-|Optional|
+|frame|SlotStyle \|undefined|Frame wrapper used by blocking placeholders (e.g., iframe blocking).|-|Optional|
+|iabConsentBanner|SlotStyle \|undefined|Root wrapper for the IAB consent banner.|-|Optional|
+|iabConsentBannerCard|SlotStyle \|undefined|Main card container for IAB banner content.|-|Optional|
+|iabConsentBannerHeader|SlotStyle \|undefined|Header region for IAB banner title/description.|-|Optional|
+|iabConsentBannerFooter|SlotStyle \|undefined|Footer container for IAB banner actions.|-|Optional|
+|iabConsentBannerOverlay|SlotStyle \|undefined|Backdrop overlay rendered behind the IAB banner.|-|Optional|
+|iabConsentDialog|SlotStyle \|undefined|Root wrapper for the IAB consent dialog.|-|Optional|
+|iabConsentDialogCard|SlotStyle \|undefined|Main card container for IAB dialog content.|-|Optional|
+|iabConsentDialogHeader|SlotStyle \|undefined|Header region for IAB dialog title/description.|-|Optional|
+|iabConsentDialogFooter|SlotStyle \|undefined|Footer container for IAB dialog actions.|-|Optional|
+|iabConsentDialogOverlay|SlotStyle \|undefined|Backdrop overlay rendered behind the IAB dialog.|-|Optional|
+|buttonPrimary|SlotStyle \|undefined|Shared primary button style used across consent components.|-|Optional|
+|buttonSecondary|SlotStyle \|undefined|Shared secondary button style used across consent components.|-|Optional|
+|toggle|SlotStyle \|undefined|Shared toggle/switch style used for category controls.|-|Optional|

package/docs/styling/slots.md

@@ -0,0 +1,93 @@
+---
+title: Component Slots
+description: Target individual component parts with styles using the slot system - className strings or inline style objects.
+---
+## What are Slots?
+
+Slots let you target specific parts of consent components with styles. Each component is built from named "slots" (e.g., `consentBannerTitle`, `consentDialogFooter`) that you can style individually.
+
+## Using Slots
+
+Pass slot styles in the theme's `slots` object:
+
+```tsx
+const theme = {
+  slots: {
+    // String value = className
+    consentBannerTitle: 'text-xl font-bold text-gray-900',
+
+    // Object value = className + inline styles
+    consentBannerCard: {
+      className: 'rounded-xl shadow-lg',
+      style: { maxWidth: '600px' },
+    },
+  },
+} satisfies Theme;
+```
+
+## Slot Style Types
+
+Each slot accepts either a `string` (treated as className) or a `SlotStyle` object:
+
+```tsx
+// String: treated as className
+consentBannerTitle: 'my-custom-class'
+
+// Object: className + style + noStyle
+consentBannerTitle: {
+  className: 'my-custom-class',
+  style: { color: 'red', fontSize: '1.5rem' },
+  noStyle: false, // Set true to remove default styles for this slot
+}
+```
+
+## Available Slots
+
+Use the typed API reference below for the full slot list and descriptions. It stays in sync with the actual component slot surface.
+
+## API Reference
+
+### ComponentSlots
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|consentBanner|SlotStyle \|undefined|Root wrapper for the consent banner portal content.|-|Optional|
+|consentBannerCard|SlotStyle \|undefined|Main card container for banner content and actions.|-|Optional|
+|consentBannerHeader|SlotStyle \|undefined|Header region containing title and description.|-|Optional|
+|consentBannerTitle|SlotStyle \|undefined|Banner title text element.|-|Optional|
+|consentBannerDescription|SlotStyle \|undefined|Banner description text element.|-|Optional|
+|consentBannerFooter|SlotStyle \|undefined|Footer container for banner action buttons.|-|Optional|
+|consentBannerFooterSubGroup|SlotStyle \|undefined|Nested button group inside the banner footer.|-|Optional|
+|consentBannerOverlay|SlotStyle \|undefined|Backdrop overlay rendered behind the banner when enabled.|-|Optional|
+|consentDialog|SlotStyle \|undefined|Root wrapper for the consent dialog modal.|-|Optional|
+|consentDialogCard|SlotStyle \|undefined|Main dialog card container.|-|Optional|
+|consentDialogHeader|SlotStyle \|undefined|Dialog header region containing title and description.|-|Optional|
+|consentDialogTitle|SlotStyle \|undefined|Dialog title text element.|-|Optional|
+|consentDialogDescription|SlotStyle \|undefined|Dialog description text element.|-|Optional|
+|consentDialogContent|SlotStyle \|undefined|Dialog content region (typically holds ConsentWidget).|-|Optional|
+|consentDialogFooter|SlotStyle \|undefined|Dialog footer container with actions/branding.|-|Optional|
+|consentDialogOverlay|SlotStyle \|undefined|Backdrop overlay rendered behind the dialog.|-|Optional|
+|consentWidget|SlotStyle \|undefined|Root wrapper for the consent widget/preferences panel.|-|Optional|
+|consentWidgetAccordion|SlotStyle \|undefined|Accordion region listing consent categories.|-|Optional|
+|consentWidgetFooter|SlotStyle \|undefined|Footer area for widget actions and links.|-|Optional|
+|consentWidgetBranding|SlotStyle \|undefined|Branding element rendered in the widget footer.|-|Optional|
+|frame|SlotStyle \|undefined|Frame wrapper used by blocking placeholders (e.g., iframe blocking).|-|Optional|
+|iabConsentBanner|SlotStyle \|undefined|Root wrapper for the IAB consent banner.|-|Optional|
+|iabConsentBannerCard|SlotStyle \|undefined|Main card container for IAB banner content.|-|Optional|
+|iabConsentBannerHeader|SlotStyle \|undefined|Header region for IAB banner title/description.|-|Optional|
+|iabConsentBannerFooter|SlotStyle \|undefined|Footer container for IAB banner actions.|-|Optional|
+|iabConsentBannerOverlay|SlotStyle \|undefined|Backdrop overlay rendered behind the IAB banner.|-|Optional|
+|iabConsentDialog|SlotStyle \|undefined|Root wrapper for the IAB consent dialog.|-|Optional|
+|iabConsentDialogCard|SlotStyle \|undefined|Main card container for IAB dialog content.|-|Optional|
+|iabConsentDialogHeader|SlotStyle \|undefined|Header region for IAB dialog title/description.|-|Optional|
+|iabConsentDialogFooter|SlotStyle \|undefined|Footer container for IAB dialog actions.|-|Optional|
+|iabConsentDialogOverlay|SlotStyle \|undefined|Backdrop overlay rendered behind the IAB dialog.|-|Optional|
+|buttonPrimary|SlotStyle \|undefined|Shared primary button style used across consent components.|-|Optional|
+|buttonSecondary|SlotStyle \|undefined|Shared secondary button style used across consent components.|-|Optional|
+|toggle|SlotStyle \|undefined|Shared toggle/switch style used for category controls.|-|Optional|
+
+### SlotStyle
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|SlotStyle|SlotStyle|Type alias for SlotStyle|-|✅ Required|

package/docs/styling/tailwind.md

@@ -0,0 +1,115 @@
+---
+title: Tailwind CSS
+description: Use Tailwind CSS utility classes to style consent components via the slot system.
+---
+c15t works with Tailwind CSS out of the box. Use the `slots` theme option to apply Tailwind utility classes to any component part.
+
+## Setup
+
+Import the standard c15t stylesheet once at the root of your app:
+
+```tsx
+// React
+import '@c15t/react/styles.css';
+
+// Next.js
+import '@c15t/nextjs/styles.css';
+```
+
+### Tailwind v4
+
+Tailwind v4 automatically scans your source files. Declare c15t's layer order once in your global CSS so utilities stay last:
+
+```css
+@layer theme, base, components, c15t, utilities;
+@import "tailwindcss";
+```
+
+### Tailwind v3
+
+Keep Tailwind's directives in your app stylesheet, but wrap `@tailwind base` in a native `base` layer so c15t's `@layer c15t` rules can sit above Preflight:
+
+```css title="app/globals.css"
+@layer base, components, c15t;
+
+@layer base {
+  @tailwind base;
+}
+
+@tailwind components;
+@tailwind utilities;
+```
+
+Then add c15t's component paths to your `content` array:
+
+```js title="tailwind.config.js"
+module.exports = {
+  content: [
+    './src/**/*.{js,ts,jsx,tsx}',
+    './node_modules/@c15t/react/**/*.{js,mjs}',
+    './node_modules/@c15t/nextjs/**/*.{js,mjs}',
+  ],
+};
+```
+
+## Using Tailwind with Slots
+
+Apply Tailwind classes via the theme's `slots` object:
+
+```tsx
+import { type ReactNode } from 'react';
+import { type Theme, ConsentManagerProvider } from '@c15t/nextjs';
+
+const theme = {
+  slots: {
+    consentBanner: 'fixed bottom-0 inset-x-0 z-50',
+    consentBannerCard: 'mx-auto max-w-2xl rounded-t-2xl bg-white p-6 shadow-2xl',
+    consentBannerTitle: 'text-lg font-semibold text-gray-900',
+    consentBannerDescription: 'mt-2 text-sm text-gray-600',
+    consentBannerFooter: 'mt-4 flex flex-wrap gap-3',
+    buttonPrimary: 'rounded-full bg-indigo-600 px-6 py-2.5 text-sm font-medium text-white hover:bg-indigo-700',
+    buttonSecondary: 'rounded-full border border-gray-300 px-6 py-2.5 text-sm font-medium text-gray-700 hover:bg-gray-50',
+    toggle: 'data-[state=checked]:bg-indigo-600',
+  },
+} satisfies Theme;
+
+export function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider options={{ theme, mode: 'hosted', backendURL: '/api/c15t' }}>
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+## Dark Mode with Tailwind
+
+Combine Tailwind's dark mode with c15t's `dark` tokens:
+
+```tsx
+const theme = {
+  colors: {
+    primary: '#6366f1',
+    surface: '#ffffff',
+    text: '#1f2937',
+  },
+  dark: {
+    primary: '#818cf8',
+    surface: '#1f2937',
+    text: '#f9fafb',
+  },
+  slots: {
+    consentBannerCard: 'bg-white dark:bg-gray-900 shadow-lg dark:shadow-gray-900/30',
+    consentBannerTitle: 'text-gray-900 dark:text-gray-100',
+  },
+} satisfies Theme;
+```
+
+## Optional: noStyle Mode
+
+If you want Tailwind to own all layout and visual styling, use `noStyle: true`.
+
+> ℹ️ **Info:**
+> When using noStyle: true with Tailwind, you're responsible for all layout and visual styling. Start with slots first, then switch to noStyle only when you need full control.
+
+For full custom markup (not just styles), see [Headless Mode](../headless).