@c15t/react 2.0.4 → 2.2.0-canary-20260727202135

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).

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

@@ -0,0 +1,155 @@
+---
+title: Tokens
+description: Reference page for tokens.
+group: reference
+---
+## Color Tokens
+
+Color tokens define the palette for all consent components. Set `colors` for light mode and `dark` for dark mode overrides.
+
+When `textOnPrimary` is omitted, c15t derives it automatically from `primary` to keep text readable on primary-filled surfaces such as stock branding tags and buttons. Set `textOnPrimary` explicitly when you need a specific foreground color.
+
+```tsx
+const theme = {
+  colors: {
+    primary: '#6366f1',
+    primaryHover: '#4f46e5',
+    surface: '#ffffff',
+    surfaceHover: '#f9fafb',
+    border: '#e5e7eb',
+    borderHover: '#d1d5db',
+    text: '#1f2937',
+    textMuted: '#6b7280',
+    textOnPrimary: '#ffffff',
+    overlay: 'rgba(0, 0, 0, 0.5)',
+    switchTrack: '#d1d5db',
+    switchTrackActive: '#6366f1',
+    switchThumb: '#ffffff',
+  },
+  dark: {
+    primary: '#818cf8',
+    surface: '#1f2937',
+    text: '#f9fafb',
+    textMuted: '#9ca3af',
+    border: '#374151',
+  },
+} satisfies Theme;
+```
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`ColorTokens\`|
+|Source Path|\`./packages/ui/src/theme/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "ColorTokens" 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.\*
+
+## Typography Tokens
+
+Control font family, sizes, weights, and line heights.
+
+```tsx
+const theme = {
+  typography: {
+    fontFamily: 'Inter, system-ui, sans-serif',
+    fontSize: { sm: '0.875rem', base: '1rem', lg: '1.125rem' },
+    fontWeight: { normal: 400, medium: 500, semibold: 600 },
+    lineHeight: { tight: '1.25', normal: '1.5', relaxed: '1.75' },
+  },
+} satisfies Theme;
+```
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`TypographyTokens\`|
+|Source Path|\`./packages/ui/src/theme/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "TypographyTokens" 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.\*
+
+## Spacing Tokens
+
+Five-step scale for internal padding, margins, and gaps.
+
+```tsx
+const theme = {
+  spacing: {
+    xs: '0.25rem',  // 4px
+    sm: '0.5rem',   // 8px
+    md: '1rem',     // 16px
+    lg: '1.5rem',   // 24px
+    xl: '2rem',     // 32px
+  },
+} satisfies Theme;
+```
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`SpacingTokens\`|
+|Source Path|\`./packages/ui/src/theme/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "SpacingTokens" 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.\*
+
+## Radius Tokens
+
+Border radius scale for rounded corners.
+
+```tsx
+const theme = {
+  radius: {
+    sm: '0.25rem',  // 4px
+    md: '0.5rem',   // 8px
+    lg: '0.75rem',  // 12px
+    full: '9999px', // Pill shape
+  },
+} satisfies Theme;
+```
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`RadiusTokens\`|
+|Source Path|\`./packages/ui/src/theme/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "RadiusTokens" 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.\*
+
+## Shadow Tokens
+
+Box shadow scale for depth and elevation.
+
+```tsx
+const theme = {
+  shadows: {
+    sm: '0 1px 2px hsla(0, 0%, 0%, 0.05)',
+    md: '0 4px 12px hsla(0, 0%, 0%, 0.08)',
+    lg: '0 8px 24px hsla(0, 0%, 0%, 0.12)',
+  },
+} satisfies Theme;
+```
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`ShadowTokens\`|
+|Source Path|\`./packages/ui/src/theme/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "ShadowTokens" 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.\*
+
+## Motion Tokens
+
+Animation duration and easing presets.
+
+```tsx
+const theme = {
+  motion: {
+    duration: { fast: '100ms', normal: '200ms', slow: '300ms' },
+    easing: 'cubic-bezier(0.4, 0, 0.2, 1)',
+    easingOut: 'cubic-bezier(0.215, 0.61, 0.355, 1)',
+    easingInOut: 'cubic-bezier(0.645, 0.045, 0.355, 1)',
+    easingSpring: 'cubic-bezier(0.34, 1.56, 0.64, 1)',
+  },
+} satisfies Theme;
+```
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`MotionTokens\`|
+|Source Path|\`./packages/ui/src/theme/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "MotionTokens" 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/troubleshooting.md

@@ -0,0 +1,82 @@
+---
+title: Troubleshooting
+description: Reference page for troubleshooting.
+group: reference
+---
+## "Provider not found" Error
+
+**Symptom:** `useConsentManager must be used within a ConsentManagerProvider` error.
+
+**Fix:** Ensure the component calling `useConsentManager()` (or any c15t hook) is rendered inside a `ConsentManagerProvider`:
+
+```tsx
+// Wrong — hook is outside the provider
+function App() {
+  const { consents } = useConsentManager(); // throws
+  return <ConsentManagerProvider options={...}>...</ConsentManagerProvider>;
+}
+
+// Correct — hook is inside the provider
+function App() {
+  return (
+    <ConsentManagerProvider options={...}>
+      <MyComponent /> {/* useConsentManager works here */}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+## Banner Doesn't Show
+
+**Possible causes:**
+
+1. **Opt-out jurisdiction** — In CCPA/opt-out regions, the banner is not shown because tracking is allowed by default. Check `model` from `useConsentManager()` — if it's `'opt-out'`, the banner is intentionally hidden.
+
+2. **Consent already given** — If the user has already made a consent choice, the banner won't reappear. Clear cookies or use `resetConsents()` to test again.
+
+3. **`activeUI` is `'none'`** — Something is explicitly setting `activeUI` to `'none'`. Check the DevTools panel for the current consent state.
+
+4. **Backend not responding** — In `'c15t'` mode, the banner waits for the backend `/init` response. Check the Network tab for failed requests to your `backendURL`.
+
+```tsx
+// Debug: check what the consent manager sees
+const { activeUI, model, isLoadingConsentInfo } = useConsentManager();
+console.log({ activeUI, model, isLoadingConsentInfo });
+```
+
+## Consent Not Persisting
+
+**Symptom:** Consent is lost after page reload.
+
+**Possible causes:**
+
+1. **Incognito/private mode** — Some browsers restrict cookie storage in private browsing.
+
+2. **Cookie settings** — In `'offline'` mode, consent is stored in cookies. Ensure cookies are not being blocked by browser settings or extensions.
+
+3. **Different domains** — Cookies are domain-scoped. If your dev server uses a different domain than production, consent won't carry over.
+
+4. **Backend errors** — In `'c15t'` mode, check that the backend is saving consent successfully. Enable `debug: true` in provider options to see detailed logs.
+
+## Scripts Not Loading
+
+**Symptom:** Third-party scripts configured in the `scripts` option don't load after consent is granted.
+
+**Checklist:**
+
+1. **Wrong category name** — The `category` on the script must match one of the `consentCategories` names. For example, `'measurement'` not `'analytics'`.
+
+2. **Consent condition not met** — Use `has('measurement')` to verify the category is actually consented.
+
+3. **Script error** — Check the browser DevTools Console for script loading errors. The `onError` callback can help debug:
+
+```tsx
+{
+  id: 'analytics',
+  src: 'https://...',
+  category: 'measurement',
+  onError: ({ error }) => console.error('Script failed:', error),
+}
+```
+
+4. **Ad blocker** — Browser extensions may block the script regardless of consent. The `anonymizeId` option (default: `true`) helps avoid pattern-based blocking.