@reblu/site-next 1.8.0 → 1.10.0

package/dist/consent.d.cts

@@ -0,0 +1,172 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { c as ConsentCategoryState, b as ConsentCategory } from './consent-shared-DbdhEXW2.cjs';
+import { AnalyticsScriptsProps } from './analytics.cjs';
+
+/**
+ * `<ConsentProvider>` / `useConsent()` — the client half of cookie consent
+ * (REB-642). See `../consent-shared` for the fail-closed parsing this relies
+ * on (imported from there, not `../consent-server`, to keep `node:crypto` out
+ * of this client entry), and `docs/architecture/cookie-consent.md` for the
+ * full design.
+ *
+ * `status: 'unknown'` is the DEFAULT-DENIED state and the value every
+ * `<ConsentGate>` treats as "not granted" — see `./gate.tsx`. It covers three
+ * cases identically, on purpose: no cookie yet, a cookie that failed
+ * `parseConsentCookie`, and a cookie recorded under a `policyVersion` that no
+ * longer matches (the tenant edited the cookie policy — REB-642's "re-ask when
+ * the version changes"). None of the three may ever resolve to granted.
+ */
+/** Whether the visitor's choice for the CURRENT policy version is known. */
+type ConsentStatus = 'unknown' | 'resolved';
+interface ConsentContextValue {
+    status: ConsentStatus;
+    categories: ConsentCategoryState;
+    /** True only when `status === 'resolved'` AND the category was explicitly granted. */
+    isGranted: (category: ConsentCategory) => boolean;
+    /** Grants every category and persists immediately. */
+    acceptAll: () => void;
+    /** Denies every category and persists immediately — the denial persists across reloads. */
+    rejectAll: () => void;
+    /** Persists exactly the categories passed — no category is granted implicitly. */
+    savePreferences: (categories: ConsentCategoryState) => void;
+    preferencesOpen: boolean;
+    openPreferences: () => void;
+    closePreferences: () => void;
+    /**
+     * Refocuses whatever element had focus immediately before `openPreferences`
+     * was called. The preferences dialog is openable from more than one place
+     * (the banner's "Configure" button, `<CookiePreferencesTrigger>` elsewhere
+     * in the tree) with no single `<Dialog.Trigger>` for Radix's own
+     * focus-restore to key off, so this is tracked explicitly here — the one
+     * funnel every opener already goes through.
+     */
+    restoreLastFocus: () => void;
+}
+interface ConsentProviderProps {
+    children: ReactNode;
+    /**
+     * `cookiePolicyVersion(tenant.cookiePolicy)` from the SITE's analytics
+     * config, or `null` when no cookie policy is stored. A stored consent
+     * recorded under a DIFFERENT version is treated as unresolved.
+     */
+    policyVersion: string | null;
+}
+declare function ConsentProvider({ children, policyVersion }: ConsentProviderProps): react_jsx_runtime.JSX.Element;
+/** Throws outside a `<ConsentProvider>` — a silent default would be a silent consent bypass. */
+declare function useConsent(): ConsentContextValue;
+
+interface ConsentGateProps {
+    category: ConsentCategory;
+    children: ReactNode;
+}
+/**
+ * `<ConsentGate>` — the allowlist enforced by construction that REB-642's
+ * design settles on: a third party is never rendered except through a
+ * component that names a consent category, and a denied or UNRESOLVED
+ * category renders `null`.
+ *
+ * The `status !== 'resolved'` branch matters as much as the denied branch: a
+ * gate that rendered children while consent is still `'unknown'` would load
+ * the third party on every fresh visitor for the split second before their
+ * cookie is read, which is exactly the race `docs/architecture/cookie-consent.md`
+ * §6.1 designs around by building tags inside a client component instead of
+ * passing a server-rendered `<AnalyticsScripts>` through as `children`.
+ */
+declare function ConsentGate({ category, children }: ConsentGateProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * `<ConsentedAnalytics>` — the `'analytics'`-gated replacement for rendering
+ * `<AnalyticsScripts>` directly in a SITE layout (REB-642 Slice 1).
+ *
+ * Reuses the REB-617 validation + escaping builders verbatim via
+ * `<AnalyticsScripts>` — this component adds NOTHING to the sink-safety
+ * argument in `../analytics.tsx`, it only decides WHETHER that already-safe
+ * renderer mounts at all. A SITE layout that still imports
+ * `@reblu/site-next/analytics` directly bypasses consent entirely, which is
+ * exactly what the source-scanning guard (REB-642 Slice 1, demo-site) exists
+ * to catch — this component is the mechanism that guard enforces.
+ */
+declare function ConsentedAnalytics(props: AnalyticsScriptsProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Copy for `<CookieBanner>`. SDK-owned defaults in Spanish (every Reblu SITE
+ * renders `<html lang='es'>` today).
+ *
+ * REB-642 §7.1 recommends tenant-editable copy be limited to a TITLE/BODY
+ * override for v1 — the per-category descriptions, the "necessary" copy and
+ * every button label stay fixed, because the copy is a compliance surface: a
+ * tenant writing "we use cookies — OK" with no reject option is the exact
+ * misconfiguration this design exists to prevent. This type is intentionally
+ * a `Partial<ConsentBannerTexts>` at the call site (see `CookieBanner`), so a
+ * later tenant-configuration slice can override `title`/`description` without
+ * touching this component's contract.
+ */
+interface ConsentBannerTexts {
+    title: string;
+    description: string;
+    acceptLabel: string;
+    rejectLabel: string;
+    manageLabel: string;
+    policyLinkLabel: string;
+    preferencesTitle: string;
+    preferencesDescription: string;
+    saveLabel: string;
+    necessaryLabel: string;
+    necessaryDescription: string;
+    categoryLabels: Record<ConsentCategory, string>;
+    categoryDescriptions: Record<ConsentCategory, string>;
+}
+declare const DEFAULT_CONSENT_BANNER_TEXTS: ConsentBannerTexts;
+
+/**
+ * `<CookieBanner>` + `<CookiePreferencesTrigger>` — the visible layer of
+ * REB-642's consent mechanism.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * ARCHITECTURE: ONE DIALOG, TWO OPENERS
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * `<CookieBanner>` owns rendering the preferences dialog (mount it ONCE, at
+ * the root of the SITE layout — it portals to `<body>` regardless of where it
+ * is mounted). `<CookiePreferencesTrigger>` is a small, unstyled-by-default
+ * button usable ANYWHERE ELSE in the tree (a footer link, a settings page) that
+ * opens the SAME dialog via `useConsent().openPreferences()`. Both read the
+ * single `preferencesOpen` boolean the `<ConsentProvider>` owns, so there is
+ * never more than one dialog instance and never two focus traps competing.
+ *
+ * This is what REB-642 calls "permanent withdrawal" — a visitor's route back
+ * to their preferences does not depend on the first-layer banner still being
+ * on screen; the banner disappears once resolved, the trigger does not.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * THE THREE-BUTTON RULE (owner decision, not configurable)
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * Reject / Configure / Accept render as three same-variant, same-size buttons
+ * in that visual order — no button is styled as more prominent than another.
+ * A tenant can override `title`/`description` text (REB-642 §7.1 recommends
+ * v1 ship with NO tenant-editable copy at all, but the prop exists so a later
+ * slice can add it without touching this component's contract); the buttons,
+ * their order, and the category taxonomy are fixed.
+ */
+interface CookieBannerProps {
+    /** Overrides merged onto `DEFAULT_CONSENT_BANNER_TEXTS`. */
+    texts?: Partial<ConsentBannerTexts>;
+    /** Where "Política de cookies" links to. */
+    policyHref?: string;
+}
+declare function CookieBanner({ texts: textsOverride, policyHref }: CookieBannerProps): react_jsx_runtime.JSX.Element;
+interface CookiePreferencesTriggerProps {
+    children?: ReactNode;
+    className?: string;
+    texts?: Partial<ConsentBannerTexts>;
+}
+/**
+ * A persistent "configure cookies" entry point, safe to place anywhere in the
+ * tree (typically a footer link) once `<CookieBanner>` is mounted at the root.
+ * Opens the same preferences dialog `<CookieBanner>` owns.
+ */
+declare function CookiePreferencesTrigger({ children, className, texts: textsOverride, }: CookiePreferencesTriggerProps): react_jsx_runtime.JSX.Element;
+
+export { type ConsentBannerTexts, type ConsentContextValue, ConsentGate, type ConsentGateProps, ConsentProvider, type ConsentProviderProps, type ConsentStatus, ConsentedAnalytics, CookieBanner, type CookieBannerProps, CookiePreferencesTrigger, type CookiePreferencesTriggerProps, DEFAULT_CONSENT_BANNER_TEXTS, useConsent };

package/dist/consent.d.ts

@@ -0,0 +1,172 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { c as ConsentCategoryState, b as ConsentCategory } from './consent-shared-DbdhEXW2.js';
+import { AnalyticsScriptsProps } from './analytics.js';
+
+/**
+ * `<ConsentProvider>` / `useConsent()` — the client half of cookie consent
+ * (REB-642). See `../consent-shared` for the fail-closed parsing this relies
+ * on (imported from there, not `../consent-server`, to keep `node:crypto` out
+ * of this client entry), and `docs/architecture/cookie-consent.md` for the
+ * full design.
+ *
+ * `status: 'unknown'` is the DEFAULT-DENIED state and the value every
+ * `<ConsentGate>` treats as "not granted" — see `./gate.tsx`. It covers three
+ * cases identically, on purpose: no cookie yet, a cookie that failed
+ * `parseConsentCookie`, and a cookie recorded under a `policyVersion` that no
+ * longer matches (the tenant edited the cookie policy — REB-642's "re-ask when
+ * the version changes"). None of the three may ever resolve to granted.
+ */
+/** Whether the visitor's choice for the CURRENT policy version is known. */
+type ConsentStatus = 'unknown' | 'resolved';
+interface ConsentContextValue {
+    status: ConsentStatus;
+    categories: ConsentCategoryState;
+    /** True only when `status === 'resolved'` AND the category was explicitly granted. */
+    isGranted: (category: ConsentCategory) => boolean;
+    /** Grants every category and persists immediately. */
+    acceptAll: () => void;
+    /** Denies every category and persists immediately — the denial persists across reloads. */
+    rejectAll: () => void;
+    /** Persists exactly the categories passed — no category is granted implicitly. */
+    savePreferences: (categories: ConsentCategoryState) => void;
+    preferencesOpen: boolean;
+    openPreferences: () => void;
+    closePreferences: () => void;
+    /**
+     * Refocuses whatever element had focus immediately before `openPreferences`
+     * was called. The preferences dialog is openable from more than one place
+     * (the banner's "Configure" button, `<CookiePreferencesTrigger>` elsewhere
+     * in the tree) with no single `<Dialog.Trigger>` for Radix's own
+     * focus-restore to key off, so this is tracked explicitly here — the one
+     * funnel every opener already goes through.
+     */
+    restoreLastFocus: () => void;
+}
+interface ConsentProviderProps {
+    children: ReactNode;
+    /**
+     * `cookiePolicyVersion(tenant.cookiePolicy)` from the SITE's analytics
+     * config, or `null` when no cookie policy is stored. A stored consent
+     * recorded under a DIFFERENT version is treated as unresolved.
+     */
+    policyVersion: string | null;
+}
+declare function ConsentProvider({ children, policyVersion }: ConsentProviderProps): react_jsx_runtime.JSX.Element;
+/** Throws outside a `<ConsentProvider>` — a silent default would be a silent consent bypass. */
+declare function useConsent(): ConsentContextValue;
+
+interface ConsentGateProps {
+    category: ConsentCategory;
+    children: ReactNode;
+}
+/**
+ * `<ConsentGate>` — the allowlist enforced by construction that REB-642's
+ * design settles on: a third party is never rendered except through a
+ * component that names a consent category, and a denied or UNRESOLVED
+ * category renders `null`.
+ *
+ * The `status !== 'resolved'` branch matters as much as the denied branch: a
+ * gate that rendered children while consent is still `'unknown'` would load
+ * the third party on every fresh visitor for the split second before their
+ * cookie is read, which is exactly the race `docs/architecture/cookie-consent.md`
+ * §6.1 designs around by building tags inside a client component instead of
+ * passing a server-rendered `<AnalyticsScripts>` through as `children`.
+ */
+declare function ConsentGate({ category, children }: ConsentGateProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * `<ConsentedAnalytics>` — the `'analytics'`-gated replacement for rendering
+ * `<AnalyticsScripts>` directly in a SITE layout (REB-642 Slice 1).
+ *
+ * Reuses the REB-617 validation + escaping builders verbatim via
+ * `<AnalyticsScripts>` — this component adds NOTHING to the sink-safety
+ * argument in `../analytics.tsx`, it only decides WHETHER that already-safe
+ * renderer mounts at all. A SITE layout that still imports
+ * `@reblu/site-next/analytics` directly bypasses consent entirely, which is
+ * exactly what the source-scanning guard (REB-642 Slice 1, demo-site) exists
+ * to catch — this component is the mechanism that guard enforces.
+ */
+declare function ConsentedAnalytics(props: AnalyticsScriptsProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Copy for `<CookieBanner>`. SDK-owned defaults in Spanish (every Reblu SITE
+ * renders `<html lang='es'>` today).
+ *
+ * REB-642 §7.1 recommends tenant-editable copy be limited to a TITLE/BODY
+ * override for v1 — the per-category descriptions, the "necessary" copy and
+ * every button label stay fixed, because the copy is a compliance surface: a
+ * tenant writing "we use cookies — OK" with no reject option is the exact
+ * misconfiguration this design exists to prevent. This type is intentionally
+ * a `Partial<ConsentBannerTexts>` at the call site (see `CookieBanner`), so a
+ * later tenant-configuration slice can override `title`/`description` without
+ * touching this component's contract.
+ */
+interface ConsentBannerTexts {
+    title: string;
+    description: string;
+    acceptLabel: string;
+    rejectLabel: string;
+    manageLabel: string;
+    policyLinkLabel: string;
+    preferencesTitle: string;
+    preferencesDescription: string;
+    saveLabel: string;
+    necessaryLabel: string;
+    necessaryDescription: string;
+    categoryLabels: Record<ConsentCategory, string>;
+    categoryDescriptions: Record<ConsentCategory, string>;
+}
+declare const DEFAULT_CONSENT_BANNER_TEXTS: ConsentBannerTexts;
+
+/**
+ * `<CookieBanner>` + `<CookiePreferencesTrigger>` — the visible layer of
+ * REB-642's consent mechanism.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * ARCHITECTURE: ONE DIALOG, TWO OPENERS
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * `<CookieBanner>` owns rendering the preferences dialog (mount it ONCE, at
+ * the root of the SITE layout — it portals to `<body>` regardless of where it
+ * is mounted). `<CookiePreferencesTrigger>` is a small, unstyled-by-default
+ * button usable ANYWHERE ELSE in the tree (a footer link, a settings page) that
+ * opens the SAME dialog via `useConsent().openPreferences()`. Both read the
+ * single `preferencesOpen` boolean the `<ConsentProvider>` owns, so there is
+ * never more than one dialog instance and never two focus traps competing.
+ *
+ * This is what REB-642 calls "permanent withdrawal" — a visitor's route back
+ * to their preferences does not depend on the first-layer banner still being
+ * on screen; the banner disappears once resolved, the trigger does not.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * THE THREE-BUTTON RULE (owner decision, not configurable)
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * Reject / Configure / Accept render as three same-variant, same-size buttons
+ * in that visual order — no button is styled as more prominent than another.
+ * A tenant can override `title`/`description` text (REB-642 §7.1 recommends
+ * v1 ship with NO tenant-editable copy at all, but the prop exists so a later
+ * slice can add it without touching this component's contract); the buttons,
+ * their order, and the category taxonomy are fixed.
+ */
+interface CookieBannerProps {
+    /** Overrides merged onto `DEFAULT_CONSENT_BANNER_TEXTS`. */
+    texts?: Partial<ConsentBannerTexts>;
+    /** Where "Política de cookies" links to. */
+    policyHref?: string;
+}
+declare function CookieBanner({ texts: textsOverride, policyHref }: CookieBannerProps): react_jsx_runtime.JSX.Element;
+interface CookiePreferencesTriggerProps {
+    children?: ReactNode;
+    className?: string;
+    texts?: Partial<ConsentBannerTexts>;
+}
+/**
+ * A persistent "configure cookies" entry point, safe to place anywhere in the
+ * tree (typically a footer link) once `<CookieBanner>` is mounted at the root.
+ * Opens the same preferences dialog `<CookieBanner>` owns.
+ */
+declare function CookiePreferencesTrigger({ children, className, texts: textsOverride, }: CookiePreferencesTriggerProps): react_jsx_runtime.JSX.Element;
+
+export { type ConsentBannerTexts, type ConsentContextValue, ConsentGate, type ConsentGateProps, ConsentProvider, type ConsentProviderProps, type ConsentStatus, ConsentedAnalytics, CookieBanner, type CookieBannerProps, CookiePreferencesTrigger, type CookiePreferencesTriggerProps, DEFAULT_CONSENT_BANNER_TEXTS, useConsent };