@c15t/react 3.0.0-alpha.1 → 3.0.0-alpha.11

package/docs/frameworks/react/customize.md

@@ -0,0 +1,258 @@
+---
+title: Customize
+description: Change the colors, fonts, layout, button styles and copy of the
+  c15t banner and dialog in a React app with theme tokens, provider options and
+  slots, and load the stylesheet yourself when you need to.
+group: frameworks
+---
+
+## Pick the right tool
+
+| Change                               | Use                                                                 |
+| ------------------------------------ | ------------------------------------------------------------------- |
+| Brand colors, fonts, radius, spacing | [Theme tokens](#change-colors-fonts-and-radius)                     |
+| Light and dark colors, animation     | [Dark mode and motion](#turn-on-dark-mode-and-change-motion)        |
+| Which button is filled or outlined   | [`consentActions`](#style-the-action-buttons)                       |
+| Banner shape and position            | [`ConsentBanner` props or `presentation`](#change-the-banner-shape) |
+| One element of a component           | [Component parts](#style-one-component-part)                        |
+| Labels and languages                 | [Copy and translations](#change-the-copy)                           |
+| Different markup entirely            | [Headless](./headless.md)                                           |
+
+[Customization](../../customization/overview.md) explains how these choices relate
+across frameworks.
+
+See the [design gallery](../../customization/recipes.md) for five banner designs,
+from a bottom bar to a fully custom one, with tested code for this framework.
+
+## Import the stylesheet yourself
+
+A React app imports no c15t stylesheet. `ConsentBanner`, `ConsentDialog` and
+the other stock components render the rules they use as `<style>` elements.
+
+Import the stylesheet yourself with Tailwind CSS 3, to put c15t's rules in a
+named cascade layer. Set `styles: false` in the provider
+options, so the components add no second copy, and import the stylesheet once
+in the module that renders `ConsentProvider`:
+
+```tsx title="src/consent.tsx (partial)"
+import 'c15t/react/styles.css';
+
+// In the ConsentProvider options:
+styles: false,
+```
+
+To import the stylesheet from CSS instead, put it at the top of your global
+stylesheet, above any `@tailwind` directives. `postcss-import`, which Vite
+uses, ignores an `@import` that follows other rules. Tailwind 3 also needs a
+PostCSS plugin;
+[Tailwind CSS](../../customization/tailwind.md#set-up-tailwind-css-3) shows the
+setup.
+
+## Change colors, fonts and radius
+
+Colors, radii, shadows, typography, and motion come from `--c15t-*` custom
+properties. The rules the components render set the default values, as
+does `styles.css` when you import it with `styles: false`. To change them,
+render `ConsentTheme` with your theme where your app renders on the server,
+or override the variables directly in your CSS.
+
+`ConsentTheme` renders a `<style id="c15t-theme">` element with the
+variables for `theme`. It is not a client component: rendered from a Server
+Component or another server-only file, the theme generator stays out of the
+browser bundle. Rendered from a client component it still works, but the
+browser downloads the generator (about 1.7 KB gzip). The provider no longer
+turns `theme` tokens into CSS. It still reads `consentActions` and slot
+styles from its `theme` option, and warns in development when `theme` holds
+tokens but the page has no `c15t-theme` stylesheet.
+
+| `ConsentTheme` prop | Purpose                                                                                                                                                                                     |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `theme`             | Colors, `dark` colors, typography, spacing, radius, shadows and motion. Defaults to the built-in theme.                                                                                     |
+| `colorScheme`       | `'dark'` makes the dark tokens the default before hydration. `'system'` follows `prefers-color-scheme` with a CSS media query. Omit it to follow a `dark` or `c15t-dark` class on `<html>`. |
+| `nonce`             | Content Security Policy nonce for the `<style>` element.                                                                                                                                    |
+
+Pass the same `colorScheme` to `ConsentTheme` and to the provider. If your
+app manages dark mode through a root class, such as next-themes' `dark`
+class, omit `colorScheme` and include that class in the server HTML.
+[Dark mode](../../customization/dark-mode.md) covers `theme.dark`, `null` and
+a dark first paint.
+
+To switch between different token sets at runtime, render `ConsentTheme`
+from a client component and change its props, which ships the generator.
+
+Outside a component, call `generateThemeCSS(theme, colorScheme)` from
+`c15t/react/utils`, or `@c15t/react/utils` with the scoped package. It
+writes the same CSS as `ConsentTheme`. Outside React, import it from
+`@c15t/ui/theme`. Call it on the server or at build time and put the result in a
+`<style>` element or your stylesheet. It escapes `<`, so the result is safe
+inside `<style>`.
+
+A single-page app has no server render, so pick one of two ways:
+
+* **Set the variables in your CSS.** Nothing extra ships to the browser:
+
+  ```css title="src/index.css"
+  :root {
+    --c15t-primary: #2f6f4e;
+    --c15t-primary-hover: #24563c;
+    --c15t-text-on-primary: #fff;
+    --c15t-radius-lg: 4px;
+  }
+  ```
+
+* **Render `ConsentTheme` next to the provider.** Use this when the theme lives
+  in TypeScript or changes at runtime. The browser downloads the theme
+  generator.
+
+  ```tsx title="src/consent-theme.ts"
+  import { defineTheme } from 'c15t/react';
+
+  export const theme = defineTheme({
+    colors: { primary: '#2f6f4e', primaryHover: '#24563c' },
+    radius: { lg: '4px' },
+  });
+  ```
+
+  In `src/consent.tsx`, render `<ConsentTheme theme={theme} />` from
+  `c15t/react` just before `<ConsentProvider>`.
+
+In a server-rendered app, such as React Router framework mode, render
+`ConsentTheme` in the root component so the `<style>` element is part of the
+server HTML. [Theme tokens](../../customization/tokens.md) lists every variable.
+
+`ConsentTheme` outranks a plain `:root` rule, wherever each one loads. If you
+use both, a variable set in both places takes the `ConsentTheme` value. Write
+your CSS overrides on `:root:root` to beat it, or move the values into the
+theme.
+
+## Style the action buttons
+
+`consentActions` decides how each action looks. `default` applies to every
+button, `primary` to the action the policy or your props mark primary, and
+`accept`, `reject`, `customize` and `dismiss` to one action each. Pass it
+through the provider's `theme` option:
+
+```tsx title="src/consent.tsx"
+<ConsentProvider
+  options={{
+    mode,
+    scripts,
+    theme: {
+      consentActions: {
+        primary: { variant: 'primary', mode: 'filled' },
+        dismiss: { variant: 'neutral', mode: 'stroke' },
+      },
+    },
+  }}
+>
+```
+
+The provider's `theme` option only reads `consentActions` and slot styles.
+Tokens passed there do nothing, and the provider logs a warning in development.
+Changing button styles does not change the policy or expire a saved choice.
+
+## Change the banner shape
+
+`ConsentBanner` takes `variant` (`floating`, `bar`, `widget` or `wall`) and
+`position`. To use one shape everywhere, set `presentation.prompt` in the
+provider options instead. This banner is a full-width bar for notices and a
+card for choices:
+
+```tsx title="src/regional-banner.tsx"
+import { ConsentBanner, usePolicyRule } from 'c15t/react';
+
+export function RegionalBanner() {
+	const policy = usePolicyRule();
+	return (
+		<ConsentBanner variant={policy?.prompt === 'notice' ? 'bar' : 'floating'} />
+	);
+}
+```
+
+Render `RegionalBanner` in place of `ConsentBanner` inside the provider.
+[ConsentBanner](./components/consent-banner.md#variants)
+lists every variant and position, and how to order buttons per policy.
+
+## Style one component part
+
+Each component part is a slot. Set slots in the provider options under
+`components`, keyed by component and part. A slot takes any attribute the
+element accepts, such as `className` or `style`.
+
+The root also carries `data-variant`, so you can restyle one shape without
+touching the others. Tailwind, giving a `bar` a brand-colored top edge and
+tighter text:
+
+```tsx
+<ConsentProvider
+	options={{
+		mode,
+		presentation: { prompt: { variant: 'bar' } },
+		components: {
+			banner: {
+				root: { className: 'group' },
+				card: {
+					className:
+						'group-data-[variant=bar]:border-t-4 group-data-[variant=bar]:border-t-emerald-600',
+				},
+			},
+			description: {
+				banner: { className: 'group-data-[variant=bar]:text-xs' },
+			},
+		},
+	}}
+/>
+```
+
+`data-variant` sits on the root, so child slots use Tailwind's `group`
+prefix to read it.
+
+[Class names and CSS-in-JS](../../customization/class-names.md) shows CSS
+Modules, vanilla-extract, StyleX and Emotion classes on a part.
+
+Set `noStyle` on a component to drop the built-in classes from every part and
+keep only what your slots pass. Set `noStyle` in the provider options to do it
+for every component.
+
+[Component parts](../../customization/slots.md) lists every part key under
+`components` and the `data-*` attributes each part carries. Action buttons
+carry `data-action`, so a single rule such as `[data-action='dismiss']`
+styles one role across every surface. Right links are underlined text by
+default, so the only button on a notice is the primary action.
+
+[Component parts](../../customization/slots.md) lists every component's part keys
+and when to drop the built-in styles with `noStyle`. The `ConsentGate`
+placeholder's parts are `components['consent-gate'].root`, `.title` and
+`.button`.
+[Class names and CSS-in-JS](../../customization/class-names.md) covers CSS
+Modules, vanilla-extract, StyleX and Emotion, and
+[Tailwind CSS](../../customization/tailwind.md) covers utilities on parts.
+
+## Turn on dark mode and change motion
+
+Pass `colorScheme` in the provider options and the same value to
+`ConsentTheme`. Leave it unset to follow a `dark` class on `<html>`, and add
+dark colors with `theme.dark`. [Dark mode](../../customization/dark-mode.md)
+covers each value and a dark first paint.
+
+`disableAnimation` in the provider options turns off the banner and dialog
+animations, and the same prop on `ConsentBanner` or `ConsentDialog` overrides
+it for one surface. [Motion and animation](../../customization/motion.md) covers
+the duration and easing tokens and reduced motion.
+
+## Change the copy
+
+Labels, descriptions and languages come from the translations in your Inth
+project and from the provider's `i18n` option. For the visitor's language,
+`i18n.messages` replace the project's copy key by key, and keys you leave out
+keep the project's wording.
+[Copy and translations](../../customization/translations.md) shows the message
+keys. For one banner, `ConsentBanner` also accepts text props such as
+`dismissButtonText`.
+
+## Check the result
+
+Clear site data and reload under a policy that shows a banner. Check the banner
+and the preferences dialog, since both read the same tokens. Test a narrow
+window, keyboard focus and contrast on the primary button. In development, the
+console warns if `theme` holds tokens but the page has no `c15t-theme` style.

package/docs/frameworks/react/embeds.md

@@ -0,0 +1,89 @@
+---
+title: Embeds
+description: Keep YouTube videos, maps and other iframes out of a React page
+  until their consent category is allowed, with ConsentGate or the iframe
+  blocker in ConsentProvider.
+group: frameworks
+---
+
+## Pick a method
+
+| Method             | Use it when                                                                                              |
+| ------------------ | -------------------------------------------------------------------------------------------------------- |
+| `ConsentGate`      | You render the iframe in a React component and want a placeholder until the visitor allows its category. |
+| The iframe blocker | The iframe comes from markup you do not render with React, such as CMS or Markdown content.              |
+
+Both keep the iframe's `src` out of the page until the category is allowed, so
+the embed's host receives no request before consent.
+
+## Gate an embed with ConsentGate
+
+Wrap the iframe in `ConsentGate` anywhere inside `ConsentProvider`:
+
+```tsx title="src/video-embed.tsx"
+import { ConsentDialogLink, ConsentGate } from 'c15t/react';
+
+export const VideoEmbed = () => (
+	<ConsentGate
+		category="measurement"
+		placeholder={
+			<div className="placeholder">
+				<p>Allow measurement to load this YouTube video.</p>
+				<ConsentDialogLink>Choose video permissions</ConsentDialogLink>
+			</div>
+		}
+	>
+		<iframe
+			title="YouTube video"
+			sandbox="allow-scripts allow-same-origin allow-presentation"
+			src="https://www.youtube-nocookie.com/embed/czTksCF6X8Y?playsinline=1"
+			allow="encrypted-media; picture-in-picture"
+			allowFullScreen
+		/>
+	</ConsentGate>
+);
+```
+
+The iframe is absent from the page until the visitor allows measurement. The
+`placeholder` shows a message and a
+[`ConsentDialogLink`](./components/consent-dialog-link.md)
+until then. When the visitor withdraws measurement, React removes the iframe.
+
+Pick the category that matches what the embed does. The example uses
+measurement for YouTube because its player measures views. A map or chat
+widget usually belongs under functionality or experience.
+[ConsentGate](./components/consent-gate.md) documents the
+built-in placeholder and every prop.
+
+## Gate an iframe with the iframe blocker
+
+`ConsentProvider` runs the iframe blocker by default. Give an iframe
+`data-src` instead of `src`, and a `data-category`:
+
+```html title="Markup from your CMS"
+<iframe
+  data-src="https://www.google.com/maps/embed?pb=YOUR_EMBED_ID"
+  data-category="functionality"
+  title="Store map"
+></iframe>
+```
+
+c15t sets `src` from `data-src` when the category is allowed and removes `src`
+when the category is withdrawn. It watches the page, so iframes added later
+are handled too. Add `data-vendor` with a vendor ID to also block the iframe
+while the visitor has turned that vendor off.
+
+To turn the blocker off, set `iframeBlocker: false` in the provider `options`.
+
+## Verify the embeds
+
+Open the production build in a private window with DevTools open, under a
+policy that asks for consent.
+
+1. No iframe has a `src` pointing at `youtube-nocookie.com` or
+   `google.com/maps`, and the Network panel shows no request to them.
+2. Allow the embed's category and save. The iframe loads.
+3. Withdraw the category and save. The page reloads without the embed.
+
+The [YouTube](../../integrations/youtube.md) and
+[Google Maps](../../integrations/google-maps.md) guides cover sizing and titles.

package/docs/frameworks/react/gpp.md

@@ -0,0 +1,163 @@
+---
+title: IAB GPP
+description: Add the IAB Global Privacy Platform API (__gpp) to a React app with
+  ConsentGPP from @c15t/react/gpp, so ad tech can read US state opt-outs and the
+  TCF EU consent string.
+group: frameworks
+---
+
+## What GPP does
+
+`ConsentGPP` from `@c15t/react/gpp` installs `window.__gpp`, the GPP 1.1 CMP
+API, and keeps its GPP string in step with the visitor's choices. Prebid.js,
+Google Ad Manager and other ad tech read US privacy signals from it.
+
+## Turn on GPP
+
+Render `ConsentGPP` inside `ConsentProvider`:
+
+```tsx title="src/consent.tsx"
+import { ConsentGPP } from '@c15t/react/gpp';
+
+<ConsentProvider options={{ mode, scripts }}>
+	<ConsentGPP />
+	{children}
+</ConsentProvider>;
+```
+
+`ConsentGPP` renders nothing. It installs `__gpp` after it mounts and
+removes it when it unmounts. It lives in its own entry, like
+`@c15t/react/iab`, so apps that do not import it bundle none of the GPP
+code. `@c15t/react` already depends on `@c15t/iab`; with the `c15t`
+package, import from `c15t/react/gpp`.
+
+The props are the GPP options listed below, for example
+`<ConsentGPP usFallback="none" />`. It works the same with a runtime you
+pass to `ConsentProvider` as `runtime`.
+
+The GPP string follows the policy and location your backend resolves for the
+visitor, so a US visitor's state comes from the backend. With `offline()`
+mode, pass the state yourself, for example
+`overrides: { country: 'US', region: 'CA' }`.
+
+To add the TCF EU section for visitors under an `iab` policy, set up
+[IAB TCF](./iab.md) as well.
+
+## How the policy decides the section
+
+The policy rule c15t matched for the visitor decides whether a section
+applies. The visitor's location only picks which US section carries it.
+
+| Matched rule and visitor                                                                       | Section in the GPP string                                                  |
+| ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `iab` rule, with IAB TCF set up                                                                | `tcfeuv2` (ID 2): the TC String the CMP confirmed, unchanged               |
+| `iab` rule, any visitor, with `tcf: false`                                                     | None; `applicableSections` is `[-1]`                                       |
+| Any other rule with the `preferences` or `opt-out` right, US visitor in a state with a section | That state's section, such as `usca` (ID 8)                                |
+| The same rule, US visitor whose region is unknown or whose state has no section                | `usnat` (ID 7), MSPA US National version 2; none with `usFallback: 'none'` |
+| The same rule, `usApproach: 'national'`                                                        | `usnat` for every US visitor                                               |
+| A rule without those rights, such as `none`                                                    | None                                                                       |
+| A visitor outside the US under any rule other than `iab`                                       | None                                                                       |
+
+Every `opt-in` and `opt-out` rule has the `preferences` right, and every
+`opt-out` rule also has `opt-out`. A `none` rule has them only if you add
+them. A rule that gives the visitor no way to opt out produces no US
+section, even when the visitor sends a GPC signal.
+
+State sections exist for California, Colorado, Connecticut, Delaware, Florida,
+Iowa, Minnesota, Montana, Nebraska, New Hampshire, New Jersey, Oregon,
+Tennessee, Texas, Utah and Virginia. Indiana, Kentucky, Maryland and Rhode
+Island are not encoded yet: their published specifications start the section
+with a header that the IAB reference implementation does not encode. Visitors
+there get the fallback, `usnat` by default. So does a US visitor whose region
+the geo headers did not supply.
+
+The MSPA US National specification describes `usnat` for MSPA signatories
+that chose the national approach. Without `mspaMode`, c15t reports the
+fallback as a transaction the MSPA does not cover (`MspaCoveredTransaction:
+2`), which still carries the opt-outs to vendors such as Prebid.js. If you
+reserve `usnat` for the national approach, set `usFallback: 'none'`; those
+visitors then get no section until their state resolves.
+
+## What the US sections report
+
+* `SaleOptOut`, `SharingOptOut` and `TargetedAdvertisingOptOut`: `1` (opted
+  out) when the `marketing` category is not permitted, otherwise `2`. A
+  refusal, a GPC signal the rule maps to `marketing` through
+  `privacySignals.gpc`, and an opt-in rule without a grant all count.
+* The opt-out notices: `1` (given), since the rule offers an opt-out.
+* The sharing or processing notice: `1` when the rule has the `disclosure`
+  right, otherwise `2`.
+* `Gpc`: the browser's Global Privacy Control signal, in sections that have a
+  GPC subsection. It is reported even when the rule does not map GPC to a
+  category, so give US rules a `privacySignals.gpc` mapping if the opt-outs
+  should follow it too.
+* Sensitive data and known-child consents: `0` (not applicable). c15t has no
+  category for them, so the string states that you do not process sensitive
+  data or knowingly process children's data. If you do, GPP from c15t does
+  not describe your processing; collect and signal that consent separately.
+* `MspaCoveredTransaction`: `2` (not covered) unless you set `mspaMode`.
+
+The notice fields are your attestation, made through the rule's rights:
+c15t cannot see whether your privacy notice is on the page. Show the notices
+the rule promises, including a persistent opt-out control.
+
+## GPP options
+
+Every field is optional. Pass them in the `gpp` option, where `gpp: true`
+uses the defaults, as props on `ConsentGPP` in React, or to `mountGPP()` in
+`@c15t/browser`.
+
+| Option             | Default                             | Effect                                                                                                                                                                                                                          |
+| ------------------ | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cmpId`            | the IAB CMP ID c15t holds, else `1` | CMP ID reported by `ping`. The GPP specification has string creators without a registered ID, including MSPA US National creators, use `1`. A TCF EU section needs the registered ID its TC String names.                       |
+| `usApproach`       | `'state'`                           | `'state'` uses the visitor's state section. `'national'` reports `usnat` for every US visitor; the MSPA reserves it for signatories that chose the national approach.                                                           |
+| `usFallback`       | `'usnat'`                           | Under the state approach, the section for a US visitor whose state is unknown or has no section: `'usnat'` or `'none'`.                                                                                                         |
+| `mspaMode`         | unset                               | `'opt-out-option'` or `'service-provider'`. Set it only if you signed the IAB Multi-State Privacy Agreement; the transaction is then reported as covered. In service provider mode the opt-outs are reported as not applicable. |
+| `optOutCategories` | `['marketing']`                     | Categories whose refusal reports an opt-out of sale, sharing and targeted advertising.                                                                                                                                          |
+| `tcf`              | `true`                              | Include the `tcfeuv2` section under an `iab` policy. It needs IAB TCF set up as well.                                                                                                                                           |
+
+## Check the signal
+
+Open the browser console on a page with GPP on and call:
+
+```js
+__gpp('ping', (data) => console.log(data));
+```
+
+For a California visitor who has not opted out, the result includes
+`applicableSections: [8]`, `signalStatus: 'ready'` and
+`parsedSections.usca[0].SaleOptOut === 2`. After the visitor refuses
+`marketing`, `SaleOptOut` is `1`. `__gpp('getField', cb, 'usca.SaleOptOut')`
+returns the same value. Scripts in iframes reach the API through the
+`__gppLocator` frame and `postMessage`.
+
+Under an `iab` rule, `parsedSections.tcfeuv2` uses the field names of the
+IAB Europe TCF section, such as `PurposeConsent`, `VendorConsent` and
+`PubRestrictions`. `getSection` and `getField` answer `null` for `tcfeuv2`,
+as the IAB reference implementation does: TCF vendors read consent from
+events, not on demand.
+
+`signalStatus` stays `'not ready'` while the policy is pending, while the
+banner or dialog is open, while an `iab` rule has no confirmed TC String,
+and while a new TC String is decoded. Listeners added with
+`addEventListener` get `signalStatus: 'not ready'`, then `cmpDisplayStatus`
+and `sectionChange` events, then `signalStatus: 'ready'`.
+
+## Ad tags that load before c15t
+
+c15t installs `__gpp` in the browser once consent starts, after it loads the
+GPP code. Vendor scripts that call `__gpp` earlier need a stub. c15t takes over
+the calls and listeners a stub queued, whether the stub keeps listeners on
+`__gpp.events`, as the GPP specification's sample does, or returns them from
+`__gpp('events')`, as `@iabgpp/stub` does. Call `initializeGPPStub()` from
+`@c15t/iab/gpp` in your first script, or use the IAB's own stub snippet.
+When another stub already answers iframes, c15t leaves that to it, so each
+iframe call gets one reply.
+
+If a CMP that has already loaded owns `__gpp`, c15t leaves it in place.
+The `gpp` option reports the conflict to the `onError` callback,
+`ConsentGPP` logs it, and `mountGPP()` and `createGPP()` throw. Run one GPP
+CMP per page.
+
+GPP signals what the visitor chose; it does not block scripts. Gate vendor
+scripts with c15t's script loading as well.

package/docs/frameworks/react/headless.md

@@ -34,13 +34,13 @@ import { useHeadlessConsentUI, useTranslations } from 'c15t/react/headless';
 
 const ACTION_LABELS = {
 	accept: 'acceptAll',
-	reject: 'rejectAll',
 	customize: 'customize',
 	dismiss: 'acknowledge',
+	reject: 'rejectAll',
 	save: 'save',
 } as const;
 
-export function Banner() {
+export const Banner = () => {
 	const { banner, performAction, openDialog } = useHeadlessConsentUI();
 	const { common, rights } = useTranslations();
 
@@ -49,7 +49,7 @@ export function Banner() {
 	}
 
 	return (
-		<section role="region" aria-label="Privacy">
+		<section aria-label="Privacy">
 			{banner.preferenceControls.map((right) => (
 				<button key={right} type="button" onClick={openDialog}>
 					{right === 'opt-out' ? rights?.optOut : rights?.preferences}
@@ -71,7 +71,7 @@ export function Banner() {
 			))}
 		</section>
 	);
-}
+};
 ```
 
 `banner.actionGroups` is the resolved layout: reject and accept share a group

package/docs/frameworks/react/hooks.md

@@ -0,0 +1,70 @@
+---
+title: Hooks
+description: Gate features and save consent choices in React components with the
+  focused hooks exported from c15t/react.
+group: frameworks
+---
+
+## Read only the state you need
+
+Every hook reads the runtime from the nearest `ConsentProvider`, so call them
+from components rendered inside that provider and import them from
+`c15t/react`.
+
+```tsx title="src/optional-feature.tsx"
+import { useConsent } from 'c15t/react';
+
+export const OptionalFeature = () => {
+	const allowed = useConsent('marketing');
+	return allowed ? <div>Optional marketing content</div> : null;
+};
+```
+
+Call hooks inside the consent provider. `useConsent` reads effective permission,
+which can be true under an opt-out policy without a recorded grant.
+
+| Need                                | Hook                                       |
+| ----------------------------------- | ------------------------------------------ |
+| One category's current permission   | `useConsent(category)`                     |
+| All current permissions             | `useConsents()`                            |
+| Recorded per-category choices       | `useExplicitChoice()`                      |
+| Whether one declared vendor may run | `useVendorAllowed(id)`                     |
+| Whether a prompt is required        | `usePromptRequirement()`                   |
+| Active policy and resolution        | `usePolicyRule()`, `usePolicyResolution()` |
+| Save an explicit choice             | `useSaveConsents()`                        |
+| Open or close a consent surface     | `useSetActiveUI()`                         |
+| Acknowledge a notice                | `useDismissNotice()`                       |
+
+## Save from a visitor action
+
+Render this component inside your existing `ConsentProvider`.
+
+```tsx title="src/reject-button.tsx"
+import { useSaveConsents } from 'c15t/react';
+
+export const RejectButton = () => {
+	const save = useSaveConsents();
+	return (
+		<button
+			type="button"
+			onClick={() => {
+				void save('none');
+			}}
+		>
+			Reject optional
+		</button>
+	);
+};
+```
+
+This is an isolated action example, not a complete policy-aware banner. Use the
+stock UI or headless surface actions for a complete prompt. Do not call save on
+mount to persist a state derived from permissions.
+
+Use focused hooks for feature gates. For a complete custom prompt or preference
+center, use `useHeadlessConsentUI()` for surface actions and `useConsentDraft()`
+for staged choices, inside one `ConsentDraftProvider` so the save commits the
+same draft. v3 has no `useConsentManager()`; the
+[`use-consent-manager-to-hooks` codemod](https://v3.c15t.com/docs/cli/commands/codemods#migrate-useconsentmanager-to-v3-hooks)
+rewrites most of its calls to hooks. Read [how consent works](../../concepts/how-consent-works.md#a-permission-is-not-a-recorded-choice) before
+treating a callback as evidence of a choice.