@c15t/react 2.0.0-rc.3 → 2.0.0-rc.5

package/docs/server-side.md

@@ -0,0 +1,153 @@
+---
+title: Server-Side Utilities
+description: Fetch consent data on the server for SSR hydration — eliminate the loading flash and improve performance.
+---
+The `@c15t/react/server` module provides utilities for fetching consent data on the server before rendering. This enables SSR hydration — consent state is available immediately on page load without a client-side fetch, eliminating the consent banner flash.
+
+> ℹ️ **Info:**
+> SSR hydration is part of the initialization flow. When SSR data is available, the client skips the API fetch entirely.
+
+```ts
+import {
+  fetchSSRData,
+  extractRelevantHeaders,
+  normalizeBackendURL,
+  validateBackendURL,
+} from '@c15t/react/server';
+```
+
+> ℹ️ **Info:**
+> If you're using Next.js, the @c15t/nextjs package wraps these utilities with automatic header resolution. See the Next.js docs for framework-specific usage.
+
+## fetchSSRData
+
+The primary function for fetching consent data on the server. It calls the c15t backend's `/init` endpoint with the user's request headers and returns the initial consent data.
+
+```ts
+import { fetchSSRData } from '@c15t/react/server';
+
+// In your server handler / page loader
+const ssrData = await fetchSSRData({
+  backendURL: 'https://your-instance.c15t.dev',
+  headers: request.headers,
+  debug: true,
+});
+```
+
+### Options
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|headers|Headers|Request headers from the framework. These should be the incoming request headers that contain geo-location information (cf-ipcountry, x-vercel-ip-country, etc.)|-|✅ Required|
+
+### Return Value
+
+Returns `SSRInitialData | undefined`. The data includes the init response (jurisdiction, translations, consent model) and GVL data when IAB is configured.
+
+### Passing SSR Data to the Provider
+
+Pass the result as a Promise to the provider's `ssrData` option:
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider, ConsentBanner, ConsentDialog } from '@c15t/react';
+import { fetchSSRData } from '@c15t/react/server';
+
+// Server component or page loader
+async function getSSRData(headers: Headers) {
+  return fetchSSRData({
+    backendURL: 'https://your-instance.c15t.dev',
+    headers,
+  });
+}
+
+export default function ConsentManager({
+  children,
+  ssrData,
+}: {
+  children: ReactNode;
+  ssrData: Promise<any>;
+}) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: 'https://your-instance.c15t.dev',
+        ssrData,
+      }}
+    >
+      <ConsentBanner />
+      <ConsentDialog />
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+## extractRelevantHeaders
+
+Extracts geo-location and forwarding headers from the incoming request. Supports headers from Cloudflare, Vercel, AWS CloudFront, and generic proxies.
+
+```ts
+import { extractRelevantHeaders } from '@c15t/react/server';
+
+const relevant = extractRelevantHeaders(request.headers);
+// Returns: { 'cf-ipcountry': 'DE', 'accept-language': 'de-DE', ... }
+```
+
+### Recognized Headers
+
+|Header|Source|Contains|
+|--|--|--|
+|`cf-ipcountry`|Cloudflare|Country code|
+|`x-vercel-ip-country`|Vercel|Country code|
+|`x-amz-cf-ipcountry`|AWS CloudFront|Country code|
+|`x-vercel-ip-country-region`|Vercel|Region code|
+|`accept-language`|Browser|Language preference|
+|`x-forwarded-host`|Proxy|Original host|
+|`x-forwarded-for`|Proxy|Client IP|
+
+## normalizeBackendURL
+
+Resolves a backend URL to an absolute URL. Absolute URLs are returned as-is. Relative URLs (starting with `/`) are resolved using the request's `Host` or `Referer` headers.
+
+```ts
+import { normalizeBackendURL } from '@c15t/react/server';
+
+// Absolute — returned as-is
+normalizeBackendURL('https://api.example.com/', headers);
+// → 'https://api.example.com'
+
+// Relative — resolved from headers
+normalizeBackendURL('/api/consent', headers);
+// → 'https://example.com/api/consent'
+```
+
+## validateBackendURL
+
+Validates and normalizes a URL without resolving relative paths. Useful for configuration validation.
+
+```ts
+import { validateBackendURL } from '@c15t/react/server';
+
+validateBackendURL('https://api.example.com/');
+// → { isAbsolute: true, normalizedURL: 'https://api.example.com' }
+
+validateBackendURL('/api/consent/');
+// → { isAbsolute: false, normalizedURL: '/api/consent' }
+```
+
+## Debugging SSR
+
+Use the [useSSRStatus](/docs/frameworks/react/hooks/use-ssr-status) hook on the client to verify SSR data was consumed:
+
+```tsx
+import { useSSRStatus } from '@c15t/react';
+
+function DebugSSR() {
+  const { ssrDataUsed, ssrSkippedReason } = useSSRStatus();
+
+  if (ssrDataUsed) return <span>SSR hydration successful</span>;
+  return <span>SSR skipped: {ssrSkippedReason ?? 'unknown'}</span>;
+}
+```

package/docs/styling/classnames.md

@@ -0,0 +1,84 @@
+---
+title: Class Names
+description: Style consent components using className props and per-slot className targeting via the theme.
+---
+## Component className
+
+All consent components accept a `className` prop:
+
+```tsx
+<ConsentBanner className="my-banner" />
+<ConsentDialog className="my-dialog" />
+<ConsentWidget className="my-widget" />
+```
+
+## 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;
+}
+```
+
+## noStyle Mode
+
+Use `noStyle` when you want to remove defaults and style from scratch:
+
+```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;
+```
+
+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/react';
+
+function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: 'https://your-instance.c15t.dev',
+        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/react';
+
+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.
+
+```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\` (default: \`hsl(0, 0%, 100%)\`)|-|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;
+}
+```