@c15t/react 2.2.0 → 3.0.0-alpha.0

package/docs/frameworks/react/components/consent-dialog-trigger.md

@@ -1,44 +1,60 @@
 ---
 title: ConsentDialogTrigger
-description: A floating, draggable button that lets users re-open the consent
-  dialog at any time.
+description: Floating button and toolbar that reopen the preference center after
+  the first prompt.
 group: frameworks
 ---
-`ConsentDialogTrigger` is a floating button that opens the consent dialog when clicked. Users can drag it to any corner of the screen, and the position persists across sessions. Use it to give users a persistent way to manage their privacy settings.
 
-## Basic Usage
+## Usage
 
-Use standalone or via the `showTrigger` prop on `ConsentDialog`:
+`ConsentDialogTrigger` is a draggable floating button that opens the preference center. Place it once, next to the banner and dialog, so visitors can revisit their choices without a footer link.
 
 ```tsx
-import { ConsentDialogTrigger } from '@c15t/react';
-
-// Standalone
-<ConsentDialogTrigger />
-
-// Via ConsentDialog
-<ConsentDialog showTrigger />
+import {
+  ConsentBanner,
+  ConsentDialog,
+  ConsentDialogTrigger,
+  ConsentProvider,
+  offline,
+} from 'c15t/react';
+import { policyRulePresets } from '@c15t/schema';
+
+const mode = offline({ policyRules: [policyRulePresets.europeOptIn()] });
+
+export function App() {
+  return (
+    <ConsentProvider options={{ mode }}>
+      <ConsentBanner />
+      <ConsentDialog />
+      <ConsentDialogTrigger showWhen="after-prompt" />
+    </ConsentProvider>
+  );
+}
 ```
 
-For inline footer links (instead of a floating button), use [`ConsentDialogLink`](/docs/frameworks/react/components/consent-dialog-link).
+`showWhen="after-prompt"` keeps the button out of the way while a choice or notice is still owed and shows it once the visitor has answered, so the banner and the trigger never compete for the same corner. The default, `always`, shows it whenever the preference center is closed.
 
-## Icon Options
+The button carries `data-c15t-rights` with the rights the active policy guarantees, so a stylesheet can label it differently under an opt-out rule.
 
-```tsx
-{/* Built-in icons */}
-<ConsentDialogTrigger icon="branding" />    {/* c15t logo (default) */}
-<ConsentDialogTrigger icon="fingerprint" /> {/* Privacy icon */}
-<ConsentDialogTrigger icon="settings" />    {/* Gear icon */}
+## Props
 
-{/* Custom icon */}
-<ConsentDialogTrigger icon={<MyCustomIcon />} />
-```
+| Prop              | Type                                                        | Default                   | Description                                                                         |
+| ----------------- | ----------------------------------------------------------- | ------------------------- | ----------------------------------------------------------------------------------- |
+| `icon`            | `'branding' \|'fingerprint' \|'settings' \|ReactNode`       | `'branding'`              | Icon rendered inside the button.                                                    |
+| `defaultPosition` | `'bottom-left' \|'bottom-right' \|'top-left' \|'top-right'` | `'bottom-right'`          | Corner the button starts in.                                                        |
+| `persistPosition` | `boolean`                                                   | `true`                    | Remember the corner the visitor dragged it to.                                      |
+| `showWhen`        | `'always' \|'after-prompt' \|'never'`                       | `'always'`                | When the button is visible. `after-prompt` waits until no choice or notice is owed. |
+| `size`            | `'sm' \|'md' \|'lg'`                                        | `'md'`                    | Button size.                                                                        |
+| `ariaLabel`       | `string`                                                    | `'Open privacy settings'` | Accessible name.                                                                    |
+| `noStyle`         | `boolean`                                                   | `false`                   | Remove the default styling.                                                         |
 
-## Configurable Toolbar
+## Configurable toolbar
 
-Use the separate `ConsentDialogTriggerToolbar` when you want to place app-owned controls beside the privacy trigger. It always renders exactly one built-in action that opens consent preferences, so `actions` only contains controls your app owns.
+Use `ConsentDialogTriggerToolbar` when you want app-owned controls beside the privacy trigger. It always renders exactly one built-in action that opens the preference center, so `actions` only holds controls your app owns.
 
 ```tsx
+import { ConsentDialogTriggerToolbar } from 'c15t/react';
+
 <ConsentDialogTriggerToolbar
   ariaLabel="Site controls"
   actions={[
@@ -63,36 +79,53 @@ Use the separate `ConsentDialogTriggerToolbar` when you want to place app-owned
 />
 ```
 
-Each custom action requires a stable `id`, accessible `label`, `icon`, and `onSelect` callback. Use `pressed` for toggle actions and `disabled` for unavailable actions. Your app remains responsible for state, integrations, and changing the icon or label. The preferences action automatically moves to the edge nearest the toolbar's snapped corner while custom actions keep their configured order.
+Each custom action needs a stable `id`, an accessible `label`, an `icon`, and an `onSelect` callback. Use `pressed` for toggle actions and `disabled` for unavailable ones. Your app owns the state behind each action. The preferences action moves to the edge nearest the toolbar's snapped corner while custom actions keep their configured order.
+
+The toolbar does not depend on the consent policy. Your actions always render, so a theme toggle stays available while a banner is up. On the toolbar, `showWhen` applies only to the built-in preferences action: `after-prompt` hides that one item while a choice or notice is owed and shows it once the visitor has answered, and `never` leaves it out. The toolbar renders nothing only when it has no visible item. On the single `ConsentDialogTrigger`, `showWhen` applies to the whole control.
 
-Toolbars are horizontal by default. Set `orientation="vertical"` to stack the actions and enable Up/Down arrow-key navigation:
+No policy, no UI. When no rule has resolved, because resolution failed, no rule matched and you set no default, or init is still withheld, the built-in preferences action and the single `ConsentDialogTrigger` render nothing; app-owned toolbar actions still do. They appear as soon as a rule resolves, without a remount. A rule with `model: 'none'` owes no rights, so the built-in action and the single trigger hide under it too, unless the rule adds `rights: ['preferences']`. The policy chooses what the control says, you choose where and when it sits, and it disappears only when there is nothing to manage.
+
+The built-in action names the strongest right the active rule guarantees. Under a rule that carries the `opt-out` right, such as a US opt-out notice, its accessible name is the translated "Do not sell or share my data" and the button carries `data-right="opt-out"`. Under any other rule it reads "Manage preferences" with `data-right="preferences"`. Either way it opens the preference center, and a `preferences.label` you pass replaces the default. The button also carries `data-c15t-rights` with every right on the rule.
+
+Toolbars are horizontal by default. Set `orientation="vertical"` to stack the actions and switch arrow-key navigation to up and down:
 
 ```tsx
-<ConsentDialogTriggerToolbar
-  orientation="vertical"
-  actions={toolbarActions}
-/>
+<ConsentDialogTriggerToolbar orientation="vertical" actions={toolbarActions} />
 ```
 
-### Toolbar Styling
+### Toolbar props
+
+| Prop              | Type                                     | Default              | Description                                                                                                                                                      |
+| ----------------- | ---------------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `actions`         | `ConsentDialogTriggerToolbarAction[]`    | `[]`                 | App-owned actions rendered beside the preferences action.                                                                                                        |
+| `preferences`     | `ConsentDialogTriggerToolbarPreferences` | `{}`                 | Overrides for the built-in action: `icon`, `label`, `onSelect`, `className`, `style`. The label defaults to the opt-out or preferences right on the active rule. |
+| `orientation`     | `'horizontal' \|'vertical'`              | `'horizontal'`       | Layout direction.                                                                                                                                                |
+| `defaultPosition` | `CornerPosition`                         | `'bottom-right'`     | Corner the toolbar starts in.                                                                                                                                    |
+| `persistPosition` | `boolean`                                | `true`               | Remember the dragged corner.                                                                                                                                     |
+| `showWhen`        | `'always' \|'after-prompt' \|'never'`    | `'always'`           | When the built-in preferences action is visible. App-owned actions always render. `after-prompt` waits until no choice or notice is owed.                        |
+| `size`            | `'sm' \|'md' \|'lg'`                     | `'md'`               | Size of each action.                                                                                                                                             |
+| `ariaLabel`       | `string`                                 | `'Privacy controls'` | Accessible name for the toolbar group.                                                                                                                           |
+| `noStyle`         | `boolean`                                | `false`              | Remove the default styling.                                                                                                                                      |
+
+### Toolbar styling
 
-The toolbar follows the standard styling precedence: internal CSS module styles, provider theme slots, then direct component overrides. Use `className` and `style` on the toolbar, or on an individual action, and use `noStyle` for a fully custom implementation.
+The toolbar follows the standard precedence: bundled styles, then provider slots, then direct `className` and `style` on the toolbar or on one action. Use `noStyle` for a fully custom implementation.
 
 ```tsx
-<ConsentManagerProvider
+<ConsentProvider
   options={{
-    theme: {
-      slots: {
-        consentDialogTriggerToolbar: 'my-toolbar',
-        consentDialogTriggerToolbarItem: 'my-toolbar-item',
-        consentDialogTriggerToolbarIcon: 'my-toolbar-icon',
+    mode: offline({ policyRules: [policyRulePresets.europeOptIn()] }),
+    components: {
+      trigger: {
+        toolbar: { className: 'my-toolbar' },
+        toolbarItem: { className: 'my-toolbar-item' },
+        toolbarIcon: { className: 'my-toolbar-icon' },
       },
     },
   }}
 >
   <ConsentDialogTriggerToolbar
     className="fixed-toolbar"
-    style={{ '--cdtt-offset': '24px' }}
     actions={[
       {
         id: 'support',
@@ -103,100 +136,7 @@ The toolbar follows the standard styling precedence: internal CSS module styles,
       },
     ]}
   />
-</ConsentManagerProvider>
+</ConsentProvider>
 ```
 
-Available toolbar theme slots are `consentDialogTriggerToolbar`, `consentDialogTriggerToolbarItem`, and `consentDialogTriggerToolbarIcon`.
-
-With `noStyle`, use `data-corner`, `data-dragging`, and `data-snapping` on the toolbar to style its current position and interaction state.
-
-## Visibility
-
-Control when the trigger is visible:
-
-```tsx
-{/* Always visible (default) */}
-<ConsentDialogTrigger showWhen="always" />
-
-{/* Only after user has made a consent choice */}
-<ConsentDialogTrigger showWhen="after-consent" />
-
-{/* Hidden (control visibility programmatically) */}
-<ConsentDialogTrigger showWhen="never" />
-```
-
-## Position
-
-Set the default corner and control persistence:
-
-```tsx
-<ConsentDialogTrigger
-  defaultPosition="bottom-left"
-  persistPosition={true} // Remembers user's drag position
-  onPositionChange={(position) => console.log('Moved to:', position)}
-/>
-```
-
-## Size
-
-```tsx
-<ConsentDialogTrigger size="sm" /> {/* Small */}
-<ConsentDialogTrigger size="md" /> {/* Medium (default) */}
-<ConsentDialogTrigger size="lg" /> {/* Large */}
-```
-
-## Compound Components
-
-Build fully custom trigger layouts using sub-components:
-
-```tsx
-<ConsentDialogTrigger.Root defaultPosition="bottom-right">
-  <ConsentDialogTrigger.Button size="md">
-    <ConsentDialogTrigger.Icon icon="settings" />
-    <ConsentDialogTrigger.Text>Privacy</ConsentDialogTrigger.Text>
-  </ConsentDialogTrigger.Button>
-</ConsentDialogTrigger.Root>
-```
-
-* `ConsentDialogTrigger.Root` — Portal wrapper with drag handling and position persistence
-* `ConsentDialogTrigger.Button` — Draggable button element with size variants
-* `ConsentDialogTrigger.Icon` — Icon display (branding, fingerprint, settings, or custom)
-* `ConsentDialogTrigger.Text` — Optional text label
-
-## Props
-
-### ConsentDialogTrigger
-
-|Property|Value|
-|:--|:--|
-|Type Name|\`ConsentDialogTriggerProps\`|
-|Source Path|\`./packages/react/src/components/consent-dialog-trigger/types.ts\`|
-
-\*ExtractedTypeTable: Could not extract "ConsentDialogTriggerProps" from "./packages/react/src/components/consent-dialog-trigger/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
-
-### ConsentDialogTriggerToolbar
-
-|Property|Value|
-|:--|:--|
-|Type Name|\`ConsentDialogTriggerToolbarProps\`|
-|Source Path|\`./packages/react/src/components/consent-dialog-trigger/types.ts\`|
-
-\*ExtractedTypeTable: Could not extract "ConsentDialogTriggerToolbarProps" from "./packages/react/src/components/consent-dialog-trigger/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
-
-### Toolbar Actions
-
-|Property|Value|
-|:--|:--|
-|Type Name|\`ConsentDialogTriggerToolbarAction\`|
-|Source Path|\`./packages/react/src/components/consent-dialog-trigger/types.ts\`|
-
-\*ExtractedTypeTable: Could not extract "ConsentDialogTriggerToolbarAction" from "./packages/react/src/components/consent-dialog-trigger/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
-
-### Preferences Action
-
-|Property|Value|
-|:--|:--|
-|Type Name|\`ConsentDialogTriggerToolbarPreferences\`|
-|Source Path|\`./packages/react/src/components/consent-dialog-trigger/types.ts\`|
-
-\*ExtractedTypeTable: Could not extract "ConsentDialogTriggerToolbarPreferences" from "./packages/react/src/components/consent-dialog-trigger/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+The toolbar slot keys are `trigger.toolbar`, `trigger.toolbarItem`, and `trigger.toolbarIcon`. With `noStyle`, style the current position and interaction state through `data-corner`, `data-dragging`, and `data-snapping` on the toolbar element.

package/docs/frameworks/react/components/consent-dialog.md

@@ -1,169 +1,204 @@
 ---
 title: ConsentDialog
-description: A modal dialog where users can toggle individual consent categories.
+description: Open the c15t preference center as a modal ConsentDialog in a React
+  app, wire its triggers and control blocking, focus and policy gating.
 group: frameworks
 ---
-`ConsentDialog` is a modal that shows toggles for each consent category. In **opt-in jurisdictions**, it typically opens when users click "Customize" on `ConsentBanner`. It can also be controlled programmatically for use on settings pages regardless of jurisdiction.
 
-## Basic Usage
-
-```tsx
-import { ConsentManagerProvider, ConsentBanner, ConsentDialog } from '@c15t/react';
-
-export function ConsentManager() {
+## Open the preference center
+
+`ConsentDialog` is the modal preference center. Mount it once inside
+`ConsentProvider`, next to the banner, and it opens whenever something makes
+`dialog` the active surface: the banner's Customize button, a
+`ConsentDialogLink` in your footer, a `ConsentDialogTrigger`, or your own
+code.
+
+```tsx title="src/consent.tsx"
+import type { ReactNode } from 'react';
+import {
+  ConsentBanner,
+  ConsentDialog,
+  ConsentDialogLink,
+  ConsentProvider,
+  hosted,
+} from 'c15t/react';
+import 'c15t/react/styles.css';
+
+const backendURL = import.meta.env.VITE_C15T_BACKEND_URL;
+if (!backendURL) throw new Error('Set VITE_C15T_BACKEND_URL');
+const mode = hosted({ url: backendURL });
+
+export function Consent({ children }: { children: ReactNode }) {
   return (
-    <ConsentManagerProvider options={{ mode: 'hosted', backendURL: 'https://your-instance.c15t.dev' }}>
+    <ConsentProvider options={{ mode }}>
+      {children}
       <ConsentBanner />
-      <ConsentDialog />
-    </ConsentManagerProvider>
-  );
-}
-```
-
-## Controlled State
-
-By default, the dialog follows `activeUI === 'dialog'` from the consent store. Use the `open` prop for manual control:
-
-```tsx
-import { useState } from 'react';
-
-function SettingsPage() {
-  const [open, setOpen] = useState(false);
-
-  return (
-    <>
-      <button onClick={() => setOpen(true)}>Privacy Settings</button>
-      <ConsentDialog open={open} />
-    </>
+      <ConsentDialog hideBranding />
+      <footer>
+        <ConsentDialogLink>Privacy settings</ConsentDialogLink>
+      </footer>
+    </ConsentProvider>
   );
 }
 ```
 
-Or use the hook to open it programmatically:
+To open it from your own component, set the active surface:
 
 ```tsx
-import { useConsentManager } from '@c15t/react';
-
-function PrivacyLink() {
-  const { setActiveUI } = useConsentManager();
+import { useSetActiveUI } from 'c15t/react';
 
+export function PrivacyMenuItem() {
+  const setActiveUI = useSetActiveUI();
   return (
-    <button onClick={() => setActiveUI('dialog')}>
-      Manage cookies
+    <button type="button" onClick={() => setActiveUI('dialog')}>
+      Cookie preferences
     </button>
   );
 }
 ```
 
-## Floating Trigger
+`ConsentDialogLink` does the same with the policy's rights exposed for
+styling; see [ConsentDialogLink](./consent-dialog-link.md). For a floating
+button, see [ConsentDialogTrigger](./consent-dialog-trigger.md). Under an IAB
+policy, mount `IABConsentDialog` from the [IAB guide](../iab/overview.md)
+instead; this dialog stays closed for the `iab` model.
 
-Add a floating button that lets users re-open the dialog after dismissing the banner:
-
-```tsx
-{/* Default trigger */}
-<ConsentDialog showTrigger />
-
-{/* Custom trigger */}
-<ConsentDialog
-  showTrigger={{
-    icon: 'settings',
-    defaultPosition: 'bottom-left',
-    showWhen: 'after-consent',
-    size: 'sm',
-  }}
-/>
-```
-
-## Branding
-
-Hide the c15t branding tag:
-
-```tsx
-<ConsentDialog hideBranding />
-```
-
-## Styling First
-
-> ℹ️ **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, consentWidgetFooter, and consentDialogTag. See Styling Overview.
-
-```tsx
-<ConsentManagerProvider
-  options={{
-    theme: {
-      colors: {
-        surface: '#fffdf8',
-        surfaceHover: '#f6f3ee',
-      },
-      slots: {
-        consentDialogCard: 'rounded-[32px] shadow-xl',
-        consentDialogHeader: 'gap-3',
-        consentWidgetFooter: 'gap-3 pt-6',
-        consentDialogTag: 'shadow-none',
-      },
-    },
-  }}
->
-  <ConsentDialog />
-</ConsentManagerProvider>
-```
-
-Dialog copy should be changed through `ConsentManagerProvider.options.i18n`, not by rebuilding the dialog structure.
-
-## Advanced: Compound Components
+## Props
 
-Use compound components only when you need custom dialog markup while still keeping c15t primitives and policy-aware footer actions:
+| Prop                      | Type                                  | Default                         | Description                                                                                                                                                                                                      |
+| ------------------------- | ------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `open`                    | `boolean`                             | follows the active surface      | Controls the open state. When set, Escape and the dialog's own Save, Accept all and Reject all buttons no longer close it; change the prop instead. A missing policy or an unlisted model still keeps it closed. |
+| `showTrigger`             | `boolean \|ConsentDialogTriggerProps` | `false`                         | Renders a floating `ConsentDialogTrigger` next to the dialog. Pass an object to configure that trigger.                                                                                                          |
+| `models`                  | `Model[]`                             | `['opt-in', 'opt-out', 'none']` | Policy models the dialog responds to. Under a model that is not listed, such as `iab`, it stays closed.                                                                                                          |
+| `legalLinks`              | `(keyof LegalLinks)[] \|null`         | none                            | Which of the links configured in the provider `options.legalLinks` render after the description. Omitting the prop renders none. `null` hides them.                                                              |
+| `hideBranding`            | `boolean`                             | `false`                         | Hides the "Secured by" tag in the card.                                                                                                                                                                          |
+| `uiSource`                | `string`                              | `'dialog'`                      | Source identifier recorded with saves made from this dialog.                                                                                                                                                     |
+| `scrollLock`, `trapFocus` | `boolean`                             | from `blocking`                 | Deprecated. Either one set to `false` makes the dialog non-blocking, unless the provider sets `presentation.preferences.blocking` explicitly, which wins. Prefer the provider option.                            |
+| `disableAnimation`        | `boolean`                             | `false`                         | Skips the enter and exit animation of the backdrop and the card.                                                                                                                                                 |
+| `noStyle`                 | `boolean`                             | `false`                         | Removes the built-in styling from every part.                                                                                                                                                                    |
+
+## Behavior
+
+The dialog is a modal wrapper around the preference center. Its card has a
+header with the title `consentManagerDialog.title` and the description
+`consentManagerDialog.description` followed by the legal links, then the
+same category accordion and Reject all, Accept all and Save actions that
+`ConsentWidget` renders, then the branding tag. It mounts through a portal
+into `document.body` after hydration, so it is never part of the server
+HTML.
+
+Without an `open` prop, the dialog follows the active surface and opens while
+it is `dialog`. These set that surface:
+
+* The Customize button on a `ConsentBanner`, and the "Manage preferences"
+  or "Do not sell or share my data" button a notice renders.
+* `ConsentDialogLink` and `ConsentDialogTrigger`.
+* The button in a `Frame` placeholder.
+* `useSetActiveUI()('dialog')` in your own component, or `openDialog()`
+  from `useHeadlessConsentUI()` on the headless subpath.
+
+The component code is split into its own chunk. It downloads when the
+dialog first opens or when a visitor hovers or focuses a Customize button,
+and renders nothing until that chunk is ready. Passing `open={true}` or
+`showTrigger` loads it on mount.
+
+Without an `open` prop, Escape closes the dialog. Save, Accept all and
+Reject all close it after the save succeeds; a save that fails keeps it
+open. With `open={true}`, these actions leave the dialog visible; the
+parent must set `open={false}` to close it. Clicking the backdrop does not
+close it. Closing discards toggles that were not saved: the next open starts
+from the recorded choice again. After a save from an uncontrolled dialog,
+every consent surface hides unless the policy still owes a prompt, in which
+case the banner returns.
+
+The preference center is blocking by default: a backdrop, body scroll lock
+and focus trap, all as one value. Set `presentation.preferences.blocking`
+to `false` in the provider options to remove all three; the deprecated
+`scrollLock` and `trapFocus` props do the same for one dialog. `variant`
+and `position` are prompt options. Setting them under
+`presentation.preferences` logs an `invalid-variant` diagnostic in
+development and changes nothing; the dialog is always centered.
+
+The dialog never opens without a resolved policy rule, even when the
+active surface is already `dialog`; it appears as soon as a rule resolves,
+without a remount. A rule with `model: 'none'` and no rights owes no consent
+UI, so the dialog stays closed under it. When such a rule lists any right,
+for example `rights: ['disclosure']` or `rights: ['preferences']`, the dialog
+can open as a settings route and Save completes without writing a consent
+record.
+
+Copy comes from these translation keys: `consentManagerDialog.title`,
+`consentManagerDialog.description`, `common.acceptAll`, `common.rejectAll`,
+`common.save`, and `consentTypes.<category>.title` and `.description` for
+each row.
+
+## Accessibility
+
+The panel carries `role="dialog"`, `aria-labelledby="consent-dialog-title"`
+and `aria-describedby="consent-dialog-description"`, plus `aria-modal="true"`
+while it is blocking. Its `dir` attribute follows the active language.
+
+While blocking, focus moves on open to the panel itself rather than to a
+button, so a screen reader announces the title and description first; Tab
+then enters the legal links and category switches, Tab and Shift+Tab wrap
+inside the panel, and on close focus returns to the element that opened the
+dialog. A non-blocking dialog manages no focus: nothing moves focus into the
+panel or back to the opener. The backdrop is `aria-hidden` and is not
+focusable.
+
+Each category switch has the category title as its accessible name. The
+`necessary` switch is disabled and always on. A saved grant that the current
+policy or a privacy signal overrides gets a note under its row, linked to
+the switch through `aria-describedby`.
+
+## Composition
+
+Every part is available as `ConsentDialog.<Part>`: `Root`, `Overlay`,
+`Card`, `Header`, `HeaderTitle`, `HeaderDescription`, `Content`, `Footer`
+and `ConsentCustomizationCard`, the stock card. `Root` provides the portal,
+open state, focus trap, scroll lock and backdrop, and accepts `open`,
+`models`, `noStyle`, `disableAnimation`, `scrollLock`, `trapFocus`,
+`uiSource` and `overlay`. Pass `overlay={false}` to render no backdrop, or a
+node to replace the built-in one.
 
 ```tsx
 <ConsentDialog.Root>
-  <ConsentDialog.Overlay />
   <ConsentDialog.Card>
     <ConsentDialog.Header>
-      <ConsentDialog.HeaderTitle />
-      <ConsentDialog.HeaderDescription />
+      <ConsentDialog.HeaderTitle>Your privacy choices</ConsentDialog.HeaderTitle>
+      <ConsentDialog.HeaderDescription legalLinks={['privacyPolicy']} />
     </ConsentDialog.Header>
     <ConsentDialog.Content>
-      <ConsentWidget.Root>
-        <ConsentWidget.Accordion type="single">
-          <ConsentWidget.AccordionItems />
-        </ConsentWidget.Accordion>
-        <ConsentWidget.PolicyActions />
-      </ConsentWidget.Root>
+      <ConsentWidget />
     </ConsentDialog.Content>
-    <ConsentDialog.Footer />
+    <ConsentDialog.Footer hideBranding />
   </ConsentDialog.Card>
 </ConsentDialog.Root>
 ```
 
-* `ConsentDialog.Root` — Portal container with focus trap, scroll lock, and animation
-* `ConsentDialog.Card` — Main dialog card
-* `ConsentDialog.Header` — Contains title and description
-* `ConsentDialog.HeaderTitle` — Dialog title
-* `ConsentDialog.HeaderDescription` — Description with optional `legalLinks`
-* `ConsentDialog.Content` — Main content area (typically contains `ConsentWidget`)
-* `ConsentDialog.Footer` — Footer with optional branding (`hideBranding` prop)
-* `ConsentDialog.Overlay` — Backdrop overlay
-* `ConsentWidget.PolicyActions` — Renders policy-aware grouped dialog actions
-
-For a quick pre-composed layout, use the shorthand card:
-
-```tsx
-<ConsentDialog.Root>
-  <ConsentDialog.ConsentCustomizationCard />
-</ConsentDialog.Root>
-```
-
-`ConsentWidget.PolicyActions` uses stock c15t widget buttons and translations by default. Pass `renderAction` only when you need to customize the action mapping, and return stock widget button compounds if you want to preserve built-in behavior and copy.
-
-For fully manual control over dialog action rendering, use `useHeadlessConsentUI()` and map `dialog.actionGroups` yourself.
-
-If the stock dialog structure still works, prefer tokens, slots, and provider configuration instead.
-
-## Props
-
-|Property|Value|
-|:--|:--|
-|Type Name|\`ConsentDialogProps\`|
-|Source Path|\`./packages/react/src/components/consent-dialog/consent-dialog.tsx\`|
-
-\*ExtractedTypeTable: Could not extract "ConsentDialogProps" from "./packages/react/src/components/consent-dialog/consent-dialog.tsx" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+Keep `ConsentWidget` inside `Content`: it owns the draft, the switches and
+the policy actions, and inherits the dialog's `uiSource`. `Footer` renders
+the branding tag unless you pass children or `hideBranding`.
+
+The positioner carries `data-slot="dialog-positioner"`, and both it and the
+panel carry `data-blocking="true"` while blocking. Provider component slots
+for the stock structure are `dialog.root`, `dialog.container`,
+`dialog.card`, `dialog.header`, `dialog.title`, `dialog.content`,
+`dialog.overlay`, `description.dialog`, `manager.footer` and `tag.dialog`.
+
+The compound parts import from `c15t/react` as properties of `ConsentDialog`,
+and `ConsentWidget` from the same module. See
+[Styling](../styling/overview.md) for slots and tokens.
+
+## Verify
+
+Use the default blocking, uncontrolled dialog and an optional in-scope
+category that is not restricted by policy or privacy signals such as GPC.
+Open the dialog from the banner's Customize button or a preferences link.
+A centered card appears over a dimmed backdrop, the page behind it stops
+scrolling, and Tab stays inside the card. Press Escape: the card closes and
+focus returns to the button you used. Open it again, turn a category on and
+choose Save. The dialog closes and `useConsent('<category>')` reports
+`true` in your components; under a choice prompt the banner does not return,
+while a `notice` prompt keeps its banner until it is acknowledged. Reload the
+page and reopen the dialog: the switch reflects the saved choice.