@react-lgpd-consent/core 0.7.0 → 0.7.2

package/CHANGELOG.md

@@ -1,5 +1,242 @@
 # Changelog - @react-lgpd-consent/core
 
+## 0.7.2
+
+### Patch Changes
+
+- [#134](https://github.com/lucianoedipo/react-lgpd-consent/pull/134) [`44b885b`](https://github.com/lucianoedipo/react-lgpd-consent/commit/44b885b7c81f1cb5822e2dcfde2975e69e8d4893) Thanks [@github-actions](https://github.com/apps/github-actions)! - ### Correções
+  - 1d15920 fix: corrigir formatação da verificação de múltiplas versões do React
+
+  ### Funcionalidades
+  - d641639 feat: adicionar gerenciamento de eventos para categorias obrigatórias no CategoriesProvider
+  - b04c00b feat: add tests for CookieBanner, FloatingPreferencesButton, and PreferencesModal components
+  - b04c00b Introduce interactive changeset script for easier versioning in monorepos.
+
+  ### Refactors e compatibilidade
+  - ef2968a refactor: replace direct document and window references with globalThis for better compatibility
+  - ef2968a Updated scriptLoader, cookieDiscovery, cookieUtils, dataLayerEvents, developerGuidance, peerDepsCheck, scriptIntegrations, and scriptLoader files to use globalThis.document and globalThis.window.
+  - ef2968a Improved cookie handling functions to check for document and window availability using globalThis.
+  - ef2968a Enhanced tests to reference globalThis for consistency.
+  - ef2968a Cleaned up code formatting and comments for clarity.
+  - b04c00b Refactor coverage check script to use node imports.
+  - b04c00b Adjust TypeDoc script for ESM compatibility.
+  - 3af2fcb Fix path resolution in tsconfig for better module imports.
+
+  ### Testes
+  - b04c00b Implement tests for CookieBanner to verify rendering based on consent and debug mode.
+  - b04c00b Enhance FloatingPreferencesButton tests to check for localized text via props.
+  - b04c00b Extend PreferencesModal tests to cover temporary preference resets, active scripts rendering, and custom text application.
+
+  ### Documentação
+  - d430eef docs: atualizar instruções para agentes com visão geral do projeto e comandos essenciais
+  - d430eef Updated documentation to reflect changes in globalThis usage.
+  - d430eef Update API documentation to include new integration functions and ESM/CJS testing configurations.
+
+## 0.7.1
+
+### Patch Changes
+
+- [#133](https://github.com/lucianoedipo/react-lgpd-consent/pull/133) [`33bc0eb`](https://github.com/lucianoedipo/react-lgpd-consent/commit/33bc0ebcb40ce65c70b02668d3c0a97efb1854f1) Thanks [@lucianoedipo](https://github.com/lucianoedipo)! - # 🧩 Fundamento Crítico de Consentimento — SUPER TASK v0.7.1
+
+  **Persistência + Loader + Consent Mode v2**
+
+  Esta release estabelece o **núcleo legal, técnico e funcional** da biblioteca react-lgpd-consent, garantindo um contrato sólido, seguro e auditável para uso institucional e governamental.
+
+  ***
+
+  ## 🔹 Bloco A — Persistência de Consentimento por Cookie
+
+  ### ✨ API Consolidada de Persistência
+
+  Nova API completa no `ConsentProvider`:
+
+  ```typescript
+  <ConsentProvider
+    cookie={{
+      name: 'lgpd-consent',
+      domain: '.example.com',  // Compartilha entre subdomínios
+      path: '/',
+      sameSite: 'Lax',        // Default seguro
+      secure: true,            // Auto em HTTPS
+      maxAge: 31536000,       // Segundos (substitui maxAgeDays)
+    }}
+  >
+  ```
+
+  **Regras Implementadas:**
+  - ✅ Defaults seguros: `SameSite=Lax`, `Secure=true` em HTTPS
+  - ✅ Categoria `necessary` **sempre forçada como true**
+  - ✅ Nenhuma gravação de cookie durante SSR
+  - ✅ Suporte completo a subdomínios via `domain`
+  - ✅ Nova opção `maxAge` (segundos, padrão moderno)
+  - ✅ Opção `maxAgeDays` deprecated mas mantida para compatibilidade
+
+  **Ambientes Suportados:**
+  - ✅ `localhost` (desenvolvimento)
+  - ✅ `dev` / `staging` (domínios customizados)
+  - ✅ `production` (HTTPS obrigatório)
+  - ✅ Comportamento **independente de NODE_ENV**
+
+  ***
+
+  ## 🔹 Bloco B — ConsentScriptLoader com Bloqueio Real
+
+  ### 🚫 Contrato de Bloqueio Garantido
+
+  > **Nenhum script não necessário executa antes do consentimento correspondente.**
+
+  ### ✨ Sistema de Fila e Priorização
+
+  Implementado `ConsentScriptLoader` com:
+
+  ```typescript
+  registerScript({
+    id: 'google-analytics',
+    category: 'analytics',
+    priority: 1, // Ordem de execução
+    execute: () => {
+      // Seu script aqui
+    },
+    onConsentUpdate: (granted) => {
+      // Reagir a mudanças de consentimento
+    },
+  })
+  ```
+
+  **Recursos Implementados:**
+  - ✅ **Fila interna de execução** com ordenação por:
+    - 1. Categoria (`necessary` → `analytics` → `marketing`, etc.)
+    - 2. Prioridade (numérica)
+    - 3. Timestamp (ordem de registro)
+  - ✅ Scripts `necessary` executam **imediatamente**
+  - ✅ Scripts de outras categorias aguardam **consentimento explícito**
+  - ✅ Suporte a `onConsentUpdate` para reconfiguração dinâmica
+  - ✅ Snapshot de consentimento para scripts que precisam do estado atual
+  - ✅ **Otimização anti-duplicação**: integrações não são reexecutadas a cada render quando criadas inline (ex.: `integrations={[createGoogleAnalyticsIntegration(...)]}`). Sistema mantém hash estrutural para detectar mudanças reais e prevenir múltiplas inicializações do mesmo script.
+
+  **Observabilidade em DEV:**
+  - ✅ Logs detalhados de ordem de execução
+  - ✅ Indicação clara de categoria liberada
+  - ✅ Rastreamento de status de cada script
+  - ⚠️ **Silencioso em produção** (performance otimizada)
+
+  ***
+
+  ## 🔹 Bloco C — Integração Nativa Google Consent Mode v2
+
+  ### 🎯 Implementação Automática
+
+  **Zero configuração manual necessária!**
+
+  ```typescript
+  import { createGoogleAnalyticsIntegration } from '@react-lgpd-consent/core'
+
+  const ga4 = createGoogleAnalyticsIntegration({
+    measurementId: 'G-XXXXXXXXXX'
+  })
+
+  <ConsentScriptLoader integrations={[ga4]} />
+  ```
+
+  **O que a biblioteca faz automaticamente:**
+  1. ✅ Inicializa `dataLayer` se não existir
+  2. ✅ Define `gtag('consent', 'default', denied)` **antes** de qualquer tag
+  3. ✅ Mapeia categorias corretamente:
+     - `analytics` → `analytics_storage`
+     - `marketing` → `ad_storage`, `ad_user_data`, `ad_personalization`
+  4. ✅ Envia `gtag('consent', 'update')` quando usuário escolhe preferências
+  5. ✅ Dispara eventos de ciclo de vida:
+     ```javascript
+     { event: 'consent_initialized' }
+     { event: 'consent_updated', preferences: {...} }
+     ```
+
+  **Factories Implementadas:**
+  - ✅ `createGoogleAnalyticsIntegration` (GA4)
+  - ✅ `createGoogleTagManagerIntegration` (GTM)
+  - ✅ Suporte a `bootstrap()` para inicialização pré-consentimento
+  - ✅ Suporte a `onConsentUpdate()` para reconfiguração dinâmica
+
+  ### 🔒 Ordem de Inicialização Segura
+
+  Fluxo garantido pela implementação:
+
+  ```
+  1. dataLayer criado
+  2. gtag('consent', 'default', denied)
+  3. Loader bloqueia tags
+  4. Usuário consente
+  5. gtag('consent', 'update', granted/denied)
+  6. Tags disparam conforme consentimento
+  ```
+
+  ### ⚡ Compatibilidade Next.js (SSR)
+  - ✅ Nenhum acesso a `window` fora de `useEffect`
+  - ✅ App Router (Next.js 13+)
+  - ✅ Pages Router (Next.js 12+)
+  - ✅ **Zero hydration mismatch**
+  - ✅ Estratégia de renderização: `client-only` quando necessário
+
+  ***
+
+  ## 🆕 Novas APIs Públicas
+
+  ### Core Package (`@react-lgpd-consent/core`):
+
+  ```typescript
+  // Registro de scripts
+  registerScript(config: RegisteredScript): void
+
+  // Factories de integrações
+  createGoogleAnalyticsIntegration(config): ScriptIntegration
+  createGoogleTagManagerIntegration(config): ScriptIntegration
+
+  // Utilitários de cookie
+  readConsentCookie(name?: string): ConsentState | null
+  writeConsentCookie(state: ConsentState, options?: CookieOptions): void
+
+  // Novos tipos
+  type RegisteredScript = { ... }
+  type ScriptIntegration = { ... }
+  interface LoadScriptOptions = { ... }
+  ```
+
+  ***
+
+  ## 📚 Documentação Atualizada
+  - ✅ **API.md** - Novas APIs de `registerScript` e Consent Mode v2
+  - ✅ **INTEGRACOES.md** - Guias completos de GA4, GTM, Facebook Pixel
+  - ✅ **MIGRATION.md** - Guia de migração v0.7.0 → v0.7.1
+  - ✅ **SUPER_TASK_VALIDATION.md** - Relatório técnico de validação completo
+
+  ***
+
+  ## 🔄 Breaking Changes
+
+  **Nenhum!** Esta release é 100% backward-compatible:
+  - ✅ Opção `maxAgeDays` deprecated mas funcional
+  - ✅ Comportamento padrão preservado
+  - ✅ APIs antigas continuam funcionando
+  - ✅ Migração gradual suportada
+
+  ***
+
+  ## 🎯 Melhorias Complementares
+
+  ### Sistema de i18n para Diagnósticos
+
+  Sistema básico de internacionalização para mensagens de peer dependencies:
+  - ✅ Suporte a pt-BR (padrão) e en
+  - ✅ API para customização: `setPeerDepsLocale()`, `setPeerDepsMessages()`
+  - ✅ Mensagens extraídas para constantes (melhor manutenibilidade)
+
+  ### Refatorações e Otimizações
+  - ✅ Strings de mensagens extraídas para constantes
+  - ✅ Separação de concerns (lógica vs conteúdo)
+  - ✅ Type safety aprimorado em toda API
+  - ✅ Performance otimizada (sem logs em produção)
+  - ✅ **Fix crítico**: Prevenção de reexecução de integrações a cada render quando `integrations` prop muda referência (inline array). Sistema agora usa hash estrutural para detectar mudanças reais e manter scripts já registrados estáveis.
+
 ## 0.7.0
 
 ### Minor Changes
@@ -143,7 +380,7 @@
   - **Correção crítica**: `loadScript` agora aguarda dinamicamente o consentimento em vez de rejeitar imediatamente, permitindo que scripts carreguem quando preferências mudarem
   - Cleanup automático do registro ao completar/falhar carregamento
   - Adicionados testes extensivos: `ConsentScriptLoader.strictmode.test.tsx` e `scriptLoader.strictmode.test.ts`
-  - Documentação completa em `docs/REACT19-STRICTMODE.md`
+  - Documentação completa em `REACT19-STRICTMODE.md`
   - Todos os 302 testes passando, incluindo 5 novos testes de StrictMode
 
   **Breaking Changes:** Nenhuma - totalmente retrocompatível

package/README.md

@@ -62,6 +62,22 @@ function MyCustomBanner() {
 - **Integrações:** Google Analytics, GTM, UserWay, Facebook Pixel, Hotjar, etc.
 - **Tipos TypeScript:** Tipagem completa para toda a API
 
+## 🧩 Scripts, Fila e Consent Mode v2
+
+- **ConsentScriptLoader** agora mantém uma fila interna por categoria e prioridade. Scripts `necessary` rodam imediatamente; os demais só executam após consentimento explícito.
+- **API programática `registerScript`**: registre callbacks inline ou integrações que não usam `<script src>` e deixe a fila disparar no momento correto. Estados da fila: `pending` → `running` → `executed` (recarrega apenas se `allowReload=true`).
+  ```ts
+  const cleanup = registerScript({
+    id: 'ga-consent-mode',
+    category: 'analytics',
+    priority: 10, // maior roda antes dentro da categoria
+    execute: bootstrapConsentMode,
+    onConsentUpdate: ({ preferences }) => pushConsentSignals(preferences),
+  })
+  ```
+- **Consent Mode v2 nativo**: `createGoogleAnalyticsIntegration` e `createGoogleTagManagerIntegration` inicializam `consent=default` (denied) e enviam `consent=update` conforme as preferências do usuário, sem snippet manual.
+- **Observabilidade dev-only**: logs ordenados de execução para depurar a fila (silenciados em produção).
+
 ## 🆕 Novidades v0.7.0
 
 ### Callbacks de Lifecycle
@@ -123,4 +139,3 @@ Para documentação completa, exemplos e API reference:
 ## 📄 Licença
 
 MIT © [Luciano Édipo](https://github.com/lucianoedipo)
-