@c15t/nextjs 2.1.0 → 2.2.1

package/docs/shared/react/styling/classnames.md

@@ -0,0 +1,93 @@
+---
+title: Classnames
+description: Reference page for classnames.
+group: reference
+---
+## Prefer Slots for Stock Components
+
+There is no single top-level `className` contract across every pre-built consent component.
+
+For the stock `ConsentBanner`, `ConsentDialog`, and `ConsentWidget`, prefer `theme.slots` first. That keeps the markup intact and lets you target the exact part you need.
+
+## Per-Slot className
+
+Target individual component parts via the theme's `slots` object. Each slot accepts a string (className) or an object with `className` and `style`:
+
+```tsx
+const theme = {
+  slots: {
+    consentBannerTitle: 'text-xl font-semibold',
+    consentBannerDescription: 'text-sm text-gray-600',
+    consentBannerFooter: 'flex gap-3',
+    buttonPrimary: 'rounded-full px-6',
+  },
+} satisfies Theme;
+```
+
+## Combining with CSS Modules
+
+```tsx
+import styles from './consent.module.css';
+
+const theme = {
+  slots: {
+    consentBannerCard: styles.bannerCard,
+    consentBannerTitle: styles.bannerTitle,
+    buttonPrimary: styles.primaryButton,
+  },
+} satisfies Theme;
+```
+
+```css title="consent.module.css"
+.bannerCard {
+  backdrop-filter: blur(12px);
+  background: rgba(255, 255, 255, 0.9);
+}
+
+.bannerTitle {
+  font-size: 1.25rem;
+  font-weight: 700;
+}
+
+.primaryButton {
+  border-radius: 9999px;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+```
+
+## When to Use Raw className
+
+Use raw className-level styling when:
+
+* your styling system is already class-driven
+* tokens are too broad for the change
+* slots already identify the correct element
+
+If the request is "make the banner footer darker", prefer `theme.colors.surfaceHover` first. If the request is "add a border and spacing only to the footer", prefer `theme.slots.consentBannerFooter`.
+
+## Advanced: `noStyle`
+
+Use `noStyle` only when you want to remove defaults and style from scratch while still keeping c15t's component structure:
+
+```tsx
+{/* Remove all styles from a specific component */}
+<ConsentBanner noStyle />
+
+{/* Remove all styles globally */}
+<ConsentManagerProvider options={{ noStyle: true, ... }}>
+```
+
+You can also set `noStyle` per-slot:
+
+```tsx
+const theme = {
+  slots: {
+    consentBannerCard: { noStyle: true, className: 'my-custom-card' },
+  },
+} satisfies Theme;
+```
+
+Treat `noStyle` as an advanced escape hatch. Do not jump to it just because a token or slot needs debugging.
+
+For full custom markup and behavior, continue to [Headless Mode](../headless).

package/docs/shared/react/styling/color-scheme.md

@@ -0,0 +1,35 @@
+---
+title: Color Scheme
+description: Reference page for color scheme.
+group: reference
+---
+c15t supports light and dark mode through the theme's `colors` and `dark` token groups. The active color scheme is determined by one of three methods:
+
+1. **Explicit setting** via the `colorScheme` option
+2. **CSS class detection** - c15t checks for `.dark` on the document element
+3. **System preference** - matches `prefers-color-scheme` media query
+
+|Value|Behavior|
+|--|--|
+|`'light'`|Force light mode|
+|`'dark'`|Force dark mode|
+|`'system'`|Follow `prefers-color-scheme` media query|
+|`null`|Disable - c15t won't manage color scheme|
+
+## How Dark Mode Works
+
+When dark mode is active, c15t applies the `dark` token values as CSS variable overrides. Only tokens specified in `dark` are overridden - unset tokens fall back to the `colors` values. This also applies to `textOnPrimary`: if you omit it, c15t derives a readable foreground from the active `primary` color in that scheme.
+
+```tsx
+const theme = {
+  colors: {
+    surface: '#ffffff',     // Light mode
+    text: '#1f2937',        // Light mode
+  },
+  dark: {
+    surface: '#1f2937',     // Dark mode override
+    text: '#f9fafb',        // Dark mode override
+    // primary is NOT set - inherits from colors.primary
+  },
+} satisfies Theme;
+```

package/docs/shared/react/styling/css-variables.md

@@ -0,0 +1,53 @@
+---
+title: CSS Variables
+description: Reference page for css variables.
+group: reference
+---
+Every theme token is converted to a `--c15t-*` CSS custom property at runtime. You can override these variables in your stylesheet without using the JavaScript theme API.
+
+## Variable Reference
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`ThemeCSSVariables\`|
+|Source Path|\`./packages/ui/src/theme/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "ThemeCSSVariables" from "./packages/ui/src/theme/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+## Overriding Variables
+
+Override in your stylesheet:
+
+```css
+:root {
+  --c15t-primary: #8b5cf6;
+  --c15t-surface: #fafafa;
+  --c15t-radius-md: 1rem;
+}
+
+/* Dark mode overrides */
+.dark,
+.c15t-dark {
+  --c15t-primary: #a78bfa;
+  --c15t-surface: #18181b;
+  --c15t-text: #fafafa;
+}
+```
+
+## Scoped Overrides
+
+Target specific components by scoping variables:
+
+```tsx
+<div className="checkout-consent">
+  <ConsentBanner />
+</div>
+```
+
+```css
+/* Only affect c15t components inside .checkout-consent */
+.checkout-consent {
+  --c15t-surface: #f0f9ff;
+  --c15t-radius-lg: 1.5rem;
+}
+```

package/docs/shared/react/styling/overview.md

@@ -0,0 +1,261 @@
+---
+title: Overview
+description: Reference page for overview.
+group: reference
+---
+c15t's theming system gives you multiple levels of control, but most customization should stay inside the pre-built components.
+
+Start with the lowest-power tool that solves the problem:
+
+1. **Pre-built component APIs** — provider options and component props such as `layout`, `direction`, `primaryButton`, `legalLinks`, and `theme.consentActions`
+2. **Design tokens** — global colors, typography, spacing, radius, shadows, and motion
+3. **Slots** — targeted styling for specific parts such as the banner card, footer, or title
+4. **CSS variables or className-level overrides** — when you need to integrate with external CSS systems
+5. **Compound components** — when you must rearrange markup while still using c15t primitives
+6. **`noStyle`** — when you want c15t structure but you need to own all visual styling
+7. **Headless** — when you want fully custom markup and behavior
+
+Keep styling and escalation as separate decisions:
+
+* If you are still using the stock banner, dialog, or widget, stay with props, tokens, and slots.
+* Escalate to compound components, `noStyle`, or headless only when the structure or behavior itself must change.
+
+## Styling Approaches
+
+|Approach|Control|Use When|
+|--|--|--|
+|**Component and provider APIs**|High|Reordering actions, changing button emphasis, configuring links, hiding branding, changing copy via `i18n`|
+|**Tokens**|High|Changing global colors, typography, spacing, radius, shadows, or motion|
+|**Slots**|Medium|Targeting specific component parts (for example `consentBannerFooter` or `consentDialogCard`)|
+|**CSS variables / className**|Medium|Integrating with an existing stylesheet or utility classes after tokens and slots|
+|**Compound components**|Structure|Rearranging existing c15t primitives without going fully custom|
+|**noStyle**|Full visuals|Keeping c15t structure but replacing all visual defaults|
+|**Headless**|Full|Replacing both markup and behavior|
+
+## Styling Inside Pre-Built Components
+
+Start here before you consider compound components or headless mode.
+
+### 1. Provider and component configuration
+
+Use the stock APIs first:
+
+* `layout`, `direction`, and `primaryButton` for banner action arrangement
+* `legalLinks` for link visibility
+* `hideBranding` and `showTrigger` for dialog and widget behavior
+* `theme.consentActions` for stock banner and dialog button treatment
+* `i18n` on `ConsentManagerProvider` for copy changes
+
+```tsx
+<ConsentBanner layout={['customize', ['reject', 'accept']]} primaryButton="accept" />
+```
+
+### 2. Design tokens
+
+Set global values for colors, typography, spacing, radius, shadows, and motion:
+
+```tsx
+options={{ theme: { colors: { primary: '#6366f1' } } }}
+```
+
+Use tokens first when the change is semantic:
+
+* Banner card background -> `theme.colors.surface`
+* Banner footer background -> `theme.colors.surfaceHover`
+* Shared copy color -> `theme.colors.text` and `theme.colors.textMuted`
+* Primary-filled surfaces such as stock branding tags and filled actions -> `theme.colors.primary` with `theme.colors.textOnPrimary` as the matching foreground override
+
+```tsx
+options={{
+  theme: {
+    colors: {
+      surface: '#ffffff',
+      surfaceHover: '#f6f3ee',
+    },
+  },
+}}
+```
+
+If you set `theme.colors.primary` but omit `theme.colors.textOnPrimary`, c15t derives a readable foreground automatically. Add `textOnPrimary` only when you need to force a specific branded foreground color.
+
+### 3. Component slots
+
+Target specific component parts via the `slots` object:
+
+```tsx
+options={{
+  theme: {
+    slots: {
+      consentBannerCard: 'rounded-[28px] shadow-xl',
+      consentBannerFooter: 'border-t border-black/10',
+      consentBannerTitle: 'tracking-tight',
+    },
+  },
+}}
+```
+
+Use slots when the component part is right but the local styling needs adjustment.
+
+### 4. CSS variables and className-level overrides
+
+Override `--c15t-*` custom properties in your stylesheet or attach classes through slots when your app styling is driven externally.
+
+Reach for this after tokens and slots, not before.
+
+```tsx
+options={{
+  theme: {
+    slots: {
+      consentBannerFooter: 'bg-[var(--banner-footer)]',
+    },
+  },
+}}
+```
+
+## Escalating Beyond Pre-Built Components
+
+Only move up this ladder when the lower rung cannot satisfy the request.
+
+### 5. Compound components
+
+Use compound components when you need to rearrange existing c15t primitives:
+
+```tsx
+<ConsentBanner.Root>
+  <ConsentBanner.Card>
+    <ConsentBanner.Header>
+      <ConsentBanner.Title />
+      <ConsentBanner.Description />
+    </ConsentBanner.Header>
+    <ConsentBanner.Footer>
+      <ConsentBanner.CustomizeButton />
+      <ConsentBanner.FooterSubGroup>
+        <ConsentBanner.RejectButton />
+        <ConsentBanner.AcceptButton />
+      </ConsentBanner.FooterSubGroup>
+    </ConsentBanner.Footer>
+  </ConsentBanner.Card>
+</ConsentBanner.Root>
+```
+
+### 6. `noStyle`
+
+Use `noStyle` only when the c15t structure is still correct but you want to replace all visual defaults:
+
+```tsx
+<ConsentBanner noStyle />
+```
+
+### 7. Headless
+
+Go headless only when you are replacing both markup and behavior. For that path, continue to [Headless Mode](../headless).
+
+## Common Styling Tasks
+
+### Change the banner footer background
+
+```tsx
+options={{
+  theme: {
+    colors: {
+      surfaceHover: '#f6f3ee',
+    },
+  },
+}}
+```
+
+Use `theme.colors.surfaceHover` before trying raw CSS.
+
+### Change the banner card background
+
+```tsx
+options={{
+  theme: {
+    colors: {
+      surface: '#fffdf8',
+    },
+  },
+}}
+```
+
+Use `theme.colors.surface` before overriding banner CSS variables directly.
+
+### Tweak the banner card, footer, or title styling without changing markup
+
+```tsx
+options={{
+  theme: {
+    slots: {
+      consentBannerCard: 'rounded-[28px] shadow-xl',
+      consentBannerFooter: 'border-t border-black/10 px-6',
+      consentBannerTitle: 'text-xl tracking-tight',
+    },
+  },
+}}
+```
+
+### Change stock 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`.
+
+### Change banner copy without replacing the component
+
+```tsx
+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',
+        },
+      },
+    },
+  },
+}}
+```
+
+### Enable dark mode safely
+
+```tsx
+options={{
+  colorScheme: 'system',
+  theme: {
+    colors: { surface: '#ffffff', text: '#1f2937' },
+    dark: { surface: '#111827', text: '#f9fafb' },
+  },
+}}
+```
+
+> ℹ️ **Info:**
+> If a token change does not show up where you expect, check how that component maps tokens to CSS variables before escalating. For example, the stock banner footer background comes from colors.surfaceHover, not a separate footer token.
+>
+> ⚠️ **Warning:**
+> Do not jump to CSS overrides or !important because a token did not appear to work at first glance.noStyle: true removes layout and visual defaults. Treat it as an advanced opt-out, not a normal theming step.Headless mode is for replacing markup and behavior, not for styling-only requests.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
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`Theme\`|
+|Source Path|\`./packages/ui/src/theme/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "Theme" from "./packages/ui/src/theme/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/shared/react/styling/slots.md

@@ -0,0 +1,93 @@
+---
+title: Slots
+description: Reference page for slots.
+group: reference
+---
+## What are Slots?
+
+Slots let you target specific parts of consent components with styles. Each component is built from named slots such as `consentBannerTitle` and `consentDialogTag`.
+
+Use slots after the stock component APIs and design tokens:
+
+* If the change is semantic, prefer tokens first. For example, the stock banner footer background comes from `theme.colors.surfaceHover`.
+* If the component part is correct but you need a local tweak, use a slot.
+
+Common banner slot choices:
+
+* `consentBannerCard` for card radius, shadow, width, and local background treatment
+* `consentBannerFooter` for spacing, borders, and local footer styling
+* `consentBannerTitle` for title typography
+* `buttonPrimary` and `buttonSecondary` for shared button classes
+
+## Using Slots
+
+Pass slot styles in the theme's `slots` object:
+
+```tsx
+const theme = {
+  slots: {
+    consentBannerFooter: 'border-t border-black/10 px-6',
+    consentBannerTitle: 'text-xl font-bold tracking-tight',
+
+    // 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
+consentBannerFooter: {
+  className: 'border-t border-black/10',
+  style: { paddingBlock: '1rem' },
+  noStyle: false, // Set true only when you want to remove this slot's default styling
+}
+```
+
+`noStyle` on a slot is an advanced escape hatch. Start with className and style overrides first.
+
+## Example: Style the stock banner without changing markup
+
+```tsx
+const theme = {
+  colors: {
+    surface: '#fffdf8',
+    surfaceHover: '#f6f3ee',
+  },
+  slots: {
+    consentBannerCard: 'rounded-[28px] shadow-xl',
+    consentBannerFooter: 'border-t border-black/10 px-6',
+    consentBannerTitle: 'tracking-tight',
+  },
+} satisfies Theme;
+```
+
+## 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
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`ComponentSlots\`|
+|Source Path|\`./packages/ui/src/theme/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "ComponentSlots" from "./packages/ui/src/theme/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`SlotStyle\`|
+|Source Path|\`./packages/ui/src/theme/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "SlotStyle" from "./packages/ui/src/theme/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/shared/react/styling/stylesheet-entrypoint.md

@@ -0,0 +1,8 @@
+---
+title: Stylesheet Entrypoint
+description: Reference page for stylesheet entrypoint.
+group: reference
+---
+Keeping the c15t stylesheet in your global CSS entrypoint makes layer and cascade order explicit. JS/TSX side-effect imports can load in a different order across framework and Tailwind tooling, which makes style regressions harder to debug.
+
+With Tailwind v4, keep c15t at the end of the top-level `@import` block so Fumadocs, `tw-animate-css`, and other preset imports do not override c15t theme tokens.

package/docs/shared/react/styling/tailwind.md

@@ -0,0 +1,88 @@
+---
+title: Tailwind
+description: Reference page for tailwind.
+group: reference
+---
+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 in your app-level CSS entrypoint:
+
+```css
+/* React: src/index.css */
+@import "@c15t/react/styles.css";
+
+/* Next.js: app/globals.css */
+@import "@c15t/nextjs/styles.css";
+```
+
+Keeping the c15t stylesheet in your global CSS entrypoint makes layer and cascade order explicit. JS/TSX side-effect imports can load in a different order across framework and Tailwind tooling, which makes style regressions harder to debug.
+
+With Tailwind v4, keep c15t at the end of the top-level `@import` block so Fumadocs, `tw-animate-css`, and other preset imports do not override c15t theme tokens.
+
+### Tailwind v4
+
+Tailwind v4 automatically scans your source files. Import Tailwind normally, then keep the c15t stylesheet last in the top-level `@import` block so Fumadocs, `tw-animate-css`, or other preset styles load first. c15t component styles join Tailwind's `components` layer automatically, so no extra c15t-specific layer declaration is needed:
+
+```css title="src/index.css"
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "@c15t/react/styles.css";
+```
+
+```css title="app/globals.css"
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "@c15t/nextjs/styles.css";
+```
+
+### Tailwind v3
+
+Import the Tailwind 3-compatible c15t stylesheet after `@tailwind components;` and before `@tailwind utilities;`:
+
+```css title="src/index.css"
+@tailwind base;
+@tailwind components;
+@import "@c15t/react/styles.tw3.css";
+@tailwind utilities;
+```
+
+```css title="app/globals.css"
+@tailwind base;
+@tailwind components;
+@import "@c15t/nextjs/styles.tw3.css";
+@tailwind utilities;
+```
+
+## 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).