@c15t/nextjs 2.2.0 → 3.0.0-alpha.0

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

@@ -1,62 +1,123 @@
 ---
 title: ConsentDialogLink
-description: An inline trigger for opening the consent dialog from footers,
-  legal pages, and account settings.
+description: Open the preference center from a Next.js footer with
+  ConsentDialogLink, a Client Component that renders an unstyled button inside
+  ConsentRoot.
 group: frameworks
 ---
-`ConsentDialogLink` is an inline trigger for opening the consent dialog from places like site footers, legal pages, or account settings. It is unstyled by default, so it inherits your app's typography and link/button styles.
 
-## Basic Usage
+## Reopen the preference center from your footer
 
-```tsx
-import { ConsentDialogLink } from '@c15t/nextjs/components/consent-dialog-link';
+`ConsentDialogLink` is an unstyled button that opens the consent dialog.
+Put it where your site already keeps its legal links, so preferences stay
+reachable after the banner closes. It is a Client Component and must render
+inside the `ConsentRoot` from your
+[App Router](../app-router.md) or
+[Pages Router](../pages-router.md) setup, which also mounts
+the `ConsentDialog` it opens.
+
+```tsx title="components/site-footer.tsx"
+'use client';
+
+import Link from 'next/link';
+import { ConsentDialogLink } from 'c15t/next';
 
 export function SiteFooter() {
   return (
     <footer>
-      <ConsentDialogLink>
-        Your privacy settings
-      </ConsentDialogLink>
+      <nav aria-label="Legal">
+        <Link href="/privacy">Privacy policy</Link>
+        <Link href="/terms">Terms</Link>
+        <ConsentDialogLink className="footer-link">Privacy settings</ConsentDialogLink>
+      </nav>
     </footer>
   );
 }
 ```
 
-## Footer Link (unstyled by default)
-
-```tsx
-<footer>
-  <ConsentDialogLink>
-    Your privacy settings
-  </ConsentDialogLink>
-</footer>
-```
+Render `SiteFooter` from the root layout as a child of the `Consent`
+wrapper, in place of the inline footer the router guides show. The layout
+stays a Server Component; only this file needs `'use client'`. The link
+renders a `button`, so the CSS for `.footer-link` should reset button chrome
+if your footer styles target anchors only.
 
-## Render as an Anchor
-
-Use `asChild` to keep semantic anchor markup while still opening the dialog:
+To reuse an existing link component, pass `asChild`:
 
 ```tsx
 <ConsentDialogLink asChild>
-  <a href="#privacy-settings">Manage Preferences</a>
+  <a href="#cookie-preferences">Manage cookies</a>
 </ConsentDialogLink>
 ```
 
-## Optional Styling Control
+## Props
 
-The component defaults to `noStyle={true}`. Set it to `false` if you want c15t button styles:
+| Prop       | Type              | Default  | Description                                                                                                                                                   |
+| ---------- | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `children` | `ReactNode`       | required | The visible label, such as "Privacy settings" or "Manage preferences". It is also the accessible name.                                                        |
+| `asChild`  | `boolean`         | `false`  | Renders your own element, such as an anchor, instead of a `button`, and attaches the click handler to it.                                                     |
+| `noStyle`  | `boolean`         | `true`   | Omits c15t button classes. Native browser styles remain unless your CSS resets them. Pass `false` to render it as a consent button with `variant` and `mode`. |
+| `onClick`  | `(event) => void` | none     | Runs before the dialog opens. Call `event.preventDefault()` to keep it closed.                                                                                |
 
-```tsx
-<ConsentDialogLink noStyle={false}>
-  Privacy Settings
-</ConsentDialogLink>
-```
+Other `button` attributes such as `className`, `style`, `id` and `aria-*`
+pass through to the rendered element.
 
-## Props
+## Behavior
+
+`ConsentDialogLink` renders a `button` with `type="button"` and no c15t
+styling by default. Clicking it makes `dialog` the active surface, which opens a
+mounted `ConsentDialog`. It performs no save and does not change any
+permission.
+
+The element carries `data-c15t-rights` listing the rights of the active
+policy rule, for example `disclosure opt-out preferences` under a US
+opt-out rule and `disclosure preferences` under an opt-in rule, so a
+stylesheet or a `::after` label can adapt the wording by region.
+
+Without a resolved policy rule the link renders nothing and appears as soon
+as a rule resolves, without a remount. A rule with `model: 'none'` and an
+empty `rights` list owes no consent UI, so the link hides under it; a `none`
+rule that lists any right, such as `['disclosure']`, shows the link and the
+dialog opens as a settings route.
+
+Mount exactly one `ConsentDialog` inside the same provider. If none is
+mounted, the click still switches the active surface: nothing opens, and a
+banner that was showing closes because the surface is no longer `banner`.
+
+With `asChild`, the child's own `onClick` runs first; if it calls
+`event.preventDefault()` the dialog stays closed. c15t does not prevent the
+child's native behavior, so an anchor still follows its `href`. Use a
+fragment or the current page as the destination, or render a `button`.
+
+### ConsentDialogLink or ConsentDialogTrigger
+
+Both open the same dialog and carry `data-c15t-rights`. Use
+`ConsentDialogLink` where the control belongs in your own layout: a footer,
+a privacy page, a settings menu. It has no position, icon or visibility
+rule of its own. Use `ConsentDialogTrigger` when you want a floating,
+draggable button that positions itself in a corner and can wait until the
+prompt is answered.
+
+`ConsentDialogTrigger` has its own page: [ConsentDialogTrigger](./consent-dialog-trigger.md).
+
+## Accessibility
+
+The rendered `button` is keyboard-focusable and activates with Enter and
+Space; its accessible name is the text you pass as `children`, so give it
+words that describe the destination rather than "click here". Because the
+dialog it opens is labelled by its own title and, while blocking, returns
+focus to the link on close, no additional `aria-haspopup` or
+`aria-controls` is added; a non-blocking dialog manages no focus, so the
+link does not regain it. With `asChild`,
+focusability comes from your element: use a `button` or an anchor with an
+`href`.
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`ConsentDialogLinkProps\`|
-|Source Path|\`./packages/react/src/components/consent-preferences-link/consent-preferences-link.tsx\`|
+## Verify
 
-\*ExtractedTypeTable: Could not extract "ConsentDialogLinkProps" from "./packages/react/src/components/consent-preferences-link/consent-preferences-link.tsx" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+Scroll to the footer. With the footer button reset applied, the link uses
+your footer's text styles and has no button chrome. Activate it with a click or with Enter: the preference
+center opens as a centered dialog. Close it with Escape: with the default
+blocking dialog, focus returns to the link. In your browser's element
+inspector the link has
+`data-c15t-rights`; change the visitor's region to a US opt-out rule and
+the value includes `opt-out`. Under a rule with `model: 'none'` and no
+rights, the link is absent.

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

@@ -1,44 +1,54 @@
 ---
 title: ConsentDialogTrigger
-description: A floating, draggable button that lets users re-open the consent
-  dialog at any time.
+description: Add the floating ConsentDialogTrigger button or toolbar to a
+  Next.js ConsentRoot so visitors can reopen the preference center.
 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/nextjs';
+Keep the boundary, stylesheet and transport from your
+[router setup](../quickstart.md). Add this component as a child
+of the existing boundary, alongside its banner and dialog:
+
+```tsx title="components/privacy-trigger.tsx"
+'use client';
 
-// Standalone
-<ConsentDialogTrigger />
+import { ConsentDialogTrigger } from 'c15t/next';
 
-// Via ConsentDialog
-<ConsentDialog showTrigger />
+export function PrivacyTrigger() {
+  return <ConsentDialogTrigger showWhen="after-prompt" />;
+}
 ```
 
-For inline footer links (instead of a floating button), use [`ConsentDialogLink`](/docs/frameworks/next/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 `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.
 
-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.
+This partial example belongs in a Client Component inside the existing boundary.
+Define the theme state, icons and callbacks in that component.
 
 ```tsx
+import { ConsentDialogTriggerToolbar } from 'c15t/next';
+
 <ConsentDialogTriggerToolbar
   ariaLabel="Site controls"
   actions={[
@@ -63,140 +73,55 @@ 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.
-
-Toolbars are horizontal by default. Set `orientation="vertical"` to stack the actions and enable Up/Down arrow-key navigation:
-
-```tsx
-<ConsentDialogTriggerToolbar
-  orientation="vertical"
-  actions={toolbarActions}
-/>
-```
-
-### 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.
-
-```tsx
-<ConsentManagerProvider
-  options={{
-    theme: {
-      slots: {
-        consentDialogTriggerToolbar: 'my-toolbar',
-        consentDialogTriggerToolbarItem: 'my-toolbar-item',
-        consentDialogTriggerToolbarIcon: 'my-toolbar-icon',
-      },
-    },
-  }}
->
-  <ConsentDialogTriggerToolbar
-    className="fixed-toolbar"
-    style={{ '--cdtt-offset': '24px' }}
-    actions={[
-      {
-        id: 'support',
-        label: 'Open support chat',
-        icon: <ChatIcon />,
-        onSelect: openSupportChat,
-        className: 'support-action',
-      },
-    ]}
-  />
-</ConsentManagerProvider>
-```
-
-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:
+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.
 
-```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
+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.
 
-Set the default corner and control persistence:
+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.
 
-```tsx
-<ConsentDialogTrigger
-  defaultPosition="bottom-left"
-  persistPosition={true} // Remembers user's drag position
-  onPositionChange={(position) => console.log('Moved to:', position)}
-/>
-```
+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.
 
-## Size
+Toolbars are horizontal by default. Set `orientation="vertical"` to stack the actions and switch arrow-key navigation to up and down:
 
 ```tsx
-<ConsentDialogTrigger size="sm" /> {/* Small */}
-<ConsentDialogTrigger size="md" /> {/* Medium (default) */}
-<ConsentDialogTrigger size="lg" /> {/* Large */}
+<ConsentDialogTriggerToolbar orientation="vertical" actions={toolbarActions} />
 ```
 
-## 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>
+### 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 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.
+
+Add these slot values to `options.components` on your existing
+`ConsentRoot` or `ConsentProvider`. Merge them with any existing component
+slots and retain the configured transport:
+
+```ts
+const triggerSlots = {
+  toolbar: { className: 'my-toolbar' },
+  toolbarItem: { className: 'my-toolbar-item' },
+  toolbarIcon: { className: 'my-toolbar-icon' },
+};
+
+// In the existing options.components object:
+// trigger: triggerSlots
 ```
 
-* `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\`|
+For one toolbar, pass `className="fixed-toolbar"` directly. Each app-owned
+item also accepts `className`, such as `className: 'support-action'` on your
+support action. Keep its icon and callback in the Client Component.
 
-\*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.