@c15t/react 2.2.0 → 3.0.0-alpha.0

package/docs/frameworks/react/styling/overview.md

@@ -1,302 +1,207 @@
 ---
-title: Styling Overview
-description: Customize every aspect of c15t's consent components using design
-  tokens, component slots, and CSS variables.
+title: Styling
+description: Import the React stylesheet and theme c15t components with tokens,
+  slots, and class names on ConsentProvider.
 group: frameworks
 ---
-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:
+## Stylesheet
 
-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|
-
-## Quick Start
-
-Use the `Theme` type for TypeScript autocomplete and validation:
-
-```tsx
-import { type ReactNode } from 'react';
-import { type Theme, ConsentManagerProvider } from '@c15t/react';
-
-const theme = {
-  colors: {
-    primary: '#6366f1',
-    primaryHover: '#4f46e5',
-    surface: '#ffffff',
-    text: '#1f2937',
-    textMuted: '#6b7280',
-  },
-  radius: {
-    md: '0.75rem',
-    lg: '1rem',
-  },
-  spacing: {
-    md: '1.25rem',
-  },
-} satisfies Theme;
-
-export function ConsentManager({ children }: { children: ReactNode }) {
-  return (
-    <ConsentManagerProvider
-      options={{
-        mode: 'hosted',
-        backendURL: 'https://your-instance.c15t.dev',
-        theme,
-      }}
-    >
-      {children}
-    </ConsentManagerProvider>
-  );
-}
-```
-
-## 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
+Import the stylesheet once, next to your global CSS, in the entry module that
+renders `ConsentProvider`:
 
 ```tsx
-<ConsentBanner layout={['customize', ['reject', 'accept']]} primaryButton="accept" />
+import 'c15t/react/styles.css';
 ```
 
-### 2. Design tokens
-
-Set global values for colors, typography, spacing, radius, shadows, and motion:
-
-```tsx
-options={{ theme: { colors: { primary: '#6366f1' } } }}
+Every rule lives in `@layer components`, so unlayered utilities from Tailwind
+v4 and atomic classes from StyleX override it without specificity tricks.
+Tailwind v3 treats `@layer components` as its own directive, so import the
+Tailwind 3 build from your Tailwind entry instead, between the `components`
+and `utilities` directives:
+
+```css
+@tailwind base;
+@tailwind components;
+@import 'c15t/react/styles.tw3.css';
+@tailwind utilities;
 ```
 
-Use tokens first when the change is semantic:
+## Tokens
 
-* 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
+The provider snippets below are partial configuration examples. Apply them to
+your existing `ConsentProvider` from `c15t/react`, keeping its `mode`, children
+and other options.
 
-```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:
+Colors, radii, shadows, typography, and motion come from `--c15t-*` custom
+properties. Set them on the provider through `theme`, or override the
+variables directly in your CSS.
 
 ```tsx
-options={{
-  theme: {
-    slots: {
-      consentBannerCard: 'rounded-[28px] shadow-xl',
-      consentBannerFooter: 'border-t border-black/10',
-      consentBannerTitle: 'tracking-tight',
-    },
-  },
-}}
+import { ConsentProvider, defineTheme } from 'c15t/react';
+
+const theme = defineTheme({
+	colors: { primary: '#2f6f4e' },
+	radius: { lg: '4px' },
+	consentActions: {
+		primary: { variant: 'primary', mode: 'filled' },
+		dismiss: { variant: 'neutral', mode: 'stroke' },
+	},
+});
+
+<ConsentProvider options={{ mode, theme }} />;
 ```
 
-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.
+`consentActions` decides how each action role looks: `default` applies to
+every button, `primary` to whichever actions the policy or your props mark
+primary, and `accept`, `reject`, `customize`, and `dismiss` to one role each.
+Per-action keys win over `primary`, which wins over `default`.
 
-Reach for this after tokens and slots, not before.
+Banner sizing has its own variables. Override them in CSS when a variant
+needs a different footprint:
 
-```tsx
-options={{
-  theme: {
-    slots: {
-      consentBannerFooter: 'bg-[var(--banner-footer)]',
-    },
-  },
-}}
-```
+| Variable                            | Default | Applies to       |
+| ----------------------------------- | ------- | ---------------- |
+| `--consent-banner-max-width`        | `440px` | `floating` cards |
+| `--consent-banner-widget-max-width` | `20rem` | `widget` chips   |
+| `--consent-banner-wall-max-width`   | `30rem` | `wall` cards     |
 
-## Escalating Beyond Pre-Built Components
+## Colors by consent model
 
-Only move up this ladder when the lower rung cannot satisfy the request.
+The primary action can change while the brand color stays the same. Set
+`consentActions.primary` once, then select `primaryButton` per policy as
+shown in [ConsentBanner](../components/consent-banner.md#per-policy-buttons).
 
-### 5. Compound components
+To give opt-in and opt-out banners different colors, scope the tokens to
+the root's attributes. Include hover and foreground colors when overriding
+CSS tokens directly:
 
-Use compound components when you need to rearrange existing c15t primitives:
+```css
+[data-prompt][data-model='opt-in'] {
+	--c15t-primary: #2f6f4e;
+	--c15t-primary-hover: #24563c;
+	--c15t-text-on-primary: #fff;
+}
 
-```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>
+[data-prompt][data-model='opt-out'] {
+	--c15t-primary: #6b3fa0;
+	--c15t-primary-hover: #55327f;
+	--c15t-text-on-primary: #fff;
+}
 ```
 
-### 6. `noStyle`
+These colors apply to the action marked primary. Button layout and color
+changes do not change the policy or expire a saved choice.
 
-Use `noStyle` only when the c15t structure is still correct but you want to replace all visual defaults:
+## Slots
 
-```tsx
-<ConsentBanner noStyle />
-```
+Each component part is a slot. A slot accepts any attributes the element
+takes, so the contract is the same whether you write class strings or pass an
+object with `className` and `style`. Set slots on the provider under
+`components`, keyed by component and part.
 
-### 7. Headless
+For a full-width notice, use the supported `bar` variant. Inside your existing
+provider, replace the stock banner with:
 
-Go headless only when you are replacing both markup and behavior. For that path, continue to [Headless Mode](../headless).
+```tsx title="src/regional-banner.tsx"
+import { ConsentBanner, usePolicyRule } from 'c15t/react';
 
-## Common Styling Tasks
-
-### Change the banner footer background
-
-```tsx
-options={{
-  theme: {
-    colors: {
-      surfaceHover: '#f6f3ee',
-    },
-  },
-}}
+export function RegionalBanner() {
+  const policy = usePolicyRule();
+  return <ConsentBanner variant={policy?.prompt === 'notice' ? 'bar' : 'floating'} />;
+}
 ```
 
-Use `theme.colors.surfaceHover` before trying raw CSS.
-
-### Change the banner card background
+To remove the notice card's radius, add these values to the existing
+`options.components.banner` slots. The root owns `data-prompt`, so the card
+uses Tailwind's `group` selector to read it:
 
-```tsx
-options={{
-  theme: {
-    colors: {
-      surface: '#fffdf8',
-    },
+```ts
+const bannerSlots = {
+  root: { className: 'group' },
+  card: { className: 'group-data-[prompt=notice]:rounded-none' },
+  rightLink: {
+    className: 'underline-offset-4 data-[right=opt-out]:text-red-700',
   },
-}}
-```
-
-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',
-    },
-  },
-}}
+// In the existing options.components object:
+// banner: bannerSlots
 ```
 
-### Change stock consent action button styles semantically
+The root also carries `data-variant`, so you can restyle one shape without
+touching the others. Tailwind, giving a `bar` a brand-colored top edge and
+tighter text:
 
 ```tsx
-options={{
-  theme: {
-    consentActions: {
-      default: { mode: 'stroke' },
-      accept: { variant: 'primary', mode: 'stroke' },
-      customize: { variant: 'neutral', mode: 'ghost' },
-    },
-  },
-}}
+<ConsentProvider
+	options={{
+		mode,
+		presentation: { prompt: { variant: 'bar' } },
+		components: {
+			banner: {
+				root: { className: 'group' },
+				card: {
+					className:
+						'group-data-[variant=bar]:border-t-4 group-data-[variant=bar]:border-t-emerald-600',
+				},
+			},
+			description: {
+				banner: { className: 'group-data-[variant=bar]:text-xs' },
+			},
+		},
+	}}
+/>
 ```
 
-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`.
+`data-variant` sits on the root, so child slots use Tailwind's `group`
+prefix to read it.
 
-### Change banner copy without replacing the component
+StyleX, spreading the result of `stylex.props()` into a slot:
 
 ```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',
-        },
-      },
-    },
-  },
-}}
+import * as stylex from '@stylexjs/stylex';
+
+const styles = stylex.create({
+	card: { borderRadius: 0, boxShadow: 'none' },
+	rightLink: { textUnderlineOffset: 4, color: 'rgb(185 28 28)' },
+});
+
+<ConsentProvider
+	options={{
+		mode,
+		components: {
+			banner: {
+				card: stylex.props(styles.card),
+				rightLink: stylex.props(styles.rightLink),
+			},
+		},
+	}}
+/>;
 ```
 
-### 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.\*
+Set `noStyle` on a component to drop the built-in classes from every part and
+keep only what your slots pass. Set `noStyle` in the provider options to do it
+for every component.
+
+Banner slot keys under `components.banner`:
+
+| Key           | Element                                                                                                           |
+| ------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `root`        | Fixed-position wrapper carrying `data-prompt`, `data-model`, `data-variant`, `data-position`, and `data-blocking` |
+| `cardShell`   | Sizes the card and holds the branding tag                                                                         |
+| `card`        | The visible card, carrying `data-state`                                                                           |
+| `header`      | Title and description container                                                                                   |
+| `title`       | Heading                                                                                                           |
+| `footer`      | Action area                                                                                                       |
+| `actions`     | Group of action groups                                                                                            |
+| `actionGroup` | One group of equally prominent actions                                                                            |
+| `rights`      | Group of right links, rendered before the actions                                                                 |
+| `rightLink`   | One right link, carrying `data-action="right"` and `data-right`                                                   |
+| `overlay`     | Backdrop shown when the banner blocks the page                                                                    |
+
+Action buttons carry `data-action` and `data-variant`, and right links carry
+`data-action="right"`, so a single rule such as `[data-action='dismiss']` or
+`[data-action='right']` styles one role across every surface. Right links are
+underlined text by default, so the only button on a notice is the primary
+action.

package/docs/frameworks/react/troubleshooting.md

@@ -1,139 +1,67 @@
 ---
-title: Troubleshooting
-description: Solutions for common issues with @c15t/react — provider errors,
-  missing banners, consent persistence, and more.
+title: Troubleshoot React consent
+description: Diagnose policy resolution, early scripts, storage and rendering problems.
 group: frameworks
 ---
-## "Provider not found" Error
 
-**Symptom:** `useConsentManager must be used within a ConsentManagerProvider` error.
+## Why is there no banner?
 
-**Fix:** Ensure the component calling `useConsentManager()` (or any c15t hook) is rendered inside a `ConsentManagerProvider`:
+Inspect `resolution` and `promptRequirement` before changing styles. Pending or
+failed initialization, no matching rule, a valid stored choice and a rule that
+requires no prompt can all produce no banner for different reasons. A missing
+stylesheet can also make rendered controls appear incorrectly.
 
-```tsx
-// Wrong — hook is outside the provider
-function App() {
-  const { consents } = useConsentManager(); // throws
-  return <ConsentManagerProvider options={...}>...</ConsentManagerProvider>;
-}
+Check the backend URL and Network response, then confirm the active policy for
+the visitor's location. Do not solve missing UI by granting every category or
+setting `enabled: false`: disabling the runtime permits optional loading.
 
-// Correct — hook is inside the provider
-function App() {
-  return (
-    <ConsentManagerProvider options={...}>
-      <MyComponent /> {/* useConsentManager works here */}
-    </ConsentManagerProvider>
-  );
-}
-```
+## Why does the UI disappear with a content blocker?
 
-## Banner Doesn't Show
+Check the browser Network panel for `ERR_BLOCKED_BY_CLIENT` or a failed dynamic
+import. Older c15t builds used component filenames such as
+`consent-dialog-*.js`, which some cookie-annoyance lists block. Update the c15t
+packages and rebuild the app. Current component modules use neutral filenames;
+public component imports stay the same. This also covers Vite development
+requests used by TanStack Start and other Vite integrations.
 
-**Possible causes:**
+Extensions can separately hide elements with cosmetic filters or block a
+configured backend URL. Check the failed request or hidden element to distinguish
+those cases from a missing component module.
 
-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.
+## Why does analytics run before a choice?
 
-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.
+Check effective permission under the selected policy, then find every loader
+for that vendor. Remove unconditional script tags, framework analytics plugins
+and duplicate tag-manager entries. c15t's script registration only controls the
+scripts registered with it.
 
-3. **`activeUI` is `'none'`** — Something is explicitly setting `activeUI` to `'none'`. Check the DevTools panel for the current consent state.
+Google helpers intentionally load with Consent Mode defaults. A Google request
+is not by itself proof that its storage consent was granted. If your requirement
+is no request at all, do not use an always-loaded helper unchanged.
 
-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`.
+## Why does a choice disappear on reload?
 
-```tsx
-// Debug: check what the consent manager sees
-const { activeUI, model, isLoadingConsentInfo } = useConsentManager();
-console.log({ activeUI, model, isLoadingConsentInfo });
-```
+Check whether persistence is disabled, browser storage is blocked, the origin
+changed, or the receipt expired or no longer matches the current policy.
+A development example with `persistence: false` deliberately resets on reload.
+Do not "repair" persistence by saving permissions automatically on mount.
 
-## Consent Not Persisting
+## Why does hydration differ from server HTML?
 
-**Symptom:** Consent is lost after page reload.
+Use the adapter's request helper and pass the returned configuration unchanged
+to its boundary. Check that server and browser use the same backend and policy
+inputs. A module-level mutable runtime on a server can share one visitor's state
+with another request; create request-owned state instead.
 
-**Possible causes:**
+## Why does static hosting fail when development works?
 
-1. **Incognito/private mode** — Some browsers restrict cookie storage in private browsing.
+A static host has no app server for init routes, proxies or server functions.
+Use absolute external consent URLs or an explicitly local policy. Test the
+production output with a static file server, not the framework dev server.
 
-2. **Cookie settings** — In `'offline'` mode, consent is stored in cookies. Ensure cookies are not being blocked by browser settings or extensions.
+## Why does customization do nothing?
 
-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.
-
-## SSR Hydration Mismatch
-
-**Symptom:** React hydration warnings, consent banner flashes briefly, or consent state differs between server and client.
-
-**Fixes:**
-
-1. **Missing `ssrData`** — Ensure you're passing the SSR data Promise to the provider:
-
-```tsx
-<ConsentManagerProvider
-  options={{
-    mode: 'hosted',
-    backendURL: '...',
-    ssrData: fetchSSRData({ backendURL: '...', headers }),
-  }}
->
-```
-
-2. **Stale cache** — If using a CDN or caching layer, ensure the SSR data is fresh per-request and not shared across users.
-
-3. **Debug with `useSSRStatus`** — Check if SSR data was actually consumed:
-
-```tsx
-const { ssrDataUsed, ssrSkippedReason } = useSSRStatus();
-```
-
-See [Server-Side Utilities](/docs/frameworks/react/server-side) for full SSR setup.
-
-## TypeScript Errors
-
-**Common import issues:**
-
-```tsx
-// Components and hooks — main entry point
-import { ConsentManagerProvider, useConsentManager } from '@c15t/react';
-
-// Server utilities — separate entry point
-import { fetchSSRData } from '@c15t/react/server';
-
-// Headless (hooks only, no components)
-import { useConsentManager } from '@c15t/react/headless';
-```
-
-If you see type errors after updating, try:
-
-```sh
-rm -rf node_modules/.cache
-bun install
-```
-
-## Still Stuck?
-
-* Enable `debug: true` in provider options for verbose console logging
-* Use the [DevTools](/docs/frameworks/react/components/dev-tools) panel to inspect live consent state
-* Check the [GitHub issues](https://github.com/c15t/c15t/issues) for known bugs
+Check the imported stylesheet, the correct token or slot, and which element
+carries the state attribute. `data-variant` on a banner root is not a matching
+attribute on its child card. Check cascade layers and the Tailwind version
+before adding specificity. See [customization](../../customization/overview.md).