@c15t/react 2.2.1 → 3.0.0-alpha.0

package/docs/frameworks/react/concepts/policy-presets.md

@@ -0,0 +1,123 @@
+---
+title: Policy presets
+description: Understand how policy rules affect React prompts, permissions and
+  persistent privacy controls.
+group: frameworks
+---
+
+## What the policy controls
+
+A policy rule selects the permission model, categories, prompt and persistent
+privacy controls for a visitor. Your app reads the resolved rule and effective
+permissions. It should not choose a different rule just to hide a banner.
+
+| Policy setting        | What your app should expect                                                                                                          |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `model: 'opt-in'`     | Optional categories in scope wait for consent.                                                                                       |
+| `model: 'opt-out'`    | Categories in scope can be allowed before a choice. Saved refusals and privacy signals can restrict them.                            |
+| `model: 'none'`       | Categories in scope are allowed without an initial prompt. Stock consent controls stay hidden unless the rule grants privacy rights. |
+| `prompt: 'choice'`    | The banner asks for a choice when the current state requires one.                                                                    |
+| `prompt: 'notice'`    | Dismissing the notice records an acknowledgement, not a consent grant.                                                               |
+| `prompt: 'none'`      | No automatic prompt. The rule can still require a way to open preferences.                                                           |
+| `scopeMode: 'strict'` | Optional categories outside the rule's scope stay denied.                                                                            |
+
+Keep a persistent preferences entry point wherever the policy provides that
+right. A visitor who dismissed a notice or rejected tracking still needs a way
+to revisit their choice. Stock components read the rule's rights; custom UI
+must do the same.
+
+Use `effectivePermissions` to gate a script or embed. A `true` value under an
+opt-out rule does not mean the visitor clicked Accept. Read `explicitChoice`
+when you need the visitor's recorded decision. See
+[consent state](../../../guides/consent-state.md) for these distinctions.
+
+## Where to change the rules
+
+For Inth, configure policy rules on your hosted project. The app receives those
+rules through the configured [data-fetching path](../../../guides/data-fetching.md). Importing
+`recommendedPolicyRules()` or changing browser styling does not override the
+hosted policy.
+
+For a backend you operate, use the
+[policy packs guide](https://c15t.com/docs/self-host/guides/policy-packs). It covers
+`manifest.policyRules`, preset selection and custom matchers. Browser-only
+setups own their rules locally; see
+[deployment modes](../../../guides/deployment-modes.md).
+
+Presets are starting configurations. Select them for your actual processing,
+and review their assumptions before allowing optional categories by default.
+A country match does not establish a legal basis for a vendor's data use.
+
+## Why the banner may be absent
+
+A missing banner can be an expected policy outcome or an initialization problem.
+Check `resolution.status` before interpreting the active model.
+
+| State                                                   | What to check                                                                                                                         |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| A policy matched and `promptRequirement.kind` is `none` | The rule does not ask for an initial prompt, or the stored records already satisfy it. Check persistent preferences separately.       |
+| A policy matched but a category is denied               | Inspect `effectivePermissions`, `explicitChoice`, `privacySignals` and `restrictions`. A saved refusal or GPC can keep it denied.     |
+| No policy has matched                                   | Check backend connectivity, location inputs and policy configuration. Optional categories stay denied while resolution is unresolved. |
+
+Do not treat `policyRule` alone as proof that a policy resolved. The snapshot
+also carries a safe rule for evaluation while resolution is pending or failed.
+Use `resolution.policy` only after checking for `status: 'matched'`.
+
+The local `recommendedPolicyRules()` pack uses opt-in rules for Europe and
+Québec, opt-out for its supported US privacy states, and a no-prompt `none`
+default for other known locations. An unknown country uses its strict opt-in
+fallback. A US country with a missing state gets the US opt-out fallback.
+These are the local pack's defaults, not a promise about your Inth project.
+Browser-only mode does not discover a visitor's country from their IP address.
+
+## Inspect the active policy
+
+Place this diagnostic component inside your existing consent
+provider. It reads state without recording a choice.
+
+```tsx title="src/consent-policy-debug.tsx"
+import { useSnapshot } from 'c15t/react';
+
+export function ConsentPolicyDebug() {
+  const snapshot = useSnapshot();
+  const resolution = snapshot.resolution;
+
+  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>
+  );
+}
+```
+
+The diagnostic subscribes to consent changes. Remove it after verification.
+For a production feature gate, use `useConsent('marketing')` or the category
+your feature needs instead of subscribing to the whole snapshot.
+
+## Change appearance without changing policy
+
+Keep one banner and one dialog in your existing
+provider. Use
+[styling](../styling/overview.md) to change their appearance,
+or [headless UI](../headless.md) for custom markup.
+Presentation settings change layout and emphasis; policy rules decide which
+actions and privacy rights the app must expose.
+
+## Verify policy behavior
+
+Use a fresh browser profile to check the intended location, then repeat with a
+saved rejection and GPC enabled. Confirm that the expected prompt and
+preferences controls appear, and that denied scripts and embeds make no
+requests. Test missing location inputs too. Follow
+[verify consent](../../../guides/verify-consent.md) for the full flow.

package/docs/frameworks/react/headless.md

@@ -1,192 +1,98 @@
 ---
-title: Headless Mode
-description: Build fully custom consent UI using only hooks - no pre-built
-  components required.
+title: Headless
+description: Build a custom consent banner in React with the c15t/react/headless
+  hooks inside your ConsentProvider.
 group: frameworks
 ---
-c15t's headless mode means using the hooks (`useConsentManager`, `useTranslations`, etc.) without any pre-built UI components. This gives you complete control over the consent experience.
 
-Before you go headless, walk the customization ladder in order:
-
-1. **Pre-built components** - Use provider options, component props, tokens, slots, and `theme.consentActions`
-2. **Compound components** - Rearrange c15t primitives when the markup order must change
-3. **`noStyle`** - Keep c15t structure but replace its styling
-4. **Headless** - Use only hooks and build the entire UI yourself
-
-## When to Go Headless
-
-Go headless when:
-
-* Your design system requires complete control over markup
-* You need a consent flow that doesn't fit the banner/dialog pattern
-* You want to embed consent choices inline rather than as overlays
-
-Use a lower-power tool instead when:
-
-* The component structure works but the styling doesn't -> use tokens, slots, or `noStyle`
-* You only need to rearrange existing c15t parts -> use compound components
-* You want to change copy -> use `ConsentManagerProvider.options.i18n`
-* You only need to restyle stock actions -> use `theme.consentActions`
-
-> ⚠️ **Warning:**
-> Headless mode is not the first answer for pure theming. If you are still trying to debug why a banner footer color did not change, stay in the styling system and verify the token-to-component mapping before you rebuild the UI.
-
-> ℹ️ **Info:**
-> Need a policy-aware implementation guide? See Building Headless Components.
-
-## Full Example: Custom Consent Banner
-
-```tsx
-import { useConsentManager, useTranslations } from '@c15t/react';
-
-function CustomConsentBanner() {
-  const {
-    activeUI,
-    consents,
-    consentCategories,
-    consentTypes,
-    saveConsents,
-    setSelectedConsent,
-    selectedConsents,
-  } = useConsentManager();
-  const translations = useTranslations();
-
-  if (activeUI !== 'banner') return null;
-
-  const displayedTypes = consentTypes.filter(
-    (t) => consentCategories.includes(t.name) && t.display
-  );
-
-  return (
-    <div className="fixed bottom-0 inset-x-0 bg-white border-t p-6 shadow-lg z-50">
-      <h2 className="text-lg font-semibold">
-        {translations.cookieBanner.title}
-      </h2>
-      <p className="text-sm text-gray-600 mt-1">
-        {translations.cookieBanner.description}
-      </p>
-
-      <div className="mt-4 space-y-3">
-        {displayedTypes.map((type) => (
-          <label key={type.name} className="flex items-center gap-3">
-            <input
-              type="checkbox"
-              checked={selectedConsents[type.name] ?? consents[type.name] ?? false}
-              disabled={type.disabled}
-              onChange={(e) => setSelectedConsent(type.name, e.target.checked)}
-            />
-            <div>
-              <span className="font-medium">
-                {translations.consentTypes[type.name]?.title ?? type.name}
-              </span>
-              <p className="text-xs text-gray-500">{type.description}</p>
-            </div>
-          </label>
-        ))}
-      </div>
-
-      <div className="mt-4 flex gap-3">
-        <button
-          onClick={() => saveConsents('necessary')}
-          className="px-4 py-2 border rounded"
-        >
-          {translations.common.rejectAll}
-        </button>
-        <button
-          onClick={() => saveConsents('custom')}
-          className="px-4 py-2 border rounded"
-        >
-          {translations.common.save}
-        </button>
-        <button
-          onClick={() => saveConsents('all')}
-          className="px-4 py-2 bg-blue-600 text-white rounded"
-        >
-          {translations.common.acceptAll}
-        </button>
-      </div>
-    </div>
-  );
+## When to go headless
+
+The pre-built banner and dialog cover most designs through props, slots, and
+the stylesheet. Go headless when your markup has to be something else
+entirely: a design system component, a native sheet, or a layout the compound
+parts cannot express.
+
+Headless code owns the rendered controls, so it also owns the compliance
+outcome. The hooks hand you the actions a policy requires, the rights it must
+keep reachable, and diagnostics when your presentation drops one. Render from
+those lists rather than from a fixed set of buttons, and a site that later adds
+a notice region keeps working without a code change.
+
+Check for a policy before rendering your own surfaces. `useModel()` from
+`c15t/react` returns `null` while no rule has resolved and `'none'` under a
+rule that owes no consent UI, and the pre-built surfaces render nothing in that
+state.
+
+## Minimal example
+
+The headless hooks read the runtime from the nearest `ConsentProvider` from
+`c15t/react`. Render this component inside that provider in place of the stock
+banner, and keep the dialog and persistent preferences control.
+
+```tsx title="src/consent-banner.tsx"
+import { useHeadlessConsentUI, useTranslations } from 'c15t/react/headless';
+
+const ACTION_LABELS = {
+	accept: 'acceptAll',
+	reject: 'rejectAll',
+	customize: 'customize',
+	dismiss: 'acknowledge',
+	save: 'save',
+} as const;
+
+export function Banner() {
+	const { banner, performAction, openDialog } = useHeadlessConsentUI();
+	const { common, rights } = useTranslations();
+
+	if (!banner.isVisible) {
+		return null;
+	}
+
+	return (
+		<section role="region" aria-label="Privacy">
+			{banner.preferenceControls.map((right) => (
+				<button key={right} type="button" onClick={openDialog}>
+					{right === 'opt-out' ? rights?.optOut : rights?.preferences}
+				</button>
+			))}
+			{banner.actionGroups.map((group) => (
+				<div key={group.join('-')}>
+					{group.map((action) => (
+						<button
+							key={action}
+							type="button"
+							data-primary={banner.primaryActions.includes(action) || undefined}
+							onClick={() => performAction(action)}
+						>
+							{common[ACTION_LABELS[action]]}
+						</button>
+					))}
+				</div>
+			))}
+		</section>
+	);
 }
 ```
 
-## Usage with Provider
-
-The headless UI still needs a `ConsentManagerProvider`:
-
-```tsx
-import { type ReactNode } from 'react';
-import { ConsentManagerProvider } from '@c15t/react';
-
-export function ConsentManager({ children }: { children: ReactNode }) {
-  return (
-    <ConsentManagerProvider
-      options={{
-        mode: 'hosted',
-        backendURL: 'https://your-instance.c15t.dev',
-        consentCategories: ['necessary', 'measurement', 'marketing'],
-      }}
-    >
-      <CustomConsentBanner />
-      {children}
-    </ConsentManagerProvider>
-  );
-}
-```
-
-## Custom Dialog
-
-Build a custom consent dialog for detailed category management:
-
-```tsx
-import { useConsentManager, useTranslations } from '@c15t/react';
-
-function CustomConsentDialog() {
-  const {
-    activeUI,
-    setActiveUI,
-    consentTypes,
-    consentCategories,
-    selectedConsents,
-    consents,
-    setSelectedConsent,
-    saveConsents,
-    has,
-  } = useConsentManager();
-  const translations = useTranslations();
-
-  if (activeUI !== 'dialog') return null;
-
-  return (
-    <div className="fixed inset-0 z-50 flex items-center justify-center">
-      <div className="absolute inset-0 bg-black/50" onClick={() => setActiveUI('none')} />
-      <div className="relative bg-white rounded-xl p-6 max-w-md w-full">
-        <h2 className="text-lg font-semibold">{translations.consentManagerDialog.title}</h2>
-
-        {consentTypes
-          .filter((t) => consentCategories.includes(t.name))
-          .map((type) => (
-            <div key={type.name} className="flex items-center justify-between py-3 border-b">
-              <div>
-                <p className="font-medium">{translations.consentTypes[type.name]?.title}</p>
-                <p className="text-sm text-gray-500">{type.description}</p>
-              </div>
-              <input
-                type="checkbox"
-                checked={selectedConsents[type.name] ?? consents[type.name] ?? false}
-                disabled={type.disabled}
-                onChange={(e) => setSelectedConsent(type.name, e.target.checked)}
-              />
-            </div>
-          ))}
-
-        <div className="mt-4 flex justify-end gap-2">
-          <button onClick={() => saveConsents('necessary')}>Reject</button>
-          <button onClick={() => saveConsents('custom')}>Save</button>
-          <button onClick={() => saveConsents('all')}>Accept All</button>
-        </div>
-      </div>
-    </div>
-  );
-}
-```
+`banner.actionGroups` is the resolved layout: reject and accept share a group
+at equal prominence, and the rest follow. `banner.orderedActions` is the same
+list flattened. Under a notice the only action is `dismiss`, and
+`banner.preferenceControls` recommends additional buttons for opening
+preferences. Under a notice it contains `opt-out`, which selects the
+"Do not sell or share my data" label. The example renders that button and
+an "OK" button. Both controls keep their own command: opening
+preferences and dismissing the notice.
+
+The list is a rendering helper. It does not establish that your UI implements
+all policy rights. Provide disclosure and persistent preferences access.
+
+`performAction` saves all categories for `accept`, none for `reject`, the
+current draft for `save`, records a dismissal for `dismiss`, and opens the
+preference center for `customize`. `banner.diagnostics` reports when a host
+layout drops a required action or gives equivalent actions different
+prominence. Review each diagnostic when configuring custom presentation.
+
+`banner.variant`, `banner.position`, and `banner.blocking` carry the resolved
+shape from `presentation.prompt`, so a headless surface can follow the same
+bar, widget, or wall choice the pre-built banner would make, and can trap
+focus and lock scroll exactly when `blocking` is true.

package/docs/frameworks/react/hooks/use-consent-manager/overview.md

@@ -1,172 +1,58 @@
 ---
-title: useConsentManager
-description: The primary hook for accessing consent state and actions. Returns
-  the full consent store including all state properties and action methods.
+title: Hooks
+description: Gate features and save consent choices in React components with the
+  focused hooks exported from c15t/react.
 group: frameworks
 ---
-`useConsentManager()` is the primary hook for interacting with the consent system. It returns the complete consent store state and all action methods.
 
-```tsx
-import { useConsentManager } from '@c15t/react';
+## Read only the state you need
 
-function MyComponent() {
-  const {
-    consents,
-    model,
-    has,
-    saveConsents,
-    // ... all state and actions
-  } = useConsentManager();
-}
-```
-
-> ⚠️ **Warning:**
-> Must be used within a ConsentManagerProvider. Throws an error if used outside the provider.
-
-## State Properties
-
-|Property|Value|
-|:--|:--|
-|Type Name|\`StoreRuntimeState\`|
-|Source Path|\`./packages/core/src/store/type.ts\`|
-
-\*ExtractedTypeTable: Could not extract "StoreRuntimeState" from "./packages/core/src/store/type.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
-
-## Action Methods
-
-|Property|Value|
-|:--|:--|
-|Type Name|\`StoreActions\`|
-|Source Path|\`./packages/core/src/store/type.ts\`|
-
-\*ExtractedTypeTable: Could not extract "StoreActions" from "./packages/core/src/store/type.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
-
-## User Identification
-
-You can link a consent subject to your own internal user ID or a non-secret anonymous visitor ID. c15t stores the identifier in the subject row's `externalId` field. Consent records remain associated with that subject through `subjectId`, so your backend can find the subject and its related consent records by external ID for GDPR Article 15 exports.
-
-### 1. Providing the Current User ID
-
-When using Clerk, wait for Clerk to load and prefer its authenticated `userId`. Before sign-in, you can fall back to a non-secret visitor ID from your application:
-
-> ⚠️ **Warning:**
-> Values passed through options.user are available to client-side JavaScript. Pass only a non-secret identifier, such as a Clerk userId or an opaque visitor ID. Never pass a Clerk session token or a value returned by getToken().
-
-```tsx
-import { useAuth } from '@clerk/react';
-import { ConsentManagerProvider } from '@c15t/react';
-
-function ConsentApp() {
-  // Render this component beneath your existing ClerkProvider.
-  const { isLoaded, isSignedIn, userId } = useAuth();
-
-  if (!isLoaded) {
-    return null;
-  }
-
-  const visitorId = getVisitorId();
-  const consentUser = isSignedIn && userId
-    ? { id: userId, identityProvider: 'clerk' }
-    : visitorId
-      ? { id: visitorId, identityProvider: 'anonymous-visitor' }
-      : undefined;
-
-  return (
-    <ConsentManagerProvider
-      options={{
-        mode: 'hosted',
-        backendURL: 'https://your-instance.c15t.dev',
-        consentCategories: ['necessary', 'measurement', 'marketing'],
-        user: consentUser,
-      }}
-    >
-      <ClerkConsentSync />
-      <MyComponents />
-    </ConsentManagerProvider>
-  );
-}
-```
-
-### 2. Synchronizing Clerk Sign-ins
-
-Use a component inside `ConsentManagerProvider` to update the current consent subject when Clerk's authentication state changes:
-
-```tsx
-import { useAuth } from '@clerk/react';
-import { useConsentManager } from '@c15t/react';
-import { useEffect } from 'react';
+Every hook reads the runtime from the nearest `ConsentProvider`, so call them
+from components rendered inside that provider and import them from
+`c15t/react`.
 
-function ClerkConsentSync() {
-  const { isLoaded, isSignedIn, userId } = useAuth();
-  const { identifyUser } = useConsentManager();
+```tsx title="src/optional-feature.tsx"
+import { useConsent } from 'c15t/react';
 
-  useEffect(() => {
-    if (!isLoaded || !isSignedIn || !userId) {
-      return;
-    }
-
-    void identifyUser({
-      id: userId,
-      identityProvider: 'clerk',
-    }).then(() => {
-      clearVisitorId();
-    });
-  }, [identifyUser, isLoaded, isSignedIn, userId]);
-
-  return null;
+export function OptionalFeature() {
+  const allowed = useConsent('marketing');
+  return allowed ? <div>Optional marketing content</div> : null;
 }
 ```
 
-`identifyUser()` replaces the subject's current `externalId`; it does not retain the anonymous ID as an alias. Once a visitor is linked to Clerk, clear the previous visitor ID from the application state or storage used by `getVisitorId()` so it cannot replace the Clerk ID later.
-
-> ℹ️ **Info:**
-> Backend subject identification requires hosted mode (mode: 'hosted'). In offline mode, identifyUser() cannot update a backend subject. Identifiers supplied through options.user can still be held in client state and persisted with locally stored consent, so do not place sensitive values there.
+Call hooks inside the consent provider. `useConsent` reads effective permission,
+which can be true under an opt-out policy without a recorded grant.
 
-## Key Types
+| Need                              | Hook                                       |
+| --------------------------------- | ------------------------------------------ |
+| One category's current permission | `useConsent(category)`                     |
+| All current permissions           | `useConsents()`                            |
+| Recorded per-category choices     | `useExplicitChoice()`                      |
+| 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()`                       |
 
-### ConsentState
+## Save from a visitor action
 
-A record mapping consent category names to their boolean values:
-
-```ts
-type ConsentState = Record<AllConsentNames, boolean>;
-// Example: { necessary: true, measurement: true, marketing: false }
-```
+Render this component inside your existing `ConsentProvider`.
 
-### ConsentInfo
+```tsx title="src/reject-button.tsx"
+import { useSaveConsents } from 'c15t/react';
 
-Metadata about when and how consent was recorded:
-
-```ts
-interface ConsentInfo {
-  time: number;                    // Epoch timestamp when consent was recorded
-  subjectId?: string;              // Client-generated subject ID (sub_xxx format)
-  externalId?: string;             // External user ID linked via identifyUser()
-  identityProvider?: string;       // Identity provider (e.g. 'clerk', 'auth0')
+export function RejectButton() {
+  const save = useSaveConsents();
+  return <button type="button" onClick={() => void save('none')}>Reject optional</button>;
 }
 ```
 
-### LocationInfo
-
-Detected geographic location from the c15t backend:
-
-```ts
-interface LocationInfo {
-  countryCode: string;     // ISO 3166-1 alpha-2 (e.g. 'DE')
-  regionCode: string;      // Region/state code (e.g. 'BY')
-  jurisdiction: string;    // Applicable jurisdiction (e.g. 'GDPR', 'CCPA')
-}
-```
-
-### Model
-
-The active consent model:
-
-```ts
-type Model = 'opt-in' | 'opt-out' | 'iab' | null;
-```
+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.
 
-* `'opt-in'` — Explicit consent required before tracking (GDPR)
-* `'opt-out'` — Tracking allowed by default, user can opt out (CCPA)
-* `'iab'` — IAB TCF 2.3 compliance mode
-* `null` — No jurisdiction detected yet
+`useConsentManager` remains available for the combined UI API, including draft
+management. Prefer focused hooks for simple feature gates and use the headless
+UI hook when implementing a complete custom prompt. Read
+[consent state](../../../../guides/consent-state.md) before treating a callback as evidence
+of a choice.