@c15t/react 2.0.0-rc.6 → 2.0.0-rc.7

package/dist-types/components/consent-banner/index.d.ts

@@ -34,8 +34,9 @@ export interface ConsentBannerCompoundComponent extends FC<ConsentBannerProps> {
  *
  * @remarks
  * This component serves as the main entry point for rendering a consent banner.
- * It provides a structured layout with customizable title, description, and action buttons
- * for accepting, rejecting, or customizing consent preferences.
+ * Start with the pre-built component and its existing configuration surface.
+ * For most customization, use `ConsentManagerProvider` options, theme tokens,
+ * slots, and `theme.consentActions` before reaching for compound composition.
  *
  * Key features:
  * - Fully accessible by default
@@ -43,7 +44,7 @@ export interface ConsentBannerCompoundComponent extends FC<ConsentBannerProps> {
  * - Customizable appearance
  * - Responsive design
  * - Error boundary protection
- * - Compound component pattern support
+ * - Advanced compound component support when markup must change
  *
  * @example
  * Simple usage with default settings:
@@ -52,35 +53,54 @@ export interface ConsentBannerCompoundComponent extends FC<ConsentBannerProps> {
  * ```
  *
  * @example
- * Customized usage with all props:
+ * Preferred customization via provider `i18n`, theme tokens, and slots:
  * ```tsx
- * <ConsentBanner
- *   title="Cookie Settings"
- *   description="We use cookies to enhance your browsing experience"
- *   rejectButtonText="Decline"
- *   customizeButtonText="Preferences"
- *   acceptButtonText="Allow All"
- * />
+ * <ConsentManagerProvider
+ *   options={{
+ *     i18n: {
+ *       locale: 'en',
+ *       messages: {
+ *         en: {
+ *           cookieBanner: { title: 'Privacy choices' },
+ *         },
+ *       },
+ *     },
+ *     theme: {
+ *       colors: {
+ *         surface: '#fffdf8',
+ *         surfaceHover: '#f6f3ee',
+ *       },
+ *       slots: {
+ *         consentBannerCard: 'rounded-3xl',
+ *         consentBannerFooter: 'border-t border-black/10',
+ *       },
+ *     },
+ *   }}
+ * >
+ *   <ConsentBanner primaryButton="accept" />
+ * </ConsentManagerProvider>
  * ```
  *
  * @example
+ * Advanced custom markup with compound components:
  * ```tsx
  * <ConsentBanner.Root>
- *   <ConsentBanner.Content>
- *     <ConsentBanner.Title>Cookie Settings</ConsentBanner.Title>
- *     <ConsentBanner.Description>
- *       Choose your cookie preferences
- *     </ConsentBanner.Description>
- *     <ConsentBanner.Actions>
- *       <ConsentBanner.RejectButton>Decline</ConsentBanner.RejectButton>
- *       <ConsentBanner.CustomizeButton>Customize</ConsentBanner.CustomizeButton>
- *       <ConsentBanner.AcceptButton>Accept</ConsentBanner.AcceptButton>
- *     </ConsentBanner.Actions>
- *   </ConsentBanner.Content>
+ *   <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>
  * ```
- * Note: Next.js Server Components do not support compound components. Ensure you add 'use client' to the file.
- * Using compound components for custom layout:
+ * Note: Next.js Server Components do not support compound components. Ensure you add `'use client'` to the file.
  *
  * @public
  */

package/dist-types/components/consent-dialog/index.d.ts

@@ -42,30 +42,51 @@ export interface ConsentDialogCompoundComponent extends FC<ConsentDialogProps> {
  * - Provides an accessible modal interface for consent customization
  * - Implements smooth enter/exit animations
  * - Manages proper focus handling
- * - Supports theme customization
+ * - Supports theme customization through provider tokens and slots
  * - Handles client-side portal rendering
+ * - Exposes compound primitives for advanced markup changes
  *
  * @example
+ * Basic usage:
  * ```tsx
- * <ConsentDialog
- *   theme={customTheme}
- *   disableAnimation={false}
- *   noStyle={false}
- * />
+ * <ConsentDialog />
  * ```
  *
  * @example
+ * Preferred customization with stock structure:
+ * ```tsx
+ * <ConsentManagerProvider
+ *   options={{
+ *     theme: {
+ *       slots: {
+ *         consentDialogCard: 'rounded-3xl shadow-xl',
+ *         consentDialogFooter: 'border-t border-black/10',
+ *       },
+ *     },
+ *   }}
+ * >
+ *   <ConsentDialog hideBranding showTrigger />
+ * </ConsentManagerProvider>
+ * ```
+ *
+ * @example
+ * Advanced custom markup with compound components:
  * ```tsx
  * <ConsentDialog.Root>
  *   <ConsentDialog.Card>
  *     <ConsentDialog.Header>
- *       <ConsentDialog.HeaderTitle>Consent Manager</ConsentDialog.HeaderTitle>
+ *       <ConsentDialog.HeaderTitle />
+ *       <ConsentDialog.HeaderDescription />
  *     </ConsentDialog.Header>
+ *     <ConsentDialog.Content>
+ *       <ConsentWidget />
+ *     </ConsentDialog.Content>
+ *     <ConsentDialog.Footer />
  *   </ConsentDialog.Card>
  * </ConsentDialog.Root>
  * ```
  *
- * Note: Next.js Server Components do not support compound components. Ensure you add 'use client' to the file.
+ * Note: Next.js Server Components do not support compound components. Ensure you add `'use client'` to the file.
  *
  * @public
  */

package/dist-types/components/consent-preferences-link/consent-preferences-link.d.ts

@@ -13,4 +13,3 @@ export interface ConsentDialogLinkProps extends Omit<ConsentButtonProps, 'childr
     children: ReactNode;
 }
 export declare const ConsentDialogLink: import("react").ForwardRefExoticComponent<ConsentDialogLinkProps & import("react").RefAttributes<HTMLButtonElement>>;
-lement>>;

package/dist-types/components/consent-widget/atoms/accordion.d.ts

@@ -7,20 +7,21 @@ declare const ConsentWidgetAccordionTriggerInner: import("react").ForwardRefExot
 declare const ConsentWidgetAccordionContent: import("react").ForwardRefExoticComponent<PreferenceItem.PreferenceItemContentProps & import("react").RefAttributes<HTMLDivElement>>;
 declare const ConsentWidgetAccordionArrow: import("react").ForwardRefExoticComponent<PreferenceItem.PreferenceItemSlotProps & import("react").RefAttributes<HTMLDivElement>>;
 declare const ConsentWidgetSwitch: import("react").ForwardRefExoticComponent<RadixSwitch.SwitchProps & import("react").RefAttributes<HTMLButtonElement>>;
-type ConsentWidgetAccordionProps = {
+type ConsentWidgetAccordionProps = Omit<BoxProps, 'themeKey'> & {
+    'data-testid'?: string;
     children: ReactNode;
     onValueChange?: (value: string | string[]) => void;
     type?: 'multiple' | 'single';
     value?: string | string[];
 };
-declare const ConsentWidgetAccordion: ({ children, onValueChange, type, value, }: ConsentWidgetAccordionProps) => import("react/jsx-runtime").JSX.Element;
+declare const ConsentWidgetAccordion: ({ "data-testid": dataTestId, children, className, noStyle, onValueChange, style, type, value, ...props }: ConsentWidgetAccordionProps) => import("react/jsx-runtime").JSX.Element;
 declare const ConsentWidgetAccordionItems: () => import("react/jsx-runtime").JSX.Element[];
 declare const ConsentWidgetAccordionItem: import("react").ForwardRefExoticComponent<Omit<PreferenceItem.PreferenceItemRootProps & import("react").RefAttributes<HTMLDivElement>, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
 declare const AccordionTriggerInner: import("react").ForwardRefExoticComponent<PreferenceItem.PreferenceItemTriggerProps & import("react").RefAttributes<HTMLButtonElement>>;
 declare const AccordionTrigger: import("react").ForwardRefExoticComponent<BoxProps & import("react").RefAttributes<HTMLDivElement>>;
 declare const AccordionContent: import("react").ForwardRefExoticComponent<PreferenceItem.PreferenceItemContentProps & import("react").RefAttributes<HTMLDivElement>>;
 declare const AccordionArrow: import("react").ForwardRefExoticComponent<PreferenceItem.PreferenceItemSlotProps & import("react").RefAttributes<HTMLDivElement>>;
-declare const Accordion: ({ children, onValueChange, type, value, }: ConsentWidgetAccordionProps) => import("react/jsx-runtime").JSX.Element;
+declare const Accordion: ({ "data-testid": dataTestId, children, className, noStyle, onValueChange, style, type, value, ...props }: ConsentWidgetAccordionProps) => import("react/jsx-runtime").JSX.Element;
 declare const Switch: import("react").ForwardRefExoticComponent<RadixSwitch.SwitchProps & import("react").RefAttributes<HTMLButtonElement>>;
 declare const AccordionItems: () => import("react/jsx-runtime").JSX.Element[];
 declare const AccordionItem: import("react").ForwardRefExoticComponent<Omit<PreferenceItem.PreferenceItemRootProps & import("react").RefAttributes<HTMLDivElement>, "ref"> & import("react").RefAttributes<HTMLDivElement>>;

package/dist-types/components/consent-widget/index.d.ts

@@ -44,11 +44,11 @@ export interface ConsentWidgetCompoundComponent extends FC<ConsentWidgetProps> {
  *
  * @remarks
  * Key features:
- * - Implements compound component pattern for flexible composition
  * - Manages consent state and user interactions
  * - Provides accessible controls for consent management
- * - Supports comprehensive theming
+ * - Supports comprehensive theming with tokens and slots
  * - Handles accordion state management
+ * - Exposes compound primitives for advanced layout changes
  *
  * @example
  * Basic usage:
@@ -59,15 +59,32 @@ export interface ConsentWidgetCompoundComponent extends FC<ConsentWidgetProps> {
  * ```
  *
  * @example
- * Compound components:
+ * Preferred stock customization with theme slots:
+ * ```tsx
+ * <ConsentManagerProvider
+ *   options={{
+ *     theme: {
+ *       slots: {
+ *         consentWidgetAccordion: 'rounded-3xl border border-black/10',
+ *         consentWidgetFooter: 'border-t border-black/10',
+ *       },
+ *     },
+ *   }}
+ * >
+ *   <ConsentWidget hideBranding />
+ * </ConsentManagerProvider>
+ * ```
+ *
+ * @example
+ * Advanced compound components:
  * ```tsx
  * <ConsentWidget.Root>
  *   <ConsentWidget.Accordion>
  *     <ConsentWidget.AccordionItems />
- *    </ConsentWidget.Accordion>
- *  </ConsentWidget.Root>
+ *   </ConsentWidget.Accordion>
+ * </ConsentWidget.Root>
  * ```
- * Note: Next.js Server Components do not support compound components. Ensure you add 'use client' to the file.
+ * Note: Next.js Server Components do not support compound components. Ensure you add `'use client'` to the file.
  *
  */
 declare const ConsentWidget: ConsentWidgetCompoundComponent;

package/dist-types/version.d.ts

@@ -1 +1 @@
-export declare const version = "2.0.0-rc.6";
+export declare const version = "2.0.0-rc.7";

package/docs/building-headless-components.md

@@ -4,6 +4,9 @@ description: Build policy-aware custom consent components in React using the hea
 ---
 Building headless components is easier now because c15t exposes policy-aware primitives instead of forcing you to reconstruct banner rules by hand.
 
+> ⚠️ **Warning:**
+> Headless is the last step in the customization ladder. Use this guide only when pre-built components, tokens, slots, compound components, and noStyle are no longer sufficient.
+
 The headless stack is:
 
 * `useHeadlessConsentUI()` for policy-aware banner/dialog actions, ordering, layout, and primary actions hints

package/docs/components/consent-banner.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: A pre-built consent banner that appears when user consent is needed. Supports policy-aware layout, theming, and advanced composition when markup must change.
 ---
 `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.
 
@@ -18,20 +18,6 @@ export function ConsentManager() {
 }
 ```
 
-## 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):
@@ -86,6 +72,37 @@ Use the provider `theme` prop to control how stock consent actions look:
 
 Policy packs control grouping, ordering, and direction. The theme controls button appearance.
 
+## Styling First
+
+> ℹ️ **Info:**
+> For pure theming, stay inside the pre-built banner. Start with layout props, theme.consentActions, design tokens, and theme.slots before reaching for compound components. See Styling Overview.
+
+The stock banner maps common visual changes to the theme system:
+
+* Card background -> `theme.colors.surface`
+* Footer background -> `theme.colors.surfaceHover`
+* Card, footer, and title tweaks -> `theme.slots.consentBannerCard`, `consentBannerFooter`, and `consentBannerTitle`
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    theme: {
+      colors: {
+        surface: '#fffdf8',
+        surfaceHover: '#f6f3ee',
+      },
+      slots: {
+        consentBannerCard: 'rounded-[28px] shadow-xl',
+        consentBannerFooter: 'border-t border-black/10 px-6',
+        consentBannerTitle: 'tracking-tight',
+      },
+    },
+  }}
+>
+  <ConsentBanner />
+</ConsentManagerProvider>
+```
+
 ### Primary Button
 
 Highlight specific button(s) as the primary action:
@@ -116,9 +133,40 @@ Control which legal links appear in the banner description:
 > ℹ️ **Info:**
 > Legal link URLs are configured in the ConsentManagerProvider options via the legalLinks prop, not on the banner itself.
 
-## Compound Components
+## Customizing Copy
+
+Prefer provider `i18n` when you want to rename the stock banner content:
+
+```tsx
+<ConsentManagerProvider
+  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',
+          },
+        },
+      },
+    },
+  }}
+>
+  <ConsentBanner />
+</ConsentManagerProvider>
+```
+
+Direct text props such as `title`, `description`, and `acceptButtonText` are still supported for one-off overrides, but `i18n` is the preferred path for copy changes.
 
-Build fully custom banner layouts using sub-components:
+## Advanced: Compound Components
+
+Use compound components only when the stock banner structure is no longer enough and you need to rearrange existing c15t primitives:
 
 ```tsx
 <ConsentBanner.Root>
@@ -142,7 +190,7 @@ Build fully custom banner layouts using sub-components:
 * `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.Title` — Heading, defaults to translation `cookieBanner.title`
 * `ConsentBanner.Description` — Description text, supports `legalLinks` prop
 * `ConsentBanner.Footer` — Action buttons container
 * `ConsentBanner.FooterSubGroup` — Groups related buttons together
@@ -151,6 +199,8 @@ Build fully custom banner layouts using sub-components:
 * `ConsentBanner.AcceptButton` — Accepts all consent
 * `ConsentBanner.Overlay` — Optional backdrop overlay
 
+If you only need styling changes, stay with tokens and slots instead of rebuilding the banner layout.
+
 ## Props
 
 ### ConsentBannerProps

package/docs/components/consent-dialog.md

@@ -81,9 +81,36 @@ Hide the c15t branding in the dialog footer:
 <ConsentDialog hideBranding />
 ```
 
-## Compound Components
+## Styling First
 
-Build fully custom dialog layouts using sub-components:
+> ℹ️ **Info:**
+> If you are only changing visuals, stay with the stock dialog and use the theme system first. Start with tokens and slots such as consentDialogCard, consentDialogHeader, and consentDialogFooter. See Styling Overview.
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    theme: {
+      colors: {
+        surface: '#fffdf8',
+        surfaceHover: '#f6f3ee',
+      },
+      slots: {
+        consentDialogCard: 'rounded-[32px] shadow-xl',
+        consentDialogHeader: 'gap-3',
+        consentDialogFooter: 'border-t border-black/10 px-6',
+      },
+    },
+  }}
+>
+  <ConsentDialog />
+</ConsentManagerProvider>
+```
+
+Dialog copy should be changed through `ConsentManagerProvider.options.i18n`, not by rebuilding the dialog structure.
+
+## Advanced: Compound Components
+
+Use compound components only when you need custom dialog markup while still keeping c15t primitives:
 
 ```tsx
 <ConsentDialog.Root>
@@ -118,6 +145,8 @@ For a quick pre-composed layout, use the shorthand card:
 </ConsentDialog.Root>
 ```
 
+If the stock dialog structure still works, prefer tokens, slots, and provider configuration instead.
+
 ## Props
 
 ### ConsentDialogProps

package/docs/components/consent-widget.md

@@ -35,9 +35,36 @@ export function PrivacySettingsPage() {
 
 Each consent category is rendered as an expandable accordion item. Clicking the category header expands it to show a description and any associated services. Users can toggle individual categories on or off using the switch control. The `necessary` category is always enabled and cannot be toggled.
 
-## Compound Components
+## Styling First
 
-Build fully custom widget layouts using sub-components:
+> ℹ️ **Info:**
+> Most widget customization should stay in the stock component. Use theme tokens and slots such as consentWidgetAccordion, consentWidgetFooter, and toggle before reaching for compound components. See Styling Overview.
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    theme: {
+      colors: {
+        surface: '#fffdf8',
+        surfaceHover: '#f6f3ee',
+      },
+      slots: {
+        consentWidgetAccordion: 'rounded-3xl border border-black/10',
+        consentWidgetFooter: 'border-t border-black/10 px-6',
+        toggle: 'shadow-sm',
+      },
+    },
+  }}
+>
+  <ConsentWidget />
+</ConsentManagerProvider>
+```
+
+Widget copy should be changed through `ConsentManagerProvider.options.i18n` so the inline UI stays aligned with the rest of the consent experience.
+
+## Advanced: Compound Components
+
+Use compound components only when you need to rearrange the widget's existing primitives:
 
 ```tsx
 <ConsentWidget.Root>
@@ -68,6 +95,8 @@ Build fully custom widget layouts using sub-components:
 * `ConsentWidget.RejectButton` — Rejects all consent
 * `ConsentWidget.SaveButton` — Saves custom selections
 
+If the stock widget structure is already correct, stay with tokens and slots instead of rebuilding the layout.
+
 ## Props
 
 ### ConsentWidgetProps

package/docs/headless.md

@@ -4,11 +4,12 @@ description: Build fully custom consent UI using only hooks - no pre-built compo
 ---
 c15t's headless mode means using the hooks (`useConsentManager`, `useTranslations`, etc.) without any pre-built UI components. This gives you complete control over the consent experience.
 
-There are three levels of customization:
+Before you go headless, walk the customization ladder in order:
 
-1. **Props** - Use pre-built components with custom text and configuration
-2. **noStyle** - Use pre-built components with their structure but strip all styles
-3. **Headless** - Use only hooks and build the entire UI yourself
+1. **Pre-built components** - Use provider options, component props, tokens, slots, and `theme.consentActions`
+2. **Compound components** - Rearrange c15t primitives when the markup order must change
+3. **`noStyle`** - Keep c15t structure but replace its styling
+4. **Headless** - Use only hooks and build the entire UI yourself
 
 ## When to Go Headless
 
@@ -18,10 +19,15 @@ Go headless when:
 * You need a consent flow that doesn't fit the banner/dialog pattern
 * You want to embed consent choices inline rather than as overlays
 
-Use `noStyle` instead when:
+Use a lower-power tool instead when:
 
-* The component structure works but the styling doesn't
-* You want to apply your own CSS/Tailwind without fighting defaults
+* The component structure works but the styling doesn't -> use tokens, slots, or `noStyle`
+* You only need to rearrange existing c15t parts -> use compound components
+* You want to change copy -> use `ConsentManagerProvider.options.i18n`
+* You only need to restyle stock actions -> use `theme.consentActions`
+
+> ⚠️ **Warning:**
+> Headless mode is not the first answer for pure theming. If you are still trying to debug why a banner footer color did not change, stay in the styling system and verify the token-to-component mapping before you rebuild the UI.
 
 > ℹ️ **Info:**
 > Need a policy-aware implementation guide? See Building Headless Components.

package/docs/styling/classnames.md

@@ -2,15 +2,11 @@
 title: Class Names
 description: Style consent components using className props and per-slot className targeting via the theme.
 ---
-## Component className
+## Prefer Slots for Stock Components
 
-All consent components accept a `className` prop:
+There is no single top-level `className` contract across every pre-built consent component.
 
-```tsx
-<ConsentBanner className="my-banner" />
-<ConsentDialog className="my-dialog" />
-<ConsentWidget className="my-widget" />
-```
+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
 
@@ -59,9 +55,19 @@ const theme = {
 }
 ```
 
-## noStyle Mode
+## 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
 
-Use `noStyle` when you want to remove defaults and style from scratch:
+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 */}
@@ -81,4 +87,6 @@ const theme = {
 } 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).