react-lgpd-consent 0.2.5 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/COMPLIANCE.md +73 -287
- package/README.md +87 -667
- package/dist/{PreferencesModal-B6N62JYB.js → PreferencesModal-XCTM6WJN.js} +1 -1
- package/dist/{chunk-4LLZREFO.js → chunk-R3IKVZBC.js} +466 -225
- package/dist/index.cjs +732 -643
- package/dist/index.d.cts +141 -125
- package/dist/index.d.ts +141 -125
- package/dist/index.js +7 -182
- package/package.json +12 -1
package/README.md
CHANGED
|
@@ -1,751 +1,171 @@
|
|
|
1
1
|
# react-lgpd-consent 🍪
|
|
2
2
|
|
|
3
|
-
[](
|
|
4
|
-
|
|
5
|
-
A v0.2.2 inclui sistema inteligente que **orienta developers sobre configuração adequada para compliance LGPD**:
|
|
6
|
-
|
|
7
|
-
- 🧠 **Console Automático**: Avisos e sugestões sobre configuração
|
|
8
|
-
- 🎯 **UI Dinâmica**: Componentes se adaptam à configuração do projeto
|
|
9
|
-
- 🛡️ **Compliance por Design**: Previne problemas de conformidade LGPD
|
|
10
|
-
- 🔧 **Hooks Avançados**: `useCategories()` e `useCategoryStatus()` para controle total
|
|
11
|
-
|
|
12
|
-
**Desativando os Avisos:**
|
|
13
|
-
|
|
14
|
-
Por padrão, os avisos são desativados automaticamente em builds de produção (`process.env.NODE_ENV === 'production'`). Para desativá-los explicitamente em desenvolvimento, você pode usar a prop `disableDeveloperGuidance` no `ConsentProvider`:
|
|
15
|
-
|
|
16
|
-
```tsx
|
|
17
|
-
<ConsentProvider disableDeveloperGuidance={true}>
|
|
18
|
-
{/* Sua aplicação */}
|
|
19
|
-
</ConsentProvider>
|
|
20
|
-
```
|
|
21
|
-
|
|
22
|
-
A forma anterior de desativar os avisos via `window.__LGPD_DISABLE_GUIDANCE__ = true` ainda funciona, mas o uso da prop é a forma **preferencial e mais idiomática** em React.
|
|
23
|
-
|
|
24
|
-
## 📖 Uso Básico - Configuração Consciente (v0.2.2)
|
|
25
|
-
|
|
26
|
-
### 1. Setup Básico (Compliance LGPD Automática)
|
|
27
|
-
|
|
28
|
-
````tsx
|
|
29
|
-
import { ConsentProvider, CookieBanner } from 'react-lgpd-consent'
|
|
30
|
-
|
|
31
|
-
function App() {
|
|
32
|
-
return (
|
|
33
|
-
<ConsentProvider
|
|
34
|
-
// 🛡️ Especificar apenas categorias necessárias (Minimização de Dados LGPD)
|
|
35
|
-
categories={{
|
|
36
|
-
enabledCategories: ['analytics'], // Apenas analytics + necessary
|
|
37
|
-
}}
|
|
38
|
-
|
|
39
|
-
// � Textos ANPD para compliance (opcionais)
|
|
40
|
-
texts={{
|
|
41
|
-
bannerMessage: "Utilizamos cookies conforme LGPD...",
|
|
42
|
-
controllerInfo: "Controlado por: Empresa XYZ - CNPJ: 00.000.000/0001-00",
|
|
43
|
-
dataTypes: "Coletamos: dados de navegação para análise estatística",
|
|
44
|
-
userRights: "Direitos: acessar, corrigir, excluir dados (dpo@empresa.com)"
|
|
45
|
-
}}
|
|
46
|
-
|
|
47
|
-
// 🔔 Callbacks para auditoria (opcionais)
|
|
48
|
-
onConsentGiven={(state) => console.log('Consentimento registrado:', state)}
|
|
49
|
-
>
|
|
50
|
-
<CookieBanner policyLinkUrl="/politica-de-privacidade" />
|
|
51
|
-
<YourApp />
|
|
52
|
-
</ConsentProvider>
|
|
53
|
-
)
|
|
54
|
-
}
|
|
55
|
-
```eact-lgpd-consent?style=for-the-badge)](https://github.com/lucianoedipo/react-lgpd-consent/blob/main/LICENSE)
|
|
56
|
-
[](https://www.typescriptlang.org/)
|
|
57
|
-
[](https://reactjs.org/)
|
|
58
|
-
[](https://mui.com/)
|
|
3
|
+
[](https://www.npmjs.com/package/react-lgpd-consent)
|
|
59
4
|
[](https://bundlephobia.com/package/react-lgpd-consent)
|
|
60
5
|
[](https://www.npmjs.com/package/react-lgpd-consent)
|
|
6
|
+
[](https://www.typescriptlang.org/)
|
|
7
|
+
[](https://github.com/lucianoedipo/react-lgpd-consent/blob/main/LICENSE)
|
|
61
8
|
|
|
62
|
-
|
|
63
|
-
[](https://mui.com/)
|
|
64
|
-
|
|
65
|
-
> **Biblioteca completa de consentimento de cookies para React e Next.js em conformidade com a LGPD**
|
|
9
|
+
> **Biblioteca completa de consentimento de cookies para React, em conformidade com a LGPD.**
|
|
66
10
|
|
|
67
|
-
Solução moderna, acessível e personalizável para gerenciar consentimento de cookies em aplicações React, com suporte
|
|
11
|
+
Solução moderna, acessível e personalizável para gerenciar o consentimento de cookies em aplicações React, com suporte a SSR, Material-UI, e um sistema inteligente de orientações para desenvolvedores.
|
|
68
12
|
|
|
69
13
|
## ✨ Características Principais
|
|
70
14
|
|
|
71
|
-
- 🇧🇷 **Conformidade
|
|
72
|
-
-
|
|
73
|
-
-
|
|
74
|
-
-
|
|
75
|
-
-
|
|
76
|
-
-
|
|
77
|
-
- 🎨 **
|
|
78
|
-
- ♿ **Acessibilidade**:
|
|
79
|
-
-
|
|
80
|
-
-
|
|
81
|
-
-
|
|
82
|
-
- 🎯 **Granular Control**: Controle individual por categoria ativa
|
|
83
|
-
- 🚫 **Banner Bloqueante**: Modo opcional para exigir interação antes de continuar
|
|
84
|
-
- 🎨 **Sistema de Temas**: Temas customizáveis para integração visual perfeita
|
|
85
|
-
- ⚡ **Carregamento Automático**: Scripts só executam após consentimento explícito
|
|
86
|
-
- 🔌 **Modal Automático**: Modal de preferências incluído automaticamente com lazy loading
|
|
87
|
-
- 🎛️ **Botão Flutuante**: Componente opcional para acesso fácil às preferências
|
|
15
|
+
- 🇧🇷 **Conformidade com a LGPD**: Desenvolvido seguindo as diretrizes da ANPD.
|
|
16
|
+
- 🧠 **Orientações para Desenvolvedores**: Avisos e sugestões automáticas no console para garantir uma configuração adequada.
|
|
17
|
+
- 🎯 **UI Dinâmica e Inteligente**: Os componentes se adaptam automaticamente às categorias de cookies que você realmente utiliza.
|
|
18
|
+
- 🛡️ **Minimização de Dados**: O cookie de consentimento armazena apenas as informações estritamente necessárias.
|
|
19
|
+
- 🚀 **Integrações Nativas**: Carregue scripts como Google Analytics e GTM automaticamente após o consentimento.
|
|
20
|
+
- ⏰ **Auditoria**: O cookie armazena metadados essenciais como data do consentimento, versão e origem.
|
|
21
|
+
- 🎨 **Customizável**: Personalize textos, tema (Material-UI) e componentes.
|
|
22
|
+
- ♿ **Acessibilidade**: Suporte para navegação por teclado e leitores de tela.
|
|
23
|
+
- 📦 **Leve e Otimizado**: Performance em foco, com tree-shaking.
|
|
24
|
+
- ✨ **Renderização Automática de UI**: O `ConsentProvider` agora gerencia a exibição do banner e do botão flutuante por padrão.
|
|
25
|
+
- 🎨 **Componentes UI Sobrescrevíveis**: Forneça seus próprios componentes de UI com tipagem clara para total personalização.
|
|
88
26
|
|
|
89
27
|
## 🚀 Instalação
|
|
90
28
|
|
|
91
29
|
```bash
|
|
92
30
|
npm install react-lgpd-consent
|
|
93
|
-
|
|
94
|
-
yarn add react-lgpd-consent
|
|
95
|
-
# ou
|
|
96
|
-
pnpm add react-lgpd-consent
|
|
97
|
-
````
|
|
31
|
+
```
|
|
98
32
|
|
|
99
|
-
|
|
33
|
+
Você também precisará das dependências `peer`, caso ainda não as tenha:
|
|
100
34
|
|
|
101
35
|
```bash
|
|
102
|
-
npm install @mui/material js-cookie
|
|
36
|
+
npm install react react-dom @mui/material js-cookie
|
|
103
37
|
```
|
|
104
38
|
|
|
105
|
-
##
|
|
106
|
-
|
|
107
|
-
### 🍪 Categorias Baseadas no Guia da ANPD
|
|
108
|
-
|
|
109
|
-
A biblioteca agora inclui **6 categorias** baseadas no Guia Orientativo da ANPD:
|
|
39
|
+
## 📖 Uso Básico
|
|
110
40
|
|
|
111
|
-
|
|
112
|
-
- **`analytics`**: Análise e estatísticas de uso
|
|
113
|
-
- **`functional`**: Funcionalidades extras (preferências, idioma)
|
|
114
|
-
- **`marketing`**: Publicidade e marketing direcionado
|
|
115
|
-
- **`social`**: Integração com redes sociais
|
|
116
|
-
- **`personalization`**: Personalização de conteúdo
|
|
117
|
-
|
|
118
|
-
### 🛡️ Conformidade LGPD Rigorosa (v0.2.1)
|
|
119
|
-
|
|
120
|
-
**Princípio da Minimização**: Cookie contém apenas categorias realmente utilizadas:
|
|
41
|
+
O exemplo abaixo mostra como implementar um banner de consentimento funcional com o mínimo de configuração.
|
|
121
42
|
|
|
122
43
|
```tsx
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
enabledCategories: ['analytics'], // Apenas analytics + necessary
|
|
126
|
-
customCategories: [{
|
|
127
|
-
id: 'governo',
|
|
128
|
-
name: 'Integração Governamental',
|
|
129
|
-
description: 'Cookies para sistemas gov.br',
|
|
130
|
-
essential: false
|
|
131
|
-
}]
|
|
132
|
-
}}
|
|
133
|
-
blocking={true} // Banner bloqueia até decisão explícita
|
|
134
|
-
>
|
|
135
|
-
```
|
|
44
|
+
// Em seu componente principal, como App.tsx
|
|
45
|
+
import { ConsentProvider } from 'react-lgpd-consent'
|
|
136
46
|
|
|
137
|
-
|
|
47
|
+
function App() {
|
|
48
|
+
return (
|
|
49
|
+
<ConsentProvider
|
|
50
|
+
// 1. Especifique as categorias que seu site utiliza
|
|
51
|
+
categories={{
|
|
52
|
+
enabledCategories: ['analytics', 'marketing'],
|
|
53
|
+
}}
|
|
54
|
+
// 2. (Opcional) Adicione textos para total transparência
|
|
55
|
+
texts={{
|
|
56
|
+
controllerInfo: 'Controlado por: Sua Empresa LTDA',
|
|
57
|
+
userRights: 'Você tem o direito de acessar e corrigir seus dados.',
|
|
58
|
+
}}
|
|
59
|
+
// 3. (Opcional) Adicione callbacks para auditoria
|
|
60
|
+
onConsentGiven={(state) => console.log('Consentimento dado:', state)}
|
|
61
|
+
>
|
|
62
|
+
{/* O resto da sua aplicação */}
|
|
63
|
+
<h1>Meu Site</h1>
|
|
64
|
+
<p>Bem-vindo ao meu site.</p>
|
|
138
65
|
|
|
139
|
-
|
|
140
|
-
{
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
"preferences": { "necessary": true, "analytics": false, "governo": true },
|
|
144
|
-
"consentDate": "2025-08-12T14:30:00.000Z",
|
|
145
|
-
"lastUpdate": "2025-08-12T14:30:00.000Z",
|
|
146
|
-
"source": "banner"
|
|
66
|
+
{/* O ConsentProvider agora renderiza automaticamente o banner e o botão flutuante */}
|
|
67
|
+
{/* Você pode sobrescrevê-los usando as props CookieBannerComponent e FloatingPreferencesButtonComponent */}
|
|
68
|
+
</ConsentProvider>
|
|
69
|
+
)
|
|
147
70
|
}
|
|
71
|
+
|
|
72
|
+
export default App
|
|
148
73
|
```
|
|
149
74
|
|
|
150
|
-
|
|
75
|
+
## 🔧 API e Funcionalidades
|
|
151
76
|
|
|
152
|
-
###
|
|
77
|
+
### Configuração Consciente
|
|
153
78
|
|
|
154
|
-
A
|
|
79
|
+
A prop `categories` no `ConsentProvider` é o ponto central da biblioteca. Ela força o desenvolvedor a declarar quais categorias de cookies são utilizadas, em linha com o princípio de minimização de dados da LGPD.
|
|
155
80
|
|
|
156
81
|
```tsx
|
|
157
|
-
// ⚠️ Sem configuração - usa padrão e avisa
|
|
158
|
-
<ConsentProvider>
|
|
159
|
-
<App />
|
|
160
|
-
</ConsentProvider>
|
|
161
|
-
// Console: "Usando padrão: necessary + analytics. Especificar para produção."
|
|
162
|
-
|
|
163
|
-
// ✅ Configuração explícita - recomendado
|
|
164
82
|
<ConsentProvider
|
|
165
83
|
categories={{
|
|
166
|
-
|
|
167
|
-
|
|
84
|
+
// Habilita as categorias padrão 'analytics' e 'functional'
|
|
85
|
+
enabledCategories: ['analytics', 'functional'],
|
|
168
86
|
}}
|
|
169
87
|
>
|
|
170
|
-
|
|
171
|
-
</ConsentProvider>
|
|
172
|
-
```
|
|
173
|
-
|
|
174
|
-
**Console de desenvolvimento** mostra automaticamente:
|
|
175
|
-
|
|
176
|
-
- 🟨 **Avisos**: Configuração faltante ou inconsistente
|
|
177
|
-
- 💡 **Sugestões**: Melhorias para compliance
|
|
178
|
-
- 🔧 **Tabela de categorias ativas**: Para UI customizada
|
|
179
|
-
|
|
180
|
-
> 📋 **[Sistema de Orientações Completo](./docs/ORIENTACOES-DESENVOLVIMENTO.md)**
|
|
181
|
-
|
|
182
|
-
### 🔧 Categorias Customizadas (API Legacy)
|
|
183
|
-
|
|
184
|
-
```tsx
|
|
185
|
-
// LEGACY: ainda suportado, mas deprecated
|
|
186
|
-
const customCategories = [
|
|
187
|
-
{
|
|
188
|
-
id: 'governo',
|
|
189
|
-
name: 'Integração Governo',
|
|
190
|
-
description: 'Cookies para integração com sistemas governamentais.',
|
|
191
|
-
essential: false,
|
|
192
|
-
cookies: ['gov_session', 'cpf_hash']
|
|
193
|
-
}
|
|
194
|
-
]
|
|
195
|
-
|
|
196
|
-
<ConsentProvider customCategories={customCategories}>
|
|
197
|
-
{/* Sua aplicação */}
|
|
88
|
+
{/*...*/}
|
|
198
89
|
</ConsentProvider>
|
|
199
90
|
```
|
|
200
91
|
|
|
201
|
-
###
|
|
202
|
-
|
|
203
|
-
Os componentes agora **renderizam automaticamente** baseado na configuração:
|
|
204
|
-
|
|
205
|
-
```tsx
|
|
206
|
-
import { useCategories, useCategoryStatus } from 'react-lgpd-consent'
|
|
207
|
-
|
|
208
|
-
// ✅ Modal customizado que se adapta às categorias ativas
|
|
209
|
-
function CustomPreferencesModal() {
|
|
210
|
-
const { toggleableCategories } = useCategories()
|
|
211
|
-
const { preferences, setPreferences } = useConsent()
|
|
212
|
-
|
|
213
|
-
return (
|
|
214
|
-
<dialog>
|
|
215
|
-
{/* Renderiza APENAS categorias configuradas no projeto */}
|
|
216
|
-
{toggleableCategories.map((category) => (
|
|
217
|
-
<label key={category.id}>
|
|
218
|
-
<input
|
|
219
|
-
type="checkbox"
|
|
220
|
-
checked={preferences[category.id] ?? false} // ✅ Controlado
|
|
221
|
-
onChange={(e) =>
|
|
222
|
-
setPreferences({
|
|
223
|
-
...preferences,
|
|
224
|
-
[category.id]: e.target.checked,
|
|
225
|
-
})
|
|
226
|
-
}
|
|
227
|
-
/>
|
|
228
|
-
<strong>{category.name}</strong>
|
|
229
|
-
<p>{category.description}</p>
|
|
230
|
-
</label>
|
|
231
|
-
))}
|
|
232
|
-
</dialog>
|
|
233
|
-
)
|
|
234
|
-
}
|
|
235
|
-
|
|
236
|
-
// ✅ Feature condicional baseada em configuração
|
|
237
|
-
function AnalyticsDashboard() {
|
|
238
|
-
const analytics = useCategoryStatus('analytics')
|
|
239
|
-
|
|
240
|
-
if (!analytics.isActive) {
|
|
241
|
-
return null // Categoria não configurada - não renderiza
|
|
242
|
-
}
|
|
243
|
-
|
|
244
|
-
return <div>Dashboard só aparece se analytics estiver configurado!</div>
|
|
245
|
-
}
|
|
246
|
-
```
|
|
247
|
-
|
|
248
|
-
**Benefícios:**
|
|
249
|
-
|
|
250
|
-
- ✅ **Zero bugs**: UI sempre consistente com configuração
|
|
251
|
-
- ✅ **Performance**: Não renderiza categorias não utilizadas
|
|
252
|
-
- ✅ **Manutenibilidade**: Mudou configuração? UI atualiza automaticamente
|
|
253
|
-
- ✅ **Orientação**: Console avisa sobre inconsistências
|
|
92
|
+
### Carregamento de Scripts (`ConsentScriptLoader`)
|
|
254
93
|
|
|
255
|
-
|
|
94
|
+
Evite carregar scripts de rastreamento antes do consentimento. O `ConsentScriptLoader` faz isso automaticamente.
|
|
256
95
|
|
|
257
96
|
```tsx
|
|
258
97
|
import {
|
|
98
|
+
ConsentProvider,
|
|
259
99
|
ConsentScriptLoader,
|
|
260
100
|
createGoogleAnalyticsIntegration,
|
|
261
|
-
createUserWayIntegration,
|
|
262
101
|
} from 'react-lgpd-consent'
|
|
263
102
|
|
|
264
103
|
const integrations = [
|
|
265
104
|
createGoogleAnalyticsIntegration({
|
|
266
|
-
measurementId: '
|
|
267
|
-
}),
|
|
268
|
-
createUserWayIntegration({
|
|
269
|
-
accountId: 'USERWAY_ACCOUNT_ID',
|
|
105
|
+
measurementId: 'G-XXXXXXXXXX',
|
|
270
106
|
}),
|
|
271
107
|
]
|
|
272
108
|
|
|
273
109
|
function App() {
|
|
274
110
|
return (
|
|
275
|
-
<ConsentProvider>
|
|
276
|
-
{/*
|
|
111
|
+
<ConsentProvider categories={{ enabledCategories: ['analytics'] }}>
|
|
112
|
+
{/* Este componente carrega os scripts para você quando o consentimento é dado */}
|
|
277
113
|
<ConsentScriptLoader integrations={integrations} />
|
|
278
114
|
|
|
279
|
-
|
|
280
|
-
</ConsentProvider>
|
|
281
|
-
)
|
|
282
|
-
}
|
|
283
|
-
```
|
|
284
|
-
|
|
285
|
-
### 📝 Textos ANPD Expandidos
|
|
286
|
-
|
|
287
|
-
```tsx
|
|
288
|
-
<ConsentProvider
|
|
289
|
-
texts={{
|
|
290
|
-
bannerMessage: 'Utilizamos cookies para melhorar sua experiência.',
|
|
291
|
-
// Textos ANPD opcionais
|
|
292
|
-
controllerInfo: 'Controlado por Empresa LTDA (CNPJ: 00.000.000/0001-00)',
|
|
293
|
-
dataTypes: 'Coletamos dados de navegação, preferências e interações.',
|
|
294
|
-
thirdPartySharing: 'Compartilhamos com: Google Analytics, Facebook Pixel',
|
|
295
|
-
userRights: 'Você tem direito a acesso, correção e exclusão dos dados.',
|
|
296
|
-
contactInfo: 'Contato DPO: dpo@empresa.com.br | (11) 9999-9999',
|
|
297
|
-
retentionPeriod: 'Dados armazenados por até 12 meses.',
|
|
298
|
-
lawfulBasis: 'Base legal: consentimento do titular dos dados.',
|
|
299
|
-
transferCountries: 'Dados podem ser transferidos para: EUA, Irlanda.',
|
|
300
|
-
}}
|
|
301
|
-
>
|
|
302
|
-
{/* Os textos são exibidos condicionalmente apenas se definidos */}
|
|
303
|
-
</ConsentProvider>
|
|
304
|
-
```
|
|
305
|
-
|
|
306
|
-
## � Exemplo Completo
|
|
307
|
-
|
|
308
|
-
```tsx
|
|
309
|
-
import {
|
|
310
|
-
ConsentProvider,
|
|
311
|
-
CookieBanner,
|
|
312
|
-
FloatingPreferencesButton,
|
|
313
|
-
} from 'react-lgpd-consent'
|
|
314
|
-
|
|
315
|
-
function App() {
|
|
316
|
-
return (
|
|
317
|
-
<ConsentProvider>
|
|
318
|
-
<div>
|
|
319
|
-
<h1>Meu Site</h1>
|
|
320
|
-
<p>Conteúdo do site...</p>
|
|
321
|
-
|
|
322
|
-
{/* Banner de cookies - Modal incluído automaticamente! */}
|
|
323
|
-
<CookieBanner policyLinkUrl="/privacy-policy" blocking={true} />
|
|
324
|
-
|
|
325
|
-
{/* Botão flutuante opcional para acesso às preferências */}
|
|
326
|
-
<FloatingPreferencesButton position="bottom-right" />
|
|
327
|
-
</div>
|
|
328
|
-
</ConsentProvider>
|
|
329
|
-
)
|
|
330
|
-
}
|
|
331
|
-
```
|
|
332
|
-
|
|
333
|
-
## �📖 Uso Básico
|
|
334
|
-
|
|
335
|
-
### 1. Setup do Provider
|
|
336
|
-
|
|
337
|
-
```tsx
|
|
338
|
-
import { ConsentProvider } from 'react-lgpd-consent'
|
|
339
|
-
|
|
340
|
-
function App() {
|
|
341
|
-
return (
|
|
342
|
-
<ConsentProvider>
|
|
343
|
-
<YourApp />
|
|
115
|
+
{/* ... resto do app */}
|
|
344
116
|
</ConsentProvider>
|
|
345
117
|
)
|
|
346
118
|
}
|
|
347
119
|
```
|
|
348
120
|
|
|
349
|
-
###
|
|
350
|
-
|
|
351
|
-
```tsx
|
|
352
|
-
import { CookieBanner } from 'react-lgpd-consent'
|
|
353
|
-
|
|
354
|
-
function Layout() {
|
|
355
|
-
return (
|
|
356
|
-
<>
|
|
357
|
-
<YourContent />
|
|
358
|
-
<CookieBanner
|
|
359
|
-
policyLinkUrl="/politica-privacidade"
|
|
360
|
-
blocking={true} // Padrão: bloqueia até decisão
|
|
361
|
-
/>
|
|
362
|
-
{/* Modal de preferências incluído automaticamente! */}
|
|
363
|
-
</>
|
|
364
|
-
)
|
|
365
|
-
}
|
|
366
|
-
```
|
|
367
|
-
|
|
368
|
-
### 3. Uso do Hook
|
|
369
|
-
|
|
370
|
-
```tsx
|
|
371
|
-
import { useConsent } from 'react-lgpd-consent'
|
|
372
|
-
|
|
373
|
-
function MyComponent() {
|
|
374
|
-
const { consented, preferences, acceptAll, openPreferences } = useConsent()
|
|
375
|
-
|
|
376
|
-
return (
|
|
377
|
-
<div>
|
|
378
|
-
<p>Consentimento: {consented ? 'Dado' : 'Pendente'}</p>
|
|
379
|
-
<button onClick={acceptAll}>Aceitar Todos</button>
|
|
380
|
-
<button onClick={openPreferences}>Gerenciar Preferências</button>
|
|
381
|
-
</div>
|
|
382
|
-
)
|
|
383
|
-
}
|
|
384
|
-
```
|
|
385
|
-
|
|
386
|
-
> ✅ **O modal de preferências é incluído automaticamente pelo ConsentProvider!** Não é mais necessário renderizá-lo manualmente.
|
|
121
|
+
### Renderização Condicional (`ConsentGate`)
|
|
387
122
|
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
### 4. Carregamento Condicional de Scripts
|
|
123
|
+
Renderize componentes ou partes da sua UI apenas se o usuário consentiu com uma categoria específica.
|
|
391
124
|
|
|
392
125
|
```tsx
|
|
393
|
-
import { ConsentGate
|
|
126
|
+
import { ConsentGate } from 'react-lgpd-consent'
|
|
394
127
|
|
|
395
|
-
function
|
|
128
|
+
function MarketingPixel() {
|
|
396
129
|
return (
|
|
397
|
-
<ConsentGate category="
|
|
398
|
-
|
|
130
|
+
<ConsentGate category="marketing">
|
|
131
|
+
{/* Este componente só será renderizado se o usuário aceitar cookies de marketing */}
|
|
132
|
+
<img src="/pixel.gif" alt="Marketing Pixel" />
|
|
399
133
|
</ConsentGate>
|
|
400
134
|
)
|
|
401
135
|
}
|
|
402
|
-
|
|
403
|
-
// Ou carregando scripts que aguardam consentimento
|
|
404
|
-
function MyComponent() {
|
|
405
|
-
const { preferences, consented } = useConsent()
|
|
406
|
-
|
|
407
|
-
useEffect(() => {
|
|
408
|
-
if (consented && preferences.analytics) {
|
|
409
|
-
loadConditionalScript(
|
|
410
|
-
'ga',
|
|
411
|
-
'https://www.googletagmanager.com/gtag/js?id=GA_ID',
|
|
412
|
-
() => preferences.analytics, // Condição que aguarda
|
|
413
|
-
)
|
|
414
|
-
}
|
|
415
|
-
}, [preferences, consented])
|
|
416
|
-
}
|
|
417
|
-
````
|
|
418
|
-
|
|
419
|
-
## 🎨 Customização
|
|
420
|
-
|
|
421
|
-
### Banner Bloqueante vs Não-bloqueante
|
|
422
|
-
|
|
423
|
-
```tsx
|
|
424
|
-
// Banner bloqueante (padrão) - impede interação até decisão
|
|
425
|
-
<CookieBanner blocking={true} />
|
|
426
|
-
|
|
427
|
-
// Banner não-intrusivo - permite navegação
|
|
428
|
-
<CookieBanner blocking={false} />
|
|
429
|
-
```
|
|
430
|
-
|
|
431
|
-
### Tema Personalizado
|
|
432
|
-
|
|
433
|
-
```tsx
|
|
434
|
-
import { ConsentProvider, defaultConsentTheme } from 'react-lgpd-consent'
|
|
435
|
-
import { createTheme } from '@mui/material/styles'
|
|
436
|
-
|
|
437
|
-
const meuTema = createTheme({
|
|
438
|
-
...defaultConsentTheme,
|
|
439
|
-
palette: {
|
|
440
|
-
...defaultConsentTheme.palette,
|
|
441
|
-
primary: {
|
|
442
|
-
main: '#1976d2', // Sua cor principal
|
|
443
|
-
},
|
|
444
|
-
},
|
|
445
|
-
})
|
|
446
|
-
|
|
447
|
-
<ConsentProvider theme={meuTema}>
|
|
448
|
-
<App />
|
|
449
|
-
</ConsentProvider>
|
|
450
|
-
```
|
|
451
|
-
|
|
452
|
-
### Textos Personalizados
|
|
453
|
-
|
|
454
|
-
```tsx
|
|
455
|
-
<ConsentProvider
|
|
456
|
-
texts={{
|
|
457
|
-
bannerMessage: "Utilizamos cookies para melhorar sua experiência.",
|
|
458
|
-
acceptAll: "Aceitar Todos",
|
|
459
|
-
declineAll: "Recusar Opcionais",
|
|
460
|
-
preferences: "Configurar"
|
|
461
|
-
}}
|
|
462
|
-
>
|
|
463
|
-
```
|
|
464
|
-
|
|
465
|
-
### Configuração do Cookie
|
|
466
|
-
|
|
467
|
-
```tsx
|
|
468
|
-
<ConsentProvider
|
|
469
|
-
cookie={{
|
|
470
|
-
name: 'meuSiteConsent',
|
|
471
|
-
maxAgeDays: 180,
|
|
472
|
-
sameSite: 'Strict'
|
|
473
|
-
}}
|
|
474
|
-
>
|
|
475
|
-
```
|
|
476
|
-
|
|
477
|
-
### Callbacks
|
|
478
|
-
|
|
479
|
-
```tsx
|
|
480
|
-
<ConsentProvider
|
|
481
|
-
onConsentGiven={(state) => {
|
|
482
|
-
console.log('Consentimento dado:', state)
|
|
483
|
-
// Inicializar analytics, etc.
|
|
484
|
-
}}
|
|
485
|
-
onPreferencesSaved={(prefs) => {
|
|
486
|
-
console.log('Preferências salvas:', prefs)
|
|
487
|
-
}}
|
|
488
|
-
>
|
|
489
|
-
```
|
|
490
|
-
|
|
491
|
-
## � Banner Bloqueante
|
|
492
|
-
|
|
493
|
-
Para cenários onde é necessário bloquear o acesso até obter consentimento explícito:
|
|
494
|
-
|
|
495
|
-
```tsx
|
|
496
|
-
<CookieBanner blocking />
|
|
497
|
-
```
|
|
498
|
-
|
|
499
|
-
Com `blocking={true}`, o banner:
|
|
500
|
-
|
|
501
|
-
- Cria um overlay escuro sobre todo o conteúdo
|
|
502
|
-
- Impede interação com o resto da página
|
|
503
|
-
- É útil para casos críticos onde consentimento é obrigatório
|
|
504
|
-
|
|
505
|
-
## 🎨 Sistema de Temas
|
|
506
|
-
|
|
507
|
-
### Tema Personalizado
|
|
508
|
-
|
|
509
|
-
```tsx
|
|
510
|
-
import { createTheme } from '@mui/material/styles'
|
|
511
|
-
|
|
512
|
-
const meuTema = createTheme({
|
|
513
|
-
palette: {
|
|
514
|
-
primary: { main: '#2196f3' },
|
|
515
|
-
secondary: { main: '#f50057' },
|
|
516
|
-
},
|
|
517
|
-
})
|
|
518
|
-
|
|
519
|
-
<ConsentProvider theme={meuTema}>
|
|
520
|
-
<App />
|
|
521
|
-
</ConsentProvider>
|
|
522
|
-
```
|
|
523
|
-
|
|
524
|
-
### Tema Padrão
|
|
525
|
-
|
|
526
|
-
O tema padrão do react-lgpd-consent está disponível para customização:
|
|
527
|
-
|
|
528
|
-
```tsx
|
|
529
|
-
import { defaultConsentTheme } from 'react-lgpd-consent'
|
|
530
|
-
|
|
531
|
-
const temaCustomizado = createTheme({
|
|
532
|
-
...defaultConsentTheme,
|
|
533
|
-
palette: {
|
|
534
|
-
...defaultConsentTheme.palette,
|
|
535
|
-
primary: { main: '#your-color' },
|
|
536
|
-
},
|
|
537
|
-
})
|
|
538
|
-
```
|
|
539
|
-
|
|
540
|
-
## ⚡ Carregamento Inteligente de Scripts
|
|
541
|
-
|
|
542
|
-
### Função loadScript
|
|
543
|
-
|
|
544
|
-
Scripts aguardam automaticamente o **consentimento finalizado** (banner fechado ou preferências salvas):
|
|
545
|
-
|
|
546
|
-
```tsx
|
|
547
|
-
import { loadScript } from 'react-lgpd-consent'
|
|
548
|
-
|
|
549
|
-
// Carrega script apenas após consentimento para analytics
|
|
550
|
-
await loadScript(
|
|
551
|
-
'gtag',
|
|
552
|
-
'https://www.googletagmanager.com/gtag/js?id=GA_ID',
|
|
553
|
-
'analytics', // Categoria obrigatória
|
|
554
|
-
)
|
|
555
|
-
|
|
556
|
-
// Script geral (sempre carrega após consentimento)
|
|
557
|
-
await loadScript('custom-script', 'https://example.com/script.js')
|
|
558
|
-
```
|
|
559
|
-
|
|
560
|
-
### Comportamento Inteligente
|
|
561
|
-
|
|
562
|
-
- **Aguarda decisão final**: Não executa durante mudanças no modal de preferências
|
|
563
|
-
- **Só executa após salvar**: Scripts só rodam quando o usuário finaliza as preferências
|
|
564
|
-
- **Baseado em categoria**: Respeita as permissões por categoria
|
|
565
|
-
|
|
566
|
-
## 🎨 Personalização Total
|
|
567
|
-
|
|
568
|
-
### Modal de Preferências Customizado
|
|
569
|
-
|
|
570
|
-
Substitua completamente o modal padrão com seu próprio componente:
|
|
571
|
-
|
|
572
|
-
```tsx
|
|
573
|
-
import { ConsentProvider, useConsent } from 'react-lgpd-consent'
|
|
574
|
-
import MeuModalCustomizado from './MeuModalCustomizado'
|
|
575
|
-
|
|
576
|
-
function App() {
|
|
577
|
-
return (
|
|
578
|
-
<ConsentProvider
|
|
579
|
-
PreferencesModalComponent={MeuModalCustomizado}
|
|
580
|
-
preferencesModalProps={{ variant: 'custom' }}
|
|
581
|
-
>
|
|
582
|
-
<MeuApp />
|
|
583
|
-
</ConsentProvider>
|
|
584
|
-
)
|
|
585
|
-
}
|
|
586
|
-
|
|
587
|
-
// Seu componente customizado
|
|
588
|
-
function MeuModalCustomizado({ variant }) {
|
|
589
|
-
const { isModalOpen, closePreferences, setPreference } = useConsent()
|
|
590
|
-
|
|
591
|
-
return (
|
|
592
|
-
<MyCustomDialog open={isModalOpen} onClose={closePreferences}>
|
|
593
|
-
{/* Seu design personalizado aqui */}
|
|
594
|
-
</MyCustomDialog>
|
|
595
|
-
)
|
|
596
|
-
}
|
|
597
|
-
```
|
|
598
|
-
|
|
599
|
-
### Desabilitar Modal Automático
|
|
600
|
-
|
|
601
|
-
Para controle total, desabilite o modal automático:
|
|
602
|
-
|
|
603
|
-
```tsx
|
|
604
|
-
<ConsentProvider disableAutomaticModal>
|
|
605
|
-
<MeuApp />
|
|
606
|
-
{/* Renderize seus componentes customizados onde quiser */}
|
|
607
|
-
<MeuModalTotalmenteCustomizado />
|
|
608
|
-
</ConsentProvider>
|
|
609
|
-
```
|
|
610
|
-
|
|
611
|
-
## �🔧 API Completa
|
|
612
|
-
|
|
613
|
-
### Components
|
|
614
|
-
|
|
615
|
-
| Componente | Descrição | Props Principais |
|
|
616
|
-
| --------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
|
|
617
|
-
| `ConsentProvider` | Provider principal do contexto | `initialState`, `texts`, `theme`, `hideBranding`, `PreferencesModalComponent`, `disableDeveloperGuidance`, callbacks |
|
|
618
|
-
| `CookieBanner` | Banner de consentimento | `policyLinkUrl`, `blocking`, `hideBranding`, `debug`, pass-through MUI props |
|
|
619
|
-
| `PreferencesModal` | Modal de preferências (incluído automaticamente) | `DialogProps`, `hideBranding` - **Opcional** |
|
|
620
|
-
| `FloatingPreferencesButton` | Botão flutuante para abrir preferências | `position`, `hideWhenConsented`, `tooltip`, `icon`, `FabProps` |
|
|
621
|
-
| `ConsentGate` | Renderização condicional por categoria | `category`, `children` |
|
|
622
|
-
|
|
623
|
-
### Hook `useConsent()`
|
|
624
|
-
|
|
625
|
-
```typescript
|
|
626
|
-
interface ConsentContextValue {
|
|
627
|
-
consented: boolean // usuário já consentiu?
|
|
628
|
-
preferences: ConsentPreferences // preferências atuais
|
|
629
|
-
isModalOpen: boolean // estado do modal de preferências
|
|
630
|
-
acceptAll(): void // aceitar todas as categorias
|
|
631
|
-
rejectAll(): void // recusar opcionais
|
|
632
|
-
setPreference(cat: Category, value: boolean): void // definir categoria específica
|
|
633
|
-
openPreferences(): void // abrir modal de preferências
|
|
634
|
-
closePreferences(): void // fechar modal
|
|
635
|
-
resetConsent(): void // resetar tudo
|
|
636
|
-
}
|
|
637
|
-
```
|
|
638
|
-
|
|
639
|
-
### Hook `useConsentTexts()`
|
|
640
|
-
|
|
641
|
-
```typescript
|
|
642
|
-
// Acesso aos textos contextuais
|
|
643
|
-
const texts = useConsentTexts()
|
|
644
|
-
console.log(texts.banner.title) // "Política de Cookies"
|
|
645
136
|
```
|
|
646
137
|
|
|
647
|
-
###
|
|
138
|
+
### API e Funcionalidades
|
|
648
139
|
|
|
649
|
-
|
|
650
|
-
- `defaultConsentTheme` - Tema padrão do Material-UI
|
|
651
|
-
- Tipos TypeScript completos exportados## 🌐 SSR / Next.js
|
|
140
|
+
A versão `v0.3.0` simplifica a API e melhora a experiência do desenvolvedor.
|
|
652
141
|
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
656
|
-
// pages/_app.tsx (Next.js)
|
|
657
|
-
function MyApp({ Component, pageProps }) {
|
|
658
|
-
return (
|
|
659
|
-
<ConsentProvider
|
|
660
|
-
initialState={{
|
|
661
|
-
consented: false,
|
|
662
|
-
preferences: { analytics: false, marketing: false },
|
|
663
|
-
}}
|
|
664
|
-
>
|
|
665
|
-
<Component {...pageProps} />
|
|
666
|
-
</ConsentProvider>
|
|
667
|
-
)
|
|
668
|
-
}
|
|
669
|
-
```
|
|
142
|
+
- **Componentes UI Sobrescrevíveis com Tipagem Clara**: Agora você pode fornecer seus próprios componentes para o banner, modal e botão flutuante, com props tipadas para garantir a compatibilidade. Consulte `CustomCookieBannerProps`, `CustomPreferencesModalProps` e `CustomFloatingPreferencesButtonProps` para detalhes.
|
|
143
|
+
- **Controle Simplificado do Modal**: A prop `disableAutomaticModal` foi removida. A visibilidade do modal é controlada internamente.
|
|
144
|
+
- **Remoção de Hooks Internos**: O hook `useConsentComponentProps` foi removido para simplificar a API. Use `useConsent()` e `useConsentTexts()` diretamente.
|
|
670
145
|
|
|
671
|
-
|
|
146
|
+
### Hooks
|
|
672
147
|
|
|
673
|
-
A biblioteca
|
|
148
|
+
A biblioteca exporta hooks para controle total e criação de UIs customizadas:
|
|
674
149
|
|
|
675
|
-
-
|
|
676
|
-
-
|
|
677
|
-
-
|
|
678
|
-
- ✅ Contrastes adequados
|
|
679
|
-
- ✅ Estrutura semântica correta
|
|
150
|
+
- `useConsent()`: O hook principal para interagir com o estado de consentimento.
|
|
151
|
+
- `useCategories()`: Retorna a lista de todas as categorias ativas no projeto.
|
|
152
|
+
- `useCategoryStatus('id')`: Verifica se uma categoria específica está ativa e configurada.
|
|
680
153
|
|
|
681
|
-
##
|
|
154
|
+
## 🛡️ Conformidade e LGPD
|
|
682
155
|
|
|
683
|
-
|
|
156
|
+
Esta biblioteca foi projetada para auxiliar na conformidade com a LGPD, implementando princípios como:
|
|
684
157
|
|
|
685
|
-
-
|
|
686
|
-
-
|
|
687
|
-
-
|
|
688
|
-
-
|
|
158
|
+
- **Consentimento Granular**: O usuário pode escolher quais categorias aceitar.
|
|
159
|
+
- **Minimização de Dados**: Apenas as categorias declaradas são gerenciadas e armazenadas no cookie.
|
|
160
|
+
- **Transparência**: O sistema de textos e o cookie de auditoria fornecem informações claras.
|
|
161
|
+
- **Facilidade de Revogação**: O usuário pode alterar suas preferências a qualquer momento.
|
|
689
162
|
|
|
690
|
-
|
|
163
|
+
Para mais detalhes, consulte o nosso **[Guia de Conformidade](docs/CONFORMIDADE-LGPD.md)**.
|
|
691
164
|
|
|
692
|
-
|
|
165
|
+
## 🤝 Contribuições
|
|
693
166
|
|
|
694
|
-
|
|
695
|
-
2. Crie uma branch para sua feature (`git checkout -b feature/AmazingFeature`)
|
|
696
|
-
3. Commit suas mudanças (`git commit -m 'Add some AmazingFeature'`)
|
|
697
|
-
4. Push para a branch (`git push origin feature/AmazingFeature`)
|
|
698
|
-
5. Abra um Pull Request
|
|
167
|
+
Contribuições são bem-vindas! Sinta-se à vontade para abrir uma _issue_ ou um _pull request_.
|
|
699
168
|
|
|
700
169
|
## 📄 Licença
|
|
701
170
|
|
|
702
|
-
Este projeto está
|
|
703
|
-
|
|
704
|
-
## 🙋♀️ Suporte
|
|
705
|
-
|
|
706
|
-
- 📖 [Documentação](./docs)
|
|
707
|
-
- 🐛 [Issues](https://github.com/lucianoedipo/react-lgpd-consent/issues)
|
|
708
|
-
- 💬 [Discussões](https://github.com/lucianoedipo/react-lgpd-consent/discussions)
|
|
709
|
-
|
|
710
|
-
## 🔮 Roadmap
|
|
711
|
-
|
|
712
|
-
### ✅ v0.2.2 - Sistema de Orientações (Lançado!)
|
|
713
|
-
|
|
714
|
-
**Implementado: Sistema inteligente de orientação para desenvolvedores**
|
|
715
|
-
|
|
716
|
-
- ✅ **Console de Desenvolvimento**: Avisos automáticos e orientações
|
|
717
|
-
- ✅ **UI Dinâmica**: Componentes se adaptam à configuração do projeto
|
|
718
|
-
- ✅ **Hooks Avançados**: `useCategories()` e `useCategoryStatus()`
|
|
719
|
-
- ✅ **Validação Automática**: Prevenção de bugs de configuração vs UI
|
|
720
|
-
|
|
721
|
-
### v0.2.7 - Compliance Avançado (Próxima Release)
|
|
722
|
-
|
|
723
|
-
**Baseado em feedback de uso real em projetos governamentais:**
|
|
724
|
-
|
|
725
|
-
- 📋 **Sistema de Logs de Auditoria**: Rastreamento completo para prestação de contas
|
|
726
|
-
- 📜 **Templates Setoriais**: Textos pré-configurados (governo, saúde, educação)
|
|
727
|
-
- 🎨 **Presets Visuais**: Identidade visual por setor (acessibilidade WCAG AAA)
|
|
728
|
-
- 📊 **Dashboard para DPOs**: Relatórios automáticos de compliance
|
|
729
|
-
- 🔌 **Mais Integrações**: Microsoft Clarity, Hotjar, Intercom, LinkedIn
|
|
730
|
-
|
|
731
|
-
### v0.3.0 - Multi-Regulamentação
|
|
732
|
-
|
|
733
|
-
- 🌍 **Suporte GDPR/CCPA**: Detecção automática por geolocalização
|
|
734
|
-
- 🏗️ **Sistema de Plugins**: Extensões de terceiros
|
|
735
|
-
- 🎭 **Temas Avançados**: Design system tokens
|
|
736
|
-
|
|
737
|
-
### v0.4.0 - Enterprise
|
|
738
|
-
|
|
739
|
-
- 📈 **Analytics Avançadas**: Dashboards completos
|
|
740
|
-
- 🔄 **Sync Multi-Domínio**: Consentimento compartilhado
|
|
741
|
-
- 🛡️ **Segurança Empresarial**: Criptografia, audit logs remotos
|
|
742
|
-
|
|
743
|
-
> 📋 **Implementado na v0.2.2**: Sistema de orientações para developers e UI dinâmica
|
|
744
|
-
|
|
745
|
-
---
|
|
746
|
-
|
|
747
|
-
<div align="center">
|
|
748
|
-
|
|
749
|
-
**Feito com ❤️ para a comunidade React brasileira**
|
|
750
|
-
|
|
751
|
-
</div>
|
|
171
|
+
Este projeto está sob a licença MIT. Veja o arquivo [LICENSE](LICENSE) para mais detalhes.
|