@c15t/react 2.2.1 → 3.0.0-alpha.1

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

@@ -1,258 +1,275 @@
 ---
 title: ConsentBanner
-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.
+description: Pre-built consent banner shown when consent is required.
 group: frameworks
 ---
-`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.
 
-## Basic Usage
+## Usage
 
 ```tsx
-import { ConsentManagerProvider, ConsentBanner } from '@c15t/react';
-
-export function ConsentManager() {
-  return (
-    <ConsentManagerProvider options={{ mode: 'hosted', backendURL: 'https://your-instance.c15t.dev' }}>
-      <ConsentBanner />
-    </ConsentManagerProvider>
-  );
+import { ConsentBanner, ConsentDialog, ConsentProvider, offline } from 'c15t/react';
+import { policyRulePresets } from '@c15t/schema';
+
+const mode = offline({ policyRules: [policyRulePresets.europeOptIn()] });
+
+export function Consent({ children }: { children: React.ReactNode }) {
+	return (
+		<ConsentProvider options={{ mode }}>
+			{children}
+			<ConsentBanner />
+			<ConsentDialog />
+		</ConsentProvider>
+	);
 }
 ```
 
-## Button Layout
+The banner renders whatever the active policy rule requires. It reads the rule
+through the provider, so the same component serves every region:
+
+* A `choice` prompt shows the actions the rule allows: reject and accept at
+  equal prominence, plus customize when the rule offers it.
+* A `notice` prompt shows an "OK" button and a button styled as
+  underlined text, labeled "Do not sell or share my data". The latter opens
+  preferences. A notice never traps focus or locks scroll.
+* A rule with `prompt: 'none'` renders nothing.
+
+An opt-out rule with `prompt: 'none'` still has rights, so the preference
+center and the dialog trigger stay available as the route to preferences. A
+rule with `model: 'none'` owes no rights, so nothing renders unless you add
+`rights: ['preferences']`. With no resolved rule at all, because resolution
+failed, no rule matched and you set no default, or init is still withheld, no
+consent surface renders: not the banner, the dialog, the widget, the
+preferences link, or the trigger. They appear as soon as a rule resolves,
+without a remount. `offline()` without `policyRules` resolves the recommended
+pack, so it shows the strict opt-in banner until you pass a country.
+
+Acknowledging a notice records its dismissal. It does not record consent or
+change category permissions, including existing denials and privacy-signal
+restrictions. Customize the label through `common.acknowledge` in your
+translations, or use `dismissButtonText` for one banner.
+
+The additional preferences button uses the opt-out label when appropriate.
+A choice prompt without Customize renders a "Manage preferences" button.
+Both are button elements that open the preference center; CSS gives them
+an underlined text appearance. They do not submit an opt-out by themselves.
+
+`preferenceControls` recommends these extra buttons for the stock UI.
+It does not verify disclosure or access to rights. Configure your legal links
+and keep preferences reachable after the banner closes.
 
-The `layout` prop controls button arrangement. Each item is either a button ID or an array of button IDs (which groups them together):
-
-```tsx
-{/* Default: reject and accept grouped, customize separate */}
-<ConsentBanner layout={[['reject', 'accept'], 'customize']} />
-
-{/* All buttons in one group */}
-<ConsentBanner layout={[['reject', 'customize', 'accept']]} />
-
-{/* Accept first, then reject and customize grouped */}
-<ConsentBanner layout={['accept', ['reject', 'customize']]} />
-```
+## Props
 
-To stack groups vertically, pair the same grouped layout with `direction="column"`:
+| Prop                  | Type                                          | Default              | Description                                                                                          |
+| --------------------- | --------------------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------- |
+| `title`               | `ReactNode`                                   | translation          | Overrides the title. Under a notice the default is `cookieBanner.noticeTitle`.                       |
+| `description`         | `ReactNode`                                   | translation          | Overrides the description. Under a notice the default is `cookieBanner.noticeDescription`.           |
+| `acceptButtonText`    | `ReactNode`                                   | `common.acceptAll`   | Accept label.                                                                                        |
+| `rejectButtonText`    | `ReactNode`                                   | `common.rejectAll`   | Reject label.                                                                                        |
+| `customizeButtonText` | `ReactNode`                                   | `common.customize`   | Customize label.                                                                                     |
+| `dismissButtonText`   | `ReactNode`                                   | `common.acknowledge` | Label of the notice acknowledgement.                                                                 |
+| `variant`             | `PromptVariant`                               | `floating`           | Shape of the prompt. See [Variants](#variants).                                                      |
+| `position`            | `PromptPosition`                              | per variant          | Where the prompt sits. Must be valid for the variant.                                                |
+| `blocking`            | `boolean`                                     | `true` on `wall`     | Backdrop, scroll lock, focus trap, and no outside dismissal, as one value.                           |
+| `layout`              | `ConsentBannerLayout`                         | policy default       | Orders and groups actions. Required actions the layout omits are restored.                           |
+| `primaryButton`       | `ConsentBannerButton \|ConsentBannerButton[]` | `'customize'`        | Which actions get the primary treatment. On a notice, dismiss is primary when it is the only action. |
+| `direction`           | `'row' \|'column'`                            | `'row'`              | How action groups flow.                                                                              |
+| `legalLinks`          | `(keyof LegalLinks)[] \|null`                 | none                 | Which configured legal links render inline.                                                          |
+| `hideBranding`        | `boolean`                                     | `false`              | Hides the "Secured by" tag.                                                                          |
+| `scrollLock`          | `boolean`                                     | unset                | Deprecated. Use `blocking` to control scrolling, focus and backdrop together.                        |
+| `trapFocus`           | `boolean`                                     | unset                | Deprecated. Use `blocking`.                                                                          |
+| `disableAnimation`    | `boolean`                                     | `false`              | Skips enter and exit animations.                                                                     |
+| `noStyle`             | `boolean`                                     | `false`              | Removes the built-in styling from every part.                                                        |
+
+## Per-policy buttons
+
+The default already makes Customize primary on a choice banner and OK
+primary on a notice. To set button order and treatment for specific rules,
+read the active policy inside the provider:
 
 ```tsx
-<ConsentBanner
-  layout={['customize', ['reject', 'accept']]}
-  direction="column"
-/>
+import { ConsentBanner, usePolicyRule } from 'c15t/react';
+import type { ConsentBannerProps } from 'c15t/react';
+
+const banners: Record<
+	string,
+	Pick<ConsentBannerProps, 'layout' | 'primaryButton' | 'variant'>
+> = {
+	europe_opt_in: {
+		layout: [['reject', 'accept'], 'customize'],
+		primaryButton: 'customize',
+	},
+	us_privacy_states: {
+		layout: ['dismiss'],
+		primaryButton: 'dismiss',
+		variant: 'bar',
+	},
+};
+
+export function RegionalBanner() {
+	const policy = usePolicyRule();
+	return <ConsentBanner {...(policy ? banners[policy.id] : undefined)} />;
+}
 ```
 
-## Policy-Driven UI Profile
-
-When using backend runtime policies, `policy.ui.uiProfile` can control banner action presentation:
-
-* `compact` — default desktop sizing
-* `balanced` — auto-fills compact and grouped layouts with moderate emphasis
-* `strict` — always fills action controls for explicit, high-clarity layouts
-
-## Theme-Level Button Styling
-
-Use the provider `theme` prop to control how stock consent actions look:
-
-```tsx
-<ConsentManagerProvider
-  options={{
-    theme: {
-      consentActions: {
-        default: { mode: 'stroke' },
-        accept: { variant: 'primary', mode: 'stroke' },
-        customize: { variant: 'neutral', mode: 'ghost' },
-      },
-    },
-  }}
->
-  <ConsentBanner />
-</ConsentManagerProvider>
+Render `RegionalBanner` inside `ConsentProvider`. The layout controls the
+action groups; the opt-out preferences button still appears on a notice.
+Required actions omitted from a layout are restored. Accept and Reject
+keep equivalent default prominence.
+
+Choose one brand color and make whichever action is primary use a filled
+button through the provider's theme:
+
+```ts
+const theme = {
+	colors: { primary: '#2f6f4e', primaryHover: '#24563c' },
+	consentActions: {
+		primary: { variant: 'primary', mode: 'filled' },
+	},
+} as const;
 ```
 
-Policy packs control grouping, ordering, and direction. The theme controls button appearance.
-
-## Styling First
+Pass `theme` in `ConsentProvider` options. Per-action theme overrides such
+as `consentActions.dismiss` take precedence over this primary style.
+See [Styling](../styling/overview.md) for tokens and slots, and
+[Policy presets](../concepts/policy-presets.md) for the rule IDs and coverage.
 
-> ℹ️ **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.
+## Variants
 
-The stock banner maps common visual changes to the theme system:
+The policy decides which actions the banner offers. The variant decides the
+shape those actions take. Both come from the same component, so a bar for a
+notice region and a card for an opt-in region need no extra components.
 
-* Card background -> `theme.colors.surface`
-* Footer background -> `theme.colors.surfaceHover`
-* Card, footer, and title tweaks -> `theme.slots.consentBannerCard`, `consentBannerFooter`, and `consentBannerTitle`
+Set the variant on the banner, or on the provider under
+`presentation.prompt` when every banner should share it. The prop wins.
 
 ```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>
+<ConsentBanner variant="floating" position="bottom-center" />
 ```
 
-### Primary Button
-
-Highlight specific button(s) as the primary action:
+A floating card in a corner or centered on an edge. This is the default for
+every prompt. A notice keeps the same card, with its right link and "OK" in the footer.
 
 ```tsx
-{/* Single primary */}
-<ConsentBanner primaryButton="accept" />
-
-{/* Multiple primaries */}
-<ConsentBanner primaryButton={['accept', 'customize']} />
+<ConsentBanner variant="bar" position="top" />
 ```
 
-## Legal Links
-
-Control which legal links appear in the banner description:
+A bar across the full width of the viewport. From 1024px wide the text, the
+right links, and the controls share one row. Opt in to it for regions that
+expect a classic cookie bar.
 
 ```tsx
-{/* Show all configured links (default) */}
-<ConsentBanner legalLinks={undefined} />
-
-{/* Show no links */}
-<ConsentBanner legalLinks={null} />
-
-{/* Show specific links */}
-<ConsentBanner legalLinks={['privacyPolicy', 'cookiePolicy']} />
+<ConsentBanner variant="widget" position="bottom-right" />
 ```
 
-> ℹ️ **Info:**
-> Legal link URLs are configured in the ConsentManagerProvider options via the legalLinks prop, not on the banner itself.
-
-## Customizing Copy
-
-Prefer provider `i18n` when you want to rename the stock banner content:
+A compact card with smaller type. The full description and its legal links
+remain visible. Pair it with a short notice.
 
 ```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>
+<ConsentBanner variant="wall" />
 ```
 
-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.
+A centered card over a backdrop that blocks the page until the visitor
+answers. A wall is always blocking.
 
-## Advanced: Compound Components
+Each variant accepts its own positions:
 
-Use compound components only when the stock banner structure is no longer enough and you need to rearrange existing c15t primitives while keeping policy-driven action grouping and emphasis:
+| Variant    | Positions                                                                             | Default        |
+| ---------- | ------------------------------------------------------------------------------------- | -------------- |
+| `floating` | `bottom-left`, `bottom-right`, `top-left`, `top-right`, `bottom-center`, `top-center` | `bottom-left`  |
+| `bar`      | `top`, `bottom`                                                                       | `bottom`       |
+| `widget`   | `bottom-left`, `bottom-right`, `top-left`, `top-right`                                | `bottom-right` |
+| `wall`     | `center`                                                                              | `center`       |
 
-```tsx
-<ConsentBanner.Root>
-  <ConsentBanner.Overlay />
-  <ConsentBanner.Card>
-    <ConsentBanner.Header>
-      <ConsentBanner.Title />
-      <ConsentBanner.Description />
-    </ConsentBanner.Header>
-    <ConsentBanner.PolicyActions />
-  </ConsentBanner.Card>
-</ConsentBanner.Root>
-```
+A default corner mirrors left and right for right-to-left languages. A
+position you set is never mirrored. A position that is not valid for the
+variant falls back to the default and logs an `invalid-position` diagnostic
+in development.
 
-* `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.Description` — Description text, supports `legalLinks` prop
-* `ConsentBanner.PolicyActions` — Renders policy-aware grouped actions inside the banner footer
-* `ConsentBanner.Footer` — Action buttons container
-* `ConsentBanner.FooterSubGroup` — Groups related buttons together
-* `ConsentBanner.RejectButton` — Rejects all consent
-* `ConsentBanner.CustomizeButton` — Opens the consent dialog
-* `ConsentBanner.AcceptButton` — Accepts all consent
-* `ConsentBanner.Overlay` — Optional backdrop overlay
-
-For a fixed layout that intentionally ignores policy grouping, render the footer manually:
+`blocking` controls the backdrop, scroll lock, and focus trap together.
+An explicit value overrides the deprecated `scrollLock` and `trapFocus`
+options. Without `blocking`, either legacy option set to `false` selects
+non-blocking behavior; otherwise a legacy `true` selects blocking behavior.
 
-```tsx
-<ConsentBanner.Root>
-  <ConsentBanner.Card>
-    <ConsentBanner.Header>
-      <ConsentBanner.Title />
-      <ConsentBanner.Description />
-    </ConsentBanner.Header>
-    <ConsentBanner.Footer>
-      <ConsentBanner.FooterSubGroup>
-        <ConsentBanner.RejectButton />
-        <ConsentBanner.AcceptButton />
-      </ConsentBanner.FooterSubGroup>
-      <ConsentBanner.CustomizeButton />
-    </ConsentBanner.Footer>
-  </ConsentBanner.Card>
-</ConsentBanner.Root>
-```
+A choice `wall` always blocks. Notices always stay non-blocking, and asking
+for a notice `wall` falls back to `floating` with an `invalid-variant`
+diagnostic. Blocking banners carry `role="dialog"` and `aria-modal="true"`.
+Non-blocking banners leave page controls usable by keyboard and pointer.
 
-## Using `renderAction` with c15t Defaults
+`PromptVariant` and `PromptPosition` are exported from `c15t/react`.
+Compound parts can read the resolved shape with `useConsentBannerSurface()`,
+which returns `variant`, `position`, `positionSource` (`host` or `default`),
+and `blocking`.
 
-`ConsentBanner.PolicyActions` renders stock c15t buttons and translations by default.
+## Composition
+
+Every part is available as `ConsentBanner.<Part>` for custom layouts. The
+parts read the same policy state the pre-built banner does, so a custom layout
+still gets the right actions for the active rule.
 
 ```tsx
-<ConsentBanner.PolicyActions />
+import { ConsentBanner } from 'c15t/react';
+
+export function CompactBanner() {
+	return (
+		<ConsentBanner.Root>
+			<ConsentBanner.Card>
+				<ConsentBanner.Header>
+					<ConsentBanner.Title />
+					<ConsentBanner.Description />
+				</ConsentBanner.Header>
+				<ConsentBanner.PolicyActions />
+			</ConsentBanner.Card>
+		</ConsentBanner.Root>
+	);
+}
 ```
 
-`renderAction` is optional. When you want custom mapping but still want the built-in c15t button behavior and copy, return the stock button compounds:
+`ConsentBanner.PolicyActions` renders the resolved action groups and, before
+them, the additional preferences buttons. Pass children to replace those
+buttons while retaining the policy action groups. This supports custom labels
+and button markup.
+
+Use the individual parts when you need a different order or your own markup:
+
+* `ConsentBanner.AcceptButton`, `ConsentBanner.RejectButton`,
+  `ConsentBanner.CustomizeButton`, and `ConsentBanner.DismissButton` render one
+  action each. `DismissButton` defaults its label to `common.acknowledge`.
+* `ConsentBanner.Rights` renders the additional preferences buttons. It
+  renders nothing when the list is empty. Pass `rights` to override the
+  list.
+* `ConsentBanner.RightLink` renders a single right. `right` is `'opt-out'`
+  or `'preferences'`. By default it is a button element styled as an
+  underlined text link, carrying `data-action="right"` and `data-right`; it
+  opens the preference center on click and accepts `asChild` to render your
+  own element, such as an anchor to a dedicated opt-out page.
 
 ```tsx
-<ConsentBanner.PolicyActions
-renderAction={(action, props) => {
-  const { key, ...buttonProps } = props
-
-  switch (action) {
-    case 'accept':
-        return <ConsentBanner.AcceptButton key={key} {...buttonProps} />
-    case 'reject':
-        return <ConsentBanner.RejectButton key={key} {...buttonProps} />
-    case 'customize':
-        return <ConsentBanner.CustomizeButton key={key} {...buttonProps} />
-  }
-}}
-/>
+<ConsentBanner.Rights>
+	<ConsentBanner.RightLink right="opt-out" asChild>
+		<a href="/privacy/do-not-sell">Do not sell or share my data</a>
+	</ConsentBanner.RightLink>
+</ConsentBanner.Rights>
 ```
 
-`renderAction` is still meant for stock button compounds. If you want completely custom button elements and click handling, use `useHeadlessConsentUI()` and render `banner.actionGroups` manually instead of `ConsentBanner.PolicyActions`.
+`useBannerCopy()` returns the title, description, and prompt kind the banner
+would use, for custom headers that still follow the notice copy.
 
-If you only need styling changes, stay with tokens and slots instead of rebuilding the banner layout.
+## Data attributes
 
-## Props
+The root element carries attributes you can target from CSS or Tailwind. The
+card carries `data-state` (`open` or `closed`) for the enter and exit
+animations.
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`ConsentBannerProps\`|
-|Source Path|\`./packages/react/src/components/consent-banner/consent-banner.tsx\`|
+| Attribute       | Values                                |
+| --------------- | ------------------------------------- |
+| `data-prompt`   | `choice`, `notice`                    |
+| `data-model`    | `opt-in`, `opt-out`, `iab`            |
+| `data-variant`  | `floating`, `bar`, `widget`, `wall`   |
+| `data-position` | The resolved position for the variant |
+| `data-blocking` | `true`, present only while blocking   |
 
-\*ExtractedTypeTable: Could not extract "ConsentBannerProps" from "./packages/react/src/components/consent-banner/consent-banner.tsx" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+Each action button carries `data-action`, and each right link carries
+`data-action="right"` plus `data-right`. The built-in stylesheet keys every
+variant's geometry on `data-variant` and `data-position`, and uses
+`data-prompt="notice"` to lay the footer out as one row with the right
+links leading and "OK" trailing.

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

@@ -1,62 +1,115 @@
 ---
 title: ConsentDialogLink
-description: An inline trigger for opening the consent dialog from footers,
-  legal pages, and account settings.
+description: Add a ConsentDialogLink to a React footer so visitors reopen the
+  c15t preference center from your own text link, with asChild and rights data.
 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/react/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 needs a mounted `ConsentDialog` in the
+same `ConsentProvider`; the [quickstart](../quickstart.md) mounts both.
+
+```tsx title="src/site-footer.tsx"
+import { ConsentDialogLink } from 'c15t/react';
 
 export function SiteFooter() {
   return (
     <footer>
-      <ConsentDialogLink>
-        Your privacy settings
-      </ConsentDialogLink>
+      <nav aria-label="Legal">
+        <a href="/privacy">Privacy policy</a>
+        <a href="/terms">Terms</a>
+        <ConsentDialogLink className="footer-link">Privacy settings</ConsentDialogLink>
+      </nav>
     </footer>
   );
 }
 ```
 
-## Footer Link (unstyled by default)
-
-```tsx
-<footer>
-  <ConsentDialogLink>
-    Your privacy settings
-  </ConsentDialogLink>
-</footer>
-```
-
-## Render as an Anchor
+Render `SiteFooter` inside the `Consent` wrapper from your quickstart so the
+link can reach the provider. It renders a `button`, so the CSS for
+`.footer-link` should reset button chrome if your footer styles target
+anchors only.
 
-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.