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

package/{dist → dist-types}/utils/theme-utils.d.ts

@@ -2,7 +2,7 @@
  * Utility functions for processing the v2 theme system.
  * Handles token-to-CSS variable conversion and dark mode overrides.
  */
-import type { ThemeCSSVariables } from '@c15t/ui/theme';
+import type { ThemeCSSVariables } from '../../../ui/dist-types/theme/index.d.ts';
 import type { Theme } from '../types/theme/style-types';
 /**
  * Default design tokens for the v2 theme system.
@@ -16,4 +16,3 @@ export declare function themeToVars(theme: Theme, isDark?: boolean): ThemeCSSVar
  * Generates a CSS string for the theme variables.
  */
 export declare function generateThemeCSS(theme: Theme): string;
-//# sourceMappingURL=theme-utils.d.ts.map

package/dist-types/version.d.ts

@@ -0,0 +1 @@
+export declare const version = "2.0.0-rc.5";

package/docs/README.md

@@ -0,0 +1,76 @@
+# c15t React Docs
+
+React-focused c15t docs for consent UI, hooks, headless flows, and script integrations.
+
+If you are changing consent flows, consent UI, script loading, server-side setup, or backend configuration in an app that uses this package, start here before editing code.
+
+## Start Here
+
+- [Quickstart](./quickstart.md)
+- [Headless](./headless.md)
+- [Building Headless Components](./building-headless-components.md)
+- [Callbacks](./callbacks.md)
+- [Google Tag Manager](./integrations/google-tag-manager.md)
+
+## Workflow Rules
+
+### Styling
+
+Use this when:
+- customizing component appearance
+- adapting c15t components to a design system
+- deciding how far to override the default UI
+
+Prefer:
+- Prefer design tokens first.
+- If tokens are not enough, use component slots.
+- Then use CSS variables or `className` for targeted overrides.
+
+If that is not enough:
+- Use `noStyle` or a full headless rebuild only when the design system cannot be expressed through the supported styling layers.
+
+Avoid:
+- Do not rebuild the consent UI from scratch if tokens, slots, or scoped overrides are sufficient.
+
+Read next:
+- [Overview](./styling/overview.md)
+- [Tokens](./styling/tokens.md)
+- [Slots](./styling/slots.md)
+- [Css Variables](./styling/css-variables.md)
+
+### Consent UI Customization
+
+Use this when:
+- changing banners, dialogs, or preference centers
+- deciding between built-in components and headless APIs
+
+Prefer:
+- Prefer the built-in components and their documented customization surfaces first.
+- If the UI requirements diverge significantly, use the headless APIs.
+
+Avoid:
+- Do not rebuild the full consent flow if a token, slot, or component override is enough.
+
+Read next:
+- [Quickstart](./quickstart.md)
+- [Consent Banner](./components/consent-banner.md)
+- [Headless](./headless.md)
+- [Building Headless Components](./building-headless-components.md)
+
+### Scripts & Integrations
+
+Use this when:
+- adding third-party scripts in React components or providers
+- wiring analytics or advertising behind consent
+
+Prefer:
+- Prefer premade scripts from `@c15t/scripts/*`.
+- Start from the integration docs before implementing custom script wiring in React components.
+
+Avoid:
+- Do not duplicate consent-sync logic in React effects when the integration already handles it.
+
+Read next:
+- [Script Loader](./script-loader.md)
+- [Google Tag Manager](./integrations/google-tag-manager.md)
+- [Meta Pixel](./integrations/meta-pixel.md)

package/docs/building-headless-components.md

@@ -0,0 +1,245 @@
+---
+title: Building Headless Components
+description: Build policy-aware custom consent components in React using the headless hooks and policy-pack tooling.
+---
+Building headless components is easier now because c15t exposes policy-aware primitives instead of forcing you to reconstruct banner rules by hand.
+
+The headless stack is:
+
+* `useHeadlessConsentUI()` for policy-aware banner/dialog actions, ordering, layout, and primary action hints
+* `useConsentManager()` for runtime state, categories, selected consent state, and policy metadata
+* `useTranslations()` for the resolved copy
+* `offlinePolicy.policyPacks` for offline previews that behave like backend policy resolution
+
+> ℹ️ **Info:**
+> This guide is about building your own components while still respecting resolved policy-pack behavior. For the general headless overview, see Headless Mode.
+
+## What the Headless Tooling Gives You
+
+The main win is that your custom UI can stay aligned with policy packs without duplicating policy logic in your components.
+
+`useHeadlessConsentUI()` already resolves:
+
+* which actions are allowed
+* the order those actions should render in
+* grouped actions from policy `layout`
+* layout `direction` (`row` or `column`)
+* the primary action
+* UI profile and scroll-lock hints
+* whether the banner or dialog should currently be visible
+
+That means your component mostly focuses on markup and design-system concerns instead of re-implementing policy interpretation.
+
+## Provider Setup for Local Policy Testing
+
+```tsx
+import type { ReactNode } from 'react';
+import {
+  ConsentManagerProvider,
+  policyPackPresets,
+} from '@c15t/react';
+
+export function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'offline',
+        offlinePolicy: {
+          policyPacks: [
+            policyPackPresets.californiaOptOut(),
+            policyPackPresets.europeOptIn(),
+            policyPackPresets.worldNoBanner(),
+          ],
+        },
+        overrides: {
+          country: 'US',
+          region: 'CA',
+        },
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+## Policy-Aware Banner Example
+
+```tsx
+import { useHeadlessConsentUI, useTranslations } from '@c15t/react/headless';
+
+export function CustomConsentBanner() {
+  const { banner, openDialog, performAction } = useHeadlessConsentUI();
+  const translations = useTranslations();
+
+  if (!banner.isVisible) return null;
+
+  return (
+    <aside className="rounded-xl border bg-white p-6 shadow-lg">
+      <h2 className="text-lg font-semibold">{translations.cookieBanner.title}</h2>
+      <p className="mt-2 text-sm text-gray-600">
+        {translations.cookieBanner.description}
+      </p>
+
+      <div className="mt-4 space-y-2">
+        {banner.actionGroups.map((group, index) => (
+          <div key={`${group.join('-')}-${index}`} className="flex gap-2">
+            {group.map((action) => (
+              <button
+                key={action}
+                type="button"
+                className={action === banner.primaryAction ? 'btn-primary' : 'btn-secondary'}
+                onClick={() => {
+                  if (action === 'customize') {
+                    openDialog();
+                    return;
+                  }
+                  void performAction(action, { surface: 'banner' });
+                }}
+              >
+                {action === 'accept'
+                  ? translations.common.acceptAll
+                  : action === 'reject'
+                    ? translations.common.rejectAll
+                    : translations.common.customize}
+              </button>
+            ))}
+          </div>
+        ))}
+      </div>
+    </aside>
+  );
+}
+```
+
+## Category List That Respects the Resolved Policy
+
+```tsx
+import {
+  useConsentManager,
+  useHeadlessConsentUI,
+  useTranslations,
+} from '@c15t/react/headless';
+
+export function CustomConsentDialog() {
+  const { dialog, performDialogAction, saveCustomPreferences } = useHeadlessConsentUI();
+  const {
+    consentTypes,
+    consentCategories,
+    consents,
+    selectedConsents,
+    setSelectedConsent,
+  } = useConsentManager();
+  const translations = useTranslations();
+
+  if (!dialog.isVisible) return null;
+
+  const displayedTypes = consentTypes.filter(
+    (type) => type.display && consentCategories.includes(type.name)
+  );
+
+  return (
+    <section className="rounded-xl border bg-white p-6 shadow-xl">
+      <h2 className="text-lg font-semibold">
+        {translations.consentManagerDialog.title}
+      </h2>
+
+      <div className="mt-4 space-y-3">
+        {displayedTypes.map((type) => (
+          <label key={type.name} className="flex items-start justify-between gap-4">
+            <div>
+              <p className="font-medium">
+                {translations.consentTypes[type.name]?.title ?? type.name}
+              </p>
+              <p className="text-sm text-gray-600">{type.description}</p>
+            </div>
+            <input
+              type="checkbox"
+              checked={selectedConsents[type.name] ?? consents[type.name] ?? false}
+              disabled={type.disabled}
+              onChange={(event) =>
+                setSelectedConsent(type.name, event.target.checked)
+              }
+            />
+          </label>
+        ))}
+      </div>
+
+      <div className="mt-4 flex gap-2">
+        {dialog.orderedActions.map((action) => (
+          <button
+            key={action}
+            type="button"
+            onClick={() => {
+              if (action === 'customize') {
+                void saveCustomPreferences();
+                return;
+              }
+              void performDialogAction(action);
+            }}
+          >
+            {action === 'accept'
+              ? translations.common.acceptAll
+              : action === 'reject'
+                ? translations.common.rejectAll
+                : translations.common.save}
+          </button>
+        ))}
+      </div>
+    </section>
+  );
+}
+```
+
+## What a Policy-Aware Headless Component Should Respect
+
+When you build custom banner or dialog components, make sure they use:
+
+* `activeUI` or `banner.isVisible` / `dialog.isVisible` for visibility
+* `allowedActions`, `orderedActions`, or `actionGroups` instead of hard-coding buttons
+* `primaryAction` for visual emphasis
+* `consentCategories` when deciding which category toggles to render
+* `policyDecision` when you want to debug why a specific UI state was chosen
+
+If you ignore those values, your custom UI can drift away from the resolved policy pack even though the underlying consent engine is configured correctly.
+
+## Test Custom UI Against the Resolved Policy
+
+```ts
+import {
+  getEffectivePolicy,
+  type PolicyUIState,
+  validateUIAgainstPolicy,
+} from 'c15t';
+
+const policy = getEffectivePolicy(initData);
+
+const bannerState: PolicyUIState = {
+  mode: 'banner',
+  actions: ['accept', 'reject', 'customize'],
+  layout: 'split',
+  uiProfile: 'compact',
+  scrollLock: false,
+};
+
+const issues = validateUIAgainstPolicy({
+  policy,
+  state: bannerState,
+});
+
+expect(issues).toEqual([]);
+```
+
+## Validation and Testing
+
+If you are building a reusable headless component library, validate your rendered UI against the resolved runtime policy in tests.
+
+The core package exposes:
+
+* `getEffectivePolicy(initData)` to read the resolved policy from `/init`
+* `validateUIAgainstPolicy({ policy, state })` to detect mismatches such as wrong actions, layout, or mode
+
+This is useful when your design system renders custom button arrangements and you want tests to catch policy drift early.
+
+> ℹ️ **Info:**
+> Use this together with Policy Packs when you want to preview multiple regional experiences locally.

package/docs/callbacks.md

@@ -0,0 +1,117 @@
+---
+title: Callbacks
+description: React to consent lifecycle events - initialization, consent changes, errors, and revocation reloads.
+---
+Callbacks let you run custom code at key points in the consent lifecycle. Define them in the provider's `callbacks` option, or register them dynamically via `useConsentManager()`.
+
+## Configuration
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/react';
+
+export function ConsentManager({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: 'https://your-instance.c15t.dev',
+        callbacks: {
+          onBannerFetched: ({ jurisdiction, location, translations }) => {
+            console.log('Jurisdiction:', jurisdiction);
+            console.log('Country:', location.countryCode);
+            console.log('Language:', translations.language);
+          },
+          onConsentSet: ({ preferences }) => {
+            // Fire analytics event
+            analytics.track('consent_updated', { preferences });
+          },
+          onError: ({ error }) => {
+            errorReporter.captureMessage(error);
+          },
+          onBeforeConsentRevocationReload: ({ preferences }) => {
+            // Flush pending analytics before page reloads
+            analytics.flush();
+          },
+        },
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+## Available Callbacks
+
+### `onBannerFetched`
+
+Called when the consent banner data is fetched from the backend (or loaded from SSR data). The payload includes jurisdiction info, location data, and resolved translations.
+
+```tsx
+onBannerFetched: ({ jurisdiction, location, translations }) => {
+  // jurisdiction: 'GDPR' | 'CCPA' | { code: 'GDPR', message: '...' } | ...
+  // location: { countryCode: 'DE', regionCode: 'BY' }
+  // translations: { language: 'de', translations: {...} }
+}
+```
+
+### `onConsentSet`
+
+Called whenever consent preferences are saved - whether by user action (`saveConsents()`), automatic defaults, or on initialization when no jurisdiction is detected.
+
+```tsx
+onConsentSet: ({ preferences }) => {
+  // preferences: { necessary: true, measurement: true, marketing: false, ... }
+  if (preferences.measurement) {
+    loadAnalytics();
+  }
+}
+```
+
+### `onError`
+
+Called when an error occurs during consent operations (e.g., API request failure). If no `onError` callback is provided, errors are logged to `console.error`.
+
+```tsx
+onError: ({ error }) => {
+  // error: string describing what went wrong
+  Sentry.captureMessage(`Consent error: ${error}`);
+}
+```
+
+### `onBeforeConsentRevocationReload`
+
+Called synchronously before the page reloads due to consent revocation. This is your last chance to run cleanup before the reload. Keep this callback fast - avoid async operations.
+
+```tsx
+onBeforeConsentRevocationReload: ({ preferences }) => {
+  // Flush any pending data
+  navigator.sendBeacon('/api/flush', JSON.stringify({ session: sessionId }));
+}
+```
+
+## Dynamic Registration
+
+Register or update callbacks at runtime using `setCallback()`:
+
+```tsx
+import { useEffect } from 'react';
+import { useConsentManager } from '@c15t/react';
+
+function ConsentAnalytics() {
+  const { setCallback } = useConsentManager();
+
+  useEffect(() => {
+    setCallback('onConsentSet', ({ preferences }) => {
+      analytics.track('consent_changed', preferences);
+    });
+
+    return () => {
+      setCallback('onConsentSet', undefined);
+    };
+  }, [setCallback]);
+
+  return null;
+}
+```

package/docs/components/consent-banner.md

@@ -0,0 +1,174 @@
+---
+title: ConsentBanner
+description: A pre-built consent banner that appears when user consent is needed. Supports custom layout, button arrangement, and full compound component composition.
+---
+`ConsentBanner` is a ready-to-use consent banner that appears automatically in **opt-in jurisdictions** (like GDPR) where explicit consent is required before tracking. In opt-out jurisdictions (like CCPA), the banner won't appear — users get an opt-out mechanism instead. It includes reject, accept, and customize buttons with configurable layout.
+
+## Basic Usage
+
+```tsx
+import { ConsentManagerProvider, ConsentBanner } from '@c15t/react';
+
+export function ConsentManager() {
+  return (
+    <ConsentManagerProvider options={{ mode: 'hosted', backendURL: 'https://your-instance.c15t.dev' }}>
+      <ConsentBanner />
+    </ConsentManagerProvider>
+  );
+}
+```
+
+## Customizing Content
+
+Override the default title, description, and button labels:
+
+```tsx
+<ConsentBanner
+  title="We value your privacy"
+  description="We use cookies to enhance your browsing experience and analyze site traffic."
+  acceptButtonText="Accept all"
+  rejectButtonText="Reject all"
+  customizeButtonText="Manage preferences"
+/>
+```
+
+## Button Layout
+
+The `layout` prop controls button arrangement. Each item is either a button ID or an array of button IDs (which groups them together):
+
+```tsx
+{/* Default: reject and accept grouped, customize separate */}
+<ConsentBanner layout={[['reject', 'accept'], 'customize']} />
+
+{/* All buttons in one group */}
+<ConsentBanner layout={[['reject', 'customize', 'accept']]} />
+
+{/* Accept first, then reject and customize grouped */}
+<ConsentBanner layout={['accept', ['reject', 'customize']]} />
+```
+
+To stack groups vertically, pair the same grouped layout with `direction="column"`:
+
+```tsx
+<ConsentBanner
+  layout={['customize', ['reject', 'accept']]}
+  direction="column"
+/>
+```
+
+## Policy-Driven UI Profile
+
+When using backend runtime policies, `policy.ui.uiProfile` can control banner action presentation:
+
+* `compact` — default desktop sizing
+* `balanced` — auto-fills compact and grouped layouts with moderate emphasis
+* `strict` — always fills action controls for explicit, high-clarity layouts
+
+## Theme-Level Button Styling
+
+Use the provider `theme` prop to control how stock consent actions look:
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    theme: {
+      consentActions: {
+        default: { mode: 'stroke' },
+        accept: { variant: 'primary', mode: 'stroke' },
+        customize: { variant: 'neutral', mode: 'ghost' },
+      },
+    },
+  }}
+>
+  <ConsentBanner />
+</ConsentManagerProvider>
+```
+
+Policy packs control grouping, ordering, and direction. The theme controls button appearance.
+
+### Primary Button
+
+Highlight specific button(s) as the primary action:
+
+```tsx
+{/* Single primary */}
+<ConsentBanner primaryButton="accept" />
+
+{/* Multiple primaries */}
+<ConsentBanner primaryButton={['accept', 'customize']} />
+```
+
+## Legal Links
+
+Control which legal links appear in the banner description:
+
+```tsx
+{/* Show all configured links (default) */}
+<ConsentBanner legalLinks={undefined} />
+
+{/* Show no links */}
+<ConsentBanner legalLinks={null} />
+
+{/* Show specific links */}
+<ConsentBanner legalLinks={['privacyPolicy', 'cookiePolicy']} />
+```
+
+> ℹ️ **Info:**
+> Legal link URLs are configured in the ConsentManagerProvider options via the legalLinks prop, not on the banner itself.
+
+## Compound Components
+
+Build fully custom banner layouts using sub-components:
+
+```tsx
+<ConsentBanner.Root>
+  <ConsentBanner.Overlay />
+  <ConsentBanner.Card>
+    <ConsentBanner.Header>
+      <ConsentBanner.Title />
+      <ConsentBanner.Description />
+    </ConsentBanner.Header>
+    <ConsentBanner.Footer>
+      <ConsentBanner.FooterSubGroup>
+        <ConsentBanner.RejectButton />
+        <ConsentBanner.AcceptButton />
+      </ConsentBanner.FooterSubGroup>
+      <ConsentBanner.CustomizeButton />
+    </ConsentBanner.Footer>
+  </ConsentBanner.Card>
+</ConsentBanner.Root>
+```
+
+* `ConsentBanner.Root` — Outermost container, provides theme context
+* `ConsentBanner.Card` — Main content card with optional focus trapping
+* `ConsentBanner.Header` — Contains title and description
+* `ConsentBanner.Title` — Heading, defaults to translation `consentBanner.title`
+* `ConsentBanner.Description` — Description text, supports `legalLinks` prop
+* `ConsentBanner.Footer` — Action buttons container
+* `ConsentBanner.FooterSubGroup` — Groups related buttons together
+* `ConsentBanner.RejectButton` — Rejects all consent
+* `ConsentBanner.CustomizeButton` — Opens the consent dialog
+* `ConsentBanner.AcceptButton` — Accepts all consent
+* `ConsentBanner.Overlay` — Optional backdrop overlay
+
+## Props
+
+### ConsentBannerProps
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|noStyle|boolean \|undefined|When true, removes all default styling from the component|false|Optional|
+|title|ReactNode|Content to display as the banner's title|undefined|Optional|
+|description|ReactNode|Content to display as the banner's description|undefined|Optional|
+|rejectButtonText|ReactNode|Content to display on the reject button|undefined|Optional|
+|customizeButtonText|ReactNode|Content to display on the customize button|undefined|Optional|
+|acceptButtonText|ReactNode|Content to display on the accept button|undefined|Optional|
+|scrollLock|boolean \|undefined|When true, the consent banner will lock the scroll of the page|false|Optional|
+|trapFocus|boolean \|undefined|When true, the consent banner will trap focus|true|Optional|
+|disableAnimation|boolean \|undefined|When true, disables the entrance/exit animations|false|Optional|
+|legalLinks|(keyof LegalLinksTranslations)\[] \|null \|undefined|Controls which legal links to display. Options: \`undefined\` (default): Shows all available legal links; \`null\`: Explicitly hides all legal links; Array of keys: Shows only the specified legal links|-|Optional|
+|layout|ConsentBannerLayout \|undefined|Defines the layout of buttons in the footer. Allows reordering and grouping of buttons.|-|Optional|
+|direction|PolicyUiActionDirection \|undefined|Defines how footer button groups flow.|-|Optional|
+|primaryButton|ConsentBannerButton \|undefined|Specifies which button(s) should be highlighted as the primary action.|-|Optional|
+|models|Model \|undefined|Which consent models this banner responds to.|\['opt-in']|Optional|
+|uiSource|string \|undefined|Override the UI source identifier sent with consent API calls.|'banner'|Optional|

package/docs/components/consent-dialog-link.md

@@ -0,0 +1,59 @@
+---
+title: ConsentDialogLink
+description: An inline trigger for opening the consent dialog from footers, legal pages, and account settings.
+---
+`ConsentDialogLink` is an inline trigger for opening the consent dialog from places like site footers, legal pages, or account settings. It is unstyled by default, so it inherits your app's typography and link/button styles.
+
+## Basic Usage
+
+```tsx
+import { ConsentDialogLink } from '@c15t/react/components/consent-dialog-link';
+
+export function SiteFooter() {
+  return (
+    <footer>
+      <ConsentDialogLink>
+        Your privacy settings
+      </ConsentDialogLink>
+    </footer>
+  );
+}
+```
+
+## Footer Link (unstyled by default)
+
+```tsx
+<footer>
+  <ConsentDialogLink>
+    Your privacy settings
+  </ConsentDialogLink>
+</footer>
+```
+
+## Render as an Anchor
+
+Use `asChild` to keep semantic anchor markup while still opening the dialog:
+
+```tsx
+<ConsentDialogLink asChild>
+  <a href="#privacy-settings">Manage Preferences</a>
+</ConsentDialogLink>
+```
+
+## Optional Styling Control
+
+The component defaults to `noStyle={true}`. Set it to `false` if you want c15t button styles:
+
+```tsx
+<ConsentDialogLink noStyle={false}>
+  Privacy Settings
+</ConsentDialogLink>
+```
+
+## Props
+
+### ConsentDialogLinkProps
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|children|ReactNode|Custom trigger content, for example "Your privacy settings" or "Manage preferences".|-|✅ Required|