suaveplan/openspec/changes/enterprise-react-consent-overlay/proposal.md at main

SuavePlan/suaveplan

Fork 0

Files

admin fbc70f96e6 Initial Commit

2026-05-27 23:29:53 +01:00

2.8 KiB

Raw Permalink Blame History

Change ID: enterprise-react-consent-overlay
Package: @suaveplan/react-consent-overlay
Category: react
Target path: react/auth/react-consent-overlay
Status: PROPOSED
Date: 2026-04-24
Reference spec: /mnt/s/web/suaveplan/enterprise/react-consent-overlay.md

Summary

Deliver @suaveplan/react-consent-overlay on genesis from scratch at enterprise quality. GDPR/cookie/terms/age-gate consent framework for React 19: v2 gate-based pipeline (AgeGate, CookieGate, TermsGate, CustomGate, GateManager), v1 ConsentProvider/ConsentBanner/ConsentOverlay for back-compat, pluggable storage (cookie/localStorage/memory), Zustand stores (consent/audio/gate), plugin system (GTM, Analytics, ScrollValidation, AgeVerification), industry presets, policy components, multi-layer audio-permission system, and i18n bundles (EN, CY, ZH). Genesis adds Playwright E2E coverage, Storybook stories for every gate and audio component, and 100% test coverage.

Current-state audit (genesis)

Package does not exist on genesis — fresh build.

Available workspace deps on genesis

Package	Role
`@suaveplan/error` (`workspace:^`)	`ConsentError`
`@suaveplan/react-translate` (`workspace:^`)	i18n foundation
`zod` (`catalog:forms`)	Gate + config schemas
`@opentelemetry/api` (`catalog:observability`)	`consent.accept` / `consent.decline` spans

External: zustand catalog:state, tslib catalog:build. React 18/19 peer.

Preserved public API surface (v2 Core)

ConsentContext, ConsentProviderV2, DEFAULT_CONFIG, useConsent, useConsentCategory, useConsentStatus, useConsentGate, useEnabledCategories, useIsWhitelisted, useTermsAccepted, useAgeVerified, AgeGate, CookieGate, TermsGate, CustomGate, GateManager, ConsentOverlayV2, FocusTrap, plus all policy + audio + plugin exports.

v1 Back-compat exports preserved: ConsentProvider, ConsentBanner, ConsentOverlay.

New additions for genesis

ConsentError — codes: CONSENT_CONTEXT_MISSING, CONSENT_GATE_FAILED, CONSENT_STORAGE_FAILED.
Storybook for every gate and audio component — default, accepted, declined, loading, playground.
Playwright E2E — CookieGate accept/decline flow, AgeGate age verification, audio permission flow.
OTel spans — consent.accept, consent.decline, consent.gate_passed.

File layout

react/auth/react-consent-overlay/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    v2/
      context/ gates/ overlay/ stores/ plugins/ presets/ policy/ audio/
    v1/ (back-compat)
    i18n/ (en, cy, zh translations)
    utils/ (storage adapters)
    types/
  e2e/
    consent.spec.ts
    audio-permission.spec.ts

2.8 KiB Raw Permalink Blame History

OpenSpec Change: enterprise-react-consent-overlay