@c15t/react 3.0.0-alpha.3 → 3.0.0-alpha.5

package/docs/guides/shared-consent-controls.md

@@ -1,158 +0,0 @@
----
-title: Share consent controls across frameworks
-description: Use the same c15t script lifecycle, external consent source, and
-  event controls in every framework.
-group: guides
----
-
-## Choose one consent authority
-
-c15t owns script loading, consent gates, lifecycle callbacks, and optional cleanup
-through its framework-independent core. React, Vue, Svelte, Astro, and the browser
-client connect to that core. Next.js and TanStack Start use the React provider;
-Nuxt uses Vue; SvelteKit uses Svelte. None requires Astro for these controls.
-
-With c15t as the consent authority, keep your framework's hosted, self-hosted, or
-offline setup. Offline mode keeps choices in the browser; a hosted backend can
-store records. The script SDK and event dispatcher work with either mode.
-
-To keep another CMP, provide a `consentSource`. It owns the banner, preferences,
-records, expiration, privacy signals, and category mapping. c15t follows its
-current permissions without creating a second choice record. Optional categories
-start denied, including during SSR. An unavailable source or a failed read denies
-them again. Initialize the CMP independently, or register its loader as an
-explicitly early-loading script so it does not wait for its own consent.
-
-The source contract is exported from `@c15t/core/runtime`:
-
-```ts title="src/consent-source.ts — adapter skeleton"
-import type { ExternalConsentSource } from 'c15t/runtime';
-import { provider } from './existing-cmp';
-
-export const consentSource: ExternalConsentSource = {
-  getPermissions: () => provider.getCategoryPermissions(),
-  subscribe: (notify) => provider.subscribe(notify),
-  openPreferences: () => provider.openPreferences(),
-};
-```
-
-`provider` is your application's adapter for the existing CMP, not a c15t export.
-Map its categories to c15t's `measurement`, `marketing`, `functionality`, and
-`experience` booleans. Missing categories are denied; `necessary` stays true.
-Return `null` until the CMP is ready. `subscribe` must notify on initialization,
-changes, withdrawal, and expiration, and return a function that removes listeners.
-Keep browser access inside these functions so importing the adapter during SSR is safe.
-
-If `subscribe` throws, c15t reports the failure through `callbacks.onError` and
-continues startup with optional categories denied. The failed connection ignores
-later notifications and does not forward preference requests. Recreate the owner
-after the CMP is available to connect again.
-
-## Pass the controls to your framework
-
-The `consentSource` option is available at these registration points. Register your SDK configurations through the same owner's
-`scripts` option. Do not create an additional runtime beside an existing provider.
-
-| Framework                   | Registration point                                                                                                             |
-| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| React                       | `ConsentProvider options={{ mode, consentSource, scripts }}`                                                                   |
-| Next.js / TanStack Start    | `ConsentRoot options={{ consentSource }}` with `scripts` as a top-level prop; `ConsentProvider` also accepts the React options |
-| Vue                         | `app.use(c15tVue, { consentSource, scripts })`                                                                                 |
-| Nuxt                        | `app.config.ts` → `c15t: { consentSource, scripts }`                                                                           |
-| Svelte / SvelteKit          | `ConsentManagerProvider` options or corresponding top-level props                                                              |
-| Astro                       | `clientOptions.consentSource`                                                                                                  |
-| Browser client              | `createConsentClient({ consentSource, scripts })`                                                                              |
-| Headless JavaScript / Solid | `createConsentRuntime({ mode, consentSource, scripts })`                                                                       |
-
-For example, a React client boundary can use the source directly:
-
-```tsx title="src/Consent.tsx"
-'use client';
-
-import type { ReactNode } from 'react';
-import { ConsentProvider, offline, useSetActiveUI } from 'c15t/react';
-import { googleTagManager } from '@c15t/scripts/google-tag-manager';
-import { consentSource } from './consent-source';
-
-const mode = offline();
-const scripts = [googleTagManager({ id: 'GTM-EXAMPLE' })];
-
-function Preferences() {
-  const setActiveUI = useSetActiveUI();
-  return <button type="button" onClick={() => setActiveUI('dialog')}>Privacy settings</button>;
-}
-
-export function Consent({ children }: { children: ReactNode }) {
-  return (
-    <ConsentProvider options={{ mode, consentSource, scripts }}>
-      {children}
-      <Preferences />
-    </ConsentProvider>
-  );
-}
-```
-
-Replace the container ID. `mode` remains required by the provider API, but an
-external source bypasses c15t backend initialization and persistence. Omit c15t's
-banner and dialog. Preference links, hooks, and `kernel.set.activeUI('dialog')`
-delegate to the source. Preference-opening failures reach `callbacks.onError`;
-`kernel.commands.save()` rejects instead of recording a second choice.
-
-In Next.js, construct the source in the client boundary; do not pass functions
-from a Server Component. Existing `ConsentRoot` state can stay serializable, but
-c15t records do not establish external permissions. A client-owned
-`ConsentProvider` avoids a redundant server consent fetch for external-only setups.
-For Nuxt, use `app.config.ts` for the functions, not serialized public runtime
-configuration; the module skips its consent fetch and record hydration when a
-source is configured. Browser access remains deferred until mount.
-
-Solid currently ships UI primitives, not a lifecycle provider. Create the core
-runtime once, call `start()` from `onMount`, and `dispose()` from `onCleanup`.
-Other frameworks' providers perform that lifecycle automatically. A provider given
-an existing `runtime` borrows it: configure controls on the runtime owner, which
-also owns starting and disposing it.
-
-## Handle withdrawal and application events
-
-When the source withdraws an optional category that was granted, c15t reloads
-the page, as it does when a visitor revokes consent in c15t's own UI. Removing a
-script element cannot stop JavaScript that already ran, so the reload starts a
-page with only permitted code. The reload runs in the next task, after
-synchronous consent callbacks and `onBeforeConsentRevocationReload`. Disposing
-the owner cancels a pending reload.
-
-c15t cannot tell a visitor's withdrawal from expiry or a reset in the CMP, so
-any notification that turns off a granted category reloads. The CMP owns
-persistence: store the new decision before notifying c15t, or the reloaded page
-reads the old one. Set `reloadOnConsentRevoked: false` to handle withdrawal
-yourself. c15t still updates gates and calls script consent callbacks.
-
-`createEventDispatcher` from `@c15t/scripts/events` also has no framework dependency:
-
-```ts title="src/events.ts — attach to an existing runtime"
-import { createEventDispatcher } from '@c15t/scripts/events';
-
-const events = createEventDispatcher({
-  scripts,
-  getSnapshot: () => runtime.kernel.getSnapshot(),
-});
-events.track('docs_search', { resultCount: 4 });
-```
-
-Here `scripts` is the same configuration registered with the existing `runtime`.
-For a provider-owned kernel, use that kernel's live `getSnapshot` instead. The
-dispatcher sends only to configured integrations with supported event APIs when
-measurement and the script's own consent condition allow it. It discards denied
-events, isolates vendor failures, and deduplicates explicitly configured SPA
-pageviews. It does not subscribe to a framework router: notify it from your
-router's navigation hook. Use vendor-specific helpers for APIs outside the shared
-event contract.
-
-## Verify the integration
-
-Test an undecided visitor, an existing grant, withdrawal, expiry, and a source
-that cannot be read. Check that only permitted scripts execute, the preference
-control opens the existing CMP, c15t does not render another banner or persist
-another receipt, and unmounting removes the source listeners. Test your actual
-CMP category mapping and tag-manager container; shared gates do not validate
-those configurations or establish compliance by themselves.

package/docs/integrations/clear-on-revocation.md

@@ -1,167 +0,0 @@
----
-title: Clear on revocation
-description: Remove configured first-party cookies and Web Storage keys when
-  their consent category is denied.
-group: integrations
----
-
-## Configure cleanup
-
-Add `clearOnRevocation` to your provider or runtime options. Declare only the
-data owned by each optional category:
-
-```ts
-import { hosted, type ClearOnRevocationConfig } from 'c15t';
-import { createConsentRuntime } from 'c15t/runtime';
-
-const clearOnRevocation = {
-	measurement: {
-		cookies: ['_ga', '_ga_*'],
-		localStorage: ['analytics:*'],
-	},
-	marketing: {
-		cookies: ['_fbp'],
-		sessionStorage: ['campaign-id'],
-	},
-} satisfies ClearOnRevocationConfig;
-
-const runtime = createConsentRuntime({
-	mode: hosted({ url: '/api/c15t' }),
-	clearOnRevocation,
-});
-
-// Start in the browser after mount. The endpoint must serve your c15t backend.
-runtime.start();
-
-// Call runtime.dispose() when the app no longer needs consent management.
-```
-
-For React, pass the same configuration through `ConsentProvider.options`:
-
-```tsx
-import type { ReactNode } from 'react';
-import { ConsentProvider, hosted } from 'c15t/react';
-
-const mode = hosted({ url: '/api/c15t' });
-
-export function Consent({ children }: { children: ReactNode }) {
-	return (
-		<ConsentProvider
-			options={{
-				mode,
-				clearOnRevocation: {
-					measurement: { cookies: ['_ga', '_ga_*'] },
-				},
-			}}
-		>
-			{children}
-		</ConsentProvider>
-	);
-}
-```
-
-The same option is available in Next.js and TanStack Start `ConsentRoot` props, Vue and
-Nuxt configuration, Svelte providers, and Astro integration options. Solid and
-other headless integrations can use `createConsentRuntime` as shown above.
-Every adapter uses the same cleanup module.
-
-Omitting `clearOnRevocation` leaves cleanup disabled. The provider option is
-initial-only. Remount the provider to replace its cleanup configuration. For
-a shared runtime, configure the runtime owner rather than a borrowing provider.
-
-## Matching names and cookie scopes
-
-Use an exact string or a nonempty prefix followed by `*`. `_ga_*` matches
-`_ga_ABC123`; it does not match `_ga`. Regular expressions, wildcards in other
-positions, and a bare `*` are unsupported. Web Storage keys may contain spaces,
-Unicode, and punctuation. Cookie names use their raw spelling, without URL
-decoding.
-
-Cookies can share a name while having different domains or paths. Cleanup
-tries the current host and its parent domains, and the current path and its
-ancestors. To target a specific scope, use an object:
-
-```ts
-const clearOnRevocation = {
-	measurement: {
-		cookies: [
-			{ name: 'analytics-id', domain: 'example.com', path: '/' },
-			{ name: 'checkout-metrics', domain: '', path: '/checkout' },
-			{ name: 'partitioned-metrics', partitioned: true },
-		],
-	},
-};
-```
-
-An empty `domain` means host-only. Explicit domains and paths replace the
-automatic attempts for that field. Exact names can be deleted at a configured
-path even when the current page cannot read that cookie. Prefix matching can
-only discover cookie names visible to the current page, so use an exact name
-for a cookie on another path.
-
-Partitioned cookies require `partitioned: true`; ordinary targets remove
-unpartitioned cookies. Cookie deletion preserves the browser's `__Secure-`
-and `__Host-` prefix requirements. c15t protects its own consent, notice,
-privacy, pending-save, and IAB consent records in cookies and localStorage,
-including configured custom storage keys, even if your patterns match them.
-c15t does not store consent in sessionStorage, so targeted entries there are
-removed even when their names match consent storage keys.
-
-## When cleanup runs
-
-The runtime attaches cleanup after persistence and the script loader. Cleanup
-waits while the policy is pending. On the first settled snapshot, it removes
-configured data for every denied category. This includes a new opt-in visitor
-who has not made a choice and a returning visitor whose permission expired.
-
-After that first pass, cleanup runs when a category changes from allowed to
-denied. Saving a refusal, expiry, a policy change, Global Privacy Control,
-or synchronized records can cause that transition. Under an opt-out policy,
-an expired grant that remains effectively allowed does not trigger deletion.
-The `necessary` category cannot be configured for cleanup.
-
-Cleanup keeps waiting if a failed initial request leaves the policy pending.
-If a previously settled policy falls back to denial after an initialization
-failure, cleanup removes its configured data. A later successful retry cannot
-restore deleted data.
-
-Runtime construction, server rendering, draft checkbox edits, opening the
-dialog, and disposal do not clear data. Cleanup does not poll storage or repeat
-on unrelated UI updates.
-
-## Use an existing kernel
-
-For a manually assembled integration, attach the module in the browser after
-persistence hydration and script-loader setup:
-
-```ts
-import { createClearOnRevocation } from 'c15t/modules/clear-on-revocation';
-
-const cleanup = createClearOnRevocation({
-	kernel,
-	config: { measurement: { cookies: ['_ga', '_ga_*'] } },
-	storageConfig,
-});
-
-// Stop observing consent when this integration is torn down.
-cleanup.dispose();
-```
-
-Here `kernel` is your existing consent kernel. Pass the same `storageConfig`
-used by persistence so cleanup protects custom record keys. Attaching the
-module can immediately clear denied categories if the policy is already
-settled. Do not also attach it when your provider or runtime owns cleanup.
-
-## Browser limits
-
-Cleanup can remove JavaScript-accessible first-party cookies and keys in the
-current origin's `localStorage` and `sessionStorage`. It cannot remove
-`HttpOnly` cookies or another origin's data. Keep `HttpOnly` protections and
-use your server to expire cookies that require server access. Cookie deletion
-must match the cookie's scope. See the
-[browser cookie documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Cookies).
-
-Browser restrictions can prevent reads or deletions. Cleanup failures do not
-block consent updates. A running SDK may write data again after a sweep, so
-keep script gating and the integration's consent-change or teardown behavior
-configured. Deleting a script element cannot undo JavaScript it already ran.

package/docs/integrations/granular-consent.md

@@ -1,210 +0,0 @@
----
-title: Granular consent
-description: Let visitors grant a category and still turn one vendor off,
-  without adopting IAB TCF.
-group: integrations
----
-
-Granular consent is choice below the category level: a visitor grants
-marketing and still turns Meta off. The unit of that choice is a vendor, so
-the API names them `vendors`, `vendor` and `data-vendor`, and the hooks
-`useVendorAllowed` and `useVendorDraft`. Everything else stays as it is:
-categories, policies, and the preference center gain vendor rows rather than
-a second consent model.
-
-## Declare vendors
-
-Add `vendors` to your runtime options. Each vendor sits inside a category
-condition and needs a name and a privacy policy URL so the preference surface
-can list it. The React provider takes the same option once its preference
-center renders vendor rows; scripts, rules and iframes are gated the same way
-whichever place declares it:
-
-```ts
-import { hosted, type Vendor } from 'c15t';
-import { createConsentRuntime } from 'c15t/runtime';
-
-const vendors = [
-	{
-		id: 'meta-pixel',
-		name: 'Meta Pixel',
-		category: 'marketing',
-		privacyPolicyUrl: 'https://www.facebook.com/privacy/policy/',
-		description: 'Ad conversion measurement and audiences.',
-	},
-	{
-		id: 'google-analytics',
-		name: 'Google Analytics',
-		category: 'measurement',
-		privacyPolicyUrl: 'https://policies.google.com/privacy',
-	},
-] satisfies Vendor[];
-
-const runtime = createConsentRuntime({
-	mode: hosted({ url: '/api/c15t' }),
-	vendors,
-	scripts: [
-		{
-			id: 'meta-pixel',
-			category: 'marketing',
-			vendor: 'meta-pixel',
-			src: 'https://connect.facebook.net/en_US/fbevents.js',
-		},
-	],
-});
-
-// Start in the browser after mount. The endpoint must serve your c15t backend.
-runtime.start();
-```
-
-The `id` is a lowercase slug of up to 64 characters. Reuse it as the `vendor`
-field on scripts and network rules and as the `data-vendor` attribute on
-iframes. Integrations from `@c15t/scripts` already set `vendor` to their
-manifest slug, so `gtag()` and `metaPixel()` need no extra wiring.
-
-A backend can also declare vendors. Add `vendors` and an optional
-`vendorListVersion` to the manifest configuration; `/init` returns them and the
-client merges them with the vendors declared in code. When both declare the
-same id, the copy declared in code wins, and the backend copy comes back if the
-code declaration is removed later. A slug used by a script, rule or iframe
-but declared nowhere still gates loading. It is hidden from the preference surface, and the
-runtime warns about it outside production.
-
-## How a vendor is gated
-
-A target loads when its category condition passes and the visitor has not
-turned its vendor off:
-
-```text
-loads  =  category condition satisfied  AND  vendor not denied
-```
-
-The category is evaluated first, so an unknown category still throws as a
-configuration error. The iframe blocker is the exception: an `<iframe>` with an
-unknown `data-category` stays blocked and logs a console warning, so one typo
-can't stop the other iframes on the page from being gated. A vendor toggle never grants a category on its own: with
-marketing denied, `meta-pixel` stays blocked whatever its own switch says.
-A script with `alwaysLoad` still mounts, as it does for a denied category;
-its callbacks receive the vendor result in `info.vendor.granted` so a
-self-managing SDK can honor it.
-
-Under an `iab` policy the `vendor` slug is inert. Vendor consent then comes from
-the TC string through `vendorId`, and the vendor rows are not shown.
-
-The same rule applies to the three gates:
-
-| Surface         | Field                           |
-| --------------- | ------------------------------- |
-| Script loader   | `Script.vendor`                 |
-| Network blocker | `NetworkBlockerRule.vendor`     |
-| Iframe blocker  | `data-vendor` on the `<iframe>` |
-
-An iframe with `data-vendor` and no `data-category` is gated on the vendor
-alone. An unknown `data-vendor` value is granted rather than thrown: a vendor
-the visitor never saw cannot have been turned off. Such a frame has no
-category to follow, so a denial the visitor recorded earlier holds even while
-nothing declares the slug, for example before the backend's vendor list has
-arrived on a cold start.
-
-A script, rule or frame keeps its slug declared for as long as it is
-configured. If a backend list or a provider update drops the entry, the
-loader or blocker puts it back, so a stored denial keeps gating it. A slug
-several modules share stays under every category they name it with, whichever
-module updates last, and drops a category only once no module names it there.
-Disposing a loader or blocker, or removing a gated frame from the page, drops
-what only it named, so a vendor no live module owns stops being toggleable.
-
-## Record a vendor choice
-
-Vendor grants travel with the save. Stage them and confirm with the next save,
-or pass them next to the categories:
-
-```ts
-// Stage from a toggle handler; nothing changes until save({}) runs. The
-// empty patch confirms no category, so only the staged vendor is recorded;
-// save() with no input would reconfirm every displayed category too.
-runtime.stageVendorConsent('meta-pixel', false);
-await runtime.kernel.commands.save({});
-
-// Or confirm categories and vendors in one action.
-await runtime.kernel.commands.save({
-	marketing: true,
-	measurement: true,
-	vendors: { 'meta-pixel': false },
-});
-```
-
-`stageVendorConsent` stages a vendor slug for the next save; it is not the
-IAB handle's `setVendorConsent`, which sets a TCF vendor by numeric id and
-takes effect at once. The grants can also travel in the save context as
-`{ vendors }`, which wins when both are given.
-
-Only the vendors the visitor turned off are stored. Accept all and reject all
-both clear that list, so vendors follow their category on a bulk action. A bulk
-action narrowed to the displayed categories only lifts the denials of vendors
-those categories decide on their own; a vendor another granted category would
-still load keeps its denial. A
-vendor that is not declared, or is declared with `disabled: true`, is ignored.
-Under an opt-out policy every vendor starts on and the stored list is the
-do-not-sell list.
-
-A vendor-only change records without touching category receipts. The kernel
-emits `vendors:recorded` rather than `choice:recorded`, writes the
-`<storageKey>-vendors` cookie and localStorage entry, and sends the complete
-grant map to the backend as `vendorChoice`. Category confirmation times are not
-renewed. The vendor entry also carries the subject id, so a visitor whose first
-act only decided vendors keeps the same subject after a reload even though no
-category record exists yet.
-
-Scripts see the vendor result in their callbacks. `ScriptCallbackInfo.vendor`
-carries `{ id, granted }` outside IAB mode. Integrations that send Google
-Consent Mode or RudderStack signals send every category as denied while their
-vendor is off, so the vendor's own consent API cannot re-enable tracking.
-
-## Show vendors in the preference center
-
-The `ConsentWidget` and `ConsentDialog` in React, Vue and Svelte list vendors
-under their category when the provider declares them. Pass the same `vendors`
-array to `ConsentProvider`, to the `vendors` prop of `ConsentRoot` in
-[Next.js](https://c15t.com/docs/frameworks/next/script-loader#granular-consent) and
-[TanStack Start](https://c15t.com/docs/frameworks/tanstack-start/quickstart#granular-consent),
-to the Nuxt module or Vue plugin config next to `scripts`, or to
-`ConsentManagerProvider` options in Svelte:
-
-```tsx
-import { ConsentProvider, hosted } from 'c15t/react';
-
-<ConsentProvider options={{ mode: hosted({ url: '/api/c15t' }), vendors }}>
-	{children}
-</ConsentProvider>;
-```
-
-Each category row expands to one card per vendor with its own switch. The
-switches disable while the category is off in the draft, and Save records the
-vendors the visitor moved. A custom control uses `useVendorDraft()` from
-`c15t/react` to read and stage the same grants, with `isStale` and `reset` for
-a draft the policy or vendor list changed under, and `useVendorAllowed(id)` to
-read one vendor's effective result. Copy comes from
-`consentManagerDialog.vendors.{title, privacyPolicy, disabledByCategory,
-switchLabel}` in the translations. In Vue, `useConsentDraft()` returns the
-same `vendors` map and `setVendor`; in Svelte, `getConsentManager()` exposes
-`selectedVendors`, `setSelectedVendor` and `getDisplayedVendors(category)`.
-The three frameworks render the same cards, and the parity suite compares
-their markup, accessibility tree, computed styles and geometry.
-
-## What a denial does not do
-
-Turning a vendor off blocks future loads and requests. It does not delete the
-cookies that vendor already set, and
-[clear on revocation](./clear-on-revocation.md) does not help here:
-it runs when a category is denied, and the category stays granted when only one
-of its vendors is off. Remove that vendor's cookies yourself from an
-`onConsentChange` callback that checks `info.vendor.granted`.
-
-A vendor denial has no expiry and no policy basis. It stays until the visitor
-changes it or a bulk action clears it, including across a policy change that
-requires the category choice again.
-
-Adding a vendor to the list does not reopen consent. New vendors default to on
-inside a granted category. Use the policy rule's `copyRevision` when a new
-vendor should prompt the visitor again.