@react-lgpd-consent/core 0.6.3 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,335 @@
 # Changelog - @react-lgpd-consent/core
 
+## 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
+
+- [#124](https://github.com/lucianoedipo/react-lgpd-consent/pull/124) [`7669c4f`](https://github.com/lucianoedipo/react-lgpd-consent/commit/7669c4fba84b5cfea8f7da8ab65468110d3e77f7) Thanks [@lucianoedipo](https://github.com/lucianoedipo)! - # v0.7.0 - Código Limpo, Testes Aprimorados e Qualidade de Código
+
+  Esta release é parte do trabalho nas issues: [#60](https://github.com/lucianoedipo/react-lgpd-consent/issues/60), [#63](https://github.com/lucianoedipo/react-lgpd-consent/issues/63), [#64](https://github.com/lucianoedipo/react-lgpd-consent/issues/64), [#65](https://github.com/lucianoedipo/react-lgpd-consent/issues/65), [#68](https://github.com/lucianoedipo/react-lgpd-consent/issues/68), [#70](https://github.com/lucianoedipo/react-lgpd-consent/issues/70), [#71](https://github.com/lucianoedipo/react-lgpd-consent/issues/71), [#72](https://github.com/lucianoedipo/react-lgpd-consent/issues/72)
+
+  ## 🧹 Correções de Lint e Code Quality
+
+  ### Migração para APIs Modernas
+  - **globalThis**: Convertidos ~50+ usos de `window` e `global` para `globalThis.window` e `globalThis` (compatibilidade SSR/universal)
+  - **String.replaceAll()**: Migrado de `replace()` com regex global para `replaceAll()` (ES2021)
+  - **Object.hasOwn()**: Migrado de `Object.prototype.hasOwnProperty.call()` para `Object.hasOwn()` (ES2022)
+  - **Number.parseInt()**: Padronizado uso de `Number.parseInt()` em vez de `parseInt()` global
+
+  ### TypeScript Configuration
+  - Adicionado `ES2021.String` ao lib do tsconfig para suportar `String.replaceAll()`
+  - Adicionado `ES2022.Object` ao lib do tsconfig para suportar `Object.hasOwn()`
+  - Mantida compatibilidade com target `ES2020`
+
+  > **ℹ️ Atenção à Compatibilidade com Browsers**
+  >
+  > Esta versão faz uso de recursos ES2021/ES2022 (`String.replaceAll()`, `Object.hasOwn()`, etc.), que não estão disponíveis em todos os navegadores (especialmente versões antigas do Safari, Edge ou Firefox). Se você utiliza este pacote em aplicações web que precisam suportar navegadores legados, é recomendado configurar um transpiler (como Babel) e/ou polyfills apropriados para garantir compatibilidade.
+
+  ### Melhorias de Código
+  - **cookieDiscovery.ts**: Função `matchPattern` movida para outer scope (evita recriação)
+  - **validation.ts**: Adicionado warning quando prop `categories` não é fornecida
+  - **Condições**: Invertidas condições negadas para melhor legibilidade
+  - **Type Safety**: Correções de type assertions em testes
+
+  ## 🧪 Aumento Significativo de Cobertura de Testes
+
+  ### Cobertura Geral: 94.82% → 95.46% (+0.64%)
+
+  | Arquivo                | Antes  | Depois      | Melhoria |
+  | ---------------------- | ------ | ----------- | -------- |
+  | **theme.ts**           | 83.33% | **100%** ✅ | +16.67%  |
+  | **cookieDiscovery.ts** | 88.13% | **96.61%**  | +8.48%   |
+  | **peerDepsCheck.ts**   | 74.19% | **80.64%**  | +6.45%   |
+  | **validation.ts**      | 96.87% | **98.24%**  | +1.37%   |
+
+  ### Novos Testes Adicionados (+33 testes: 318 → 351)
+
+  #### peerDepsCheck.ts
+  - Testes para detecção de múltiplas instâncias React via DevTools hook
+  - Testes para verificação de versões React no limite inferior/superior do range
+  - Testes para logging de erros e warnings quando `logWarnings=true`
+  - Cobertura de edge cases de versão semver complexa
+
+  #### dataLayerEvents.ts
+  - Testes para `ensureDataLayer` criar dataLayer quando undefined
+  - Testes para preservação de eventos existentes no dataLayer
+  - Testes para origins programmatic/reset
+  - Testes para previousCategories vazias/undefined
+  - Testes de SSR safety (window parcialmente definido)
+  - Testes para falha silenciosa de dataLayer.push
+
+  #### cookieDiscovery.ts
+  - Testes para uso de cookies descobertos globalmente (`__LGPD_DISCOVERED_COOKIES__`)
+  - Testes para `registerOverrides=true` chamando `setCookieCatalogOverrides`
+  - Testes para cookies sem nome ou duplicados
+  - Testes para match de padrões wildcard
+
+  #### cookieUtils.ts
+  - Testes para JSON malformado e objetos vazios
+  - Testes para `buildConsentStorageKey` com caracteres especiais
+  - Testes para `createConsentAuditEntry` com estado mínimo
+  - Testes para uso de nomes customizados em `removeConsentCookie`
+
+  #### theme.ts (100% coverage)
+  - Testes completos para palette, typography e component overrides
+  - Testes para button contained hover shadows
+  - Testes para Paper e Dialog border radius
+  - Testes para função deprecada `defaultConsentTheme()`
+  - Verificação de novas instâncias a cada chamada
+
+  ## 📚 Documentação
+
+  ### DEVELOPMENT.md
+  - Adicionada seção **"Cobertura de Testes"** com tabela de métricas por módulo
+  - Comando para rodar testes com cobertura: `pnpm test:coverage`
+  - Tabela detalhada mostrando Statements/Branches/Functions/Lines por pacote
+
+  ### TypeDoc
+  - Documentação regenerada com todas as APIs atualizadas
+  - 15 warnings aceitáveis sobre links relativos para pacotes do monorepo
+
+  ## ✅ Validação
+  - ✅ **type-check**: Todos os tipos válidos (ES2021/ES2022 APIs suportadas)
+  - ✅ **lint**: Código limpo sem erros
+  - ✅ **test**: 351/351 testes passando (100%)
+  - ✅ **build**: Build limpo de todos os pacotes
+  - ✅ **docs**: TypeDoc gerado com sucesso
+
+  ## 🔧 Arquivos Modificados
+
+  ### Core Package
+  - `src/utils/scriptIntegrations.ts`: globalThis, Date.now()
+  - `src/utils/peerDepsCheck.ts`: globalThis, Number.parseInt()
+  - `src/utils/dataLayerEvents.ts`: globalThis, ??= operator
+  - `src/utils/cookieUtils.ts`: replaceAll(), globalThis, condição invertida
+  - `src/utils/cookieDiscovery.ts`: matchPattern outer scope
+  - `src/utils/validation.ts`: warning categories undefined
+  - `src/context/ConsentContext.tsx`: Object.hasOwn(), state deps
+  - `src/context/__tests__/CategoriesContext.test.tsx`: globalThis
+  - `__tests__/*`: +25 novos testes
+
+  ### MUI Package
+  - `src/utils/theme.ts`: 100% coverage
+  - `src/utils/__tests__/theme.test.ts`: +8 novos testes
+
+  ### Configuration
+  - `tsconfig.base.json`: ES2021.String, ES2022.Object no lib
+
+  ### Documentation
+  - `DEVELOPMENT.md`: seção de cobertura de testes
+
+  ***
+
+  **Breaking Changes:** Nenhuma
+  **Migration Required:** Não
+
+  Esta release foca em qualidade de código, testes robustos e aderência a padrões modernos do JavaScript/TypeScript.
+
 ## 0.6.3
 
 ### Patch Changes
@@ -42,5 +372,19 @@
   - 🚀 Configuração de Turborepo para builds otimizados
   - 📦 Configuração de Changesets para versionamento automatizado
 
-As notas de versão completas são mantidas no arquivo `CHANGELOG.md` da raiz do repositório.  
-Este pacote segue a numeração conjunta da biblioteca `react-lgpd-consent`.
+---
+
+## Versões Anteriores (< 0.6.0)
+
+Para histórico completo de versões 0.5.x e anteriores, consulte:
+
+- [CHANGELOG.md do pacote principal](../react-lgpd-consent/CHANGELOG.md)
+- [Releases no GitHub](https://github.com/lucianoedipo/react-lgpd-consent/releases)
+
+**Resumo de marcos importantes:**
+
+- **v0.5.0** (25/10/2025): Arquitetura modular - criação dos pacotes `@react-lgpd-consent/core` e `@react-lgpd-consent/mui`
+- **v0.4.5** (25/10/2025): DataLayer events para Google Tag Manager
+- **v0.4.1** (21/09/2025): Expansão de integrações nativas (Hotjar, Mixpanel, Clarity, Intercom, Zendesk)
+- **v0.3.0-v0.4.0**: Sistema de design tokens, categorias customizadas, testes de acessibilidade
+- **v0.1.0-v0.2.x**: Implementação inicial com ConsentProvider, CookieBanner, PreferencesModal

package/README.md

@@ -62,6 +62,68 @@ 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
+
+```tsx
+import { ConsentProvider } from '@react-lgpd-consent/core'
+
+<ConsentProvider
+  onConsentInit={(state) => console.log('Init:', state)}
+  onConsentChange={(current, previous) => {
+    console.log('Mudou:', { current, previous })
+  }}
+  onAuditLog={(entry) => {
+    // Enviar para backend
+    fetch('/api/audit', { method: 'POST', body: JSON.stringify(entry) })
+  }}
+>
+```
+
+### Presets ANPD
+
+```tsx
+import { createAnpdCategories, ANPD_CATEGORY_PRESETS } from '@react-lgpd-consent/core'
+
+// Preset BÁSICO
+const basic = createAnpdCategories({ include: ['analytics'] })
+
+// Preset COMPLETO
+const full = createAnpdCategories({
+  include: ['analytics', 'marketing', 'functional', 'social', 'personalization']
+})
+```
+
+### Auditoria de Consentimento
+
+```tsx
+import { createConsentAuditEntry } from '@react-lgpd-consent/core'
+
+const audit = createConsentAuditEntry(
+  { consented: true, preferences: { analytics: true } },
+  { action: 'update', storageKey: 'lgpd-consent__v1' }
+)
+```
+
+📖 **Saiba mais:** [TROUBLESHOOTING.md](../../TROUBLESHOOTING.md)
+
 ## 📚 Documentação
 
 Para documentação completa, exemplos e API reference:
@@ -77,4 +139,3 @@ Para documentação completa, exemplos e API reference:
 ## 📄 Licença
 
 MIT © [Luciano Édipo](https://github.com/lucianoedipo)
-