@c15t/nextjs 2.2.1 → 3.0.0-alpha.0

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

@@ -1,169 +1,224 @@
 ---
 title: ConsentDialog
-description: A modal dialog where users can toggle individual consent categories.
+description: Mount ConsentDialog as a Client Component inside a Next.js
+  ConsentRoot to open the preference center from the banner, links and triggers.
 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/nextjs';
-
-export function ConsentManager() {
+## Open the preference center
+
+`ConsentDialog` is the modal preference center. It is a Client Component, so
+it lives in the `components/consent.tsx` wrapper from the
+[App Router](../app-router.md) or
+[Pages Router](../pages-router.md) setup, inside the
+`ConsentRoot` that already provides the consent runtime. Mount it once,
+next to the banner; 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="components/consent.tsx"
+'use client';
+
+import type { ReactNode } from 'react';
+import {
+  ConsentBanner,
+  ConsentDialog,
+  ConsentDialogLink,
+  ConsentRoot,
+} from 'c15t/next';
+import type { ConsentRootProps } from 'c15t/next';
+import { consentConfig } from '../c15t.config';
+
+export function Consent({
+  children,
+  state,
+}: {
+  children: ReactNode;
+  state: ConsentRootProps['state'];
+}) {
   return (
-    <ConsentManagerProvider options={{ mode: 'hosted', backendURL: '/api/c15t' }}>
+    <ConsentRoot state={state} config={consentConfig}>
+      {children}
       <ConsentBanner />
-      <ConsentDialog />
-    </ConsentManagerProvider>
+      <ConsentDialog hideBranding />
+      <footer>
+        <ConsentDialogLink>Privacy settings</ConsentDialogLink>
+      </footer>
+    </ConsentRoot>
   );
 }
 ```
 
-## Controlled State
+The root layout renders `Consent` with the `state` from
+`resolveConsent`, as in the router guides. The dialog itself renders
+nothing on the server: it mounts through a portal after hydration, so the
+server HTML and the streamed shell are unaffected by it. If the visitor owes
+a choice or notice, routes that await `resolveConsent` can render the
+banner on the server. Pages Router pages without `getServerSideProps` show it
+after browser policy resolution. No banner appears when the policy requires
+no prompt or an existing record already satisfies it.
 
-By default, the dialog follows `activeUI === 'dialog'` from the consent store. Use the `open` prop for manual control:
+To open it from another Client Component inside the boundary, set the active
+surface:
 
-```tsx
-import { useState } from 'react';
+```tsx title="components/privacy-menu-item.tsx"
+'use client';
 
-function SettingsPage() {
-  const [open, setOpen] = useState(false);
+import { useSetActiveUI } from 'c15t/next';
 
+export function PrivacyMenuItem() {
+  const setActiveUI = useSetActiveUI();
   return (
-    <>
-      <button onClick={() => setOpen(true)}>Privacy Settings</button>
-      <ConsentDialog open={open} />
-    </>
-  );
-}
-```
-
-Or use the hook to open it programmatically:
-
-```tsx
-import { useConsentManager } from '@c15t/nextjs';
-
-function PrivacyLink() {
-  const { setActiveUI } = useConsentManager();
-
-  return (
-    <button onClick={() => setActiveUI('dialog')}>
-      Manage cookies
+    <button type="button" onClick={() => setActiveUI('dialog')}>
+      Cookie preferences
     </button>
   );
 }
 ```
 
-## Floating Trigger
-
-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>
-```
+`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.
 
-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/next` as properties of `ConsentDialog`,
+and `ConsentWidget` from the same module. Server Components cannot render
+them: keep the composition in a file with `'use client'`. 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.