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

package/docs/frameworks/react/compose.md

@@ -0,0 +1,354 @@
+---
+title: Compose your own banner
+description: Build a React consent banner from the ConsentBanner parts in
+  c15t/react, with your own markup and buttons, while the policy still decides
+  which actions appear.
+group: frameworks
+---
+
+## When to compose
+
+Compose the banner from its parts when you need its elements in a different
+order, an element it does not have, or your design system's button in place
+of c15t's. The parts keep the stock
+behavior. They read the same policy, record the same choices and render the
+same class names, so theme tokens and slots still apply.
+
+Try the lighter tools first:
+
+| Change                            | Use                                                                               |
+| --------------------------------- | --------------------------------------------------------------------------------- |
+| Colors, type, radius, spacing     | [Theme tokens](../../customization/tokens.md)                                     |
+| Classes or attributes on one part | [Component parts](../../customization/slots.md)                                   |
+| Labels and languages              | [Copy and translations](../../customization/translations.md)                      |
+| Shape, position, button order     | `ConsentBanner` props such as `variant`, `position`, `layout` and `primaryButton` |
+| Different markup or order         | Compound parts, on this page                                                      |
+| Entirely custom UI and behavior   | Headless hooks                                                                    |
+
+For a banner that shares nothing with the stock markup, use the
+[headless hooks](./headless.md). For one changed class,
+token or prop, see [customize](./customize.md).
+
+## Compose the banner
+
+`CookieBanner` keeps the stock card, title and copy, and renders each action
+the policy asks for as your design system's button. `BrandButton` stands in
+for that button:
+
+```tsx title="src/brand-button.tsx"
+import { forwardRef } from 'react';
+import type { ButtonHTMLAttributes, ForwardedRef } from 'react';
+
+interface BrandButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+	tone?: 'solid' | 'outline';
+}
+
+const renderBrandButton = function renderBrandButton(
+	{ className, tone = 'outline', type, ...props }: BrandButtonProps,
+	ref: ForwardedRef<HTMLButtonElement>
+) {
+	return (
+		<button
+			ref={ref}
+			{...props}
+			className={['brand-button', className].filter(Boolean).join(' ')}
+			data-tone={tone}
+			// Under `asChild`, c15t passes no type. Default to `button` so an
+			// action never submits a surrounding form.
+			type={type === 'submit' ? 'submit' : 'button'}
+		/>
+	);
+};
+
+/**
+ * Your design system's button. To work under `asChild`, it forwards its ref
+ * and passes every other prop to the `button` element, so c15t's click
+ * handler, `data-action` and class names reach the DOM.
+ */
+export const BrandButton = forwardRef(renderBrandButton);
+
+BrandButton.displayName = 'BrandButton';
+```
+
+```tsx title="src/cookie-banner.tsx"
+import { ConsentBanner, useTranslations } from 'c15t/react';
+
+import { BrandButton } from './brand-button';
+
+const actionParts = {
+	accept: ConsentBanner.AcceptButton,
+	customize: ConsentBanner.CustomizeButton,
+	dismiss: ConsentBanner.DismissButton,
+	reject: ConsentBanner.RejectButton,
+} as const;
+
+/**
+ * The stock card, title and copy, with each action the policy asks for
+ * rendered as your own button. `PolicyActions` decides which actions appear
+ * and in what order, so a notice still gets its acknowledgement.
+ */
+export const CookieBanner = () => {
+	const { common } = useTranslations();
+	const labels = {
+		accept: common.acceptAll,
+		customize: common.customize,
+		dismiss: common.acknowledge,
+		reject: common.rejectAll,
+	};
+
+	return (
+		<ConsentBanner.Root>
+			<ConsentBanner.Card>
+				<ConsentBanner.Header>
+					<ConsentBanner.Title />
+					<ConsentBanner.Description />
+				</ConsentBanner.Header>
+				<ConsentBanner.PolicyActions
+					renderAction={(action, { key, isPrimary, ...props }) => {
+						if (action === 'save') {
+							return null;
+						}
+						const Action = actionParts[action];
+						return (
+							<Action key={key} {...props} asChild noStyle>
+								<BrandButton tone={isPrimary ? 'solid' : 'outline'}>
+									{labels[action]}
+								</BrandButton>
+							</Action>
+						);
+					}}
+				/>
+			</ConsentBanner.Card>
+		</ConsentBanner.Root>
+	);
+};
+```
+
+The parts read the nearest `ConsentProvider`. In the `src/consent.tsx` file
+from the [quickstart](./quickstart.md), import
+`CookieBanner` from `./cookie-banner` and render it in place of
+`ConsentBanner`, next to `ConsentDialog`:
+
+```tsx title="src/consent.tsx (partial)"
+<ConsentProvider options={{ mode, scripts }}>
+	{children}
+	<CookieBanner />
+	<ConsentDialog />
+	<footer>
+		<ConsentDialogLink>Privacy settings</ConsentDialogLink>
+	</footer>
+</ConsentProvider>;
+```
+
+`ConsentBanner.Root` renders only while the banner is the active surface,
+the same condition the stock `ConsentBanner` uses, so `CookieBanner` needs
+no visibility logic. It renders nothing before a policy resolves and closes
+once the visitor chooses.
+
+`ConsentBanner.PolicyActions` renders the actions the policy asks for, in
+the policy's order and groups, with any rights links, such as "Do not sell
+or share my data", before them. For each action it calls `renderAction`
+with the action name and the props c15t would give the stock button:
+`key`, `consentAction`, `isPrimary`, and a `style` that stretches the
+buttons when the layout fills the row. Return an element to replace that
+button, or `null` to keep the stock one. The banner never renders `save`,
+so the example skips it.
+
+Each action part gets those props plus `asChild` and `noStyle`. `asChild`
+renders `BrandButton` in place of c15t's `button`, and `noStyle` drops
+c15t's button classes so they do not compete with yours. The part keeps its
+behavior. Accept saves every category and Reject saves only necessary, and
+both close the banner. Customize opens the preference dialog. Dismiss
+records that the visitor saw a notice, without recording a choice.
+
+With `asChild`, the part's default label does not render, because your
+element keeps its own children. `useTranslations()` returns the labels the
+stock buttons use, in the visitor's language.
+
+Under a notice, the policy asks only for an acknowledgement, so
+`PolicyActions` passes `dismiss` and `CookieBanner` renders one button. If
+you place `ConsentBanner.AcceptButton` and `ConsentBanner.RejectButton`
+yourself instead, they render under every policy, including one that owes
+only a notice.
+
+## Banner parts
+
+Every part is a property of `ConsentBanner`. All parts except `Root` and
+`PolicyActions` forward their ref, and they accept the attributes of the
+element they render plus `noStyle`.
+
+| Part              | Renders                                                                                                                                  | Props                                                                                                                                         |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Root`            | The `div` that positions the banner, only while the banner shows. Renders the backdrop itself when blocking.                             | `variant`, `position`, `blocking`, `models` (default `['opt-in', 'opt-out']`), `uiSource` (default `'banner'`), `noStyle`, `disableAnimation` |
+| `Card`            | The visible `div`, labelled with the title. `role="region"`, or `role="dialog"` with `aria-modal="true"` and a focus trap when blocking. | `asChild`                                                                                                                                     |
+| `Header`          | A `div` for the title and copy.                                                                                                          | `asChild`                                                                                                                                     |
+| `Title`           | An `h2` with the translated title, or the notice title under a notice.                                                                   | children replace the text                                                                                                                     |
+| `Description`     | A `div` with the translated copy and the configured legal links.                                                                         | `legalLinks`, `asChild`                                                                                                                       |
+| `PolicyActions`   | `Footer`, the rights links and the policy's action groups.                                                                               | `renderAction`, children replace the rights links                                                                                             |
+| `Footer`          | A `div` for the actions.                                                                                                                 | `asChild`                                                                                                                                     |
+| `FooterSubGroup`  | A `div` for one group of actions. `Actions` is an alias.                                                                                 | `asChild`                                                                                                                                     |
+| `AcceptButton`    | A `button` that saves every category and closes the banner.                                                                              | action button props                                                                                                                           |
+| `RejectButton`    | A `button` that saves only necessary and closes the banner.                                                                              | action button props                                                                                                                           |
+| `CustomizeButton` | A `button` that opens the preference dialog.                                                                                             | action button props                                                                                                                           |
+| `DismissButton`   | A `button` that acknowledges a notice.                                                                                                   | action button props                                                                                                                           |
+| `Rights`          | A `div` with one `RightLink` per right the policy recommends, or nothing.                                                                | `rights`, `asChild`                                                                                                                           |
+| `RightLink`       | A `button` styled as underlined text that opens the preference dialog.                                                                   | `right` (`'opt-out'` or `'preferences'`), `asChild`                                                                                           |
+| `Overlay`         | The backdrop of a blocking banner. `Root` already renders it, so do not add it.                                                          | none                                                                                                                                          |
+
+`Content` is an alias of `Card`.
+
+The action buttons take `asChild`, `noStyle`, `consentAction`, `isPrimary`,
+`variant` (`'primary'` or `'neutral'`), `mode` (`'filled'`, `'stroke'`,
+`'lighter'` or `'ghost'`), `onClick` and any `button` attribute. Your
+`onClick` runs before the action, and calling `event.preventDefault()` in
+it skips the action. `consentAction` sets `data-action` and selects the
+`theme.consentActions` entry. `PolicyActions` passes it for you, and
+`DismissButton` sets it itself. A button you place yourself has no
+`data-action` and no per-action theme until you pass `consentAction`.
+
+`useConsentBannerSurface()` returns the `variant`, `position`,
+`positionSource` and `blocking` that `Root` resolved, for your own elements
+that depend on the banner's shape.
+
+[ConsentBanner](./components/consent-banner.md) lists the
+stock banner's props, variants and data attributes.
+
+## Render a part as your own element
+
+`asChild` swaps the part's element for the one element you pass as its
+child. `Card`, `Header`, `Description`, `Footer`, `FooterSubGroup`,
+`Rights`, `RightLink` and the action buttons support it. `Root` and
+`Overlay` ignore it, and `Title` always renders an `h2`, so a child you pass
+to `Title` ends up inside that `h2`. `Description` with `asChild` drops the
+inline legal links.
+
+The part merges its props onto your element:
+
+* The part's props apply first, and props you set on the child win.
+* `className` keeps both, the part's classes first.
+* `style` merges, and your values win per property.
+* Event handlers both run, yours first. On an action button, calling
+  `event.preventDefault()` in yours skips c15t's action.
+* The part's ref and your child's ref both receive the DOM node.
+* Your child keeps its own children. The part's default content, such as a
+  button label, does not render.
+
+Your component has to pass its ref and every prop it does not use to its
+DOM element. Otherwise c15t's click handler, `data-action` and focus
+handling never reach the page. The `BrandButton` in the example does both.
+Pass exactly one element. Text, a fragment or several children render
+nothing.
+
+Action buttons pass no `type` under `asChild`, so give your button a
+default of `type="button"`. Without it, the button submits a surrounding
+form.
+
+## Compose the preference dialog
+
+`ConsentDialog` has parts too. Compose it when the dialog needs a different
+header or footer, and keep `ConsentWidget` inside `Content`. The widget
+owns the category switches, the draft and the policy's Save, Accept and
+Reject buttons.
+
+| Part                       | Renders                                                                                                                | Props                                                                                                                                                                                          |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Root`                     | The dialog in a portal on `document.body`, with its open state, backdrop, focus trap, scroll lock and Escape to close. | `open`, `models` (default `['opt-in', 'opt-out', 'none']`), `overlay` (a node, or `false` for none), `noStyle`, `disableAnimation`, `scrollLock`, `trapFocus`, `uiSource` (default `'dialog'`) |
+| `Card`                     | The panel `div`.                                                                                                       | `className`, `style`, `noStyle`                                                                                                                                                                |
+| `Header`                   | A `div` for the title and copy.                                                                                        | `asChild`                                                                                                                                                                                      |
+| `HeaderTitle`              | An `h2` with `id="consent-dialog-title"`.                                                                              | children replace the text                                                                                                                                                                      |
+| `HeaderDescription`        | A `div` with `id="consent-dialog-description"` and the legal links.                                                    | `legalLinks`, `asChild`                                                                                                                                                                        |
+| `Content`                  | A `div` for `ConsentWidget`.                                                                                           | `asChild`                                                                                                                                                                                      |
+| `Footer`                   | A `div` with the branding tag, unless you pass children or `hideBranding`.                                             | `hideBranding`, `asChild`                                                                                                                                                                      |
+| `ConsentCustomizationCard` | The stock card with all of the above.                                                                                  | `legalLinks`, `hideBranding`, `noStyle`                                                                                                                                                        |
+| `Overlay`                  | The backdrop. `Root` already renders it.                                                                               | none                                                                                                                                                                                           |
+
+```tsx
+<ConsentDialog.Root>
+  <ConsentDialog.Card>
+    <ConsentDialog.Header>
+      <ConsentDialog.HeaderTitle>Your privacy choices</ConsentDialog.HeaderTitle>
+      <ConsentDialog.HeaderDescription />
+    </ConsentDialog.Header>
+    <ConsentDialog.Content>
+      <ConsentWidget />
+    </ConsentDialog.Content>
+    <ConsentDialog.Footer hideBranding />
+  </ConsentDialog.Card>
+</ConsentDialog.Root>
+```
+
+Render the composed dialog in place of `ConsentDialog`, next to your
+banner. The stock `ConsentDialog` downloads its code when the dialog first
+opens. The parts load that same code when they first render, and a
+composed `ConsentDialog.Root` renders on every page, so the code downloads
+with the page. `c15t/react/components/consent-dialog` exports the same
+parts without the deferral.
+
+`ConsentWidget` has parts as well, such as `ConsentWidget.Root`,
+`ConsentWidget.Accordion`, `ConsentWidget.AccordionItems` and
+`ConsentWidget.PolicyActions`, for a preference list with your own layout.
+
+The parts come from `c15t/react`, like `ConsentDialog` and `ConsentWidget`.
+[ConsentDialog](./components/consent-dialog.md) and
+[ConsentWidget](./components/consent-widget.md) list every
+part and its slots.
+
+## Keep the banner accessible
+
+The stock parts carry the roles, labels and focus handling. A composed
+banner keeps them as long as you keep the parts that own them:
+
+* `Card` owns the banner's role, label and focus trap. With `asChild`, your
+  element receives them, so do not set `role` or `aria-modal` on it.
+* `Card` takes its `aria-label` from the translated title, not from text you
+  pass to `Title`. If you change the title text, pass the same text as
+  `aria-label` on `Card`.
+* To attach your own ref to `Card`, pass a ref object from `useRef`. A
+  callback ref turns off the focus trap on a blocking banner.
+* Render each action as a real `button`. Its text is the accessible name,
+  so keep the label inside your button.
+* Keep a way to reopen preferences after the banner closes, such as the
+  `ConsentDialogLink` in your footer.
+* The dialog's `Root` names the panel with the ids on `HeaderTitle` and
+  `HeaderDescription`. Keep both parts, or put `id="consent-dialog-title"`
+  and `id="consent-dialog-description"` on your own heading and copy.
+
+## Keep theme tokens and slots working
+
+The parts render the stock class names, and the banner's `Root` renders
+c15t's rules, so c15t's styles and `--c15t-*` tokens style a composed
+banner the way they style the stock one.
+
+Slots in the provider's `options.components` reach each part by key:
+`banner.root`, `banner.card`, `banner.header`, `banner.title`,
+`description.banner`, `banner.footer` and `banner.actions`,
+`banner.actionGroup`, `banner.rights` and `banner.rightLink`. A class you
+pass to a part joins its stock and slot classes. The stock `ConsentBanner`
+also renders the `banner.cardShell` wrapper and the "Secured by" tag, and a
+composed banner renders neither.
+
+Action buttons read the `button.primary` or `button.secondary` slot and the
+`theme.consentActions` entry for their `consentAction`. `noStyle` on a
+button drops c15t's button classes and keeps slot classes. `noStyle` on
+`Root` removes the built-in styling from every part inside it.
+
+[Customize](./customize.md) shows where to set tokens,
+slots and `consentActions` in a React app.
+
+## Check the result
+
+1. Clear site data and reload. The composed banner appears with your
+   buttons. In DevTools Elements, each action is your element with a
+   `data-action` attribute. In DevTools Network, no optional vendor request
+   has fired.
+2. Tab through the banner. Every action is reachable in the policy's order
+   and shows a focus ring. Press Enter on Customize, and the preference
+   dialog opens.
+3. Click Reject all. The banner closes. Reload, and it stays closed with
+   the vendors still blocked.
+4. Reopen preferences from your footer link. The optional categories are
+   off. Allow one, save, and only that category's vendors load.
+5. If your policies include a notice region, test it too. The banner shows
+   your acknowledgement button and no Accept or Reject.
+
+[Verify consent](../../guides/verify-consent.md) has the full checklist.

package/docs/frameworks/react/content-security-policy.md

@@ -0,0 +1,149 @@
+---
+title: Content Security Policy
+description: Run c15t in a React app under a Content Security Policy, allow the
+  consent backend and vendor hosts, and pass a nonce to ConsentProvider and
+  ConsentTheme.
+group: frameworks
+---
+
+## What c15t adds to the page
+
+A React app with c15t adds these to the page, and your policy must allow them:
+
+| What                                                                                                            | Directive                                             |
+| --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
+| The `<style>` elements the banner, dialog and other stock components render with c15t's rules                   | `style-src` with a nonce                              |
+| `c15t/react/styles.css`, only if you import it with `styles: false`                                             | `style-src 'self'`                                    |
+| The `<style id="c15t-theme">` element, if you render `ConsentTheme`                                             | `style-src` with a nonce or its hash                  |
+| `<script>` elements the script loader creates for `scripts` entries, both `src` and inline                      | `script-src` with each vendor's host, or a nonce      |
+| The inline `<script>` that `consentManifest()` adds to `index.html` to send `/init` early                       | `script-src` with a nonce or its hash                 |
+| With server rendering, the inline `<script>` before the banner's buttons that holds a tap made before hydration | `script-src` with a nonce or its hash                 |
+| Browser requests to your backend's `/init` and `/subjects`                                                      | `connect-src` with the backend origin                 |
+| Iframes inside `ConsentGate`, and the frames, images and requests your vendors load                             | `frame-src`, `img-src`, `connect-src` for each vendor |
+
+In a client-rendered app, c15t components set their inline styles through
+React. A policy does not restrict styles set that way, so they need no
+directive.
+
+## Allow the consent backend
+
+With `hosted()`, the browser calls `GET {url}/init` on every page load
+and `POST {url}/subjects` when the visitor accepts, rejects or saves. With
+`manifest()`, it calls `POST {url}/subjects`, and `GET {url}/init` only when
+the policy needs a location the browser does not know. Add the
+backend's origin to `connect-src`:
+
+```txt title="Content-Security-Policy (partial)"
+connect-src 'self' https://<your-backend-host>;
+```
+
+Use the origin of the backend URL from your Inth project or self-hosted
+backend. When the URL is a same-origin path such as `/api/c15t` behind your
+own proxy, `'self'` covers it.
+
+Under an IAB TCF policy the browser also loads the Global Vendor List from the
+URL the policy provides. Allow that host in `connect-src` if you use the
+[IAB TCF add-on](./iab.md).
+
+## Allow vendor scripts
+
+The script loader adds a `<script>` element for each `scripts` entry once its
+category is allowed. List each vendor's script host in `script-src`, and the
+hosts its script calls in `connect-src` and `img-src`. The vendor's own
+documentation lists them. Scripts that a vendor script adds itself, such as a
+tag manager's tags, need their own hosts too, or `'strict-dynamic'` with a
+nonce.
+
+A `scripts` entry with inline `textContent` instead of `src` needs a nonce or
+its hash in `script-src`.
+
+## Use a nonce
+
+A nonce protects a page only when it changes on every response. A static host
+serves the same file to everyone, so use host allowlists there. Use a nonce
+when a server renders or rewrites your `index.html` per request.
+
+Pass the nonce as `options.nonce` on `ConsentProvider`. The script loader
+stamps it on every `<script>` it creates. A `nonce` on a single `scripts`
+entry takes precedence for that element. The stock components put it on the
+`<style>` elements that carry c15t's rules.
+
+With Vite, set `html.cspNonce` to a placeholder in `vite.config.ts`, and have
+your server replace it with a new nonce on every response. Vite then adds
+`<meta property="csp-nonce" nonce="...">` to the page, and the browser keeps the
+value in the tag's `nonce` property. Vite also stamps the nonce on the early
+`/init` script. Read it where you create the provider, in the
+quickstart's `src/consent.tsx`:
+
+```tsx title="src/consent.tsx (partial)"
+const nonce =
+  document.querySelector<HTMLMetaElement>('meta[property="csp-nonce"]')
+    ?.nonce || undefined;
+
+<ConsentProvider options={{ mode, scripts, nonce }}>
+```
+
+If you render `ConsentTheme`, pass it the same value:
+`<ConsentTheme theme={theme} nonce={nonce} />`.
+
+The provider reads `options.nonce` once, when it mounts. A server-rendered
+React app, such as one built with React Router framework mode, reads the nonce
+from its own request and passes it the same way.
+
+On a static host, allow the early `/init` script by the hash in the browser's
+`Refused to execute inline script` error. If the policy blocks it, the app
+sends `/init` itself.
+
+## Allow c15t's style elements
+
+The banner, dialog and other stock components render c15t's rules as
+`<style>` elements. A `style-src` without `'unsafe-inline'` must admit them.
+Either:
+
+* Set `options.nonce` on `ConsentProvider`, as in [use a nonce](#use-a-nonce).
+  The elements then render next to each component with the nonce. React 19
+  would otherwise move them into `<head>` and drop the nonce.
+* Or set `styles: false` in the provider options and import
+  `c15t/react/styles.css` from your bundle. `style-src 'self'` admits it.
+
+## Allow the theme style element
+
+`ConsentTheme` renders your theme tokens into a `<style id="c15t-theme">`
+element. Without a nonce, a `style-src` that lacks `'unsafe-inline'` blocks it,
+and the banner falls back to the default theme. The element's content depends
+only on the theme, so a hash works:
+
+1. Load the page with the policy enforced.
+2. Copy the `sha256-...` value from the `Refused to apply inline style`
+   console error.
+3. Add it to `style-src` and redeploy.
+
+Recompute the hash when you change the theme. To avoid the hash, set the
+tokens in your own stylesheet instead, as
+[customize](./customize.md) shows.
+
+## Allow embeds and the dev server
+
+Add the host of every iframe you gate to `frame-src`. A YouTube player inside
+`ConsentGate` needs `https://www.youtube-nocookie.com`, for example.
+
+Vite's dev server injects CSS as `<style>` elements, and the DevTools panel
+adds a `<style>` element without a nonce. Test the policy against a
+production build.
+
+## Verify
+
+Build the app, serve it with the policy enforced, not in report-only mode, and
+open DevTools. Test under a policy that asks for a choice, such as an EU
+opt-in policy.
+
+1. The banner renders with its theme colors, and the console shows no
+   `Refused to` error that mentions a c15t element, your backend or a vendor.
+2. Before a choice, the Network tab shows no vendor requests.
+3. Click **Accept All**. The vendor scripts load, and their `<script>` elements have ids
+   starting `c15t-`. With a nonce, read each element's `nonce` property in the
+   console. Browsers hide the attribute from `getAttribute`.
+4. The save to `/subjects` succeeds. A `connect-src` violation here means the
+   backend origin is missing.
+5. Reload. The banner stays closed, and the vendors load without a console
+   error.