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

package/docs/styling/classnames.md

@@ -0,0 +1,92 @@
+---
+title: Class Names
+description: Style consent components using className props and per-slot className targeting via the theme.
+---
+## 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/styling/color-scheme.md

@@ -0,0 +1,82 @@
+---
+title: Color Scheme
+description: Support light mode, dark mode, and system preference detection in consent components.
+---
+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
+
+## Configuration
+
+Set the color scheme on the provider:
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/nextjs';
+
+function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        colorScheme: 'system', // 'light' | 'dark' | 'system'
+        theme: {
+          colors: {
+            primary: '#6366f1',
+            surface: '#ffffff',
+            text: '#1f2937',
+          },
+          dark: {
+            primary: '#818cf8',
+            surface: '#1f2937',
+            text: '#f9fafb',
+          },
+        },
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+## useColorScheme Hook
+
+For programmatic control over the color scheme:
+
+```tsx
+import { useColorScheme } from '@c15t/nextjs';
+
+function ThemeToggle() {
+  // Pass the desired scheme - 'light', 'dark', 'system', or null (disable)
+  useColorScheme('system');
+}
+```
+
+|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/styling/css-variables.md

@@ -0,0 +1,92 @@
+---
+title: CSS Variables
+description: Reference for all --c15t-* CSS custom properties generated by the theme system.
+---
+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
+
+### ThemeCSSVariables
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|--c15t-primary|string \|undefined|\`colors.primary\` (default: \`hsl(228, 100%, 60%)\`)|-|Optional|
+|--c15t-primary-hover|string \|undefined|\`colors.primaryHover\` (default: \`hsl(228, 100%, 55%)\`)|-|Optional|
+|--c15t-surface|string \|undefined|\`colors.surface\` (default: \`hsl(0, 0%, 100%)\`)|-|Optional|
+|--c15t-surface-hover|string \|undefined|\`colors.surfaceHover\` (default: \`hsl(0, 0%, 98%)\`)|-|Optional|
+|--c15t-border|string \|undefined|\`colors.border\` (default: \`hsl(0, 0%, 90%)\`)|-|Optional|
+|--c15t-border-hover|string \|undefined|\`colors.borderHover\` (default: \`hsl(0, 0%, 85%)\`)|-|Optional|
+|--c15t-text|string \|undefined|\`colors.text\` (default: \`hsl(0, 0%, 10%)\`)|-|Optional|
+|--c15t-text-muted|string \|undefined|\`colors.textMuted\` (default: \`hsl(0, 0%, 40%)\`)|-|Optional|
+|--c15t-text-on-primary|string \|undefined|\`colors.textOnPrimary\` (auto-derived from \`colors.primary\` when omitted)|-|Optional|
+|--c15t-overlay|string \|undefined|\`colors.overlay\` (default: \`hsla(0, 0%, 0%, 0.5)\`)|-|Optional|
+|--c15t-switch-track|string \|undefined|\`colors.switchTrack\` (default: \`hsl(0, 0%, 85%)\`)|-|Optional|
+|--c15t-switch-track-active|string \|undefined|\`colors.switchTrackActive\` (default: \`hsl(228, 100%, 60%)\`)|-|Optional|
+|--c15t-switch-thumb|string \|undefined|\`colors.switchThumb\` (default: \`hsl(0, 0%, 100%)\`)|-|Optional|
+|--c15t-font-family|string \|undefined|\`typography.fontFamily\` (default: \`system-ui, -apple-system, sans-serif\`)|-|Optional|
+|--c15t-font-size-sm|string \|undefined|\`typography.fontSize.sm\` (default: \`0.875rem\`)|-|Optional|
+|--c15t-font-size-base|string \|undefined|\`typography.fontSize.base\` (default: \`1rem\`)|-|Optional|
+|--c15t-font-size-lg|string \|undefined|\`typography.fontSize.lg\` (default: \`1.125rem\`)|-|Optional|
+|--c15t-font-weight-normal|string \|undefined|\`typography.fontWeight.normal\` (default: \`400\`)|-|Optional|
+|--c15t-font-weight-medium|string \|undefined|\`typography.fontWeight.medium\` (default: \`500\`)|-|Optional|
+|--c15t-font-weight-semibold|string \|undefined|\`typography.fontWeight.semibold\` (default: \`600\`)|-|Optional|
+|--c15t-line-height-tight|string \|undefined|\`typography.lineHeight.tight\` (default: \`1.25\`)|-|Optional|
+|--c15t-line-height-normal|string \|undefined|\`typography.lineHeight.normal\` (default: \`1.5\`)|-|Optional|
+|--c15t-line-height-relaxed|string \|undefined|\`typography.lineHeight.relaxed\` (default: \`1.75\`)|-|Optional|
+|--c15t-space-xs|string \|undefined|\`spacing.xs\` (default: \`0.25rem\`)|-|Optional|
+|--c15t-space-sm|string \|undefined|\`spacing.sm\` (default: \`0.5rem\`)|-|Optional|
+|--c15t-space-md|string \|undefined|\`spacing.md\` (default: \`1rem\`)|-|Optional|
+|--c15t-space-lg|string \|undefined|\`spacing.lg\` (default: \`1.5rem\`)|-|Optional|
+|--c15t-space-xl|string \|undefined|\`spacing.xl\` (default: \`2rem\`)|-|Optional|
+|--c15t-radius-sm|string \|undefined|\`radius.sm\` (default: \`0.25rem\`)|-|Optional|
+|--c15t-radius-md|string \|undefined|\`radius.md\` (default: \`0.5rem\`)|-|Optional|
+|--c15t-radius-lg|string \|undefined|\`radius.lg\` (default: \`0.75rem\`)|-|Optional|
+|--c15t-radius-full|string \|undefined|\`radius.full\` (default: \`9999px\`)|-|Optional|
+|--c15t-shadow-sm|string \|undefined|\`shadows.sm\` (default: \`0 1px 2px hsla(0, 0%, 0%, 0.05)\`)|-|Optional|
+|--c15t-shadow-md|string \|undefined|\`shadows.md\` (default: \`0 4px 12px hsla(0, 0%, 0%, 0.08)\`)|-|Optional|
+|--c15t-shadow-lg|string \|undefined|\`shadows.lg\` (default: \`0 8px 24px hsla(0, 0%, 0%, 0.12)\`)|-|Optional|
+|--c15t-duration-fast|string \|undefined|\`motion.duration.fast\` (default: \`100ms\`)|-|Optional|
+|--c15t-duration-normal|string \|undefined|\`motion.duration.normal\` (default: \`200ms\`)|-|Optional|
+|--c15t-duration-slow|string \|undefined|\`motion.duration.slow\` (default: \`300ms\`)|-|Optional|
+|--c15t-easing|string \|undefined|\`motion.easing\` (default: \`cubic-bezier(0.4, 0, 0.2, 1)\`)|-|Optional|
+|--c15t-easing-out|string \|undefined|\`motion.easingOut\` (default: \`cubic-bezier(0.215, 0.61, 0.355, 1)\`)|-|Optional|
+|--c15t-easing-in-out|string \|undefined|\`motion.easingInOut\` (default: \`cubic-bezier(0.645, 0.045, 0.355, 1)\`)|-|Optional|
+|--c15t-easing-spring|string \|undefined|\`motion.easingSpring\` (default: \`cubic-bezier(0.34, 1.56, 0.64, 1)\`)|-|Optional|
+
+## 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;
+}
+```