@c15t/react 2.0.4 → 2.2.0-canary-20260727202135

package/docs/integrations/google-maps.md

@@ -0,0 +1,263 @@
+---
+title: Google Maps
+description: Render Google Maps only after consent with one shared Maps
+  JavaScript API loader and independently managed map instances.
+icon: google-maps
+group: integrations
+---
+`GoogleMap` is a renderable integration for React and Next.js. It keeps the
+Google Maps JavaScript API off the page until the configured consent category is
+allowed, then loads the SDK once and creates a map for each mounted component.
+
+Unlike the helpers from `@c15t/scripts`, `GoogleMap` owns both the consent-aware
+script lifecycle and the visible map container.
+
+> ℹ️ **Info:**
+> The browser must receive a Google Maps API key, so the key is visible to site visitors. Keep it out of source control, use a key created for browser use, and restrict it by website and API in Google Cloud.
+
+## Integrate with c15t
+
+`GoogleMap` must render inside a `ConsentManagerProvider`. Complete the
+[React quickstart](/docs/frameworks/react/quickstart) or
+[Next.js quickstart](/docs/frameworks/next/quickstart) first.
+
+**React**
+
+```tsx
+import { GoogleMap } from '@c15t/react';
+
+const apiKey = import.meta.env.VITE_GOOGLE_MAPS_API_KEY;
+
+export function StoreMap() {
+  if (!apiKey) {
+    return <p>Google Maps is not configured.</p>;
+  }
+
+  return (
+    <GoogleMap
+      apiKey={apiKey}
+      authReferrerPolicy="origin"
+      center={{ lat: 40.7128, lng: -74.006 }}
+      consentCategory="measurement"
+      style={{ height: 400 }}
+      zoom={12}
+    />
+  );
+}
+```
+
+**Next.js**
+
+```tsx
+'use client';
+
+import { GoogleMap } from '@c15t/nextjs';
+
+const apiKey = process.env.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY;
+
+export function StoreMap() {
+  if (!apiKey) {
+    return <p>Google Maps is not configured.</p>;
+  }
+
+  return (
+    <GoogleMap
+      apiKey={apiKey}
+      authReferrerPolicy="origin"
+      center={{ lat: 40.7128, lng: -74.006 }}
+      consentCategory="measurement"
+      style={{ height: 400 }}
+      zoom={12}
+    />
+  );
+}
+```
+
+`measurement` is a common choice for an interactive map, but the correct
+category depends on why your application uses Google Maps and the policy shown
+to your users.
+
+## How c15t loads it
+
+* **Before consent:** no Maps JavaScript API script is requested and no map
+  instance is created.
+* **After consent:** c15t registers one shared SDK loader and waits for Google's
+  callback before constructing the map.
+* **Multiple maps:** components with the same `scriptId` reuse the SDK while
+  keeping separate map instances.
+* **On revocation or unmount:** the component clears the map instance and its
+  listeners. The page-level SDK registration is retained after its first load
+  because Google supports one loader per page.
+* **Existing SDK:** if another part of the application already loaded a
+  compatible Google Maps global, the component adopts it instead of adding a
+  duplicate script.
+* **Visible states:** the blocked, loading, and error states are accessible and
+  use the active c15t translations by default.
+
+Keep one `scriptId` and one loader configuration across the page. Override the
+default `scriptId` only to coordinate with a known c15t script registration, not
+to load a second Maps SDK configuration. If two maps register conflicting
+loader options, c15t reports the conflict and tells you to align the key,
+language, region, libraries, and other loader options. A different `scriptId`
+does not make a second Google loader safe.
+
+## Configure the map
+
+Pass `center`, `zoom`, `mapId`, and `options` as you would when constructing a
+Google map:
+
+```tsx
+<GoogleMap
+  apiKey={apiKey}
+  center={{ lat: 51.5072, lng: -0.1276 }}
+  consentCategory="measurement"
+  mapId="YOUR_MAP_ID"
+  options={{
+    disableDefaultUI: true,
+    gestureHandling: 'cooperative',
+  }}
+  zoom={11}
+/>
+```
+
+Changes to `center`, `zoom`, and updateable `options` are applied to the existing
+map. Changing `mapId` recreates it because Google treats that value as
+construction-time configuration.
+
+The component has a default height of `320px`. Override `style.height` or apply
+a class with an explicit height when your layout needs another size.
+
+### Loader options
+
+The direct Maps JavaScript API loader options are available as component props:
+
+* `libraries`
+* `language`
+* `region`
+* `version`
+* `authReferrerPolicy`
+* `mapIds`
+* `channel`
+* `solutionChannel`
+* `nonce`
+
+`mapIds` preloads map ID configuration; `mapId` selects the map ID for the
+component instance.
+
+## Handle loading and errors
+
+The built-in loading and error states use `frame.loading` and `frame.error` from
+your c15t messages. The consent placeholder uses the localized consent-type
+title in both its message and button—for example, an `Analytics` title produces
+“Enable Analytics consent.”
+
+Use the fallback props when you need integration-specific content and `onError`
+for reporting:
+
+```tsx
+import { Frame, GoogleMap } from '@c15t/react';
+
+function reportMapError(error: Error) {
+  // Send the error to your observability provider.
+}
+
+<GoogleMap
+  apiKey={apiKey}
+  center={{ lat: 40.7128, lng: -74.006 }}
+  consentCategory="measurement"
+  loadingFallback={<p>Loading map…</p>}
+  errorFallback={<p>The map could not be loaded.</p>}
+  onError={reportMapError}
+  placeholder={
+    <Frame.Root>
+      <Frame.Title>Allow measurement consent to view this map.</Frame.Title>
+      <Frame.Button category="measurement" />
+    </Frame.Root>
+  }
+/>
+```
+
+`onError` covers loader failures, timeouts, map-constructor failures, and
+Google's global authentication failure callback. Authentication failures
+usually indicate an invalid key, missing billing, a disabled API, or a referrer
+that is not allowed.
+
+If you provide a custom `placeholder`, include `Frame.Button` or another way to
+reopen consent preferences or grant the required category.
+
+### Retry a failed map
+
+Increment `retryKey` to retry the same map after a loader, authentication, or
+constructor failure:
+
+```tsx
+import { GoogleMap } from '@c15t/react';
+import { useState } from 'react';
+
+function RetryableMap({ apiKey }: { apiKey: string }) {
+  const [retryKey, setRetryKey] = useState(0);
+
+  return (
+    <>
+      <GoogleMap
+        apiKey={apiKey}
+        center={{ lat: 40.7128, lng: -74.006 }}
+        retryKey={retryKey}
+      />
+
+      <button type="button" onClick={() => setRetryKey((key) => key + 1)}>
+        Retry map
+      </button>
+    </>
+  );
+}
+```
+
+Changing `retryKey` clears the failed attempt and retries with the same
+`scriptId`. A successful page-level SDK registration remains shared and is not
+loaded again.
+
+## Secure the browser key
+
+For production:
+
+1. Create a key specifically for the browser application.
+2. Apply a **Websites** application restriction for every allowed development
+   and production origin.
+3. Restrict the key to the **Maps JavaScript API** and any additional APIs used
+   by requested libraries.
+4. Keep the value in an untracked environment file and expose it through the
+   browser environment variable required by your framework.
+5. Monitor key usage and rotate the key if you see unexpected traffic.
+
+When `authReferrerPolicy="origin"` is set, configure origin-level website
+restrictions without URL paths.
+
+* [Google Maps Platform security guidance](https://developers.google.com/maps/api-security-best-practices)
+* [Maps JavaScript API loader options](https://developers.google.com/maps/documentation/javascript/load-maps-js-api)
+* [Maps Demo Key for local prototypes](https://developers.google.com/maps/documentation/javascript/demo-key)
+
+## Verify setup
+
+1. Clear saved consent and reload the page.
+2. Confirm no request to `maps.googleapis.com/maps/api/js` occurs before the
+   configured category is allowed.
+3. Grant consent and confirm the map reaches its ready state.
+4. Render two maps with the same `scriptId` and confirm only one loader script is
+   added.
+5. Revoke consent and confirm each map instance is removed.
+6. Test a rejected key or referrer and confirm `errorFallback` and `onError`
+   receive the failure.
+7. Fix the rejected configuration, change `retryKey`, and confirm the map can
+   recover without changing `scriptId`.
+
+## Types
+
+### GoogleMapProps
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`GoogleMapProps\`|
+|Source Path|\`./packages/react/src/components/integrations/google-map.tsx\`|
+
+\*ExtractedTypeTable: Could not extract "GoogleMapProps" from "./packages/react/src/components/integrations/google-map.tsx" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*

package/docs/integrations/google-tag-manager.md

@@ -1,31 +1,104 @@
 ---
 title: Google Tag Manager
-description: Deploy and manage marketing tags centrally with automatic consent state synchronization.
-lastModified: 2026-02-10
-
+description: Deploy and manage marketing tags centrally with automatic consent
+  state synchronization.
 icon: google-tag-manager
+group: integrations
 ---
 Google Tag Manager (GTM) is Google's tag management system that lets you deploy and manage marketing tags, analytics scripts, and conversion pixels without modifying your codebase. Instead of hardcoding multiple scripts, you configure them through GTM's web interface.
 
-c15t automatically injects the GTM script into your page and syncs consent state with GTM using Consent Mode v2. By default, c15t loads GTM regardless of consent because GTM manages its own internal consent state and only fires tags when appropriate consent is granted.
+c15t automatically injects the GTM script into your page and syncs consent state with GTM using Consent Mode v2. GTM manages its own internal consent state and only fires tags when appropriate consent is granted, which means it can safely load before consent is collected.
 
 This prevents GTM-managed scripts from loading without proper consent while giving you centralized control over your marketing stack.
 
 > ℹ️ **Info:**
 > Use GTM if your team manages many tags centrally in the GTM UI. Use gtag.js if you only need GA4/Google Ads directly in code. Don't run both for the same destination unless intentional, or you may duplicate events.
 
-## Implementation
+## Integrate with c15t
+
+Use your GTM container ID, which begins with `GTM-`.
+
+**React**
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/react';
+import { googleTagManager } from '@c15t/scripts/google-tag-manager';
+
+const scripts = [googleTagManager({ id: 'GTM-XXXXXXX' })];
+
+export function ConsentProvider({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: 'https://your-instance.c15t.dev',
+        scripts,
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+**Next.js**
+
+```tsx
+'use client';
+
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/nextjs';
+import { googleTagManager } from '@c15t/scripts/google-tag-manager';
+
+const scripts = [googleTagManager({ id: 'GTM-XXXXXXX' })];
+
+export function ConsentProvider({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        scripts,
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+**JavaScript**
+
+```ts
+import { getOrCreateConsentRuntime } from 'c15t';
+import { googleTagManager } from '@c15t/scripts/google-tag-manager';
+
+getOrCreateConsentRuntime({
+  mode: 'hosted',
+  backendURL: 'https://your-instance.c15t.dev',
+  scripts: [googleTagManager({ id: 'GTM-XXXXXXX' })],
+});
+```
+
+## How c15t loads it
+
+* **Category:** `necessary` (Tag Managers)
+* **Loads when:** [`alwaysLoad`](/docs/frameworks/react/script-loader#always-load) — runs on page start with Consent Mode v2 defaults set to denied
+* **On consent change:** c15t pushes a Consent Mode v2 `update` to the data layer; GTM-managed tags re-evaluate against the new state
+
+## Configure the integration
 
 1. **Creating a Tag Manager Container**
 
-   > ℹ️ Info:
-   >
+   > 📝 Note:
    > This step is optional if you already have a Tag Manager container. Ensure your container has consent overview enabled.
 
    After signing into Google Tag Manager, you can create a new container.
    Continue to Google Tag Manager
 
-   In Tag Manager, click Admin > Container Settings.Under Additional Settings, select "Enable consent overview".
+   1. In Tag Manager, click Admin > Container Settings.
+   2. Under Additional Settings, select "Enable consent overview".
 
    Enable consent overview
 
@@ -37,25 +110,22 @@ This prevents GTM-managed scripts from loading without proper consent while givi
 
    Create trigger
 
-3. **Adding / Updating tags** Now for your existing tags, you can add the "consent-update" trigger to the tag, this will fire the update event when the consent state is updated & it has the appropriate consent state.
+3. **Update tags** Now for your existing tags, you can add the "consent-update" trigger to the tag, this will fire the update event when the consent state is updated & it has the appropriate consent state.
 
    Update tags
 
-4. **Setting up c15t with Google Tag Manager** After creating your container, you can set up c15t with Google Tag Manager. All you need to do is copy and paste your container ID & begins with "GTM-".
+## Tracking events in your app
 
-   > ℹ️ Info:
-   >
-   > See the integration overview for how to pass scripts to your framework (JavaScript, React, or Next.js).
+GTM is `alwaysLoad: true`, so the GTM container and `window.dataLayer` are present from page start regardless of consent. Calls like `dataLayer.push({ event: 'signup' })` are **safe at any time** — Consent Mode v2 defaults are set to denied before the user makes a choice, and GTM-managed tags only fire when the matching consent has been granted.
 
-   ```ts
-   import { googleTagManager } from '@c15t/scripts/google-tag-manager';
+```ts
+window.dataLayer = window.dataLayer || [];
+window.dataLayer.push({ event: 'signup' });
+```
 
-   googleTagManager({
-     id: 'GTM-XXXXXXX',
-   })
-   ```
+You do not need to wrap `dataLayer.push(...)` in a `useConsentManager().has(...)` check — the consent gate happens inside GTM, not inside c15t.
 
-## Post-setup verification checklist
+## Verify setup
 
 1. Open GTM Preview mode and confirm your container (`GTM-...`) loads on page load.
 2. Before giving consent, confirm non-essential tags do not fire in GTM Preview.
@@ -67,87 +137,18 @@ This prevents GTM-managed scripts from loading without proper consent while givi
 
 ### GoogleTagManagerOptions
 
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|string|Your Google Tag Manager container ID. Begins with 'GTM-'.|-|✅ Required|
-|updateEventName|string \|undefined|Custom event name fired after consent updates. Can be used as a trigger in GTM to load scripts once consent is updated.|'consent-update'|Optional|
-|consentMapping|Record\<string, string\[]> \|undefined|Custom mapping from c15t consent categories to Google Consent Mode v2 types. Overrides the default mapping when provided.|\`\`\`ts \{ necessary: \['security\_storage'], functionality: \['functionality\_storage'], measurement: \['analytics\_storage'], marketing: \['ad\_storage', 'ad\_user\_data', 'ad\_personalization'], experience: \['personalization\_storage'], } \`\`\`|Optional|
+|Property|Value|
+|:--|:--|
+|Type Name|\`GoogleTagManagerOptions\`|
+|Source Path|\`./packages/scripts/src/vendors/tag-managers/google-tag-manager.ts\`|
+
+\*ExtractedTypeTable: Could not extract "GoogleTagManagerOptions" from "./packages/scripts/src/vendors/tag-managers/google-tag-manager.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
 
 ### Script
 
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|string|Unique identifier for the script|-|✅ Required|
-|src|string \|undefined|URL of the script to load|-|Optional|
-|textContent|string \|undefined|Inline JavaScript code to execute|-|Optional|
-|category|HasCondition\<AllConsentNames>|Consent category or condition required to load this script|-|✅ Required|
-|callbackOnly|boolean \|undefined|Whether this is a callback-only script that doesn't need to load an external resource. When true, no script tag will be added to the DOM, only callbacks will be executed.|false|Optional|
-|persistAfterConsentRevoked|boolean \|undefined|Whether the script should persist after consent is revoked.|false|Optional|
-|alwaysLoad|boolean \|undefined|Whether the script should always load regardless of consent state. This is useful for scripts like Google Tag Manager or PostHog that manage their own consent state internally. The script will load immediately and never be unloaded based on consent changes. Note: When using this option, you are responsible for ensuring the script itself respects user consent preferences through its own consent management.|false|Optional|
-|fetchPriority|"high" \|"low" \|"auto" \|undefined|Priority hint for browser resource loading|-|Optional|
-|attributes|Record\<string, string> \|undefined|Additional attributes to add to the script element|-|Optional|
-|async|boolean \|undefined|Whether to use async loading|-|Optional|
-|defer|boolean \|undefined|Whether to defer script loading|-|Optional|
-|nonce|string \|undefined|Content Security Policy nonce|-|Optional|
-|anonymizeId|boolean \|undefined|Whether to use an anonymized ID for the script element, this helps ensure the script is not blocked by ad blockers|true|Optional|
-|target|"head" \|"body" \|undefined|Where to inject the script element in the DOM. Options: \`'head'\`: Scripts are appended to \`\<head>\` (default); \`'body'\`: Scripts are appended to \`\<body>\`|'head'|Optional|
-|onBeforeLoad|Object \|undefined|Callback executed before the script is loaded|-|Optional|
-|onLoad|Object \|undefined|Callback executed when the script loads successfully|-|Optional|
-|onError|Object \|undefined|Callback executed if the script fails to load|-|Optional|
-|onConsentChange|Object \|undefined|Callback executed whenever the consent store is changed. This callback only applies to scripts already loaded.|-|Optional|
-|vendorId|string \|number \|undefined|IAB TCF vendor ID - links script to a registered vendor. When in IAB mode, the script will only load if this vendor has consent. Takes precedence over \`category\` when in IAB mode. Use custom vendor IDs (string or number) to gate non-IAB vendors too.|-|Optional|
-|iabPurposes|number\[] \|undefined|IAB TCF purpose IDs this script requires consent for. When in IAB mode and no vendorId is set, the script will only load if ALL specified purposes have consent.|-|Optional|
-|iabLegIntPurposes|number\[] \|undefined|IAB TCF legitimate interest purpose IDs. These purposes can operate under legitimate interest instead of consent. The script loads if all iabPurposes have consent OR all iabLegIntPurposes have legitimate interest established.|-|Optional|
-|iabSpecialFeatures|number\[] \|undefined|IAB TCF special feature IDs this script requires. Options: 1: Use precise geolocation data; 2: Actively scan device characteristics for identification|-|Optional|
-
-#### `onBeforeLoad`
-
-Callback executed before the script is loaded
-
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|string|The original script ID|-|✅ Required|
-|elementId|string|The actual DOM element ID used (anonymized if enabled)|-|✅ Required|
-|hasConsent|boolean|Has consent|-|✅ Required|
-|consents|ConsentState|The current consent state|-|✅ Required|
-|element|HTMLScriptElement \|undefined|The script element (for load/error callbacks) Will be undefined for callback-only scripts|-|Optional|
-|error|Error \|undefined|Error information (for error callbacks)|-|Optional|
-
-#### `onLoad`
-
-Callback executed when the script loads successfully
-
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|string|The original script ID|-|✅ Required|
-|elementId|string|The actual DOM element ID used (anonymized if enabled)|-|✅ Required|
-|hasConsent|boolean|Has consent|-|✅ Required|
-|consents|ConsentState|The current consent state|-|✅ Required|
-|element|HTMLScriptElement \|undefined|The script element (for load/error callbacks) Will be undefined for callback-only scripts|-|Optional|
-|error|Error \|undefined|Error information (for error callbacks)|-|Optional|
-
-#### `onError`
-
-Callback executed if the script fails to load
-
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|string|The original script ID|-|✅ Required|
-|elementId|string|The actual DOM element ID used (anonymized if enabled)|-|✅ Required|
-|hasConsent|boolean|Has consent|-|✅ Required|
-|consents|ConsentState|The current consent state|-|✅ Required|
-|element|HTMLScriptElement \|undefined|The script element (for load/error callbacks) Will be undefined for callback-only scripts|-|Optional|
-|error|Error \|undefined|Error information (for error callbacks)|-|Optional|
-
-#### `onConsentChange`
-
-Callback executed whenever the consent store is changed. This callback only applies to scripts already loaded.
-
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|string|The original script ID|-|✅ Required|
-|elementId|string|The actual DOM element ID used (anonymized if enabled)|-|✅ Required|
-|hasConsent|boolean|Has consent|-|✅ Required|
-|consents|ConsentState|The current consent state|-|✅ Required|
-|element|HTMLScriptElement \|undefined|The script element (for load/error callbacks) Will be undefined for callback-only scripts|-|Optional|
-|error|Error \|undefined|Error information (for error callbacks)|-|Optional|
+|Property|Value|
+|:--|:--|
+|Type Name|\`Script\`|
+|Source Path|\`./packages/core/src/libs/script-loader/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "Script" from "./packages/core/src/libs/script-loader/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*