@cartbase/storefront 0.1.0

package/src/tracking/consent-banner.tsx

@@ -0,0 +1,355 @@
+"use client"
+
+import { useCallback, useEffect, useState } from "react"
+
+import {
+  CONSENT_OPEN_EVENT,
+  applyConsent,
+  openConsentSettings,
+  readConsentCookie,
+  writeConsentCookie,
+  type ConsentChoices,
+  type ConsentCopy,
+  type ConsentLayout,
+} from "./consent"
+
+/**
+ * ConsentBanner — the built-in Consent Mode v2 UI.
+ *
+ * Ported from the barter reference implementation
+ * `src/components/storefront/consent/consent-banner.tsx` (itself from
+ * `@1click/ui/src/tracking/consent-banner.tsx` v2.3.1, shipped on Alenika
+ * d3d3d39), parameterized per docs/cards/consent-management.md: copy +
+ * layout + privacyHref + rejectOnFirstLayer come from the store's config
+ * (`GET /api/store/consent` — `copy` is REQUIRED here because the server
+ * payload is always complete; pick the locale with `pickConsentCopy()`).
+ * Class names use STOREFRONT theme tokens (bg-card / text-foreground / …)
+ * — no hardcoded colors; a storefront's theme defines them, which is how
+ * per-store accents work.
+ *
+ * Two layouts (merchant setting):
+ *   - `modal` (default, per merchant decision 2026-07-18: bars get
+ *     ignored, and an ignored banner = permanently denied consent): a
+ *     centered blocking modal over a dark backdrop, body scroll locked,
+ *     no click-outside dismiss and no X — the only exits are a consent
+ *     choice. Shown once per stored choice (12-month cookie).
+ *   - `banner-bottom`: a non-blocking bottom banner — NO backdrop, NO
+ *     scroll lock, NOT aria-modal, and it must not trap focus (card
+ *     trap). Same two layers, same exits.
+ *
+ * Layer 1: short text + accept (primary) + settings (ghost). A
+ * first-layer reject renders only when `rejectOnFirstLayer` is true —
+ * default follows the prevailing EU e-commerce pattern where declining
+ * lives one layer deeper. The settings layer ALWAYS carries a functional
+ * reject-all — reject exists and is reachable (not a cookie wall), which
+ * is what keeps the pattern defensible.
+ *
+ * Layer 2: purpose toggles + save + accept-all + reject-all.
+ * Re-openable any time via `openConsentSettings()` (see
+ * <ConsentSettingsLink>) so consent can be changed/withdrawn.
+ *
+ * The synchronous consent DEFAULT is <ConsentInit>'s job — this
+ * component only collects the choice and applies the live update.
+ * In `mode: "external"` the storefront simply does not mount this
+ * component (see `shouldRenderBanner()`) — gating keeps working off
+ * the shared cookie seam.
+ *
+ * z-[70]: above the cart drawer (z-[60]) — a blocking modal that can
+ * be covered isn't blocking. In practice it shows on first landing,
+ * before any drawer interaction.
+ */
+export function ConsentBanner({
+  copy,
+  layout = "modal",
+  privacyHref = "/cookies",
+  rejectOnFirstLayer = false,
+}: {
+  /** Resolved per-locale copy from the store's consent config
+   * (`pickConsentCopy(consent.copy, locale)`). */
+  copy: ConsentCopy
+  layout?: ConsentLayout
+  /** Where the privacy link points — the store's cookie/privacy page. */
+  privacyHref?: string
+  /** Render a visible reject on layer 1 (strict-compliance mode). */
+  rejectOnFirstLayer?: boolean
+}) {
+  const [visible, setVisible] = useState(false)
+  const [settingsOpen, setSettingsOpen] = useState(false)
+  const [analytics, setAnalytics] = useState(true)
+  const [ads, setAds] = useState(true)
+
+  // First render decides visibility from the cookie — in an effect, not
+  // during render, so SSR HTML never includes the banner (no hydration
+  // mismatch, no flash for already-consented visitors).
+  useEffect(() => {
+    const stored = readConsentCookie()
+    if (!stored) {
+      setVisible(true)
+    } else {
+      setAnalytics(stored.analytics)
+      setAds(stored.ads)
+    }
+  }, [])
+
+  // Footer settings link → re-open on the settings layer with the stored
+  // choice pre-loaded.
+  useEffect(() => {
+    const onOpen = () => {
+      const stored = readConsentCookie()
+      if (stored) {
+        setAnalytics(stored.analytics)
+        setAds(stored.ads)
+      }
+      setSettingsOpen(true)
+      setVisible(true)
+    }
+    window.addEventListener(CONSENT_OPEN_EVENT, onOpen)
+    return () => window.removeEventListener(CONSENT_OPEN_EVENT, onOpen)
+  }, [])
+
+  // Body scroll lock — MODAL layout only. The bottom banner must leave
+  // the page fully usable (non-blocking by design).
+  const blocking = layout === "modal"
+  useEffect(() => {
+    if (!visible || !blocking) return
+    const prev = document.body.style.overflow
+    document.body.style.overflow = "hidden"
+    return () => {
+      document.body.style.overflow = prev
+    }
+  }, [visible, blocking])
+
+  const decide = useCallback((choices: Omit<ConsentChoices, "ts">) => {
+    const full: ConsentChoices = { ...choices, ts: Date.now() }
+    writeConsentCookie(full)
+    applyConsent(full)
+    setVisible(false)
+    setSettingsOpen(false)
+  }, [])
+
+  if (!visible) return null
+
+  const card = (
+    <ConsentBannerCard
+      copy={copy}
+      privacyHref={privacyHref}
+      rejectOnFirstLayer={rejectOnFirstLayer}
+      settingsOpen={settingsOpen}
+      onOpenSettings={() => setSettingsOpen(true)}
+      analytics={analytics}
+      ads={ads}
+      onAnalyticsChange={setAnalytics}
+      onAdsChange={setAds}
+      onDecide={decide}
+    />
+  )
+
+  if (blocking) {
+    return (
+      <div
+        role="dialog"
+        aria-modal="true"
+        aria-label={copy.settings_title}
+        className="fixed inset-0 z-[70] flex items-end justify-center bg-black/60 p-0 sm:items-center sm:p-6"
+      >
+        <div className="w-full rounded-t-2xl bg-card p-6 pb-[max(1.5rem,env(safe-area-inset-bottom))] shadow-2xl sm:max-w-lg sm:rounded-2xl sm:p-8">
+          {card}
+        </div>
+      </div>
+    )
+  }
+
+  // banner-bottom: non-blocking region pinned to the viewport bottom.
+  return (
+    <div
+      role="region"
+      aria-label={copy.settings_title}
+      className="fixed inset-x-0 bottom-0 z-[70] flex justify-center p-0 sm:p-4"
+    >
+      <div className="w-full rounded-t-2xl border border-border bg-card p-6 pb-[max(1.5rem,env(safe-area-inset-bottom))] shadow-2xl sm:max-w-lg sm:rounded-2xl">
+        {card}
+      </div>
+    </div>
+  )
+}
+
+/**
+ * ConsentBannerCard — the pure two-layer card (no cookie, no window),
+ * split out so the layer markup is reusable/testable on its own. NOTE:
+ * its classes resolve against STOREFRONT theme tokens; the admin
+ * settings screen renders its live preview as a token-mapped mirror of
+ * this markup because the admin bundle deliberately does not define
+ * storefront theme colors.
+ */
+export function ConsentBannerCard({
+  copy,
+  privacyHref,
+  rejectOnFirstLayer,
+  settingsOpen,
+  onOpenSettings,
+  analytics,
+  ads,
+  onAnalyticsChange,
+  onAdsChange,
+  onDecide,
+}: {
+  copy: ConsentCopy
+  privacyHref: string
+  rejectOnFirstLayer: boolean
+  settingsOpen: boolean
+  onOpenSettings: () => void
+  analytics: boolean
+  ads: boolean
+  onAnalyticsChange: (next: boolean) => void
+  onAdsChange: (next: boolean) => void
+  onDecide: (choices: Omit<ConsentChoices, "ts">) => void
+}) {
+  if (!settingsOpen) {
+    return (
+      <div className="flex flex-col gap-5">
+        <div className="flex flex-col gap-2">
+          <p className="text-lg font-semibold text-foreground">{copy.title}</p>
+          <p className="text-sm leading-relaxed text-muted-foreground">
+            {copy.body}{" "}
+            <a
+              href={privacyHref}
+              className="underline underline-offset-2 hover:text-foreground"
+            >
+              {copy.privacy_link_label}
+            </a>
+          </p>
+        </div>
+        <div className="flex flex-col gap-2">
+          <button
+            type="button"
+            onClick={() => onDecide({ analytics: true, ads: true })}
+            className="h-12 w-full rounded-md bg-foreground text-sm font-bold uppercase tracking-[0.02em] text-card transition-colors hover:bg-foreground/90"
+          >
+            {copy.accept_label}
+          </button>
+          <button
+            type="button"
+            onClick={onOpenSettings}
+            className="h-12 w-full rounded-md border border-border text-sm font-medium text-foreground transition-colors hover:bg-muted"
+          >
+            {copy.settings_label}
+          </button>
+          {rejectOnFirstLayer ? (
+            <button
+              type="button"
+              onClick={() => onDecide({ analytics: false, ads: false })}
+              className="h-10 w-full rounded-md text-[13px] font-medium text-muted-foreground hover:text-foreground"
+            >
+              {copy.reject_label}
+            </button>
+          ) : null}
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div className="flex flex-col gap-5">
+      <p className="text-lg font-semibold text-foreground">{copy.settings_title}</p>
+
+      <div className="flex flex-col gap-4">
+        <ConsentRow
+          label={copy.necessary_label}
+          description={copy.necessary_description}
+          checked
+          disabled
+        />
+        <ConsentRow
+          label={copy.analytics_label}
+          description={copy.analytics_description}
+          checked={analytics}
+          onChange={onAnalyticsChange}
+        />
+        <ConsentRow
+          label={copy.ads_label}
+          description={copy.ads_description}
+          checked={ads}
+          onChange={onAdsChange}
+        />
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <button
+          type="button"
+          onClick={() => onDecide({ analytics: true, ads: true })}
+          className="h-12 w-full rounded-md bg-foreground text-sm font-bold uppercase tracking-[0.02em] text-card transition-colors hover:bg-foreground/90"
+        >
+          {copy.accept_all_label}
+        </button>
+        <button
+          type="button"
+          onClick={() => onDecide({ analytics, ads })}
+          className="h-12 w-full rounded-md border border-border text-sm font-medium text-foreground transition-colors hover:bg-muted"
+        >
+          {copy.save_label}
+        </button>
+        <button
+          type="button"
+          onClick={() => onDecide({ analytics: false, ads: false })}
+          className="h-10 w-full rounded-md text-[13px] font-medium text-muted-foreground hover:text-foreground"
+        >
+          {copy.reject_all_label}
+        </button>
+      </div>
+    </div>
+  )
+}
+
+function ConsentRow({
+  label,
+  description,
+  checked,
+  disabled = false,
+  onChange,
+}: {
+  label: string
+  description: string
+  checked: boolean
+  disabled?: boolean
+  onChange?: (next: boolean) => void
+}) {
+  return (
+    <label
+      className={`flex items-start justify-between gap-4 ${
+        disabled ? "" : "cursor-pointer"
+      }`}
+    >
+      <span className="flex-1">
+        <span className="block text-sm font-medium text-foreground">{label}</span>
+        <span className="block text-[13px] leading-relaxed text-muted-foreground">
+          {description}
+        </span>
+      </span>
+      <input
+        type="checkbox"
+        checked={checked}
+        disabled={disabled}
+        onChange={(e) => onChange?.(e.target.checked)}
+        className="mt-0.5 h-4 w-4 shrink-0 accent-foreground"
+      />
+    </label>
+  )
+}
+
+/**
+ * ConsentSettingsLink — drop-in footer link that re-opens the banner on
+ * its settings layer ("withdraw consent as easily as it was given").
+ */
+export function ConsentSettingsLink({
+  children = "Настройки на бисквитките",
+  className,
+}: {
+  children?: React.ReactNode
+  className?: string
+}) {
+  return (
+    <button type="button" onClick={openConsentSettings} className={className}>
+      {children}
+    </button>
+  )
+}

package/src/tracking/consent-init.tsx

@@ -0,0 +1,44 @@
+import { CONSENT_INIT_SNIPPET } from "./consent"
+
+/**
+ * ConsentInit — the synchronous Consent Mode v2 "default" snippet.
+ *
+ * Ported from the barter reference implementation
+ * `src/components/storefront/consent/consent-init.tsx` (itself from
+ * `@1click/ui/src/tracking/consent-init.tsx` v2.3.1); the snippet lives in
+ * ./consent.ts (CONSENT_INIT_SNIPPET, character-identical) so its ordering
+ * contract is unit-testable.
+ *
+ * Render it as the FIRST child of <body> (App Router layouts don't
+ * expose <head> for inline scripts). A plain inline <script>
+ * (deliberately NOT next/script) executes at HTML-parse time — long
+ * before the afterInteractive <GA4>/<MetaPixel> loaders, which run
+ * post-hydration. Google's consent-mode docs require the default to be
+ * set synchronously ahead of the tag; an async default races the
+ * loader and the first hit of a returning consented visitor would
+ * ship denied.
+ *
+ * Behavior:
+ *   - No stored choice (first visit) → default ALL DENIED. Tags still
+ *     load (advanced consent mode): gtag sends cookieless pings, the
+ *     Pixel queues client-side. The <ConsentBanner> then collects the
+ *     choice and applies the live 'update'.
+ *   - Stored choice → default mirrors it, so returning visitors are
+ *     correct from the very first hit with no banner and no race.
+ *
+ * `ads_data_redaction` strips ad-click identifiers (gclid et al.) from
+ * the cookieless pings while ad_storage is denied, per Google's docs.
+ *
+ * The script is static (no props interpolated beyond the shared cookie
+ * name) — safe as a server-component inline script with a stable id.
+ * CARD TRAP: it must NEVER wait on the /api/store/consent fetch — the
+ * per-store config drives the BANNER, not this default.
+ */
+export function ConsentInit() {
+  return (
+    <script
+      id="1click-consent-init"
+      dangerouslySetInnerHTML={{ __html: CONSENT_INIT_SNIPPET }}
+    />
+  )
+}

package/src/tracking/consent.ts

@@ -0,0 +1,243 @@
+/**
+ * Consent Mode v2 — shared state + appliers.
+ *
+ * Ported from the barter reference implementation
+ * `src/components/storefront/consent/consent.ts` (itself a verbatim port of
+ * `@1click/ui/src/tracking/consent.ts` v2.3.1, shipped on Alenika d3d3d39).
+ * THE COOKIE SEAM IS THE CONTRACT: the `_1c_consent` cookie name, JSON
+ * shape `{analytics, ads, ts}` and 12-month lifetime must stay IDENTICAL
+ * across the reference impl, this package, and any external CMP — every
+ * barter-side gate reads it.
+ *
+ * One first-party cookie (`_1c_consent`) is the single source of truth
+ * for the visitor's choice. Three consumers read it:
+ *
+ *   1. `<ConsentInit>` (consent-init.tsx) — synchronous top-of-body script
+ *      that sets gtag's consent DEFAULT (granted when a stored choice says
+ *      so, denied otherwise) BEFORE any Google tag loads. Google's docs
+ *      require the default to be set synchronously ahead of the tag;
+ *      async = a race where the first hit ships unconsented.
+ *   2. `<MetaPixel>` (meta-pixel.tsx) — pushes fbq('consent', …) onto the
+ *      queue before fbq('init'), gating the Pixel the same way.
+ *   3. `<ConsentBanner>` (consent-banner.tsx) — writes the cookie on the
+ *      visitor's choice and applies the live update via `applyConsent()`.
+ *
+ * Advanced consent mode by design: tags always LOAD; while denied,
+ *   - gtag sends cookieless pings (GA4 behavioral modeling stays alive)
+ *   - fbq queues events client-side and sends nothing until 'grant'
+ *
+ * External-CMP escape hatch (consent-management card §4): in
+ * `mode: "external"` barter renders no banner — the merchant's CMP must
+ * write the SAME consent state, either by setting the cookie itself or by
+ * calling `setConsent()` below. That one seam keeps every barter-side
+ * gate working with any outside app.
+ *
+ * Per-store configuration comes from `GET /api/store/consent`
+ * (store-api.md "Consent") — defaults are ALWAYS applied server-side, so
+ * the payload is complete and renderable even for an unconfigured store.
+ * The structural `ConsentSettings` mirror + `shouldRenderBanner()` below
+ * let the storefront consume that payload without importing app code.
+ *
+ * Rybbit is deliberately OUTSIDE this system — it is the platform's
+ * self-hosted, cookieless analytics and needs no consent gate.
+ */
+
+export const CONSENT_COOKIE = "_1c_consent"
+
+/** 12 months — the conventional consent-choice lifetime in the EU. */
+export const CONSENT_MAX_AGE_SECONDS = 365 * 24 * 60 * 60
+
+/** window CustomEvent name that re-opens the banner's settings layer
+ * (dispatched by `openConsentSettings()`, e.g. from a footer link). */
+export const CONSENT_OPEN_EVENT = "1click:consent:open"
+
+export type ConsentChoices = {
+  /** analytics_storage */
+  analytics: boolean
+  /** ad_storage + ad_user_data + ad_personalization (Consent Mode v2
+   * treats the three as one merchant-facing "advertising" purpose). */
+  ads: boolean
+  /** epoch ms of the choice — lets a future policy change re-prompt. */
+  ts: number
+}
+
+export function readConsentCookie(): ConsentChoices | null {
+  if (typeof document === "undefined") return null
+  try {
+    const match = document.cookie.match(
+      new RegExp(`(?:^|; )${CONSENT_COOKIE}=([^;]*)`)
+    )
+    if (!match?.[1]) return null
+    const parsed = JSON.parse(decodeURIComponent(match[1]))
+    if (typeof parsed !== "object" || parsed === null) return null
+    return {
+      analytics: Boolean(parsed.analytics),
+      ads: Boolean(parsed.ads),
+      ts: Number(parsed.ts) || 0,
+    }
+  } catch {
+    return null
+  }
+}
+
+export function writeConsentCookie(choices: ConsentChoices): void {
+  if (typeof document === "undefined") return
+  const value = encodeURIComponent(JSON.stringify(choices))
+  document.cookie = `${CONSENT_COOKIE}=${value}; Max-Age=${CONSENT_MAX_AGE_SECONDS}; Path=/; SameSite=Lax`
+}
+
+/**
+ * Push the visitor's (new) choice to both vendors at runtime.
+ *
+ * gtag: 'update' after the synchronous 'default' — the documented CMP
+ * flow. On grant, subsequent hits carry consented state and gtag writes
+ * its cookies; the pre-choice pageview stays cookieless (modeled).
+ * fbq: 'grant' flushes the queued events, 'revoke' resumes queueing.
+ */
+export function applyConsent(choices: ConsentChoices): void {
+  if (typeof window === "undefined") return
+
+  const w = window as any
+  w.dataLayer = w.dataLayer || []
+  // Command-style push — gtag() must receive `arguments`, not an array.
+  function gtag(..._args: unknown[]) {
+    // eslint-disable-next-line prefer-rest-params
+    w.dataLayer.push(arguments)
+  }
+
+  const ad = choices.ads ? "granted" : "denied"
+  gtag("consent", "update", {
+    ad_storage: ad,
+    ad_user_data: ad,
+    ad_personalization: ad,
+    analytics_storage: choices.analytics ? "granted" : "denied",
+  })
+  gtag("set", "ads_data_redaction", !choices.ads)
+
+  if (typeof w.fbq === "function") {
+    w.fbq("consent", choices.ads ? "grant" : "revoke")
+  }
+}
+
+/**
+ * The documented external-CMP entry point: write the shared consent state
+ * (cookie) AND apply the live vendor update in one call. An outside CMP
+ * that calls this — or writes the cookie in the same shape — drives every
+ * barter-side gate exactly like the built-in banner does.
+ */
+export function setConsent(choices: Omit<ConsentChoices, "ts"> & { ts?: number }): void {
+  const full: ConsentChoices = {
+    analytics: choices.analytics,
+    ads: choices.ads,
+    ts: choices.ts ?? Date.now(),
+  }
+  writeConsentCookie(full)
+  applyConsent(full)
+}
+
+/** Re-open the consent banner (settings layer) from anywhere — e.g. a
+ * "Настройки на бисквитките" footer link. No-op if no banner mounted. */
+export function openConsentSettings(): void {
+  if (typeof window === "undefined") return
+  window.dispatchEvent(new CustomEvent(CONSENT_OPEN_EVENT))
+}
+
+/**
+ * The synchronous Consent Mode v2 "default" snippet — the crown jewel
+ * (card trap: NEVER async, NEVER config-dependent-late). Exported as a
+ * string so the ordering contract is unit-testable without a DOM:
+ * character-identical to the shipped @1click/ui v2.3.1 snippet.
+ * `<ConsentInit>` renders it as a plain inline <script>.
+ */
+export const CONSENT_INIT_SNIPPET = `
+(function(){
+  var c=null;
+  try{
+    var m=document.cookie.match(/(?:^|; )${CONSENT_COOKIE}=([^;]*)/);
+    if(m){c=JSON.parse(decodeURIComponent(m[1]));}
+  }catch(e){}
+  var ads=!!(c&&c.ads), an=!!(c&&c.analytics);
+  window.dataLayer=window.dataLayer||[];
+  function gtag(){dataLayer.push(arguments);}
+  gtag('consent','default',{
+    'ad_storage':ads?'granted':'denied',
+    'ad_user_data':ads?'granted':'denied',
+    'ad_personalization':ads?'granted':'denied',
+    'analytics_storage':an?'granted':'denied'
+  });
+  gtag('set','ads_data_redaction',!ads);
+})();
+`.trim()
+
+// ── Per-store consent config (GET /api/store/consent) ────────────────
+//
+// Structural mirror of the store consent payload — the exact allowlist
+// `publicConsentPayload()` serves (code truth: `src/lib/consent/model.ts`;
+// contract: store-api.md "Consent"). Declared locally so the package
+// never imports app code; the shapes are asserted against the live
+// endpoint by the contract tests.
+
+/** `modal` = blocking centered modal (default — bars get ignored);
+ * `banner-bottom` = non-blocking bottom banner (must NOT trap focus). */
+export type ConsentLayout = "modal" | "banner-bottom"
+
+/** `builtin` = the package renders its own banner. `external` = the
+ * merchant embeds an outside CMP; render NO banner — the CMP writes the
+ * same `_1c_consent` cookie (or calls `setConsent()`). */
+export type ConsentMode = "builtin" | "external"
+
+/** Per-locale banner copy — complete in the server payload (defaults are
+ * merged server-side; no client-side fallback logic is needed). */
+export type ConsentCopy = {
+  /** Layer 1 */
+  title: string
+  body: string
+  privacy_link_label: string
+  accept_label: string
+  settings_label: string
+  reject_label: string
+  /** Layer 2 (preferences) */
+  settings_title: string
+  accept_all_label: string
+  save_label: string
+  reject_all_label: string
+  necessary_label: string
+  necessary_description: string
+  analytics_label: string
+  analytics_description: string
+  ads_label: string
+  ads_description: string
+}
+
+/** The `consent` object of `GET /api/store/consent`. */
+export type ConsentSettings = {
+  enabled: boolean
+  mode: ConsentMode
+  layout: ConsentLayout
+  privacy_href: string
+  reject_on_first_layer: boolean
+  copy: Record<string, ConsentCopy>
+}
+
+/**
+ * Mount `<ConsentBanner>` only when this is true. `external` mode renders
+ * NO barter banner — the outside CMP owns the UI while `<ConsentInit>` +
+ * cookie gating keep working (the escape-hatch seam). Mirrors
+ * `shouldRenderBanner` in `src/lib/consent/model.ts`.
+ */
+export function shouldRenderBanner(settings: ConsentSettings): boolean {
+  return settings.enabled && settings.mode === "builtin"
+}
+
+/**
+ * Pick the copy for a locale from the server payload, falling back to
+ * `en` then to the first available locale. The server always ships
+ * complete copy per locale (defaults merged server-side), so this is
+ * pure selection — no field-level merging.
+ */
+export function pickConsentCopy(
+  copy: Record<string, ConsentCopy>,
+  locale: string
+): ConsentCopy | null {
+  return copy[locale] ?? copy["en"] ?? Object.values(copy)[0] ?? null
+}