react-lgpd-consent 0.5.3 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.6.1
+
+### Patch Changes
+
+- [#105](https://github.com/lucianoedipo/react-lgpd-consent/pull/105) [`1deb3bb`](https://github.com/lucianoedipo/react-lgpd-consent/commit/1deb3bb56853165f7ec231e73d7b1d271e51b8f1) Thanks [@lucianoedipo](https://github.com/lucianoedipo)! - chore: sincronizar pnpm-lock.yaml com versões bumpeadas
+
+- Updated dependencies [[`1deb3bb`](https://github.com/lucianoedipo/react-lgpd-consent/commit/1deb3bb56853165f7ec231e73d7b1d271e51b8f1)]:
+  - @react-lgpd-consent/core@0.6.1
+  - @react-lgpd-consent/mui@0.6.1
+
+## 0.6.0
+
+### Minor Changes
+
+- [#103](https://github.com/lucianoedipo/react-lgpd-consent/pull/103) [`4c9ebf2`](https://github.com/lucianoedipo/react-lgpd-consent/commit/4c9ebf231ff58168294f2fde405298b7087016ca) Thanks [@lucianoedipo](https://github.com/lucianoedipo)! - feat: adicionar diagnósticos de peer dependencies e sistema de troubleshooting
+  - ✨ Novo sistema de diagnóstico automático para peer deps
+  - 🔍 Detecta múltiplas instâncias de React (causa "Invalid hook call")
+  - 📋 Verifica versões de React (18-19) e MUI (5-7)
+  - 📖 Nova página TROUBLESHOOTING.md com soluções detalhadas
+  - 🔧 Mensagens acionáveis no console em modo desenvolvimento
+  - 🚀 Configuração de Turborepo para builds otimizados
+  - 📦 Configuração de Changesets para versionamento automatizado
+
+### Patch Changes
+
+- Updated dependencies [[`4c9ebf2`](https://github.com/lucianoedipo/react-lgpd-consent/commit/4c9ebf231ff58168294f2fde405298b7087016ca)]:
+  - @react-lgpd-consent/core@0.6.0
+  - @react-lgpd-consent/mui@0.6.0
+
 Todas as mudanças notáveis neste projeto serão documentadas neste arquivo.
 
 # Changelog
@@ -25,9 +54,8 @@ Esta versão introduz uma **arquitetura modular** que separa a lógica de consen
 - **Tree-shaking eficiente**: Instale apenas o que você precisa
   - Core isolado permite uso com qualquer biblioteca de UI
   - MUI opcional como peer dependency
-  
 - **Workspace PNPM**: Monorepo organizado com builds independentes
-- **Guia de migração completo**: [MIGRATION.md](./MIGRATION.md) documentando todos os cenários
+- **Guia de migração completo**: [MIGRATION.md](../../MIGRATION.md) documentando todos os cenários
 - **Scripts de publicação**: Suporte para publicar pacotes independentemente
 
 ### ⚠️ Breaking Changes
@@ -36,7 +64,7 @@ Esta versão introduz uma **arquitetura modular** que separa a lógica de consen
   - **Antes**: `<ConsentProvider theme={createTheme({...})} />`
   - **Depois**: Use `<ThemeProvider>` do Material-UI diretamente
   - **Razão**: Separação de responsabilidades - tema do MUI gerenciado pelo MUI
-  - **Migração**: Ver [MIGRATION.md](./MIGRATION.md) seção "Breaking Changes"
+  - **Migração**: Ver [MIGRATION.md](../../MIGRATION.md) seção "Breaking Changes"
 
 ### 🔄 Changed
 
@@ -70,26 +98,28 @@ packages/
 
 ### 📊 Bundle Sizes
 
-| Pacote | ESM | CJS | DTS | Dependências |
-|--------|-----|-----|-----|--------------|
-| `@react-lgpd-consent/core` | 86.04 KB | 89.12 KB | 125.82 KB | React, js-cookie, zod |
-| `@react-lgpd-consent/mui` | 17.69 KB | 20.95 KB | 11.78 KB | core + @mui/material (peer) |
-| `react-lgpd-consent` | 104 KB* | 110 KB* | 138 KB* | mui (workspace) |
+| Pacote                     | ESM      | CJS      | DTS       | Dependências                |
+| -------------------------- | -------- | -------- | --------- | --------------------------- |
+| `@react-lgpd-consent/core` | 86.04 KB | 89.12 KB | 125.82 KB | React, js-cookie, zod       |
+| `@react-lgpd-consent/mui`  | 17.69 KB | 20.95 KB | 11.78 KB  | core + @mui/material (peer) |
+| `react-lgpd-consent`       | 104 KB\* | 110 KB\* | 138 KB\*  | mui (workspace)             |
 
 \* Bundle final = core + mui (~104 KB total)
 
 ### 🎯 Migration Paths
 
 1. **Uso de componentes UI** (maioria dos usuários):
+
    ```bash
    # Opção A: Pacote agregador (zero mudanças)
    npm install react-lgpd-consent@0.5.0
-   
+
    # Opção B: Pacote MUI direto (recomendado)
    npm install @react-lgpd-consent/mui
    ```
 
 2. **Headless/UI customizada**:
+
    ```bash
    npm uninstall react-lgpd-consent @mui/material
    npm install @react-lgpd-consent/core
@@ -122,7 +152,7 @@ packages/
 
 ### 📚 Documentation
 
-- Novo [MIGRATION.md](./MIGRATION.md) com:
+- Novo [MIGRATION.md](../../MIGRATION.md) com:
   - 3 cenários de migração detalhados
   - Comparativo de bundles
   - Troubleshooting completo
@@ -152,7 +182,6 @@ packages/
   - `consent_initialized`: Disparado após hidratação inicial do `ConsentProvider`
   - `consent_updated`: Disparado quando usuário altera preferências via banner, modal ou API
   - Payload inclui: `event`, `consent_version`, `timestamp` (ISO 8601), `categories`, `origin`, `changed_categories`
-  
 - **Rastreamento de Origem**: Campo `origin` identifica fonte da mudança de consentimento
   - `'banner'`: Decisão feita no CookieBanner
   - `'modal'`: Ajuste feito no PreferencesModal
@@ -1015,17 +1044,21 @@ A v0.2.1 introduz um **sistema inteligente de orientações** que guia desenvolv
 ### 🧩 Sem breaking changes
 
 - Alterações são compatíveis; padrões seguros preservados.
+
 ## [0.5.0] - 25/10/2025 — Modularização inicial do workspace
 
 ### 🧱 Estrutura modular
+
 - Repositório convertido em workspace PNPM com três pacotes: `@react-lgpd-consent/core`, `@react-lgpd-consent/mui` e `react-lgpd-consent`.
 - Pacote agregador passa a construir entradas adicionais (`core` e `mui`) expondo subpath exports oficiais.
 
 ### 🎨 Camada MUI dedicada
+
 - Publicação inicial de `@react-lgpd-consent/mui` como _proxy_ dos componentes padrão.
 - Metadados de peer dependencies ajustados para reforçar que Material-UI é opcional (requerido apenas para a camada visual).
 
 ### 🧰 Ferramentas & DX
+
 - Scripts de lint/test/build convertidos para `pnpm --filter react-lgpd-consent <comando>`.
 - Jest e TypeDoc atualizados para apontar para `packages/core` e `packages/react-lgpd-consent`.
 - Documentação (README, QUICKSTART, DEVELOPMENT) revisada para explicar a nova arquitetura e o processo de migração gradual.

package/QUICKSTART.md

@@ -25,7 +25,7 @@ npm install @mui/material @mui/icons-material @emotion/react @emotion/styled
 
 ## 🎯 Uso Básico (30 segundos)
 
-````tsx
+```tsx
 import React from 'react'
 import { ConsentProvider } from 'react-lgpd-consent'
 
@@ -42,6 +42,7 @@ function App() {
       </main>
     </ConsentProvider>
   )
+```
 
 ## 🧭 Storybook — quick note
 
@@ -51,7 +52,7 @@ This repository ships an interactive Storybook playground used for manual testin
 
 ```bash
 npm run storybook
-````
+```
 
 - Build static Storybook (for publishing to GitHub Pages):
 
@@ -63,11 +64,6 @@ Notes:
 
 - The Storybook preview (`.storybook/preview.tsx`) applies a clean environment between stories (removes consent cookie and performs defensive DOM cleanup). Check that file when creating stories that rely on a clean initial state.
 
-}
-
-export default App
-
-````
 
 ## ⚡ Quickstarts: Next.js (App Router) e Vite
 
@@ -402,8 +398,8 @@ function MyComponent() {
 
 ## 📋 Tabela Completa de Props do ConsentProvider
 
-| Prop                                 | Tipo                                                        | Obrigatória | Padrão              | Descrição                                      |
-| ------------------------------------ | ----------------------------------------------------------- | ----------- | ------------------- | ---------------------------------------------- |
+| Prop              | Tipo                                             | Obrigatória | Padrão         | Descrição                               |
+| ----------------- | ------------------------------------------------ | ----------- | -------------- | --------------------------------------- |
 | `categories`                         | `ProjectCategoriesConfig`                                   | ✅ **Sim**  | -                   | Define as categorias de cookies do projeto     |
 | `texts`                              | `Partial<ConsentTexts>`                                     | ❌ Não      | Textos padrão PT-BR | Customiza textos da interface                  |
 | `theme`                              | `any`                                                       | ❌ Não      | Tema padrão         | Tema Material-UI para os componentes           |
@@ -422,7 +418,89 @@ function MyComponent() {
 | `preferencesModalProps`              | `object`                                                    | ❌ Não      | `{}`                | Props adicionais para o modal                  |
 | `floatingPreferencesButtonProps`     | `object`                                                    | ❌ Não      | `{}`                | Props adicionais para o botão flutuante        |
 | `initialState`                       | `ConsentState`                                              | ❌ Não      | -                   | Estado inicial para hidratação SSR             |
-| `cookie`                             | `Partial<ConsentCookieOptions>`                             | ❌ Não      | Opções padrão       | Configurações do cookie de consentimento       |
+| `cookie`                             | `Partial<ConsentCookieOptions>`                             | ❌ Não      | Opções padrão       | Configurações do cookie (override fino de `name`, `domain`, `sameSite` etc.) |
+| `storage`                            | `ConsentStorageConfig`                                      | ❌ Não      | `{ namespace: 'lgpd-consent', version: '1' }` | Namespace, versão e domínio compartilhado da chave de consentimento |
+| `onConsentVersionChange`             | `(context: ConsentVersionChangeContext) => void`            | ❌ Não      | Reset automático    | Hook disparado após bump da chave; use para limpar caches adicionais |
+
+## 🔄 Versionamento de Consentimento (0.5.x)
+
+- **Resumo da solicitação**: namespace + versão para a chave de consentimento e estratégia de migração entre releases, garantindo compartilhamento entre subdomínios.
+- **Caso de uso — problema que resolve**: quando o escopo de dados muda (novas categorias, integrações etc.), usuários precisam reafirmar consentimento. Sem um identificador de versão, o estado antigo permanece ativo e quebra conformidade.
+
+### Solução proposta
+- `storage.namespace` e `storage.version` geram automaticamente o nome do cookie via `buildConsentStorageKey`, mantendo o schema `namespace__v<versão>` (`lgpd-consent__v1` por padrão).
+- `storage.domain` centraliza o domínio compartilhado (ex.: `.gov.br`) para que um único banner sirva múltiplos subdomínios.
+- `onConsentVersionChange` é chamado sempre que a chave muda. O reset do estado é automático, mas o hook permite limpar caches customizados (ex.: localStorage, indexedDB) antes de liberar a nova experiência.
+- Guia de migração: documente no seu changelog interno quando e por que o valor de `storage.version` mudou. O bump NÃO é breaking change porque a API pública permanece compatível—apenas força o fluxo de re-consent.
+- Breaking change? **Não** — quem não configurar `storage` continua usando `lgpd-consent__v1`; ao aumentar a versão apenas ocorre re-consentimento.
+
+### Critérios de aceitação
+- Trocar `storage.version` força o fluxo completo: cookie antigo removido, `ConsentProvider` volta ao estado sem consentimento e o usuário vê o banner novamente.
+- Subdomínios compartilham o mesmo consentimento quando `storage.domain` usa um domínio com ponto (`.example.com`).
+- `onConsentVersionChange` entrega `previousKey`, `nextKey` e `resetConsent` para coordenar invalidação de caches externos.
+
+## 🔒 Cookies necessários sempre ativos
+
+- **Resumo da solicitação**: implementar a política de “necessários sempre ativos” tanto na UI quanto na persistência.
+- **Caso de uso — problema resolvido**: atende ao requisito LGPD/ANPD de que cookies estritamente necessários não podem ser desativados; evita confusão na interface e garante consistência nos hooks.
+
+### Como a biblioteca reforça a regra
+- A categoria `necessary` é adicionada automaticamente pelo `ConsentProvider` e sempre persistida como `true`.
+- `setPreference('necessary', false)` e `setPreferences({ necessary: false, ... })` são ignorados com logs de aviso — o estado permanece com `necessary=true`.
+- O `PreferencesModal` padrão exibe a categoria com switch desabilitado e o texto `Cookies necessários (sempre ativos)`.
+- `writeConsentCookie` garante `necessary=true` mesmo que o estado enviado esteja corrompido.
+- Hooks (`useConsent`, `useCategoryStatus`) e integrações (`ConsentScriptLoader`, dataLayer) sempre recebem `necessary=true`.
+
+### Exemplo (apenas cookies necessários)
+
+```tsx
+import { ConsentProvider } from '@react-lgpd-consent/core'
+
+export function MinimalBoundary({ children }: { children: React.ReactNode }) {
+  return <ConsentProvider categories={{ enabledCategories: [] }}>{children}</ConsentProvider>
+}
+```
+
+### Critérios de aceitação
+- UI, hooks, persistência e dataLayer mantêm `necessary=true` em todos os caminhos.
+- Testes automatizados cobrem tentativas de toggle/programmatic override e serialização.
+- Breaking change? **Não** — o comportamento já era esperado; agora é reforçado pelo runtime com avisos para cenários indevidos.
+
+### Exemplo completo (namespace + versão + subdomínio)
+
+```tsx
+import { buildConsentStorageKey, ConsentProvider } from 'react-lgpd-consent'
+
+function ComplianceWrapper({ children }: { children: React.ReactNode }) {
+  return (
+    <ConsentProvider
+      categories={{ enabledCategories: ['analytics', 'marketing'] }}
+      storage={{
+        namespace: 'portal.gov.br',
+        version: '2025-Q4',
+        domain: '.gov.br',
+      }}
+      cookie={{
+        // Opcional: sobrescreva o nome explicitamente (útil para auditoria legada)
+        name: buildConsentStorageKey({ namespace: 'portal.gov.br', version: '2025-Q4' }),
+      }}
+      onConsentVersionChange={({ previousKey, nextKey, resetConsent }) => {
+        console.info('[consent] versão atualizada', { previousKey, nextKey })
+        window.dataLayer?.push({ event: 'consent_version_bumped', previousKey, nextKey })
+        localStorage.removeItem('marketing-optins')
+        resetConsent()
+      }}
+    >
+      {children}
+    </ConsentProvider>
+  )
+}
+```
+
+### Alternativas consideradas
+- **Invalidar sempre** (reset em toda visita) prejudica a UX e reduz taxas de aceitação.
+- **Nunca invalidar** mantém consentimentos fora de escopo e compromete a conformidade.
+  - A solução de namespace + versão expõe explicitamente quando o reconsentimento é necessário.
 
 ## 🎨 Componentes Customizados com TypeScript
 
@@ -488,7 +566,7 @@ A biblioteca `react-lgpd-consent` não injeta um `ThemeProvider` global por cont
 
 ```tsx
 import { ConsentProvider, createDefaultConsentTheme } from 'react-lgpd-consent'
-;<ConsentProvider
+<ConsentProvider
   theme={createDefaultConsentTheme()}
   categories={{ enabledCategories: ['analytics'] }}
 >
@@ -496,6 +574,7 @@ import { ConsentProvider, createDefaultConsentTheme } from 'react-lgpd-consent'
 </ConsentProvider>
 ```
 
+
 Isso evita alterações indesejadas no contexto do MUI do seu app e problemas de SSR.
 
 ```tsx
@@ -1159,7 +1238,31 @@ function App() {
 
 ## 🆘 Solução de Problemas Comuns
 
-### "ConsentProvider must be used within ConsentProvider"
+> 💡 **Diagnósticos automáticos**: A partir da v0.5.4, o react-lgpd-consent detecta automaticamente problemas comuns (múltiplas instâncias de React, versões incompatíveis) e exibe mensagens detalhadas no console em modo desenvolvimento.
+
+Para problemas mais complexos, consulte o **[Guia Completo de Troubleshooting](../../TROUBLESHOOTING.md)**.
+
+### Erros mais comuns
+
+#### "Invalid hook call" / Múltiplas instâncias de React
+
+Se você vê este erro, provavelmente tem múltiplas versões de React carregadas. O diagnóstico automático exibirá instruções específicas para o seu gerenciador de pacotes.
+
+**Solução rápida (pnpm)**:
+```json
+{
+  "pnpm": {
+    "overrides": {
+      "react": "$react",
+      "react-dom": "$react-dom"
+    }
+  }
+}
+```
+
+**Mais detalhes**: [TROUBLESHOOTING.md - Invalid hook call](../../TROUBLESHOOTING.md#erro-invalid-hook-call)
+
+#### "ConsentProvider must be used within ConsentProvider"
 
 ```tsx
 // ❌ Errado - hook usado fora do provider
@@ -1219,9 +1322,10 @@ document.cookie = 'cookieConsent=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=/
 ## 📚 Próximos Passos
 
 - 📖 [Documentação Completa da API](./API.md)
-- 🏗️ [Guia de Conformidade LGPD](./CONFORMIDADE.md)
+- 🔧 [Guia de Troubleshooting](../../TROUBLESHOOTING.md)
+- 🏗️ [Guia de Conformidade LGPD](../../CONFORMIDADE.md)
 - 🔌 [Integrações Nativas](./INTEGRACOES.md)
-- 🧪 [Executar o Exemplo](./example/)
+- 🧪 [Executar o Exemplo](../../example/)
 
 ---