@c15t/react 3.0.0-alpha.2 → 3.0.0-alpha.4

package/docs/frameworks/react/scripts.md

@@ -0,0 +1,115 @@
+---
+title: Scripts
+description: Load vendor scripts by consent category in a React app with
+  ConsentProvider, and clear stored data or reload the page when a visitor
+  withdraws consent.
+group: frameworks
+---
+
+## Register vendor scripts
+
+Pass vendor loaders to `ConsentProvider` through `options.scripts`. The
+provider loads each script when its category is allowed and removes it when
+the category is denied. The [quickstart](./quickstart.md)
+registers PostHog and X Pixel this way:
+
+```ts title="src/scripts.ts"
+import { posthog } from '@c15t/integrations/posthog';
+import { xPixel } from '@c15t/integrations/x-pixel';
+
+export const scripts = [
+	posthog({
+		id: 'phc_your_project_key',
+		initOptions: { cookieless_mode: 'never' },
+		loadMode: 'after-consent',
+	}),
+	xPixel({ pixelId: 'your-pixel-id' }),
+];
+```
+
+The provider in `src/consent.tsx` receives them:
+
+```tsx title="src/consent.tsx"
+import {
+	ConsentBanner,
+	ConsentDialog,
+	ConsentDialogLink,
+	ConsentProvider,
+	hosted,
+} from 'c15t/react';
+import type { ReactNode } from 'react';
+
+import { scripts } from './scripts';
+
+import 'c15t/react/styles.css';
+
+const mode = hosted({ url: 'https://your-project.inth.app' });
+
+export const Consent = ({ children }: { children: ReactNode }) => (
+	<ConsentProvider options={{ mode, scripts }}>
+		{children}
+		<ConsentBanner />
+		<ConsentDialog />
+		<footer>
+			<ConsentDialogLink>Privacy settings</ConsentDialogLink>
+		</footer>
+	</ConsentProvider>
+);
+```
+
+Each helper from `@c15t/integrations` sets its own category and a stable `id`.
+Remove every other loader for the same vendor, such as a `<script>` tag in
+`index.html` or an SDK you initialize at module level, so the vendor loads
+once and only through c15t. [Integrations](../../integrations/overview.md) lists
+every helper, and [building integrations](../../integrations/building-integrations.md)
+covers a vendor without one.
+
+## What happens when consent changes
+
+* **Allowed.** The script loads, or its SDK is started, the first time its
+  category is allowed.
+* **Denied later.** The provider removes the script element. Code that already
+  ran keeps running, so after the visitor turns off a category they had
+  allowed, the provider reloads the page once the save finishes. Set
+  `reloadOnConsentRevoked: false` only if every gated vendor stops itself.
+* **`alwaysLoad` helpers.** Some integrations, such as Google Consent Mode,
+  load before consent and pass the visitor's choice to the vendor. Read the
+  vendor's guide; a category on a script does not always mean zero requests.
+
+## Embeds and other requests
+
+Scripts cover vendor code c15t loads for you. For the rest:
+
+* [Embeds](./embeds.md) keeps iframes out of the page with
+  `ConsentGate` or the iframe blocker.
+* [Network blocker](./network-blocker.md) holds `fetch` and
+  XHR calls that match a rule until their category is allowed.
+
+## Clear stored data after revocation
+
+Removing a script does not delete the cookies or storage entries it wrote. Add
+`clearOnRevocation` to the provider options to delete the entries you list for
+each category when it is denied. The option is read once, when the provider
+mounts. [Clear on revocation](./clear-on-revocation.md) covers
+configuration and browser limits.
+
+## Let visitors turn off one vendor
+
+A visitor can allow marketing and still switch off one vendor in it. Pass
+`vendors` to the provider options. Helpers from `@c15t/integrations` already carry
+their vendor slug. See [vendor consent](./vendor-consent.md).
+
+To send your own events only to allowed integrations, see
+[send events only to allowed integrations](../../integrations/overview.md#send-events-only-to-allowed-integrations).
+
+## Check the scripts
+
+Open DevTools Network in a private window, filter by each vendor's domain and
+reload.
+
+1. Before a choice under an opt-in policy, no vendor script loads.
+2. Allow one category. Only that category's vendors load.
+3. Turn the category off. The page reloads and the vendor stays absent.
+4. Reload again. The rejection holds.
+
+[Verify consent](../../guides/verify-consent.md) has the full checklist.

package/docs/frameworks/react/translations.md

@@ -0,0 +1,155 @@
+---
+title: Translations
+description: Where c15t banner and dialog copy comes from in a React app, how
+  the browser picks the visitor's language, and how to override copy and switch
+  languages with the provider's i18n option and hooks.
+group: frameworks
+---
+
+## Where the copy comes from
+
+The banner, dialog, widget and gate placeholder read their text from one set
+of translations for the visitor's language. Which set depends on the
+provider's `mode`:
+
+| Mode        | Copy comes from                                                                                                                                                                                       |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `hosted()`  | The backend's `/init` response for the visitor's language, from the translations in your Inth project or your self-hosted backend's configuration, with your `i18n` messages for that language on top |
+| `offline()` | Your `i18n` messages, merged over bundled English                                                                                                                                                     |
+
+With a backend, edit wording in your Inth project first, so it changes without
+a deploy. Code can override that copy in two places:
+
+* `i18n` in the `ConsentProvider` options changes a message everywhere it
+  appears.
+* Text props on `ConsentBanner` change one banner.
+
+[Copy and translations](../../customization/translations.md) lists the message
+keys and explains how code messages combine with the project's copy.
+
+## How c15t picks the language
+
+In `hosted()` mode the browser's `/init` request carries its own
+`Accept-Language` header, and the backend answers with copy in that language.
+When your project has no copy for it, the backend returns its fallback
+language. Set `overrides.language` in the provider options to request a
+specific language instead.
+
+In `offline()` mode, `i18n.locale` picks the language, `en` by default. The
+browser's language is not read.
+
+The banner, dialog and widget set `dir` from the active language. Right-to-left
+languages such as Arabic and Hebrew render with `dir="rtl"`, and a floating
+banner you did not position yourself moves to the opposite side.
+
+## Change the copy in code
+
+Keep the messages in their own module:
+
+```ts title="src/consent-i18n.ts"
+import type { ConsentProviderOptions } from 'c15t/react';
+
+// Keys you leave out keep the copy from your Inth project.
+export const i18n = {
+	messages: {
+		de: {
+			common: { rejectAll: 'Optionale ablehnen' },
+			cookieBanner: { title: 'Cookies auf dieser Website' },
+		},
+		en: {
+			common: { rejectAll: 'Reject optional' },
+			cookieBanner: { title: 'Cookies on this site' },
+		},
+	},
+} satisfies ConsentProviderOptions['i18n'];
+```
+
+Pass them to the provider in the file that renders it, such as
+`src/consent.tsx` from the [quickstart](./quickstart.md):
+
+```tsx title="src/consent.tsx"
+<ConsentProvider options={{ mode, scripts, i18n }}>
+```
+
+For the visitor's language, your messages replace the backend's copy key by
+key. Keys you leave out keep the project's wording, and messages for other
+languages are not applied. In `offline()` mode c15t bundles only English, so
+keys you leave out for another language show in English.
+
+The provider reads `i18n` once, when it mounts. In development it logs a
+warning if `i18n` changes later. Define the object at module level, as above,
+rather than inside a component.
+
+## Change one banner's copy
+
+`ConsentBanner` takes `title`, `description`, `acceptButtonText`,
+`rejectButtonText`, `customizeButtonText` and `dismissButtonText`. The props
+replace the text in every language, so pass values in the page's language:
+
+```tsx
+<ConsentBanner
+	title="Cookies on this site"
+	rejectButtonText="Reject optional"
+/>;
+```
+
+## Switch the language at runtime
+
+`useSetLanguage()` stores the new language, and `useInit()` resolves the policy
+again, which fetches the copy for that language. Call both from your language
+switcher:
+
+```tsx title="src/language-switcher.tsx"
+import { useInit, useSetLanguage, useSnapshot } from 'c15t/react';
+
+const languages = [
+	{ code: 'en', label: 'English' },
+	{ code: 'de', label: 'Deutsch' },
+];
+
+export const LanguageSwitcher = () => {
+	const setLanguage = useSetLanguage();
+	const init = useInit();
+	const language = useSnapshot().translations?.language ?? 'en';
+
+	return (
+		<select
+			aria-label="Consent language"
+			value={language}
+			onChange={(event) => {
+				setLanguage(event.target.value);
+				// Setting the language alone keeps the current copy. Init fetches
+				// the policy and copy for the new language.
+				void init();
+			}}
+		>
+			{languages.map(({ code, label }) => (
+				<option key={code} value={code}>
+					{label}
+				</option>
+			))}
+		</select>
+	);
+};
+```
+
+Setting the language without calling `init()` changes nothing on screen. Your
+`i18n` messages for the new language apply on top of the copy that arrives.
+Render the switcher anywhere inside `ConsentProvider`.
+
+Switching needs a backend. In `offline()` mode the copy stays in the
+`i18n.locale` language.
+
+If your site changes language through its own i18n library, you can instead
+pass its locale as `overrides.language` in the provider options. When that
+value changes, the provider resolves the policy again in the new language.
+
+## Verify
+
+1. Set your browser language to one your project translates, clear site data
+   and reload under a policy that shows a banner. DevTools Network shows the
+   `/init` request with that `Accept-Language` header, and the banner uses
+   that language.
+2. Check that a message you set in `i18n` shows in the banner.
+3. Switch the language with your switcher. A new `/init` request runs, and the
+   banner and dialog text change without a reload.

package/docs/frameworks/react/troubleshooting.md

@@ -1,67 +1,112 @@
 ---
-title: Troubleshoot React consent
-description: Diagnose policy resolution, early scripts, storage and rendering problems.
+title: Troubleshooting
+description: Fix a missing banner, early vendor requests, unstyled components
+  and theme warnings in a React app that uses c15t/react.
 group: frameworks
 ---
 
-## Why is there no banner?
+## The /init request goes to your-project.inth.app
 
-Inspect `resolution` and `promptRequirement` before changing styles. Pending or
-failed initialization, no matching rule, a valid stored choice and a rule that
-requires no prompt can all produce no banner for different reasons. A missing
-stylesheet can also make rendered controls appear incorrectly.
+**Check.** In DevTools Network, the `GET` request to `/init` goes to
+`your-project.inth.app` and fails.
 
-Check the backend URL and Network response, then confirm the active policy for
-the visitor's location. Do not solve missing UI by granting every category or
-setting `enabled: false`: disabling the runtime permits optional loading.
+**Fix.** Replace the placeholder URL in `hosted({ url })` in `src/consent.tsx`
+with the backend URL from your Inth project, exactly as Inth shows it, then
+rebuild.
 
-## Why does the UI disappear with a content blocker?
+## There is no banner
 
-Check the browser Network panel for `ERR_BLOCKED_BY_CLIENT` or a failed dynamic
-import. Older c15t builds used component filenames such as
-`consent-dialog-*.js`, which some cookie-annoyance lists block. Update the c15t
-packages and rebuild the app. Current component modules use neutral filenames;
-public component imports stay the same. This also covers Vite development
-requests used by TanStack Start and other Vite integrations.
+**Check.** In DevTools Network, find the `GET` request to `/init` on your
+backend URL.
 
-Extensions can separately hide elements with cosmetic filters or block a
-configured backend URL. Check the failed request or hidden element to distinguish
-those cases from a missing component module.
+| What you see                    | Cause                                                                                  | Fix                                                                                                           |
+| ------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| No `/init` request              | `ConsentProvider` is not mounted, or an error stopped `src/consent.tsx` from rendering | Check the console for errors and render one provider at the app root, as in the [quickstart](./quickstart.md) |
+| `/init` fails with a CORS error | Your site's origin is not trusted                                                      | Add the exact origin, including port in development, to the trusted origins in your Inth project              |
+| `/init` returns 200             | The policy for this visitor asks for no banner, or a stored choice is still valid      | Inspect the active policy with the component below, or clear site data                                        |
 
-## Why does analytics run before a choice?
+A policy with `prompt: 'none'` shows no banner by design, and so does a
+returning visitor with a valid stored choice. [Policies](../../concepts/policies.md)
+explains why a region may not show one.
 
-Check effective permission under the selected policy, then find every loader
-for that vendor. Remove unconditional script tags, framework analytics plugins
-and duplicate tag-manager entries. c15t's script registration only controls the
-scripts registered with it.
+## Inspect the active policy
 
-Google helpers intentionally load with Consent Mode defaults. A Google request
-is not by itself proof that its storage consent was granted. If your requirement
-is no request at all, do not use an always-loaded helper unchanged.
+Render this component inside `ConsentProvider`. It reads state and records no
+choice:
 
-## Why does a choice disappear on reload?
+```tsx title="src/consent-policy-debug.tsx"
+import { useSnapshot } from 'c15t/react';
 
-Check whether persistence is disabled, browser storage is blocked, the origin
-changed, or the receipt expired or no longer matches the current policy.
-A development example with `persistence: false` deliberately resets on reload.
-Do not "repair" persistence by saving permissions automatically on mount.
+export function ConsentPolicyDebug() {
+	const snapshot = useSnapshot();
+	const resolution = snapshot.resolution;
 
-## Why does hydration differ from server HTML?
+	return (
+		<pre>
+			{JSON.stringify(
+				{
+					status: resolution.status,
+					policy: resolution.status === 'matched' ? resolution.policy.id : null,
+					prompt: snapshot.promptRequirement,
+					permissions: snapshot.effectivePermissions,
+					location: snapshot.location,
+					privacySignals: snapshot.privacySignals,
+				},
+				null,
+				2
+			)}
+		</pre>
+	);
+}
+```
 
-Use the adapter's request helper and pass the returned configuration unchanged
-to its boundary. Check that server and browser use the same backend and policy
-inputs. A module-level mutable runtime on a server can share one visitor's state
-with another request; create request-owned state instead.
+The component re-renders on every consent change. Remove it after you finish.
+For a feature gate, use `useConsent('marketing')` or the category you need.
 
-## Why does static hosting fail when development works?
+## A vendor loads before the visitor chooses
 
-A static host has no app server for init routes, proxies or server functions.
-Use absolute external consent URLs or an explicitly local policy. Test the
-production output with a static file server, not the framework dev server.
+**Check.** Search `index.html`, your entry module and any tag manager for the
+vendor's script or SDK initializer.
 
-## Why does customization do nothing?
+**Fix.** Remove every loader except the one in `options.scripts`. c15t only
+gates scripts registered with it, and the network blocker cannot stop code that
+runs before the provider renders. [Scripts and embeds](./scripts.md)
+covers the options.
 
-Check the imported stylesheet, the correct token or slot, and which element
-carries the state attribute. `data-variant` on a banner root is not a matching
-attribute on its child card. Check cascade layers and the Tailwind version
-before adding specificity. See [customization](../../customization/overview.md).
+## The banner has no styles
+
+**Check.** In DevTools Elements, the banner has classes but no rules apply.
+
+**Fix.** Import `c15t/react/styles.css` once in the module that renders the
+provider. With Tailwind 3, keep that import above the `@tailwind` directives
+and add `c15t/postcss-tailwind3` before `tailwindcss` in your PostCSS
+config. Without the plugin, Tailwind 3 drops c15t's rules or fails the build
+with `` `@layer components` is used but no matching `@tailwind components` directive is present ``.
+See [Tailwind CSS](../../customization/tailwind.md#set-up-tailwind-css-3).
+
+## The console warns that theme tokens are no longer turned into CSS
+
+**Check.** `options.theme` holds colors, radius or other tokens, and the page
+has no `c15t-theme` style element. The provider only reads `consentActions`
+and slot styles from `theme`.
+
+**Fix.** Move the tokens to your CSS or render `ConsentTheme`, as shown in
+[customize](./customize.md#change-colors-fonts-and-radius).
+
+## The banner is missing from server-rendered HTML
+
+**Check.** Your app uses React Router framework mode, Remix or another
+server-rendered setup without a c15t adapter. There this is expected: the
+browser resolves consent after hydration.
+
+**Fix.** None is needed for consent to work.
+[Rendering](./rendering.md#react-router-remix-and-other-server-rendered-apps)
+explains the options.
+
+## More help
+
+[Troubleshoot consent](../../guides/troubleshooting.md) covers problems shared by
+every framework, such as a missing banner, analytics that load before a choice,
+imports that fail because npm installed c15t v2, choices that disappear on
+reload, server HTML that differs from the browser, static builds that fail and
+content blockers that hide the consent UI.

package/docs/frameworks/react/vendor-consent.md

@@ -0,0 +1,170 @@
+---
+title: Vendor consent
+description: Let visitors allow a category such as marketing in a React app and
+  still turn off one vendor in it, with the vendors option on ConsentProvider
+  and useVendorAllowed.
+group: frameworks
+---
+
+## How vendor consent works
+
+A visitor allows marketing, then switches off X Pixel. Other marketing
+scripts load; X Pixel does not. c15t loads a script, network request or
+iframe that names a vendor only when both are true:
+
+* Its category is allowed.
+* The visitor has not switched its vendor off.
+
+A vendor switch never grants a category. With marketing denied, X Pixel stays
+blocked whatever its own switch says. You do not need IAB TCF for this. Under
+an `iab` policy, c15t ignores vendor slugs and takes vendor consent from the
+TC string instead; see [IAB TCF](./iab.md).
+
+## Declare the vendors
+
+Declare the vendors next to the scripts in `src/scripts.ts`, using the `vendor`
+slug each script already carries:
+
+```ts title="src/scripts.ts (partial)"
+import type { Vendor } from 'c15t';
+
+export const vendors: Vendor[] = [
+	{
+		id: 'x-pixel',
+		name: 'X Pixel',
+		category: 'marketing',
+		privacyPolicyUrl: 'https://x.com/privacy',
+	},
+];
+```
+
+Then add them to the provider options in `src/consent.tsx`:
+
+```tsx title="src/consent.tsx (partial)"
+import { scripts, vendors } from './scripts';
+
+<ConsentProvider options={{ mode, scripts, vendors }}>
+```
+
+`vendors` is a live option, like `scripts`: passing a new list replaces the
+declared vendors. A provider that borrows a `runtime` does not accept
+`vendors`; declare them in `createConsentRuntime({ vendors })` instead.
+
+## Vendor fields
+
+| Field                                     | Required | Behavior                                                                    |
+| ----------------------------------------- | -------- | --------------------------------------------------------------------------- |
+| `id`                                      | Yes      | Lowercase slug of up to 64 characters: letters, digits, `.`, `_` and `-`.   |
+| `name`                                    | Yes      | Name shown in the preference dialog.                                        |
+| `category`                                | Yes      | A category, or a condition such as `{ or: ['measurement', 'marketing'] }`.  |
+| `privacyPolicyUrl`                        | Yes      | Link shown next to the vendor.                                              |
+| `description`, `legalName`, `homepageUrl` | No       | Extra detail shown on the vendor card.                                      |
+| `disabled`                                | No       | List the vendor without a switch. A stored denial for it no longer applies. |
+
+The `id` must match the `vendor` slug on the script. Every `@c15t/integrations`
+helper sets `vendor` to its script ID, so `xPixel()` is `x-pixel`, `gtag()`
+is `gtag` and `cloudflareZaraz()` is `cloudflare-zaraz`. Each
+[vendor guide](../../integrations/overview.md) names its slug.
+
+A self-hosted backend can declare vendors too. `/init` returns them and c15t
+merges them with the vendors in code. When both declare the same `id`, the
+code declaration wins.
+
+## Gate scripts, requests and iframes by vendor
+
+Put the vendor slug on each target:
+
+| Target               | Field                                     |
+| -------------------- | ----------------------------------------- |
+| Script configuration | `vendor: 'x-pixel'`                       |
+| Network blocker rule | `vendor: 'x-pixel'`                       |
+| Iframe blocker       | `data-vendor="x-pixel"` on the `<iframe>` |
+
+An iframe with `data-vendor` and no `data-category` is gated on the vendor
+alone. A script with `alwaysLoad` still loads when its vendor is off. Its
+callbacks receive `info.vendor.granted`, so the SDK can stop itself. The
+Google Consent Mode, RudderStack and Cloudflare Zaraz helpers do this for
+you. While their vendor is off, they send every optional category as denied.
+
+`ConsentGate` checks a category only. To render a component only while one
+vendor is allowed, read `useVendorAllowed('youtube')` and render it when the
+hook returns `true`. [Embeds](./embeds.md) covers the iframe
+blocker's `data-vendor` attribute.
+
+## What the preference dialog shows
+
+`ConsentDialog` and `ConsentWidget` list each declared vendor under its
+category, with its own switch.
+
+The dialog lists only vendors that have a `name` and a `privacyPolicyUrl`.
+A vendor's switch is disabled while its category is off. Save records the
+vendors the visitor changed. Accept All and Reject All clear every vendor
+denial, so each vendor follows its category again. The labels come from
+`consentManagerDialog.vendors` in the translations: `title`,
+`privacyPolicy`, `disabledByCategory` and `switchLabel`.
+
+## Build your own vendor switch
+
+`useVendorDraft()` from `c15t/react` reads and stages vendor switches on the
+same draft the category switches use, so one save records both.
+`useVendorAllowed(id)` returns whether a vendor may run now: it is declared,
+its category is allowed and the visitor has not switched it off.
+
+```tsx title="src/x-pixel-switch.tsx (partial)"
+import { useVendorAllowed, useVendorDraft } from 'c15t/react';
+
+const { vendors, setVendor, save } = useVendorDraft();
+const xPixelAllowed = useVendorAllowed('x-pixel');
+
+<input
+  type="checkbox"
+  checked={vendors['x-pixel'] ?? true}
+  onChange={(event) => setVendor('x-pixel', event.target.checked)}
+/>
+<button type="button" onClick={() => save()}>Save</button>
+```
+
+`save()` resolves `{ ok: false }` without recording anything when the policy
+or the vendor list changed under the edit. Call `reset()` to start again.
+`useDeclaredVendors()` returns the declared vendors, and `useVendorChoice()`
+returns the recorded vendor decision, or `null` before the visitor made one.
+
+A vendor reads as allowed only when it is declared, its category is allowed
+and the visitor has not switched it off. An id that nothing declares, in
+`vendors`, on a script or iframe, or from the backend, reads as not allowed.
+A typo such as `x-pixle` or a vendor you forgot to declare never looks like
+consent. In development, c15t logs a console warning that names the id.
+
+## What c15t stores
+
+c15t stores only the vendors a visitor switched off, and sends the full
+vendor map to the backend with the consent record. Under an opt-out policy,
+every vendor starts on. Turning a vendor off that was on reloads the page,
+the same as withdrawing a category, so code the vendor already ran stops.
+
+## What switching a vendor off does not do
+
+* It does not delete cookies the vendor already set.
+  [Clear on revocation](./clear-on-revocation.md) does not run, because the
+  category stays allowed. Delete the vendor's cookies from the script's
+  `onConsentChange` when `info.vendor.granted` is `false`.
+* It does not expire. The switch stays off until the visitor changes it or
+  uses Accept All or Reject All, even across a policy change.
+* Adding a vendor does not ask returning visitors again. A new vendor starts
+  on inside an allowed category. Change the policy's `copyRevision` if a new
+  vendor should prompt again.
+
+## Verify vendor consent
+
+Test the production build in a private window with DevTools Network open and
+filtered to `ads-twitter.com`:
+
+1. Declare `x-pixel` and register `xPixel()`. Open Privacy settings. The
+   marketing row lists X Pixel with a switch.
+2. Allow marketing and save. `uwt.js` loads.
+3. Open Privacy settings, switch X Pixel off and save. c15t reloads the
+   page. After the reload there is no `uwt.js` request, and other marketing
+   scripts still load.
+4. Reload again. The X Pixel switch is still off.
+5. Turn marketing off. The X Pixel switch is disabled.
+6. Open Privacy settings and click Accept All. `uwt.js` loads again.