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

package/docs/frameworks/react/components/dev-tools.md

@@ -1,7 +1,7 @@
 ---
 title: DevTools
-description: A development tool for inspecting consent state, geolocation,
-  loaded scripts, and consent events in real time.
+description: Inspect consent state, location, loaded scripts and consent events
+  in a React app during development with the c15t DevTools panel.
 group: frameworks
 ---
 
@@ -12,42 +12,44 @@ group: frameworks
 
 ## Installation
 
-No extra package is required for a framework adapter. The adapter and its
-engine are included with the `c15t` package and the dedicated
-`@c15t/svelte` adapter. Install `@c15t/dev-tools` directly only
-when you need the imperative `createDevTools({ kernel })` API.
+No extra package is required. The React adapter and its engine are included
+with the `c15t` package. Install `@c15t/dev-tools` directly only when you
+need the imperative `createDevTools({ kernel })` API.
 
-## Usage
+## Render DevTools in development builds
 
-This example uses Vite's `import.meta.env.DEV` build-time flag. For another
-bundler, use its development flag instead. For example, webpack projects can
-use a configured `process.env.NODE_ENV === 'development'` replacement;
-`process` is not a browser global.
+Render `DevTools` inside `ConsentProvider`. This example loads it only in
+development with Vite's `import.meta.env.DEV` flag, so production bundles never
+download it. For another bundler, use its development flag instead; for
+example, webpack projects can use a configured
+`process.env.NODE_ENV === 'development'` replacement, since `process` is not a
+browser global.
 
-```tsx
-import { lazy, Suspense, type ReactNode } from 'react';
-import { ConsentProvider, hosted } from 'c15t/react';
-
-const DevTools =
-  import.meta.env.DEV
-    ? lazy(() =>
-        import('c15t/react/devtools').then(({ DevTools }) => ({ default: DevTools })),
-      )
-    : () => null;
+```tsx title="src/consent-devtools.tsx"
+import { lazy, Suspense } from 'react';
 
-export function ConsentManager({ children }: { children: ReactNode }) {
-  return (
-    <ConsentProvider options={{ mode: hosted({ url: 'https://your-instance.c15t.dev' }) }}>
-      {children}
-      <Suspense fallback={null}>
-        <DevTools />
-      </Suspense>
-    </ConsentProvider>
-  );
+const DevTools = import.meta.env.DEV
+	? lazy(() =>
+			import('c15t/react/devtools').then(({ DevTools }) => ({
+				default: DevTools,
+			}))
+		)
+	: null;
+
+export function ConsentDevTools() {
+	return DevTools ? (
+		<Suspense fallback={null}>
+			<DevTools />
+		</Suspense>
+	) : null;
 }
 ```
 
-Import the adapter from `c15t/react/devtools` when you use the umbrella package, or `c15t/react/devtools` when you install the React package directly. `@c15t/dev-tools` exports the imperative engine, not the React component.
+Render `<ConsentDevTools />` inside the provider from your
+[quickstart](../quickstart.md), next to the banner. Import the
+component from `c15t/react/devtools` when you installed the `c15t` package, or
+from `@c15t/react/devtools` when you installed `@c15t/react` directly.
+`@c15t/dev-tools` exports the imperative engine, not the React component.
 
 If the CLI cannot identify your bundler's development flag, it generates
 `const DevTools = false` with a setup comment. Replace `false` with your
@@ -69,14 +71,39 @@ DevTools disabled instead of assuming browser globals or loading it in productio
 `position` accepts any corner: `top-left`, `top-right`, `bottom-left`, or
 `bottom-right`. Set `defaultOpen` to open the initial panel and `defaultTab`
 to choose that panel. `maxEvents` limits captured kernel and script events.
-Set `disabled` to prevent mounting without removing the component.
+Set `disabled` to prevent mounting without removing the component. The
+panel renders inside a shadow root by default, so page CSS does not reach
+it. `shadow={false}` mounts it in the light DOM with its stylesheet in
+`<head>`.
+
+## Open DevTools from the consent trigger
+
+While `ConsentDialogTriggerToolbar` or the ready-made `ConsentDialogTrigger`
+is visible, the trigger shows a DevTools button and DevTools hides its own
+floating launcher, so one control occupies the corner. The button sits at the
+end of the toolbar farthest from its corner. The panel opens just past the
+toolbar, aligned with its outer edge, and follows it when a visitor drags the
+toolbar to another corner. `position` applies again once no trigger is
+visible.
+
+`ConsentDialogTrigger` becomes a two-button toolbar while DevTools is
+mounted. A trigger composed from `ConsentDialogTrigger.Root` keeps its own
+markup, and DevTools keeps its floating launcher beside it.
+
+DevTools brings its launcher back whenever no trigger is visible, for example
+while `showWhen="after-prompt"` waits for a choice. A production build that
+loads DevTools only in development shows no DevTools button in the trigger.
+
+With the imperative engine, call `devTools.dock({ position, inline, block })`
+to hide the launcher and anchor the panel `inline` and `block` pixels from the
+viewport edges of `position`'s corner. Call `devTools.dock(null)` to restore
+the launcher.
 
 ## Panels
 
 Accept and reject apply only to categories displayed by the provider, leaving
-hidden consent values unchanged. `necessary` always remains enabled. Svelte
-and Vue adapters use their provider's displayed categories; the kernel and
-React adapter use the current policy categories by default.
+hidden consent values unchanged. `necessary` always remains enabled. The
+React adapter uses the current policy categories by default.
 
 For an imperative integration with a narrower UI, pass
 `getConsentCategories: () => ['necessary', 'measurement']` to
@@ -91,7 +118,7 @@ explicit scope or policy categories, bulk saves cover all known categories.
 | ------------ | -------------------------------------------------------------------------------------------- |
 | **Consents** | Inspect and save categories, accept all, or reject optional categories                       |
 | **Scripts**  | Configured scripts, loading status, search, and external page resources                      |
-| **Location** | Detected jurisdiction, country, region, and consent model                                    |
+| **Location** | Resolved country and region, and location overrides                                          |
 | **Policy**   | Resolved policy and UI configuration                                                         |
 | **IAB**      | Edit vendors, purposes, legitimate interests, and special features; save and copy TC strings |
 | **Events**   | Timeline of consent changes, kernel events, and script lifecycle events                      |
@@ -168,55 +195,6 @@ For custom inspection tools, `getIABControls(kernel)` and
 The getter returns undefined before module initialization and after disposal.
 A snapshot without an attached IAB module is read-only in DevTools.
 
-## Vue and Svelte
-
-Vue imports `ConsentDevTools` from `c15t/vue/devtools`.
-Render it in the app where the c15t plugin provides
-the kernel. In Nuxt, the configured c15t module provides that context.
-
-```vue
-<script setup lang="ts">
-import { defineAsyncComponent } from 'vue';
-
-const DevTools = import.meta.env.DEV
-  ? defineAsyncComponent(() => import('c15t/vue/devtools'))
-  : null;
-</script>
-
-<template>
-  <DevTools v-if="DevTools" position="bottom-right" />
-</template>
-```
-
-In Nuxt, use `import.meta.dev` instead of `import.meta.env.DEV`.
-Svelte imports the adapter from `@c15t/svelte/devtools` and renders it
-inside `ConsentManagerProvider`.
-
-```svelte
-<script lang="ts">
-  import { ConsentManagerProvider, offline } from '@c15t/svelte';
-
-  const devTools = import.meta.env.DEV
-    ? import('@c15t/svelte/devtools')
-    : null;
-</script>
-
-<ConsentManagerProvider options={{ mode: offline() }}>
-  {#if devTools}
-    {#await devTools then { ConsentDevTools }}
-      <ConsentDevTools position="bottom-right" />
-    {/await}
-  {/if}
-</ConsentManagerProvider>
-```
-
-Both adapters accept `position`, `defaultOpen`, `defaultTab`, `maxEvents`,
-`shadow` (`false` renders into the page instead of a shadow root),
-and `getConsentCategories`. Changing these presentation options recreates
-the panel and clears its event history. They do not accept React's `disabled`
-prop; conditionally render them instead. Unmounting removes the panel and
-subscriptions without changing consent.
-
 ## TanStack Devtools
 
 Each embedded panel owns its event history and subscriptions. Unmounting it
@@ -257,6 +235,19 @@ export function AppDevtools() {
 
 In a Next.js app, import `c15tDevtools` from `c15t/next/devtools` instead. Scoped installs use `@c15t/react/devtools` and `@c15t/nextjs/devtools`.
 
+The c15t panel follows the TanStack Devtools light or dark theme, not your app's consent theme. If you write the plugin entry yourself, use a render function and pass the theme to `C15tTanStackDevtoolsPanel`:
+
+```tsx
+import { C15tTanStackDevtoolsPanel } from 'c15t/react/devtools';
+
+const c15tPlugin = {
+  name: 'Consent',
+  render: (_element: HTMLElement, { theme }: { theme: 'light' | 'dark' }) => (
+    <C15tTanStackDevtoolsPanel theme={theme} />
+  ),
+};
+```
+
 ## Props
 
 | Property | Type                | Description                                 | Default | Required |

package/docs/frameworks/react/components.md

@@ -0,0 +1,113 @@
+---
+title: Components
+description: Every c15t component a React app imports from c15t/react, what each
+  renders, where each one mounts, and which to start with.
+group: frameworks
+---
+
+## Component reference
+
+`c15t/react` exports the provider, the consent UI and the hooks from one
+import path. Every component except `ConsentProvider` and `ConsentTheme`
+reads the runtime the provider creates, so render them inside
+`ConsentProvider`.
+
+| Component                             | Renders                                                                                                           | Reference                                                      |
+| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `ConsentProvider`                     | The consent runtime, which loads the policy, stores the choice and loads scripts. No markup of its own            | [ConsentProvider](./components/consent-provider.md)            |
+| `ConsentBanner`                       | The banner, when the visitor's policy asks for one                                                                | [ConsentBanner](./components/consent-banner.md)                |
+| `ConsentDialog`                       | The preference center as a modal                                                                                  | [ConsentDialog](./components/consent-dialog.md)                |
+| `ConsentWidget`                       | The preference center inline in a page, for a privacy route                                                       | [ConsentWidget](./components/consent-widget.md)                |
+| `ConsentDialogLink`                   | An unstyled button that opens the dialog, for your footer                                                         | [ConsentDialogLink](./components/consent-dialog-link.md)       |
+| `ConsentDialogTrigger`                | A floating, draggable button that opens the dialog. `ConsentDialogTriggerToolbar` adds your own actions beside it | [ConsentDialogTrigger](./components/consent-dialog-trigger.md) |
+| `ConsentGate`                         | Its children while a category is allowed, a placeholder otherwise                                                 | [ConsentGate](./components/consent-gate.md)                    |
+| `ConsentTheme`                        | A `<style>` element with your theme tokens                                                                        | [Customize](./customize.md)                                    |
+| `DevTools` from `c15t/react/devtools` | A development panel for consent state, scripts and events                                                         | [DevTools](./components/dev-tools.md)                          |
+
+Mount one `ConsentProvider` at the root of the app and keep it mounted across
+client navigation. The provider reads `mode` and its module options once,
+when it mounts.
+
+## Start with the provider, banner and dialog
+
+Most apps start with four components. `ConsentProvider` holds the runtime,
+`ConsentBanner` and `ConsentDialog` ask for a choice, and a
+`ConsentDialogLink` lets visitors reopen their preferences. The [quickstart](./quickstart.md) puts them in
+one file:
+
+```tsx title="src/consent.tsx"
+import { posthog } from '@c15t/integrations/posthog';
+import {
+	ConsentBanner,
+	ConsentDialog,
+	ConsentDialogLink,
+	ConsentProvider,
+	hosted,
+} from 'c15t/react';
+import type { ReactNode } from 'react';
+
+const options = {
+	// Asks VITE_C15T_BACKEND_URL for each visitor's policy.
+	mode: hosted(),
+	scripts: [
+		posthog({
+			id: 'phc_your_project_key',
+			initOptions: { cookieless_mode: 'never' },
+			loadMode: 'after-consent',
+		}),
+	],
+};
+
+export const Consent = ({ children }: { children: ReactNode }) => (
+	<ConsentProvider options={options}>
+		{children}
+		<ConsentBanner />
+		<ConsentDialog />
+		<footer>
+			<ConsentDialogLink>Privacy settings</ConsentDialogLink>
+		</footer>
+	</ConsentProvider>
+);
+```
+
+Add `ConsentWidget`, `ConsentDialogTrigger` or `ConsentGate` later, where a
+page needs them. Keep `ConsentDialog` mounted even when you add a widget,
+because the banner's Customize button and every dialog link open it.
+
+## Server-rendered React apps
+
+React Router framework mode, Remix and other server-rendered React apps use the
+same components. `ConsentProvider` renders on the server without touching
+browser APIs, and the banner mounts after hydration, once the browser has
+resolved the policy. [Rendering](./rendering.md#react-router-remix-and-other-server-rendered-apps)
+explains the trade-off.
+
+## IAB TCF components
+
+Import `IABProvider`, `IABConsentBanner` and `IABConsentDialog` from
+`c15t/react/iab`, render them inside `ConsentProvider` next to
+`ConsentBanner` and `ConsentDialog`, and load `c15t/react/styles.css` and
+`c15t/react/iab/styles.css` with `styles: false`. The stock banner and dialog stay closed
+under an IAB policy. See
+[IAB TCF](./iab.md).
+
+## Other entry points
+
+| Import                                                                                                                                                                                  | Exports                        | Use                                                                                                      |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------- |
+| `c15t/react/consent-banner`, `c15t/react/consent-dialog`, `c15t/react/consent-widget`, `c15t/react/consent-dialog-link`, `c15t/react/consent-dialog-trigger`, `c15t/react/consent-gate` | One component each             | A module that needs one component without the rest of the adapter                                        |
+| `c15t/react/headless`                                                                                                                                                                   | Headless hooks                 | Your own banner and dialog markup. See [headless](./headless.md)                                         |
+| `c15t/react/server`                                                                                                                                                                     | `fetchSSRData` and its helpers | Resolve `/init` in a server loader. See [rendering](./rendering.md#skip-the-browsers-first-init-request) |
+| `c15t/react/devtools`                                                                                                                                                                   | `DevTools`                     | Development only                                                                                         |
+
+## Check the components
+
+Load the app in a private window under a policy that asks for a choice:
+
+1. The banner shows, and DevTools Network has no requests to your vendors'
+   hosts.
+2. Click the footer's `ConsentDialogLink`. The dialog opens with every optional
+   category off.
+3. Allow one category and save. Its vendor requests appear, and a
+   `ConsentGate` for that category mounts its children.
+4. Reload. The banner stays closed, and the link still reopens the dialog.