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
Copy

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

✨ Novidades v0.4.4

🔧 CI/CD e Publicação

• Workflow de Publicação: Corrigido bug que impedia publicação automática no npm quando tags eram criadas após merge para main
• Codecov Integration: Adicionado upload automático de coverage reports para melhor visualização de cobertura de testes
• Badge de Coverage: Agora atualizado em tempo real via Codecov

📊 Qualidade e Confiabilidade

• Publicação Confiável: Tags agora são publicadas corretamente quando commit está no histórico da main
• Visibilidade de Cobertura: Integração completa com Codecov para tracking de qualidade

✨ Novidades v0.4.1

🎨 Design Tokens Expandidos

• 200+ pontos de customização (cores, tipografia, espaçamento, layout)
• Sistema responsivo com breakpoints e variações
• Acessibilidade nativa com contrast ratios e focus states
• Temas light/dark/auto com transições suaves

📝 Sistema Avançado de Textos

• Templates pré-configurados para ecommerce, SaaS e governo
• Internacionalização completa (pt, en, es)
• Variações de tom (formal, casual, técnico)
• Resolução automática baseada em contexto

🔍 Descoberta de Cookies (Experimental)

• Detecção automática de cookies em runtime
• Categorização inteligente usando padrões LGPD
• Integração nativa com sistema de override

⚠️ Breaking Changes

• Suporte a categorias customizadas: setPreference e ScriptIntegration.category agora usam string ao invés de Category
• Impacto mínimo: Código usando strings literais continua funcionando sem alterações
• Consulte: CHANGELOG.md para guia de migração completo

📖 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>
  )
}
Copy

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>
Copy

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.
  • Seção recomendada: “SSR/Next.js (App Router) — Padrões seguros” com boas práticas de 'use client', dynamic({ ssr: false }) e ordem dos provedores/estilos (MUI/Emotion) para evitar hydration mismatch.
  • Novo na v0.4.0: suporte a customCategories — veja a seção “Categorias customizadas (customCategories)” no Quickstart.
  • Novo na v0.4.1: integrações nativas para Facebook Pixel, Hotjar, Mixpanel, Clarity, Intercom e Zendesk — veja o guia INTEGRACOES.md.
  • Dica: use designTokens.layout.backdrop: 'auto' para backdrop sensível ao tema no banner bloqueante.
  • Auto-config de categorias: a biblioteca detecta categorias requeridas pelas integrações e exibe os toggles mesmo se você esquecer de habilitar (valor inicial sempre rejeitado). Recomendamos explicitar em categories.enabledCategories para clareza.
  • Páginas de Política/Termos não bloqueadas: se policyLinkUrl e/ou termsLinkUrl apontarem para a página atual, o overlay bloqueante não é aplicado — garantindo legibilidade destas páginas.
• 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

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

📄 Licença

MIT — veja o arquivo LICENSE.