react-lgpd-consent

react-lgpd-consent 🍪

Uma biblioteca React para gerenciamento de consentimento de cookies em conformidade com a LGPD.

Instalação • Uso Básico • 📚 Guia de Início Rápido • Documentação • 🇺🇸 🇬🇧 English • Contribuir

Comece por aqui: siga o Guia de Início Rápido (QUICKSTART.md) para um tutorial passo-a-passo, exemplos TypeScript, tabela de props e integração com MUI — recomendado para usuários novos.

🚀 Instalação

npm install react-lgpd-consent @mui/material @emotion/react @emotion/styled js-cookie

Dependências peer: react, react-dom, @mui/material e js-cookie.

📖 Uso Básico

Envolva sua aplicação com o ConsentProvider (exemplo mínimo):

import { ConsentProvider } from 'react-lgpd-consent'

export default function App() {
  return (
    <ConsentProvider categories={{ enabledCategories: ['analytics'] }}>
      <YourApp />
    </ConsentProvider>
  )
}

Nota sobre ThemeProvider e tema padrão

A biblioteca não cria um ThemeProvider global automaticamente. Ela tenta herdar o tema do seu app quando você já possui um ThemeProvider do MUI. Se você quiser aplicar explicitamente um tema de fallback para os componentes de consentimento, use a fábrica exportada createDefaultConsentTheme() e passe via prop theme:

import { ConsentProvider, createDefaultConsentTheme } from 'react-lgpd-consent'

// Aplica um tema de fallback somente para os componentes da lib
;<ConsentProvider
  theme={createDefaultConsentTheme()}
  categories={{ enabledCategories: ['analytics'] }}
>
  <App />
</ConsentProvider>

Evite depender de criação de tema no import (isso evita side-effects e problemas em SSR). Se você precisar de compatibilidade retroativa com quem importava defaultConsentTheme, entre em contato para adicionarmos um export compatível com deprecação documentada.

📚 Documentação Completa

Para mais detalhes sobre customização, hooks e funcionalidades, consulte os seguintes guias:

📋 Documentação Principal

• 📚 Guia de Início Rápido (QUICKSTART.md): Tutorial passo a passo com exemplos práticos, tabela completa de props, debugging e integrações.
• Guia da API (API.md): Referência completa de todos os componentes, hooks e tipos.
• Guia de Conformidade (CONFORMIDADE.md): Detalhes sobre as funcionalidades de conformidade com a LGPD.
• Guia de Integrações (INTEGRACOES.md): Como usar as integrações nativas e criar as suas.

🎨 Documentação Interativa (GitHub Pages)

• 📖 Storybook - Playground Interativo: Explore e teste todos os componentes em tempo real com controles interativos.
• ⚙️ TypeDoc - Referência de API: Documentação completa da API gerada automaticamente.
• 🏠 Portal de Documentação: Página inicial com navegação entre todas as documentações.

🤝 Como Contribuir

• Abra uma Issue para bugs ou melhorias.
• Siga o Guia de Desenvolvimento em DEVELOPMENT.md para enviar um PR.

📄 Licença

MIT — veja o arquivo LICENSE.

Changelog

[0.3.6] - 2025-08-28 - Correção crítica: Herança de ThemeProvider

✨ Novas funcionalidades e melhorias

• Storybook

  • Adicionado e aprimorado suporte ao Storybook com controles (args/argTypes) para componentes-chave (FloatingPreferencesButton, PreferencesModal) e suporte a tema escuro nas histórias.
  • Isolamento entre stories via reset de estado (remoção/limpeza de cookie entre stories) e ajustes em .storybook/preview.tsx para compatibilidade com Vite/ESM.

• ConsentProvider

  • blockingStrategy (opt-in) adicionado para permitir overlays de bloqueio controlados pelo provider.
  • Melhor encaminhamento de props: floatingPreferencesButtonProps agora são repassadas corretamente quando o FloatingPreferencesButton é instanciado automaticamente.

• Testes e qualidade

  • Suíte de testes ampliada: novos testes para DesignContext, useConsent, CategoriesContext, ConsentScriptLoader, cookieUtils, scriptLoader, scriptIntegrations, SafeThemeProvider, logger, ConsentGate, PreferencesModal e FloatingPreferencesButton.
  • Configuração inicial de mutation testing com Stryker.
  • Setup de testes atualizado para suprimir logs do developerGuidance durante execução normal e permitir testes dedicados que verifiquem esses logs.

• Integração e DX

  • Quickstart PT/EN e melhorias no README para facilitar adoção e contribuições.
  • Notas de troubleshooting e documentação adicional sobre Storybook e integração de componentes.

🐛 Correções importantes

• FloatingPreferencesButton — props forward

  • Sintoma: props (tooltip, hideWhenConsented, etc.) não eram aplicadas quando o botão era renderizado automaticamente pelo ConsentProvider.
  • Solução: ConsentProvider agora encaminha floatingPreferencesButtonProps corretamente para o componente padrão. Stories atualizadas.

• Storybook fixes

  • Removidos arquivos preview.ts que continham JSX; migrado para preview.tsx e ajustadas exports para evitar erros com o bundler (esbuild/vite).

🧪 Testes e estabilidade

• Cobertura e robustez
  • Adicionados testes que validam uso de hooks fora do ConsentProvider (erros esperados), hidratação a partir de cookie, callbacks (onConsentGiven, onPreferencesSaved) e fluxos de UI (abrir/fechar modal, accept/reject).
  • Ajustes no jest.setup e um jest.console-setup.ts para garantir suprimir logs antes da coleta de módulos, mantendo testes determinísticos.

📚 Documentação

• Quickstart & README
  • Novo Quickstart em PT/EN e simplificações no README com foco em QUICKSTART.
  • Documentação de uso do Storybook e troubleshooting adicionada em docs.

🛠️ Correção crítica

• Corrigido: A biblioteca não deve criar ou impor um ThemeProvider global por si só. O ConsentProvider agora herda o theme do app consumidor quando um ThemeProvider do MUI estiver presente. O Provider só envolverá com ThemeProvider se a prop theme for explicitamente fornecida.
• Motivação: Evitar conflitos de contexto MUI/Emotion, regressões visuais e problemas em SSR causados por criação de tema no escopo de módulo.
• Export: createDefaultConsentTheme() foi adicionada como fábrica para quem precisar de um fallback explícito. Mantemos também um getter de compatibilidade (deprecated) defaultConsentTheme() que retorna uma nova instância quando chamada, evitando side-effects no import.
• Compatibilidade: Uso padrão continua igual — se seu app já fornece um ThemeProvider o ConsentProvider usará o theme existente. Para quem precisa de um fallback explícito, passe theme={createDefaultConsentTheme()} ao ConsentProvider.

Nota: originalmente essa correção foi marcada como v0.3.5; devido a conflito de publicação a versão foi bumpada localmente para v0.3.6 e a entrada foi gravada nesta release.

• Limpeza de arquivos redundantes e ajustes de ESLint/preview para Storybook.

Commits representativos

• Testes e supressão de logs: fce823a, 333ce0a, a1eea7e
• Storybook / docs: 8f8c388, 6e09058, 329682c, 9b1d977, adf0d49
• Provider features: 967d278 (blockingStrategy)
• Quickstart / README: db03ae3
• Dependências / chores: 27339e7, 3b7fdba, 11c3602