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

package/docs/headless.md

@@ -0,0 +1,190 @@
+---
+title: Headless Mode
+description: Build fully custom consent UI using only hooks - no pre-built components required.
+---
+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>
+  );
+}
+```
+
+## 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>
+  );
+}
+```

package/docs/hooks/use-color-scheme.md

@@ -0,0 +1,40 @@
+---
+title: useColorScheme
+description: Manage light/dark mode preferences for consent components.
+---
+`useColorScheme()` manages the color scheme preference for c15t components. It sets up the appropriate CSS class and media query listeners.
+
+```tsx
+import { useColorScheme } from '@c15t/react';
+
+function ThemeManager() {
+  useColorScheme('system'); // Follow system preference
+}
+```
+
+## Parameters
+
+|Value|Behavior|
+|--|--|
+|`'light'`|Force light mode|
+|`'dark'`|Force dark mode|
+|`'system'`|Follow `prefers-color-scheme` media query|
+|`null`|Disable - c15t won't manage color scheme|
+|`undefined`|No-op|
+
+## Provider-Level Configuration
+
+You can also set the color scheme on the provider without using this hook:
+
+```tsx
+<ConsentManagerProvider
+  options={{
+    colorScheme: 'system',
+    // ...
+  }}
+>
+```
+
+## System Preference Detection
+
+When set to `'system'`, the hook listens for changes to the `prefers-color-scheme` media query and updates automatically when the user changes their OS theme.

package/docs/hooks/use-consent-manager/checking-consent.md

@@ -0,0 +1,94 @@
+---
+title: Checking Consent
+description: Use has() for flexible consent checks with AND, OR, and NOT logic. Check if any consent exists with hasConsented().
+---
+## has(condition)
+
+The `has()` method evaluates whether the current consent state satisfies a condition. It supports simple category checks and complex logical expressions.
+
+### Simple Check
+
+```tsx
+const { has } = useConsentManager();
+
+if (has('measurement')) {
+  // User has granted measurement consent
+}
+```
+
+### AND Logic
+
+All conditions must be true:
+
+```tsx
+has({ and: ['measurement', 'marketing'] })
+// true only if BOTH measurement AND marketing are granted
+```
+
+### OR Logic
+
+At least one condition must be true:
+
+```tsx
+has({ or: ['measurement', 'marketing'] })
+// true if EITHER measurement OR marketing is granted
+```
+
+### NOT Logic
+
+Negates a condition:
+
+```tsx
+has({ not: 'marketing' })
+// true if marketing consent is NOT granted
+```
+
+### Nested Conditions
+
+Combine operators for complex logic:
+
+```tsx
+has({
+  and: [
+    'necessary',
+    { or: ['measurement', 'marketing'] },
+    { not: 'functionality' },
+  ],
+})
+// true if: necessary AND (measurement OR marketing) AND NOT functionality
+```
+
+### HasCondition Type
+
+```ts
+type HasCondition<CategoryType> =
+  | CategoryType                                    // "measurement"
+  | { and: HasCondition[] | HasCondition }          // { and: ["a", "b"] }
+  | { or: HasCondition[] | HasCondition }           // { or: ["a", "b"] }
+  | { not: HasCondition }                           // { not: "a" }
+```
+
+## hasConsented()
+
+Returns `true` if the user has made any consent choice (accepted, rejected, or customized). Returns `false` if no consent has been recorded yet.
+
+```tsx
+const { hasConsented } = useConsentManager();
+
+if (hasConsented()) {
+  // User has previously made a consent choice
+} else {
+  // First visit — no consent recorded
+}
+```
+
+## getDisplayedConsents()
+
+Returns the consent types that should be displayed in the UI (based on active `consentCategories` and each type's `display` property):
+
+```tsx
+const { getDisplayedConsents } = useConsentManager();
+
+const visibleCategories = getDisplayedConsents();
+// Returns ConsentType[] with name, description, defaultValue, etc.
+```

package/docs/hooks/use-consent-manager/location-info.md

@@ -0,0 +1,95 @@
+---
+title: Location Info
+description: Access detected jurisdiction, country, and region. Override geolocation for testing.
+---
+## locationInfo
+
+The `locationInfo` state contains the user's detected geographic information:
+
+```tsx
+const { locationInfo } = useConsentManager();
+
+if (locationInfo) {
+  console.log(locationInfo.jurisdiction); // 'GDPR', 'CCPA', etc.
+  console.log(locationInfo.countryCode);  // 'DE', 'US', etc.
+  console.log(locationInfo.regionCode);   // 'BY', 'CA', etc.
+}
+```
+
+`locationInfo` is `null` until the backend responds with geolocation data (or in offline mode if no overrides are set).
+
+## Jurisdiction Codes
+
+|Code|Region|Consent Model|
+|--|--|--|
+|`GDPR`|European Union|opt-in|
+|`UK_GDPR`|United Kingdom|opt-in|
+|`CH`|Switzerland|opt-in|
+|`BR`|Brazil (LGPD)|opt-in|
+|`APPI`|Japan|opt-in|
+|`PIPA`|South Korea|opt-in|
+|`PIPEDA`|Canada (excl. Quebec)|opt-out|
+|`QC_LAW25`|Quebec, Canada|opt-in|
+|`CCPA`|California, USA|opt-out|
+|`AU`|Australia|opt-out|
+|`NONE`|No jurisdiction|null model|
+
+## setOverrides()
+
+Override detected values for testing or manual configuration. This triggers a re-fetch of consent banner data with the new values:
+
+```tsx
+const { setOverrides } = useConsentManager();
+
+// Override country (triggers jurisdiction detection)
+await setOverrides({ country: 'DE' });
+
+// Override language
+await setOverrides({ language: 'de' });
+
+// Override both
+await setOverrides({ country: 'US', region: 'CA', language: 'es' });
+```
+
+## setLocationInfo()
+
+Directly set location info without triggering a re-fetch:
+
+```tsx
+const { setLocationInfo } = useConsentManager();
+
+setLocationInfo({
+  jurisdiction: 'GDPR',
+  countryCode: 'DE',
+  regionCode: 'BY',
+});
+```
+
+## Testing Different Jurisdictions
+
+A development-only component for testing consent behavior across jurisdictions:
+
+```tsx
+function JurisdictionTester() {
+  const { setOverrides, model, locationInfo } = useConsentManager();
+
+  const testCases = [
+    { label: 'GDPR', country: 'DE' },
+    { label: 'CCPA', country: 'US', region: 'CA' },
+    { label: 'PIPEDA', country: 'CA', region: undefined },
+    { label: 'QC_LAW25', country: 'CA', region: 'QC' },
+    { label: 'NONE', country: 'US', region: 'TX' },
+  ];
+
+  return (
+    <div>
+      <p>Current: {locationInfo?.jurisdiction ?? 'none'} → model: {model}</p>
+      {testCases.map((tc) => (
+        <button key={tc.label} onClick={() => setOverrides({ country: tc.country, region: tc.region })}>
+          Test as {tc.label}
+        </button>
+      ))}
+    </div>
+  );
+}
+```