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

package/docs/server-side.md

@@ -0,0 +1,171 @@
+---
+title: Server-Side Data Fetching
+description: Pre-fetch consent data in Server Components with fetchInitialData — eliminate the loading flash and enable streaming.
+---
+The `@c15t/nextjs` package provides `fetchInitialData`, a server-side function that fetches consent data 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 { fetchInitialData } from '@c15t/nextjs';
+```
+
+## fetchInitialData
+
+The primary function for fetching consent data on the server. It calls the c15t backend's `/init` endpoint with the user's request headers (resolved automatically from `next/headers`) and returns the initial consent data.
+
+```ts title="app/layout.tsx"
+import { fetchInitialData } from '@c15t/nextjs';
+
+// In a Server Component — do NOT await
+const ssrData = fetchInitialData({
+  backendURL: '/api/c15t',
+  debug: process.env.NODE_ENV === 'development',
+});
+```
+
+> ℹ️ **Info:**
+> Do not await fetchInitialData() in Server Components. Pass the Promise directly to your client component so Next.js can stream the page while the consent data loads in parallel.
+>
+> ℹ️ **Info:**
+> Need fully static routes? Use C15tPrefetch in your layout and getPrefetchedInitialData() in your client provider instead of fetchInitialData(). See Optimization.
+
+### How Streaming Works
+
+The diagram below shows how the prefetch avoids blocking the page render. The server fires the `/init` request and immediately starts streaming HTML — the resolved consent data is sent as a later chunk once the backend responds.
+
+```mermaid
+sequenceDiagram
+    participant SC as Server Component
+    participant NR as Next.js Runtime
+    participant BR as Browser
+    participant BE as c15t Backend
+
+    SC->>BE: fetchInitialData() → GET /init
+    Note right of SC: Returns a Promise - (not awaited)
+    SC->>NR: Render page tree - (Promise passed as prop)
+    NR->>BR: Stream initial HTML
+    BR->>BR: Hydrate — no consent data yet
+
+    BE-->>NR: /init response resolves
+    NR->>BR: Stream resolved data chunk
+    BR->>BR: Provider receives SSR data - skips client-side /init fetch
+```
+
+### Options
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|nextCache|NextCacheOptions \|undefined|Optional Next.js cache controls for SSR init requests.|-|Optional|
+
+#### `nextCache` NextCacheOptions
+
+Optional Next.js cache controls for SSR init requests.
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|revalidateSeconds|number \|false \|undefined|Cache lifetime in seconds for the Next.js data cache. Set to false to disable Next.js caching for this call.|-|Optional|
+
+### Return Value
+
+Returns `Promise<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 unresolved Promise to the provider's `ssrData` option via a client component:
+
+```tsx title="components/consent-manager/index.tsx"
+'use client';
+
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider, ConsentBanner, ConsentDialog } from '@c15t/nextjs';
+import type { InitialDataPromise } from '@c15t/nextjs';
+
+export default function ConsentManager({
+  children,
+  ssrData,
+}: {
+  children: ReactNode;
+  ssrData?: InitialDataPromise;
+}) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        store: { ssrData },
+      }}
+    >
+      <ConsentBanner />
+      <ConsentDialog />
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+```tsx title="app/layout.tsx"
+import { fetchInitialData } from '@c15t/nextjs';
+import ConsentManager from '@/components/consent-manager';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  const ssrData = fetchInitialData({
+    backendURL: '/api/c15t',
+  });
+
+  return (
+    <html lang="en">
+      <body>
+        <ConsentManager ssrData={ssrData}>
+          {children}
+        </ConsentManager>
+      </body>
+    </html>
+  );
+}
+```
+
+## How Headers Are Resolved
+
+Unlike `@c15t/react/server` where you must pass headers manually, `fetchInitialData` uses `next/headers` to automatically resolve the incoming request headers. This means geo-location headers from Vercel, Cloudflare, or AWS CloudFront are forwarded to the c15t backend without any extra configuration.
+
+|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|
+
+## Advanced: Using @c15t/react/server Directly
+
+For advanced use cases (custom server frameworks, edge functions, or non-standard header resolution), the underlying utilities from `@c15t/react/server` are available:
+
+```ts
+import {
+  fetchSSRData,
+  extractRelevantHeaders,
+  normalizeBackendURL,
+  validateBackendURL,
+} from '@c15t/react/server';
+```
+
+See the [React Server-Side Utilities](/docs/frameworks/react/server-side) docs for full API details.
+
+## Debugging SSR
+
+Use the [useSSRStatus](/docs/frameworks/next/hooks/use-ssr-status) hook on the client to verify SSR data was consumed:
+
+```tsx
+import { useSSRStatus } from '@c15t/nextjs';
+
+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/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.
+
+```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;
+}
+```