@c15t/scripts 2.1.0 → 2.2.0-canary-20260804162155

package/docs/integrations/vercel-analytics.md

@@ -0,0 +1,141 @@
+---
+title: Vercel Analytics
+description: Bootstrap Vercel Analytics with a declarative queue and script attributes.
+group: integrations
+icon: vercel-analytics
+---
+Vercel Analytics loads through `@c15t/scripts` using a declarative queue bootstrap (`vaq` + `va`) and script attributes for DSN/endpoint options.
+
+## Integrate with c15t
+
+**React**
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/react';
+import { vercelAnalytics } from '@c15t/scripts/vercel-analytics';
+
+const scripts = [vercelAnalytics()];
+
+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 { vercelAnalytics } from '@c15t/scripts/vercel-analytics';
+
+const scripts = [vercelAnalytics()];
+
+export function ConsentProvider({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        scripts,
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+**JavaScript**
+
+```ts
+import { getOrCreateConsentRuntime } from 'c15t';
+import { vercelAnalytics } from '@c15t/scripts/vercel-analytics';
+
+getOrCreateConsentRuntime({
+  mode: 'hosted',
+  backendURL: 'https://your-instance.c15t.dev',
+  scripts: [vercelAnalytics()],
+});
+```
+
+## How c15t loads it
+
+* **Category:** `measurement` (Analytics)
+* **Loads when:** measurement consent is granted
+* **On revocation:** unloaded - c15t removes the script from the DOM and clears access to runtime globals until consent is granted again.
+
+Load the debug bundle or a custom endpoint when needed:
+
+```ts
+vercelAnalytics({
+  mode: 'development',
+  disableAutoTrack: true,
+  endpoint: 'https://analytics.example.com/v1/events',
+})
+```
+
+## Tracking events in your app
+
+c15t initializes a bootstrap phase first (`vaq` plus a local `window.va` stub), then loads the remote Vercel Analytics script after `measurement` consent is granted. Calls are safe once the bootstrap stub exists (they are queued/ignored in `vaq`), but they execute only after consent is granted and the real `window.va` is injected and flushes the queue.
+
+Guard event calls by checking consent state. From React:
+
+```tsx
+import { useCallback } from 'react';
+import { useConsentManager } from '@c15t/react';
+
+function SignupExample() {
+  const { has } = useConsentManager();
+
+  const trackSignup = useCallback(() => {
+    if (has('measurement')) {
+      window.va?.('signup', { plan: 'pro' });
+    }
+  }, [has]);
+}
+```
+
+From plain JavaScript:
+
+```ts
+import { getOrCreateConsentRuntime } from 'c15t';
+
+const { consentStore } = getOrCreateConsentRuntime();
+
+if (consentStore.getState().has('measurement')) {
+  window.va?.('signup', { plan: 'pro' });
+}
+```
+
+## Types
+
+### VercelAnalyticsOptions
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`VercelAnalyticsOptions\`|
+|Source Path|\`./packages/scripts/src/vendors/analytics/vercel-analytics.ts\`|
+
+\*ExtractedTypeTable: Could not extract "VercelAnalyticsOptions" from "./packages/scripts/src/vendors/analytics/vercel-analytics.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+### Script
+
+|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.\*

package/docs/integrations/x-pixel.md

@@ -0,0 +1,157 @@
+---
+title: X Pixel (Twitter Pixel)
+description: Track conversions and build audiences for advertising campaigns on
+  X (formerly Twitter).
+icon: x
+group: integrations
+---
+X Pixel (formerly Twitter Pixel) is X's conversion tracking and audience building tool. It helps you measure ad performance, retarget website visitors, and optimize campaigns on the X platform.
+
+## Official X documentation
+
+* [Conversion tracking for websites (X Ads Help)](https://business.x.com/en/help/campaign-measurement-and-analytics/conversion-tracking-for-websites)
+
+## Integrate with c15t
+
+**React**
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/react';
+import { xPixel } from '@c15t/scripts/x-pixel';
+
+const scripts = [xPixel({ pixelId: '123456789012345' })];
+
+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 { xPixel } from '@c15t/scripts/x-pixel';
+
+const scripts = [xPixel({ pixelId: '123456789012345' })];
+
+export function ConsentProvider({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        scripts,
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+**JavaScript**
+
+```ts
+import { getOrCreateConsentRuntime } from 'c15t';
+import { xPixel } from '@c15t/scripts/x-pixel';
+
+getOrCreateConsentRuntime({
+  mode: 'hosted',
+  backendURL: 'https://your-instance.c15t.dev',
+  scripts: [xPixel({ pixelId: '123456789012345' })],
+});
+```
+
+## How c15t loads it
+
+* **Category:** `marketing` (Ads & Pixels)
+* **Loads when:** marketing consent is granted
+* **On revocation:** unloaded — c15t removes the script element from the DOM
+
+## Configure the integration
+
+You can use the `xPixelEvent` function to track events. This is a wrapper around the `twq` function that the X Pixel script uses.
+
+```ts
+import { xPixelEvent } from '@c15t/scripts/x-pixel';
+
+xPixelEvent('tw-xxxx-xxxx', { value: 10.00, currency: 'USD' });
+```
+
+## Tracking events in your app
+
+c15t gates the X Pixel script from loading until `marketing` consent is granted. Your application code that calls `twq` or the `xPixelEvent` helper is **not** automatically gated — `window.twq` does not exist before consent is granted, and is removed again if consent is revoked. Unguarded calls throw.
+
+Guard event calls by checking consent state:
+
+```tsx
+import { useCallback } from 'react';
+import { useConsentManager } from '@c15t/react';
+import { xPixelEvent } from '@c15t/scripts/x-pixel';
+
+function useTrackPurchase() {
+  const { has } = useConsentManager();
+  return useCallback(() => {
+    if (has('marketing')) {
+      xPixelEvent('tw-xxxx-xxxx', { value: 10.0, currency: 'USD' });
+    }
+  }, [has]);
+}
+
+function PurchaseButton() {
+  const trackPurchase = useTrackPurchase();
+  return <button onClick={trackPurchase}>Complete purchase</button>;
+}
+```
+
+## Types
+
+### XPixelOptions
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`XPixelOptions\`|
+|Source Path|\`./packages/scripts/src/vendors/ads-and-pixels/x-pixel.ts\`|
+
+\*ExtractedTypeTable: Could not extract "XPixelOptions" from "./packages/scripts/src/vendors/ads-and-pixels/x-pixel.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+### Script
+
+|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.\*
+
+### XPixelEvent
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`XPixelEvent\`|
+|Source Path|\`./packages/scripts/src/vendors/ads-and-pixels/x-pixel.ts\`|
+
+\*ExtractedTypeTable: Could not extract "XPixelEvent" from "./packages/scripts/src/vendors/ads-and-pixels/x-pixel.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+### XPixelContent
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`XPixelContent\`|
+|Source Path|\`./packages/scripts/src/vendors/ads-and-pixels/x-pixel.ts\`|
+
+\*ExtractedTypeTable: Could not extract "XPixelContent" from "./packages/scripts/src/vendors/ads-and-pixels/x-pixel.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*

package/docs/integrations/youtube.md

@@ -0,0 +1,193 @@
+---
+title: YouTube
+description: Keep YouTube iframes unmounted until consent with a
+  privacy-enhanced, lazy-loaded React or Next.js embed.
+icon: youtube
+group: integrations
+---
+`YouTubeEmbed` is a renderable integration for React and Next.js. It uses c15t's
+`Frame` consent boundary, so the YouTube iframe is not mounted and no YouTube
+request is made until the configured consent category is allowed.
+
+The component does not load the YouTube IFrame Player API. It is intended for
+standard iframe embeds and keeps script readiness separate from iframe gating.
+
+## Integrate with c15t
+
+`YouTubeEmbed` 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 { YouTubeEmbed } from '@c15t/react';
+
+export function ProductVideo() {
+  return (
+    <YouTubeEmbed
+      consentCategory="marketing"
+      params={{ controls: true, playsinline: true }}
+      title="Product overview"
+      videoId="dQw4w9WgXcQ"
+    />
+  );
+}
+```
+
+**Next.js**
+
+```tsx
+'use client';
+
+import { YouTubeEmbed } from '@c15t/nextjs';
+
+export function ProductVideo() {
+  return (
+    <YouTubeEmbed
+      consentCategory="marketing"
+      params={{ controls: true, playsinline: true }}
+      title="Product overview"
+      videoId="dQw4w9WgXcQ"
+    />
+  );
+}
+```
+
+`marketing` is the default category. Choose a different category only when it
+matches the purpose of the embed and the policy presented to your users.
+
+## How c15t loads it
+
+* **Before consent:** c15t renders a placeholder and does not mount the iframe.
+* **After consent:** the iframe mounts with its final embed URL.
+* **On revocation:** the `Frame` boundary unmounts the iframe, stopping the
+  embedded player and future requests from that document.
+* **Loading behavior:** c15t reserves the final player size, shows a localized
+  loading state, and uses native iframe lazy loading by default.
+* **Default layout:** the placeholder and player share a responsive 16:9,
+  borderless frame with a `200px` minimum height.
+* **Privacy-enhanced mode:** URLs built from `videoId` use
+  `youtube-nocookie.com` by default.
+
+Privacy-enhanced mode changes the YouTube host but does not replace consent
+gating. Keep the iframe behind the category required by your privacy policy.
+
+## Build the embed URL
+
+Prefer `videoId` when you control the video:
+
+```tsx
+<YouTubeEmbed
+  consentCategory="marketing"
+  params={{
+    autoplay: false,
+    controls: true,
+    playsinline: true,
+    rel: false,
+  }}
+  start={36}
+  title="Quarterly product update"
+  videoId="dQw4w9WgXcQ"
+/>
+```
+
+Boolean `params` are serialized as YouTube's `1` and `0` values. `start` is
+serialized as the player's start time in seconds. If `params.start` is also
+present, the top-level `start` prop takes precedence.
+
+Set `privacyEnhanced={false}` only when you intentionally need the regular
+`youtube.com` host.
+
+### Migrate an existing iframe URL
+
+Use `src` when you already have a complete embed URL:
+
+```tsx
+<YouTubeEmbed
+  consentCategory="marketing"
+  src="https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ?start=36"
+  title="Quarterly product update"
+/>
+```
+
+When `src` is provided, c15t uses it unchanged. TypeScript treats `src` and
+`videoId` as mutually exclusive source modes: `start`, `params`, and
+`privacyEnhanced` are available only with `videoId`.
+
+## Style the wrapper and iframe
+
+`wrapperClassName` targets the consent-gated `Frame`. `className` and the
+forwarded ref target the iframe itself.
+
+The defaults are responsive and stable without utility classes. Override them
+only when your layout needs a different aspect ratio or height:
+
+```tsx
+<YouTubeEmbed
+  consentCategory="marketing"
+  frameProps={{ style: { aspectRatio: '4 / 3', minHeight: 280 } }}
+  style={{ borderRadius: 4 }}
+  title="Product overview"
+  videoId="dQw4w9WgXcQ"
+/>
+```
+
+`frameProps.style` is merged after the wrapper defaults. The iframe fills that
+wrapper, has no border, and inherits the wrapper radius by default.
+
+## Customize the placeholder
+
+```tsx
+import { Frame, YouTubeEmbed } from '@c15t/react';
+
+<YouTubeEmbed
+  consentCategory="marketing"
+  placeholder={
+    <Frame.Root>
+      <Frame.Title>Allow marketing consent to watch this video.</Frame.Title>
+      <Frame.Button category="marketing" />
+    </Frame.Root>
+  }
+  title="Product overview"
+  videoId="dQw4w9WgXcQ"
+/>
+```
+
+Custom placeholders should explain why the content is blocked and provide a
+clear way to change consent. Always give the iframe a meaningful `title`.
+
+Use `loadingFallback` to replace the post-consent loading message and
+`errorFallback` to replace the configuration error state. If neither `videoId`
+nor `src` is supplied at runtime, the component renders that error state instead
+of mounting an iframe.
+
+Standard cross-origin iframes do not provide a reliable player-error signal.
+`YouTubeEmbed` forwards the iframe's native `onError` when a browser emits it,
+but player-level errors require the YouTube IFrame Player API and are outside
+this iframe-only component.
+
+## Verify setup
+
+1. Clear saved consent and reload the page.
+2. Confirm there is no YouTube iframe or YouTube network request before consent.
+3. Grant the configured category and confirm exactly one iframe mounts.
+4. Confirm a `videoId` embed uses `youtube-nocookie.com` unless
+   `privacyEnhanced={false}`.
+5. Revoke consent and confirm the iframe is removed.
+6. Confirm the default 16:9 frame is borderless and reserves the same space at
+   mobile and desktop widths.
+
+See YouTube's [embedded player parameters](https://developers.google.com/youtube/player_parameters)
+for the supported query parameters.
+
+## Types
+
+### YouTubeEmbedProps
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`YouTubeEmbedProps\`|
+|Source Path|\`./packages/react/src/components/integrations/youtube-embed.tsx\`|
+
+\*ExtractedTypeTable: Could not extract "YouTubeEmbedProps" from "./packages/react/src/components/integrations/youtube-embed.tsx" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*