@c15t/react 2.0.0-rc.0 → 2.0.0-rc.10

package/docs/iab/use-gvl-data.md

@@ -0,0 +1,208 @@
+---
+title: useGVLData
+description: Hook to access processed Global Vendor List (GVL) data for building custom IAB TCF UI components.
+---
+> ❌ **Error:**
+> c15t is not yet IAB certified. The IAB TCF components are under active development and should not be used in production. APIs and behavior may change before certification is achieved.
+
+`useGVLData()` processes the raw IAB Global Vendor List (GVL) into a UI-friendly format. It handles purpose grouping into stacks, vendor mapping, special purpose/feature extraction, and loading state.
+
+Use this hook when building a custom IAB TCF UI instead of the pre-built `IABConsentDialog`.
+
+```tsx
+import { useGVLData } from '@c15t/react/hooks';
+
+function CustomIABPreferences() {
+  const { purposes, stacks, standalonePurposes, totalVendors, isLoading } = useGVLData();
+
+  if (isLoading) return <p>Loading vendor data...</p>;
+
+  return (
+    <div>
+      <p>{totalVendors} partners</p>
+      {standalonePurposes.map((purpose) => (
+        <div key={purpose.id}>
+          <h3>{purpose.name}</h3>
+          <p>{purpose.description}</p>
+          <p>{purpose.vendors.length} vendors</p>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+> ℹ️ **Info:**
+> Must be used within a ConsentManagerProvider with IAB mode enabled. Returns empty data if IAB is not configured.
+
+## Return Value
+
+The hook returns a `GVLData` object:
+
+### GVLData
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|purposes|ProcessedPurpose|-|-|✅ Required|
+|specialPurposes|ProcessedPurpose|-|-|✅ Required|
+|specialFeatures|ProcessedSpecialFeature|-|-|✅ Required|
+|features|ProcessedFeature|-|-|✅ Required|
+|stacks|ProcessedStack|-|-|✅ Required|
+|standalonePurposes|ProcessedPurpose|-|-|✅ Required|
+|totalVendors|number|-|-|✅ Required|
+|isLoading|boolean|-|-|✅ Required|
+
+#### `purposes` ProcessedPurpose
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|id|number|-|-|✅ Required|
+|name|string|-|-|✅ Required|
+|description|string|-|-|✅ Required|
+|descriptionLegal|string \|undefined|-|-|Optional|
+|illustrations|string\[]|-|-|✅ Required|
+|vendors|ProcessedVendor|-|-|✅ Required|
+|isSpecialPurpose|boolean \|undefined|-|-|Optional|
+
+#### `specialPurposes` ProcessedPurpose
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|id|number|-|-|✅ Required|
+|name|string|-|-|✅ Required|
+|description|string|-|-|✅ Required|
+|descriptionLegal|string \|undefined|-|-|Optional|
+|illustrations|string\[]|-|-|✅ Required|
+|vendors|ProcessedVendor|-|-|✅ Required|
+|isSpecialPurpose|boolean \|undefined|-|-|Optional|
+
+#### `specialFeatures` ProcessedSpecialFeature
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|id|number|-|-|✅ Required|
+|name|string|-|-|✅ Required|
+|description|string|-|-|✅ Required|
+|descriptionLegal|string \|undefined|-|-|Optional|
+|illustrations|string\[]|-|-|✅ Required|
+|vendors|ProcessedVendor|-|-|✅ Required|
+
+#### `features` ProcessedFeature
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|id|number|-|-|✅ Required|
+|name|string|-|-|✅ Required|
+|description|string|-|-|✅ Required|
+|descriptionLegal|string \|undefined|-|-|Optional|
+|illustrations|string\[]|-|-|✅ Required|
+|vendors|ProcessedVendor|-|-|✅ Required|
+
+#### `stacks` ProcessedStack
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|id|number|-|-|✅ Required|
+|name|string|-|-|✅ Required|
+|description|string|-|-|✅ Required|
+|purposes|ProcessedPurpose|-|-|✅ Required|
+
+#### `standalonePurposes` ProcessedPurpose
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|id|number|-|-|✅ Required|
+|name|string|-|-|✅ Required|
+|description|string|-|-|✅ Required|
+|descriptionLegal|string \|undefined|-|-|Optional|
+|illustrations|string\[]|-|-|✅ Required|
+|vendors|ProcessedVendor|-|-|✅ Required|
+|isSpecialPurpose|boolean \|undefined|-|-|Optional|
+
+## Types
+
+### ProcessedPurpose
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|id|number|-|-|✅ Required|
+|name|string|-|-|✅ Required|
+|description|string|-|-|✅ Required|
+|descriptionLegal|string \|undefined|-|-|Optional|
+|illustrations|string\[]|-|-|✅ Required|
+|vendors|ProcessedVendor|-|-|✅ Required|
+|isSpecialPurpose|boolean \|undefined|-|-|Optional|
+
+#### `vendors` ProcessedVendor
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|id|VendorId|-|-|✅ Required|
+|name|string|-|-|✅ Required|
+|policyUrl|string|-|-|✅ Required|
+|usesNonCookieAccess|boolean|-|-|✅ Required|
+|deviceStorageDisclosureUrl|string \|null|-|-|✅ Required|
+|usesCookies|boolean|-|-|✅ Required|
+|cookieMaxAgeSeconds|number \|null|-|-|✅ Required|
+|cookieRefresh|boolean \|undefined|-|-|Optional|
+|specialPurposes|number\[]|-|-|✅ Required|
+|specialFeatures|number\[]|-|-|✅ Required|
+|features|number\[]|-|-|✅ Required|
+|purposes|number\[]|-|-|✅ Required|
+|legIntPurposes|number\[]|-|-|✅ Required|
+|legitimateInterestUrl|string \|null \|undefined|-|-|Optional|
+|isCustom|boolean \|undefined|-|-|Optional|
+|usesLegitimateInterest|boolean \|undefined|-|-|Optional|
+|dataRetention|Object \|undefined|-|-|Optional|
+|dataDeclaration|number\[] \|undefined|-|-|Optional|
+
+### ProcessedVendor
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|id|VendorId|-|-|✅ Required|
+|name|string|-|-|✅ Required|
+|policyUrl|string|-|-|✅ Required|
+|usesNonCookieAccess|boolean|-|-|✅ Required|
+|deviceStorageDisclosureUrl|string \|null|-|-|✅ Required|
+|usesCookies|boolean|-|-|✅ Required|
+|cookieMaxAgeSeconds|number \|null|-|-|✅ Required|
+|cookieRefresh|boolean \|undefined|-|-|Optional|
+|specialPurposes|number\[]|-|-|✅ Required|
+|specialFeatures|number\[]|-|-|✅ Required|
+|features|number\[]|-|-|✅ Required|
+|purposes|number\[]|-|-|✅ Required|
+|legIntPurposes|number\[]|-|-|✅ Required|
+|legitimateInterestUrl|string \|null \|undefined|-|-|Optional|
+|isCustom|boolean \|undefined|-|-|Optional|
+|usesLegitimateInterest|boolean \|undefined|-|-|Optional|
+|dataRetention|Object \|undefined|-|-|Optional|
+|dataDeclaration|number\[] \|undefined|-|-|Optional|
+
+#### `dataRetention`
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|purposes|Record\<number, number> \|undefined|-|-|Optional|
+|specialPurposes|Record\<number, number> \|undefined|-|-|Optional|
+|stdRetention|number \|undefined|-|-|Optional|
+
+### ProcessedStack
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|id|number|-|-|✅ Required|
+|name|string|-|-|✅ Required|
+|description|string|-|-|✅ Required|
+|purposes|ProcessedPurpose|-|-|✅ Required|
+
+### ProcessedSpecialFeature
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|id|number|-|-|✅ Required|
+|name|string|-|-|✅ Required|
+|description|string|-|-|✅ Required|
+|descriptionLegal|string \|undefined|-|-|Optional|
+|illustrations|string\[]|-|-|✅ Required|
+|vendors|ProcessedVendor|-|-|✅ Required|

package/docs/iframe-blocking.md

@@ -0,0 +1,107 @@
+---
+title: Iframe Blocking
+description: Block embedded content (YouTube, social widgets, maps) until users grant consent for the appropriate category.
+---
+Embedded iframes from third parties (YouTube, Google Maps, social media widgets) can set cookies and track users without their consent. c15t provides two approaches to gate iframes behind consent:
+
+1. **`<Frame>` component** - A React component that conditionally renders children based on consent
+2. **HTML `data-category` attribute** - For raw `<iframe>` elements outside of React
+
+## Frame Component
+
+The `<Frame>` component wraps content that requires consent. Children are only mounted when the specified category has consent. When consent is not granted, a placeholder is shown instead.
+
+```tsx
+import { Frame } from '@c15t/react';
+
+function YouTubeEmbed() {
+  return (
+    <Frame category="marketing">
+      <iframe
+        src="https://www.youtube.com/embed/dQw4w9WgXcQ"
+        width="560"
+        height="315"
+        allowFullScreen
+      />
+    </Frame>
+  );
+}
+```
+
+### Custom Placeholder
+
+Replace the default placeholder with your own UI:
+
+```tsx
+<Frame
+  category="marketing"
+  placeholder={
+    <div className="flex items-center justify-center h-64 bg-gray-100 rounded">
+      <p>Enable marketing cookies to watch this video.</p>
+    </div>
+  }
+>
+  <iframe src="https://www.youtube.com/embed/..." />
+</Frame>
+```
+
+### Compound Components
+
+Build custom placeholder layouts using compound components:
+
+```tsx
+<Frame.Root category="marketing">
+  <Frame.Title category="marketing" />
+  <Frame.Button category="marketing" />
+</Frame.Root>
+```
+
+## HTML Attribute Approach
+
+For iframes outside of React (e.g., CMS content, server-rendered HTML), add `data-category` and use `data-src` instead of `src`:
+
+```html
+<iframe
+  data-src="https://www.youtube.com/embed/dQw4w9WgXcQ"
+  data-category="marketing"
+  width="560"
+  height="315"
+></iframe>
+```
+
+When consent for the specified category is granted, c15t automatically swaps `data-src` to `src`, loading the iframe. When consent is revoked, `src` is moved back to `data-src`.
+
+### Dynamic Iframes
+
+c15t uses a `MutationObserver` to watch for dynamically added iframes. Any iframe with `data-category` added to the DOM after initialization is automatically processed.
+
+## Initializing the Iframe Blocker
+
+The iframe blocker for HTML attributes needs to be initialized separately from the Frame component:
+
+```tsx
+import { useConsentManager } from '@c15t/react';
+import { useEffect } from 'react';
+
+function IframeBlockerInit() {
+  const { initializeIframeBlocker } = useConsentManager();
+
+  useEffect(() => {
+    initializeIframeBlocker();
+  }, [initializeIframeBlocker]);
+
+  return null;
+}
+```
+
+## API Reference
+
+### FrameProps
+
+|Property|Type|Description|Default|Required|
+|:--|:--|:--|:--|:--:|
+|children|ReactNode|Content rendered when consent is granted. Children are not mounted until consent is given, preventing unnecessary network requests.|-|✅ Required|
+|category|AllConsentNames|Consent category required to render children.|-|✅ Required|
+|placeholder|ReactNode|A custom placeholder component to display when consent is not met. If not provided, a default placeholder will be displayed.|-|Optional|
+|noStyle|boolean \|undefined|When true, removes all default styling from the component|false|Optional|
+|theme|any|Custom theme to override default styles while maintaining structure and accessibility. Merges with defaults. Ignored when \`noStyle=\{true}\`.|undefined|Optional|