react-lgpd-consent 0.2.5 → 0.3.1

package/COMPLIANCE.md

@@ -1,321 +1,107 @@
-# COMPLIANCE.md - react-lgpd-consent v0.2.2
+# Guia de Conformidade e Funcionalidades - react-lgpd-consent v0.3.0
 
 ## 📜 Objetivo
 
-Este documento descreve as medidas de conformidade da biblioteca **react-lgpd-consent** com a Lei Geral de Proteção de Dados (LGPD) e o Guia Orientativo da ANPD sobre Cookies e Proteção de Dados Pessoais.
+Este documento descreve as medidas de conformidade da biblioteca **react-lgpd-consent** com a Lei Geral de Proteção de Dados (LGPD) e o Guia Orientativo da ANPD, além de detalhar as ferramentas que auxiliam os desenvolvedores a manter essa conformidade.
 
-## ✅ Conformidade Atual (v0.2.2 - Sistema de Orientações)
+## ✅ Conformidade com a LGPD
 
-### 🛡️ Implementado e Funcional
+A biblioteca implementa os seguintes princípios e requisitos da LGPD:
 
-#### **Consentimento e Transparência**
+- **Consentimento Granular**: O usuário tem controle sobre cada categoria de cookie não essencial.
+- **Minimização de Dados**: Apenas as categorias de cookies ativas no projeto são armazenadas no cookie de consentimento.
+- **Transparência**: O cookie de consentimento armazena metadados de auditoria, como data, versão e origem da decisão.
+- **Facilidade de Revogação**: O usuário pode alterar suas preferências a qualquer momento através do modal.
+- **Segurança**: O cookie é configurado com `SameSite=Lax` e `secure=true` (em HTTPS) por padrão.
 
-- ✅ **Consentimento granular**: 6 categorias ANPD + categorias customizadas
-- ✅ **Sem pre-check**: cookies não essenciais desativados por padrão
-- ✅ **Revogação e reconfiguração**: funções `resetConsent()` e `openPreferences()`
-- ✅ **Base legal clara**: Consentimento explícito para cookies não essenciais
-- ✅ **Transparência total**: Informações claras sobre finalidade de cada categoria
+## 🧠 Sistema de Orientações para Desenvolvedores
 
-#### **Interface de Usuário Conforme**
+A biblioteca inclui um sistema inteligente que **orienta os desenvolvedores sobre a configuração adequada**, garantindo que a implementação final esteja em conformidade com a LGPD.
 
-- ✅ **Banner não intrusivo**: não bloqueia navegação do usuário
-- ✅ **UI dinâmica**: Mostra apenas categorias realmente utilizadas no projeto
-- ✅ **Prevenção de spam**: Sistema inteligente evita categorias desnecessárias
-- ✅ **Textos ANPD expandidos**: Campos opcionais para compliance completo
+### Console de Desenvolvimento
 
-#### **Aspectos Técnicos**
+Em ambiente de desenvolvimento, a biblioteca exibe automaticamente no console:
 
-- ✅ **Suporte SSR**: via prop `initialState` (evita flash)
-- ✅ **Acessibilidade**: foco gerenciado, navegação por teclado, ARIA adequado
-- ✅ **API estável**: identificadores em inglês, textos em pt-BR customizáveis
-- ✅ **Segurança robusta**: `SameSite=Lax`, `secure=true`, validação de cookies
-- ✅ **Minimização de dados**: Cookie contém apenas categorias utilizadas no projeto
+- **⚠️ Avisos**: Sobre configurações ausentes ou inconsistentes.
+- **💡 Sugestões**: Recomendações para melhorar a conformidade e a experiência do usuário.
+- **🔧 Tabela de Categorias Ativas**: Uma lista clara de quais categorias estão em uso, para auxiliar na construção de UIs customizadas.
 
-#### **🚨 Orientação para Desenvolvedores (NOVO v0.2.2)**
+```
+[🍪 LGPD-CONSENT] ⚠️  Avisos de Configuração
+  [🍪 LGPD-CONSENT] Nenhuma configuração de categorias especificada. Usando padrão: necessary + analytics.
 
-- ✅ **Console de compliance**: Avisos automáticos sobre configuração inadequada
-- ✅ **Validação inteligente**: Detecta problemas de conformidade e orienta correções
-- ✅ **Prevenção de erros**: Sistema evita inconsistências entre configuração e UI
-- ✅ **Documentação automática**: Orientações baseadas na configuração real do projeto
+[🍪 LGPD-CONSENT] 🔧 Categorias Ativas (para UI customizada)
+┌─────────────┬──────────────────────┬─────────────┬─────────────┐
+│     ID      │         Nome         │ Toggle UI?  │ Essencial?  │
+├─────────────┼──────────────────────┼─────────────┼─────────────┤
+│ necessary   │ Cookies Necessários  │ ❌ NÃO      │ 🔒 SIM      │
+│ analytics   │ Cookies Analíticos   │ ✅ SIM      │ ⚙️ NÃO      │
+└─────────────┴──────────────────────┴─────────────┴─────────────┘
+```
 
-## 🎯 Conformidade Específica LGPD/ANPD
+**Para desabilitar estas mensagens**, use a prop `disableDeveloperGuidance={true}` no `ConsentProvider`.
 
-### Artigo 7º LGPD - Bases Legais
+### Configuração Consciente
 
-- ✅ **Consentimento explícito**: Para cookies analytics, marketing, etc.
-- ✅ **Interesse legítimo documentado**: Para cookies funcionais essenciais
-- ✅ **Transparência**: Usuário informado sobre finalidade de cada categoria
+Para evitar avisos e garantir a conformidade, especifique explicitamente as categorias de cookies que seu projeto utiliza através da prop `categories`:
 
-### Artigo 9º LGPD - Consentimento
+```tsx
+<ConsentProvider
+  categories={{
+    // Habilita apenas as categorias padrão que você realmente usa
+    enabledCategories: ['analytics'],
+  }}
+>
+  <App />
+</ConsentProvider>
+```
 
-- ✅ **Livre**: Banner não bloqueia navegação (modo não-intrusivo por padrão)
-- ✅ **Informado**: Descrições claras de cada categoria de cookie
-- ✅ **Inequívoco**: Ação positiva necessária (sem pre-check)
-- ✅ **Específico**: Granularidade por categoria de finalidade
+### Hooks de Validação
 
-### Guia ANPD - Cookies e Proteção de Dados
+Para construir componentes de UI customizados que reagem à configuração, utilize os hooks:
 
-- ✅ **6 Categorias conformes**: necessary, analytics, functional, marketing, social, personalization
-- ✅ **Minimização automática**: Cookie contém apenas categorias do projeto
-- ✅ **Configuração consciente**: Sistema orienta sobre quais dados realmente coletar
-- ✅ **Auditabilidade**: Logs e orientações para compliance
+- `useCategories()`: Fornece uma lista completa das categorias ativas no projeto.
+- `useCategoryStatus('id')`: Verifica o status de uma categoria específica (se está ativa, se é essencial, etc.).
 
-### Princípios da LGPD
+```tsx
+import { useCategoryStatus } from 'react-lgpd-consent'
 
-- ✅ **Minimização**: Apenas dados necessários para finalidade específica
-- ✅ **Finalidade**: Cada categoria tem propósito claro e específico
-- ✅ **Transparência**: Informações acessíveis em linguagem clara
-- ✅ **Livre acesso**: Usuário pode consultar e modificar preferências
-- ✅ **Qualidade dos dados**: Validação e sanitização de cookies
+function AnalyticsFeature() {
+  const analytics = useCategoryStatus('analytics')
 
-## 🚀 Roadmap de Desenvolvimento
-
-## 🚀 Roadmap de Desenvolvimento
-
-### ✅ v0.2.2 - Sistema de Orientações (IMPLEMENTADO)
-
-**Foco**: Orientação inteligente para desenvolvedores, prevenção de problemas de compliance
-
-#### ✅ Implementado
-
-- ✅ **Sistema de orientações automáticas**: Console de desenvolvimento com avisos e sugestões
-- ✅ **UI dinâmica e inteligente**: Componentes se adaptam à configuração do projeto
-- ✅ **Validação de configuração**: Detecta problemas e orienta correções
-- ✅ **Hooks avançados**: `useCategories()` e `useCategoryStatus()` para componentes customizados
-- ✅ **Prevenção de bugs**: Sistema evita inconsistências entre configuração e UI
-- ✅ **Configuração padrão defensiva**: `necessary + analytics` quando não especificado
-- ✅ **100% backward compatible**: APIs antigas continuam funcionando
-
-### v0.2.3 - Compliance Avançado (Próxima Release)
-
-**Foco**: Estruturas avançadas, transparência total, auditoria
-
-#### 🏗️ Funcionalidades Principais
-
-- [ ] **Modal detalhado de cookies**: Catálogo completo com informações técnicas
-
-  ```typescript
-  interface CookieDetails {
-    name: string
-    purpose: string
-    duration: string
-    thirdParty?: string
-    transferCountries?: string[]
-    lawfulBasis: 'consent' | 'legitimate_interest'
-  }
-
-  interface CookieRegistry {
-    [K in Category]: {
-      description: string
-      cookies: CookieDetails[]
-      required: boolean
-      lawfulBasis: 'consent' | 'legitimate_interest'
-    }
+  // Não renderiza o componente se a categoria 'analytics' não estiver configurada no ConsentProvider
+  if (!analytics.isActive) {
+    return null
   }
-  ```
-
-- [ ] **Logs de consentimento**: Registro client-side para auditoria
-
-  ```typescript
-  interface ConsentLog {
-    timestamp: Date
-    action: 'given' | 'revoked' | 'modified' | 'configured'
-    categories: ConsentPreferences
-    userAgent: string
-    projectConfig: ProjectCategoriesConfig
-  }
-  ```
-
-- [ ] **Templates setoriais**: Configurações pré-definidas (governo, saúde, educação)
-- [ ] **Callbacks expandidos**: Eventos de auditoria e compliance
-
-### v0.2.4 - Auditoria e Relatórios
-
-**Foco**: Ferramentas de compliance para DPO
 
-#### 📊 Funcionalidades Avançadas
+  return <AnalyticsDashboard />
+}
+```
 
-- [ ] **Relatórios de compliance**: `generateComplianceReport()` com dados estruturados
-- [ ] **Exportação para DPO**: Dados formatados para auditoria ANPD
-- [ ] **Dashboard de métricas**: Estatísticas de consentimento e categorias
-- [ ] **Integração com ferramentas**: Export para sistemas de compliance
-- [ ] **Assinatura de cookies**: Integridade e não-repúdio opcional
+## 🚀 Roadmap de Funcionalidades
 
-## 🎯 Controle de Progresso
+O foco da biblioteca é estabilidade e conformidade.
 
-### Marcos de Entrega
+### v0.3.0 (Atual)
 
-#### ✅ v0.2.2 - Sistema de Orientações (COMPLETO)
+- **Foco**: Refatoração da arquitetura, melhoria da experiência do desenvolvedor (DX) e quebra de compatibilidade para simplificação.
+- **Status**: Implementado.
 
-- **Lançamento**: 2025-08-12 ✅
-- **Status**: Implementado e em produção
-- **Funcionalidades**: Sistema de orientações, UI dinâmica, hooks avançados
-- **Resultado**: Prevenção proativa de problemas de compliance
+### Próximas Versões (Pseudo-Versioning)
 
-#### v0.2.3 - Compliance Avançado 📋
-
-- **Target**: 4-6 semanas
-- **Status**: Planejamento
-- **Dependências**: Feedback de uso v0.2.2
-- **Próximos passos**: Design do `CookieRegistry` e sistema de logs
-
-#### v0.2.4 - Ferramentas DPO 📊
-
-- **Target**: 8-10 semanas
-- **Status**: Roadmap
-- **Dependências**: v0.2.3 + validação com DPOs
-- **Próximos passos**: Pesquisa com profissionais de compliance
+- **v0.+1.0 (Multi-Regulamentação e Conformidade Avançada)**:
+  - **Geolocalização-based Consent**: Detecção automática da região do usuário para aplicar a regulamentação relevante (LGPD, GDPR, CCPA).
+  - **Configurable Regulation Profiles**: Definição de perfis de regulamentação com requisitos específicos.
+  - **Dynamic Text Adaptation**: Textos adaptáveis com base na regulamentação ativa.
+  - **Modal Detalhado de Cookies**: Exibição de informações técnicas sobre cada cookie (nome, duração, provedor).
+  - **Logs de Auditoria**: Sistema de log client-side para registrar todas as interações de consentimento do usuário.
+  - **Templates Setoriais**: Configurações e textos pré-definidos para setores específicos (governo, saúde, e-commerce).
+  - **Plugin System**: Sistema de plugins para extensibilidade de integrações e lógica customizada.
+  - **Improved `ConsentGate`**: Controle mais granular (e.g., `analytics AND functional`).
+  - **Enhanced Developer Guidance**: Mais avisos e sugestões detalhadas.
 
 ## 🔒 Segurança e Privacidade
 
-### ✅ Implementado (v0.2.2)
-
-#### **Armazenamento e Persistência**
-
-- ✅ Armazenamento client-side via `js-cookie` (bibliotecario confiável)
-- ✅ `SameSite=Lax`, `secure=true` em HTTPS automaticamente
-- ✅ Sem coleta antes do consentimento explícito
-- ✅ Validação robusta de entrada e sanitização de dados
-
-#### **Minimização de Dados (LGPD Art. 6º)**
-
-- ✅ **Cookie inteligente**: Contém apenas categorias realmente utilizadas no projeto
-- ✅ **Configuração consciente**: Sistema orienta sobre quais dados realmente coletar
-- ✅ **Prevenção de spam**: Evita categorias desnecessárias na interface
-- ✅ **Versioning de schema**: Cookie com `version` para migrações futuras
-
-#### **Transparência e Auditabilidade**
-
-- ✅ **Logs estruturados**: Sistema registra decisões de configuração
-- ✅ **Orientações automáticas**: Console de desenvolvimento com guidance
-- ✅ **Documentação automática**: Baseada na configuração real do projeto
-- ✅ **Timestamps**: `consentDate` e `lastUpdate` para auditoria
-
-### 🔄 Planejado
-
-#### **v0.2.3 - Compliance Avançado**
-
-- 🔄 **Logs de consentimento**: Registro detalhado de ações do usuário
-- 🔄 **Base legal específica**: `consent` vs `legitimate_interest` por categoria
-- 🔄 **Detalhamento de cookies**: Informações técnicas completas
-
-#### **v0.2.4 - Auditoria**
-
-- 🔄 **Relatórios estruturados**: Export para ferramentas de compliance
-- 🔄 **Assinatura opcional**: Integridade e não-repúdio de cookies
-- 🔄 **Dashboard DPO**: Métricas e estatísticas para prestação de contas
-
-## 📈 Métricas de Sucesso
-
-### ✅ v0.2.2 - Sistema de Orientações (ALCANÇADO)
-
-- ✅ **Zero breaking changes**: 100% backward compatibility mantida
-- ✅ **Cobertura funcional**: Sistema de orientações implementado completamente
-- ✅ **Bundle size otimizado**: Mantido em 11.15 KB ESM
-- ✅ **Developer experience**: Console automático com orientações
-- ✅ **Type safety**: TypeScript completo para todas as funcionalidades
-
-### v0.2.3 - Compliance Avançado (META)
-
-- [ ] **Templates setoriais**: 3+ setores com configurações pré-definidas
-- [ ] **Logs estruturados**: Sistema de auditoria client-side
-- [ ] **Feedback DPO**: Validação com 2+ profissionais de compliance
-- [ ] **Documentação técnica**: Detalhes de cookies e bases legais
-
-### v0.2.4 - Ferramentas DPO (META)
-
-- [ ] **5+ projetos em produção**: Casos de uso reais documentados
-- [ ] **Dashboard funcional**: Relatórios automáticos de compliance
-- [ ] **Integração com ferramentas**: Export para sistemas de auditoria
-- [ ] **Templates por setor**: E-commerce, governo, saúde, educação
-
-## 🎯 Casos de Uso Validados
-
-### ✅ Projetos Governamentais
-
-- **ANPD Compliance**: Categorias baseadas no Guia Orientativo oficial
-- **Acessibilidade**: WCAG AAA compatível
-- **Auditabilidade**: Logs e decisões rastreáveis
-
-### ✅ E-commerce e Marketing
-
-- **Granularidade**: Controle fino sobre cookies de marketing
-- **Performance**: Zero impacto no carregamento inicial
-- **Integração**: Google Analytics, Tag Manager, UserWay nativos
-
-### ✅ Aplicações Enterprise
-
-- **Customização**: Categorias específicas por projeto
-- **Orientação**: Sistema previne erros de configuração
-- **Manutenibilidade**: UI se adapta automaticamente às mudanças
-
-## 📚 Referências e Padrões
-
-### Legislação e Regulamentação
-
-- [Lei 13.709/2018 - LGPD](https://www.planalto.gov.br/ccivil_03/_ato2015-2018/2018/lei/l13709.htm) - Lei Geral de Proteção de Dados
-- [Guia ANPD - Cookies e Proteção de Dados](https://www.gov.br/anpd/pt-br/documentos-e-publicacoes/guia-orientativo-cookies-e-protecao-de-dados-pessoais.pdf) - Orientação oficial sobre cookies
-- [Regulamentação LGPD](https://www.gov.br/anpd/pt-br/assuntos/regulamentacao) - Regulamentos da ANPD
-
-### Padrões Internacionais
-
-- [GDPR Recital 32](https://gdpr-info.eu/recitals/no-32/) - Consentimento no GDPR
-- [ePrivacy Directive](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX%3A32002L0058) - Diretiva sobre cookies
-- [ISO 27001](https://www.iso.org/isoiec-27001-information-security.html) - Segurança da informação
-- [WCAG 2.1 AAA](https://www.w3.org/WAI/WCAG21/quickref/) - Acessibilidade web
-
-### Boas Práticas Técnicas
-
-- [RFC 6265 - HTTP State Management Mechanism](https://tools.ietf.org/html/rfc6265) - Especificação de cookies
-- [OWASP Cookie Security](https://owasp.org/www-community/controls/SecureCookieAttribute) - Segurança de cookies
-- [Privacy by Design](https://www.ipc.on.ca/wp-content/uploads/Resources/7foundationalprinciples.pdf) - Princípios de privacidade
-
-## 📋 Documentação de Compliance
-
-### Para Desenvolvedores
-
-- 📖 [README.md](./README.md) - Guia de uso e configuração
-- 🔧 [ORIENTACOES-DESENVOLVIMENTO.md](./docs/ORIENTACOES-DESENVOLVIMENTO.md) - Sistema de orientações
-- 🔄 [MIGRACAO-v0.2.2.md](./docs/MIGRACAO-v0.2.2.md) - Guia de migração
-
-### Para Profissionais de Compliance
-
-- 🛡️ [CONFORMIDADE-LGPD.md](./docs/CONFORMIDADE-LGPD.md) - Guia detalhado de conformidade
-- 📊 [SUMARIO-v0.2.2.md](./docs/SUMARIO-v0.2.2.md) - Resumo executivo das funcionalidades
-- 📝 [CHANGELOG.md](./CHANGELOG.md) - Histórico de mudanças e compliance
-
-### Para Auditoria e Prestação de Contas
-
-- 🏗️ [DEVELOPMENT.md](./DEVELOPMENT.md) - Arquitetura técnica e segurança
-- 📋 **Este arquivo** - Conformidade legal e técnica consolidada
-
-## 🎯 Declaração de Conformidade
-
-### v0.2.2 (Atual)
-
-A biblioteca **react-lgpd-consent v0.2.2** está em **conformidade com**:
-
-- ✅ **LGPD (Lei 13.709/2018)**: Artigos 6º (princípios), 7º (bases legais), 8º e 9º (consentimento)
-- ✅ **Guia ANPD sobre Cookies**: 6 categorias oficiais implementadas
-- ✅ **Princípio da Minimização**: Cookie contém apenas dados necessários ao projeto
-- ✅ **Transparência**: Sistema de orientações automáticas para desenvolvedores
-- ✅ **Acessibilidade**: WCAG 2.1 AA compatível (AAA em desenvolvimento)
-- ✅ **Segurança**: RFC 6265 + OWASP Cookie Security practices
-
-### Limitações Conhecidas
-
-- ⚠️ **Server-Side Rendering**: Suporte limitado (melhorias planejadas v0.2.4+)
-- ⚠️ **Logs de auditoria**: Implementação client-side (servidor planejado v0.2.3)
-- ⚠️ **Templates setoriais**: Em desenvolvimento (v0.2.3)
-
-### Responsabilidades
-
-- **Da biblioteca**: Fornecer ferramentas conformes e orientação adequada
-- **Do implementador**: Configurar adequadamente para o contexto específico do projeto
-- **Do controlador**: Manter política de privacidade atualizada e processos de compliance
-
----
-
-**Última atualização**: 12 de agosto de 2025  
-**Versão analisada**: v0.2.2  
-**Próxima revisão**: Lançamento v0.2.3
+- **Armazenamento**: O consentimento é armazenado exclusivamente no cliente (`localStorage` ou `cookie`).
+- **Minimização**: O cookie de consentimento contém apenas as preferências para as categorias ativas no projeto, a versão da configuração e os timestamps necessários para auditoria.
+- **Sem Coleta de Dados Pessoais**: A biblioteca em si não coleta ou transmite dados pessoais.