@graffico/legal 0.3.11 → 0.3.12
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/README.md +359 -341
- package/dist/index.d.ts +38 -9
- package/dist/index.js +2 -2
- package/dist/next.d.cts +12 -0
- package/dist/next.d.ts +12 -0
- package/dist/server.d.ts +12 -0
- package/dist/server.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,341 +1,359 @@
|
|
|
1
|
-
# @graffico/legal
|
|
2
|
-
|
|
3
|
-
CMP GDPR drop-in per React / Next.js. Banner + modale, policy server-rendered, **tracker terzi che caricano solo dopo consenso**, plugin Next.js per security headers.
|
|
4
|
-
|
|
5
|
-
```bash
|
|
6
|
-
pnpm add @graffico/legal
|
|
7
|
-
```
|
|
8
|
-
|
|
9
|
-
---
|
|
10
|
-
|
|
11
|
-
## 1. Setup minimo
|
|
12
|
-
|
|
13
|
-
`src/config/legal.ts`:
|
|
14
|
-
|
|
15
|
-
```ts
|
|
16
|
-
import type { CompanyConfig } from "@graffico/legal";
|
|
17
|
-
|
|
18
|
-
export const legalConfig: CompanyConfig = {
|
|
19
|
-
name: "Mia Azienda",
|
|
20
|
-
domain: "azienda.it",
|
|
21
|
-
owners: "Mario Rossi",
|
|
22
|
-
addresses: "Via Roma 1, Milano",
|
|
23
|
-
vatNumbers: "01234567890",
|
|
24
|
-
email: "privacy@azienda.it",
|
|
25
|
-
policyVersion: "2026.05", // cambiarla invalida i consensi vecchi
|
|
26
|
-
services: ["google-analytics", "facebook-pixel", "contact-form"],
|
|
27
|
-
primaryColor: "#2c5282",
|
|
28
|
-
language: "it",
|
|
29
|
-
};
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
`app/layout.tsx`:
|
|
33
|
-
|
|
34
|
-
```tsx
|
|
35
|
-
import { LegalProvider } from "@graffico/legal/server";
|
|
36
|
-
import { legalConfig } from "@/config/legal";
|
|
37
|
-
|
|
38
|
-
export default function RootLayout({ children }) {
|
|
39
|
-
return (
|
|
40
|
-
<html>
|
|
41
|
-
<body>
|
|
42
|
-
<LegalProvider config={legalConfig}>{children}</LegalProvider>
|
|
43
|
-
</body>
|
|
44
|
-
</html>
|
|
45
|
-
);
|
|
46
|
-
}
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
`<LegalProvider>` monta automaticamente banner + modale + floating toggle.
|
|
50
|
-
|
|
51
|
-
### Tailwind / globals.css
|
|
52
|
-
|
|
53
|
-
La libreria usa Tailwind utility classes inline (niente CSS bundle). Devi dire al JIT di Tailwind di scansionare i file della libreria, altrimenti banner e modale appariranno senza stili.
|
|
54
|
-
|
|
55
|
-
**Tailwind v4** — aggiungi una direttiva `@source` in `src/app/globals.css` (o equivalente):
|
|
56
|
-
|
|
57
|
-
```css
|
|
58
|
-
@import "tailwindcss";
|
|
59
|
-
@source "../../node_modules/@graffico/legal/dist/**/*.{js,cjs}";
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
> Il path `../../` parte da `src/app/`. Se il tuo `globals.css` sta altrove, regola la profondità relativa. In monorepo con workspace, il dist è raggiungibile via `node_modules` simlink.
|
|
63
|
-
|
|
64
|
-
**Tailwind v3** — aggiungi al `tailwind.config.js`:
|
|
65
|
-
|
|
66
|
-
```js
|
|
67
|
-
module.exports = {
|
|
68
|
-
content: [
|
|
69
|
-
"./src/**/*.{js,ts,jsx,tsx}",
|
|
70
|
-
"./node_modules/@graffico/legal/dist/**/*.{js,cjs}",
|
|
71
|
-
],
|
|
72
|
-
};
|
|
73
|
-
```
|
|
74
|
-
|
|
75
|
-
---
|
|
76
|
-
|
|
77
|
-
## 2. Tracker — drop-in con consenso integrato
|
|
78
|
-
|
|
79
|
-
Importi il componente Legal, passi le API key. Lo script parte **solo dopo consenso**.
|
|
80
|
-
|
|
81
|
-
```tsx
|
|
82
|
-
import {
|
|
83
|
-
ConsentModeBoot,
|
|
84
|
-
GoogleAnalyticsLegal,
|
|
85
|
-
GoogleAdsLegal,
|
|
86
|
-
MetaPixelLegal,
|
|
87
|
-
HotjarLegal,
|
|
88
|
-
GTMLegal,
|
|
89
|
-
EmailJSLegal,
|
|
90
|
-
} from "@graffico/legal";
|
|
91
|
-
|
|
92
|
-
<LegalProvider config={legalConfig}>
|
|
93
|
-
<ConsentModeBoot /> {/* Google Consent Mode v2 default = denied */}
|
|
94
|
-
<GoogleAnalyticsLegal gaId="G-XXXX" />
|
|
95
|
-
<GoogleAdsLegal
|
|
96
|
-
conversionId="AW-XXXX"
|
|
97
|
-
conversions={{ formSubmit: { sendTo: "AW-XXXX/abc", value: 1, currency: "EUR" } }}
|
|
98
|
-
/>
|
|
99
|
-
<MetaPixelLegal pixelId="123456" events={["Lead", "Contact"]} />
|
|
100
|
-
<HotjarLegal siteId={1234567} />
|
|
101
|
-
<EmailJSLegal
|
|
102
|
-
serviceId={process.env.NEXT_PUBLIC_EMAILJS_SERVICE_ID!}
|
|
103
|
-
templateId={process.env.NEXT_PUBLIC_EMAILJS_TEMPLATE_ID!}
|
|
104
|
-
publicKey={process.env.NEXT_PUBLIC_EMAILJS_USER_ID!}
|
|
105
|
-
/>
|
|
106
|
-
{children}
|
|
107
|
-
</LegalProvider>
|
|
108
|
-
```
|
|
109
|
-
|
|
110
|
-
| Componente | Categoria default | Script gated | Note |
|
|
111
|
-
|---|---|---|---|
|
|
112
|
-
| `ConsentModeBoot` | — | — | Boot gtag stub + Consent Mode v2. **Sempre per primo.** |
|
|
113
|
-
| `GoogleAnalyticsLegal` | `statistical` | `gtag/js?id=G-…` | Anonymize IP on di default. |
|
|
114
|
-
| `GoogleAdsLegal` | `marketing` | `gtag/js?id=AW-…` | Mappa conversioni dichiarativa. |
|
|
115
|
-
| `MetaPixelLegal` | `marketing` | `fbevents.js` | Whitelist `events` opzionale. Su revoca → `fbq('consent','revoke')`. |
|
|
116
|
-
| `HotjarLegal` | `statistical` | `static.hotjar.com/c/hotjar-…` | Session recording + heatmap. |
|
|
117
|
-
| `GTMLegal` | `marketing` | `gtm.js?id=GTM-…` | Lascia ai tag interni la granularità. |
|
|
118
|
-
| `EmailJSLegal` | — (art. 6.1.b) | — | Config holder per `useEmailJS()`. |
|
|
119
|
-
|
|
120
|
-
---
|
|
121
|
-
|
|
122
|
-
## 3. Hook trigger eventi
|
|
123
|
-
|
|
124
|
-
Nei tuoi componenti `"use client"`:
|
|
125
|
-
|
|
126
|
-
```tsx
|
|
127
|
-
import { useGAEvent, useMetaEvent, useAdsConversion, useHotjarEvent } from "@graffico/legal";
|
|
128
|
-
|
|
129
|
-
const trackGA = useGAEvent();
|
|
130
|
-
const trackLead = useMetaEvent("Lead");
|
|
131
|
-
const fireConversion = useAdsConversion("formSubmit");
|
|
132
|
-
const trackHj = useHotjarEvent();
|
|
133
|
-
|
|
134
|
-
// Tutti diventano no-op senza consenso — chiama liberamente
|
|
135
|
-
trackGA("button_click", { id: "hero" });
|
|
136
|
-
trackLead({ value: 99, currency: "EUR" });
|
|
137
|
-
fireConversion();
|
|
138
|
-
trackHj("scroll_to_pricing");
|
|
139
|
-
```
|
|
140
|
-
|
|
141
|
-
---
|
|
142
|
-
|
|
143
|
-
## 4. Form contatto con consenso
|
|
144
|
-
|
|
145
|
-
```tsx
|
|
146
|
-
"use client";
|
|
147
|
-
import { useEmailJS, ConsentCheckbox } from "@graffico/legal";
|
|
148
|
-
|
|
149
|
-
export function ContactForm() {
|
|
150
|
-
const { send, status } = useEmailJS();
|
|
151
|
-
|
|
152
|
-
async function onSubmit(e: React.FormEvent<HTMLFormElement>) {
|
|
153
|
-
e.preventDefault();
|
|
154
|
-
const res = await send(e.currentTarget);
|
|
155
|
-
if (!res.ok) console.warn(res.error); // CONSENT_MISSING | CONFIG_MISSING | SEND_FAILED
|
|
156
|
-
}
|
|
157
|
-
|
|
158
|
-
return (
|
|
159
|
-
<form onSubmit={onSubmit}>
|
|
160
|
-
<input name="name" required />
|
|
161
|
-
<input name="email" type="email" required />
|
|
162
|
-
<textarea name="message" required />
|
|
163
|
-
<ConsentCheckbox /> {/* obbligatorio: blocca submit se non spuntato */}
|
|
164
|
-
<button disabled={status === "loading"}>Invia</button>
|
|
165
|
-
</form>
|
|
166
|
-
);
|
|
167
|
-
}
|
|
168
|
-
```
|
|
169
|
-
|
|
170
|
-
`send()` inietta automaticamente nel payload mail: `_consentId`, `_consentTimestamp`, `_policyVersion` (prova legale art. 7.1).
|
|
171
|
-
|
|
172
|
-
---
|
|
173
|
-
|
|
174
|
-
## 5. Pagine policy
|
|
175
|
-
|
|
176
|
-
Auto-renderizzate dalla config — incluse sezioni Processors / Transfers / Retention / DPO se valorizzati.
|
|
177
|
-
|
|
178
|
-
```tsx
|
|
179
|
-
// app/privacy-policy/page.tsx
|
|
180
|
-
import { PrivacyPolicy } from "@graffico/legal/server";
|
|
181
|
-
import { legalConfig } from "@/config/legal";
|
|
182
|
-
export default () => <PrivacyPolicy config={legalConfig} />;
|
|
183
|
-
|
|
184
|
-
// app/cookie-policy/page.tsx
|
|
185
|
-
import { CookiePolicy } from "@graffico/legal/server";
|
|
186
|
-
export default () => <CookiePolicy config={legalConfig} />;
|
|
187
|
-
```
|
|
188
|
-
|
|
189
|
-
---
|
|
190
|
-
|
|
191
|
-
## 6. Gate per embed terzi
|
|
192
|
-
|
|
193
|
-
```tsx
|
|
194
|
-
import { ConsentGate, useConsentCategory } from "@graffico/legal";
|
|
195
|
-
|
|
196
|
-
<ConsentGate
|
|
197
|
-
category="marketing"
|
|
198
|
-
fallback={<p>Abilita cookie marketing per vedere il video.</p>}
|
|
199
|
-
>
|
|
200
|
-
<iframe src="https://youtube.com/embed/…" />
|
|
201
|
-
</ConsentGate>
|
|
202
|
-
```
|
|
203
|
-
|
|
204
|
-
---
|
|
205
|
-
|
|
206
|
-
## 7. Next.js plugin — security headers
|
|
207
|
-
|
|
208
|
-
CSP derivata dai `services[]` + `processors[]`. HSTS, X-Frame, Permissions-Policy, COOP, Referrer-Policy.
|
|
209
|
-
|
|
210
|
-
```ts
|
|
211
|
-
// next.config.ts
|
|
212
|
-
import { withLegal } from "@graffico/legal/next";
|
|
213
|
-
import { legalConfig } from "@/config/legal";
|
|
214
|
-
|
|
215
|
-
const nextConfig = { /* … */ };
|
|
216
|
-
|
|
217
|
-
export default withLegal(nextConfig, legalConfig, {
|
|
218
|
-
cspReportOnly: process.env.CSP_ENFORCE !== "1", // rollout: 7gg report-only → enforce
|
|
219
|
-
});
|
|
220
|
-
```
|
|
221
|
-
|
|
222
|
-
Per `netlify.toml`:
|
|
223
|
-
|
|
224
|
-
```ts
|
|
225
|
-
import { emitNetlifyHeaders } from "@graffico/legal/next";
|
|
226
|
-
console.log(emitNetlifyHeaders(legalConfig));
|
|
227
|
-
```
|
|
228
|
-
|
|
229
|
-
---
|
|
230
|
-
|
|
231
|
-
## 8. `CompanyConfig`
|
|
232
|
-
|
|
233
|
-
```ts
|
|
234
|
-
interface CompanyConfig {
|
|
235
|
-
name: string;
|
|
236
|
-
domain: string;
|
|
237
|
-
owners: string;
|
|
238
|
-
addresses: string | string[];
|
|
239
|
-
vatNumbers: string | string[];
|
|
240
|
-
email: string;
|
|
241
|
-
|
|
242
|
-
policyVersion?: string; // cambiarla invalida i consensi pregressi
|
|
243
|
-
lastUpdated?: string; // ISO date, default oggi
|
|
244
|
-
|
|
245
|
-
services?: ServiceReference[]; // tracker dichiarati (preset id o oggetto)
|
|
246
|
-
processors?: Processor[]; // destinatari/responsabili esterni
|
|
247
|
-
retention?: RetentionMap; // tempi di conservazione per categoria
|
|
248
|
-
dpo?: DpoInfo; // se nominato (art. 37 GDPR)
|
|
249
|
-
|
|
250
|
-
theme?: "light" | "dark";
|
|
251
|
-
primaryColor?: string;
|
|
252
|
-
language?: "it" | "en";
|
|
253
|
-
togglePosition?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
|
|
254
|
-
}
|
|
255
|
-
|
|
256
|
-
interface Processor {
|
|
257
|
-
name: string;
|
|
258
|
-
purpose: string;
|
|
259
|
-
country: string;
|
|
260
|
-
transferBasis?: string; // "DPF + SCC 2021/914", "SCC", …
|
|
261
|
-
privacyUrl?: string;
|
|
262
|
-
}
|
|
263
|
-
|
|
264
|
-
interface RetentionMap {
|
|
265
|
-
contactForms?: string; // "90d"
|
|
266
|
-
analytics?: string; // "14m"
|
|
267
|
-
marketing?: string; // "2y"
|
|
268
|
-
[k: string]: string | undefined;
|
|
269
|
-
}
|
|
270
|
-
|
|
271
|
-
interface DpoInfo {
|
|
272
|
-
name: string;
|
|
273
|
-
email: string;
|
|
274
|
-
phone?: string;
|
|
275
|
-
}
|
|
276
|
-
```
|
|
277
|
-
|
|
278
|
-
---
|
|
279
|
-
|
|
280
|
-
## 9. Conformità GDPR / ePrivacy — cosa fa già la lib
|
|
281
|
-
|
|
282
|
-
- **TTL consenso 180 giorni** (`CONSENT_TTL_MS`), allineato al Garante 10/06/2021. Scaduto → re-prompt.
|
|
283
|
-
- **Re-prompt automatico** al cambio `policyVersion`.
|
|
284
|
-
- **Auto-decline su GPC / DNT** (`navigator.globalPrivacyControl`, `Sec-GPC`) senza UI.
|
|
285
|
-
- **Prova legale**: `consentId` UUID + `timestamp` ISO + `policyVersion` + `source` in localStorage e nel payload mail.
|
|
286
|
-
- **Parità grafica reject/accept** nel banner (Garante 10/06/2021 §4).
|
|
287
|
-
- **Categorie indipendenti**: `necessary` / `statistical` / `marketing`. Default OFF.
|
|
288
|
-
- **
|
|
289
|
-
- **
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
|
298
|
-
|
|
299
|
-
|
|
|
300
|
-
|
|
|
301
|
-
|
|
|
302
|
-
|
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
-
|
|
336
|
-
-
|
|
337
|
-
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
1
|
+
# @graffico/legal
|
|
2
|
+
|
|
3
|
+
CMP GDPR drop-in per React / Next.js. Banner + modale, policy server-rendered, **tracker terzi che caricano solo dopo consenso**, plugin Next.js per security headers.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
pnpm add @graffico/legal
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## 1. Setup minimo
|
|
12
|
+
|
|
13
|
+
`src/config/legal.ts`:
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
import type { CompanyConfig } from "@graffico/legal";
|
|
17
|
+
|
|
18
|
+
export const legalConfig: CompanyConfig = {
|
|
19
|
+
name: "Mia Azienda",
|
|
20
|
+
domain: "azienda.it",
|
|
21
|
+
owners: "Mario Rossi",
|
|
22
|
+
addresses: "Via Roma 1, Milano",
|
|
23
|
+
vatNumbers: "01234567890",
|
|
24
|
+
email: "privacy@azienda.it",
|
|
25
|
+
policyVersion: "2026.05", // cambiarla invalida i consensi vecchi
|
|
26
|
+
services: ["google-analytics", "facebook-pixel", "contact-form"],
|
|
27
|
+
primaryColor: "#2c5282",
|
|
28
|
+
language: "it",
|
|
29
|
+
};
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
`app/layout.tsx`:
|
|
33
|
+
|
|
34
|
+
```tsx
|
|
35
|
+
import { LegalProvider } from "@graffico/legal/server";
|
|
36
|
+
import { legalConfig } from "@/config/legal";
|
|
37
|
+
|
|
38
|
+
export default function RootLayout({ children }) {
|
|
39
|
+
return (
|
|
40
|
+
<html>
|
|
41
|
+
<body>
|
|
42
|
+
<LegalProvider config={legalConfig}>{children}</LegalProvider>
|
|
43
|
+
</body>
|
|
44
|
+
</html>
|
|
45
|
+
);
|
|
46
|
+
}
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
`<LegalProvider>` monta automaticamente banner + modale + floating toggle.
|
|
50
|
+
|
|
51
|
+
### Tailwind / globals.css
|
|
52
|
+
|
|
53
|
+
La libreria usa Tailwind utility classes inline (niente CSS bundle). Devi dire al JIT di Tailwind di scansionare i file della libreria, altrimenti banner e modale appariranno senza stili.
|
|
54
|
+
|
|
55
|
+
**Tailwind v4** — aggiungi una direttiva `@source` in `src/app/globals.css` (o equivalente):
|
|
56
|
+
|
|
57
|
+
```css
|
|
58
|
+
@import "tailwindcss";
|
|
59
|
+
@source "../../node_modules/@graffico/legal/dist/**/*.{js,cjs}";
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
> Il path `../../` parte da `src/app/`. Se il tuo `globals.css` sta altrove, regola la profondità relativa. In monorepo con workspace, il dist è raggiungibile via `node_modules` simlink.
|
|
63
|
+
|
|
64
|
+
**Tailwind v3** — aggiungi al `tailwind.config.js`:
|
|
65
|
+
|
|
66
|
+
```js
|
|
67
|
+
module.exports = {
|
|
68
|
+
content: [
|
|
69
|
+
"./src/**/*.{js,ts,jsx,tsx}",
|
|
70
|
+
"./node_modules/@graffico/legal/dist/**/*.{js,cjs}",
|
|
71
|
+
],
|
|
72
|
+
};
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
## 2. Tracker — drop-in con consenso integrato
|
|
78
|
+
|
|
79
|
+
Importi il componente Legal, passi le API key. Lo script parte **solo dopo consenso**.
|
|
80
|
+
|
|
81
|
+
```tsx
|
|
82
|
+
import {
|
|
83
|
+
ConsentModeBoot,
|
|
84
|
+
GoogleAnalyticsLegal,
|
|
85
|
+
GoogleAdsLegal,
|
|
86
|
+
MetaPixelLegal,
|
|
87
|
+
HotjarLegal,
|
|
88
|
+
GTMLegal,
|
|
89
|
+
EmailJSLegal,
|
|
90
|
+
} from "@graffico/legal";
|
|
91
|
+
|
|
92
|
+
<LegalProvider config={legalConfig}>
|
|
93
|
+
<ConsentModeBoot /> {/* Google Consent Mode v2 default = denied */}
|
|
94
|
+
<GoogleAnalyticsLegal gaId="G-XXXX" />
|
|
95
|
+
<GoogleAdsLegal
|
|
96
|
+
conversionId="AW-XXXX"
|
|
97
|
+
conversions={{ formSubmit: { sendTo: "AW-XXXX/abc", value: 1, currency: "EUR" } }}
|
|
98
|
+
/>
|
|
99
|
+
<MetaPixelLegal pixelId="123456" events={["Lead", "Contact"]} />
|
|
100
|
+
<HotjarLegal siteId={1234567} />
|
|
101
|
+
<EmailJSLegal
|
|
102
|
+
serviceId={process.env.NEXT_PUBLIC_EMAILJS_SERVICE_ID!}
|
|
103
|
+
templateId={process.env.NEXT_PUBLIC_EMAILJS_TEMPLATE_ID!}
|
|
104
|
+
publicKey={process.env.NEXT_PUBLIC_EMAILJS_USER_ID!}
|
|
105
|
+
/>
|
|
106
|
+
{children}
|
|
107
|
+
</LegalProvider>
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
| Componente | Categoria default | Script gated | Note |
|
|
111
|
+
|---|---|---|---|
|
|
112
|
+
| `ConsentModeBoot` | — | — | Boot gtag stub + Consent Mode v2. **Sempre per primo.** |
|
|
113
|
+
| `GoogleAnalyticsLegal` | `statistical` | `gtag/js?id=G-…` | Anonymize IP on di default. |
|
|
114
|
+
| `GoogleAdsLegal` | `marketing` | `gtag/js?id=AW-…` | Mappa conversioni dichiarativa. |
|
|
115
|
+
| `MetaPixelLegal` | `marketing` | `fbevents.js` | Whitelist `events` opzionale. Su revoca → `fbq('consent','revoke')`. |
|
|
116
|
+
| `HotjarLegal` | `statistical` | `static.hotjar.com/c/hotjar-…` | Session recording + heatmap. |
|
|
117
|
+
| `GTMLegal` | `marketing` | `gtm.js?id=GTM-…` | Lascia ai tag interni la granularità. |
|
|
118
|
+
| `EmailJSLegal` | — (art. 6.1.b) | — | Config holder per `useEmailJS()`. |
|
|
119
|
+
|
|
120
|
+
---
|
|
121
|
+
|
|
122
|
+
## 3. Hook trigger eventi
|
|
123
|
+
|
|
124
|
+
Nei tuoi componenti `"use client"`:
|
|
125
|
+
|
|
126
|
+
```tsx
|
|
127
|
+
import { useGAEvent, useMetaEvent, useAdsConversion, useHotjarEvent } from "@graffico/legal";
|
|
128
|
+
|
|
129
|
+
const trackGA = useGAEvent();
|
|
130
|
+
const trackLead = useMetaEvent("Lead");
|
|
131
|
+
const fireConversion = useAdsConversion("formSubmit");
|
|
132
|
+
const trackHj = useHotjarEvent();
|
|
133
|
+
|
|
134
|
+
// Tutti diventano no-op senza consenso — chiama liberamente
|
|
135
|
+
trackGA("button_click", { id: "hero" });
|
|
136
|
+
trackLead({ value: 99, currency: "EUR" });
|
|
137
|
+
fireConversion();
|
|
138
|
+
trackHj("scroll_to_pricing");
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
---
|
|
142
|
+
|
|
143
|
+
## 4. Form contatto con consenso
|
|
144
|
+
|
|
145
|
+
```tsx
|
|
146
|
+
"use client";
|
|
147
|
+
import { useEmailJS, ConsentCheckbox } from "@graffico/legal";
|
|
148
|
+
|
|
149
|
+
export function ContactForm() {
|
|
150
|
+
const { send, status } = useEmailJS();
|
|
151
|
+
|
|
152
|
+
async function onSubmit(e: React.FormEvent<HTMLFormElement>) {
|
|
153
|
+
e.preventDefault();
|
|
154
|
+
const res = await send(e.currentTarget);
|
|
155
|
+
if (!res.ok) console.warn(res.error); // CONSENT_MISSING | CONFIG_MISSING | SEND_FAILED
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
return (
|
|
159
|
+
<form onSubmit={onSubmit}>
|
|
160
|
+
<input name="name" required />
|
|
161
|
+
<input name="email" type="email" required />
|
|
162
|
+
<textarea name="message" required />
|
|
163
|
+
<ConsentCheckbox /> {/* obbligatorio: blocca submit se non spuntato */}
|
|
164
|
+
<button disabled={status === "loading"}>Invia</button>
|
|
165
|
+
</form>
|
|
166
|
+
);
|
|
167
|
+
}
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
`send()` inietta automaticamente nel payload mail: `_consentId`, `_consentTimestamp`, `_policyVersion` (prova legale art. 7.1).
|
|
171
|
+
|
|
172
|
+
---
|
|
173
|
+
|
|
174
|
+
## 5. Pagine policy
|
|
175
|
+
|
|
176
|
+
Auto-renderizzate dalla config — incluse sezioni Processors / Transfers / Retention / DPO se valorizzati.
|
|
177
|
+
|
|
178
|
+
```tsx
|
|
179
|
+
// app/privacy-policy/page.tsx
|
|
180
|
+
import { PrivacyPolicy } from "@graffico/legal/server";
|
|
181
|
+
import { legalConfig } from "@/config/legal";
|
|
182
|
+
export default () => <PrivacyPolicy config={legalConfig} />;
|
|
183
|
+
|
|
184
|
+
// app/cookie-policy/page.tsx
|
|
185
|
+
import { CookiePolicy } from "@graffico/legal/server";
|
|
186
|
+
export default () => <CookiePolicy config={legalConfig} />;
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
---
|
|
190
|
+
|
|
191
|
+
## 6. Gate per embed terzi
|
|
192
|
+
|
|
193
|
+
```tsx
|
|
194
|
+
import { ConsentGate, useConsentCategory } from "@graffico/legal";
|
|
195
|
+
|
|
196
|
+
<ConsentGate
|
|
197
|
+
category="marketing"
|
|
198
|
+
fallback={<p>Abilita cookie marketing per vedere il video.</p>}
|
|
199
|
+
>
|
|
200
|
+
<iframe src="https://youtube.com/embed/…" />
|
|
201
|
+
</ConsentGate>
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
---
|
|
205
|
+
|
|
206
|
+
## 7. Next.js plugin — security headers
|
|
207
|
+
|
|
208
|
+
CSP derivata dai `services[]` + `processors[]`. HSTS, X-Frame, Permissions-Policy, COOP, Referrer-Policy.
|
|
209
|
+
|
|
210
|
+
```ts
|
|
211
|
+
// next.config.ts
|
|
212
|
+
import { withLegal } from "@graffico/legal/next";
|
|
213
|
+
import { legalConfig } from "@/config/legal";
|
|
214
|
+
|
|
215
|
+
const nextConfig = { /* … */ };
|
|
216
|
+
|
|
217
|
+
export default withLegal(nextConfig, legalConfig, {
|
|
218
|
+
cspReportOnly: process.env.CSP_ENFORCE !== "1", // rollout: 7gg report-only → enforce
|
|
219
|
+
});
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
Per `netlify.toml`:
|
|
223
|
+
|
|
224
|
+
```ts
|
|
225
|
+
import { emitNetlifyHeaders } from "@graffico/legal/next";
|
|
226
|
+
console.log(emitNetlifyHeaders(legalConfig));
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
---
|
|
230
|
+
|
|
231
|
+
## 8. `CompanyConfig`
|
|
232
|
+
|
|
233
|
+
```ts
|
|
234
|
+
interface CompanyConfig {
|
|
235
|
+
name: string;
|
|
236
|
+
domain: string;
|
|
237
|
+
owners: string;
|
|
238
|
+
addresses: string | string[];
|
|
239
|
+
vatNumbers: string | string[];
|
|
240
|
+
email: string;
|
|
241
|
+
|
|
242
|
+
policyVersion?: string; // cambiarla invalida i consensi pregressi
|
|
243
|
+
lastUpdated?: string; // ISO date, default oggi
|
|
244
|
+
|
|
245
|
+
services?: ServiceReference[]; // tracker dichiarati (preset id o oggetto), guidano anche il testo del banner
|
|
246
|
+
processors?: Processor[]; // destinatari/responsabili esterni
|
|
247
|
+
retention?: RetentionMap; // tempi di conservazione per categoria
|
|
248
|
+
dpo?: DpoInfo; // se nominato (art. 37 GDPR)
|
|
249
|
+
|
|
250
|
+
theme?: "light" | "dark";
|
|
251
|
+
primaryColor?: string;
|
|
252
|
+
language?: "it" | "en";
|
|
253
|
+
togglePosition?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
interface Processor {
|
|
257
|
+
name: string;
|
|
258
|
+
purpose: string;
|
|
259
|
+
country: string;
|
|
260
|
+
transferBasis?: string; // "DPF + SCC 2021/914", "SCC", …
|
|
261
|
+
privacyUrl?: string;
|
|
262
|
+
}
|
|
263
|
+
|
|
264
|
+
interface RetentionMap {
|
|
265
|
+
contactForms?: string; // "90d"
|
|
266
|
+
analytics?: string; // "14m"
|
|
267
|
+
marketing?: string; // "2y"
|
|
268
|
+
[k: string]: string | undefined;
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
interface DpoInfo {
|
|
272
|
+
name: string;
|
|
273
|
+
email: string;
|
|
274
|
+
phone?: string;
|
|
275
|
+
}
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
---
|
|
279
|
+
|
|
280
|
+
## 9. Conformità GDPR / ePrivacy — cosa fa già la lib
|
|
281
|
+
|
|
282
|
+
- **TTL consenso 180 giorni** (`CONSENT_TTL_MS`), allineato al Garante 10/06/2021. Scaduto → re-prompt.
|
|
283
|
+
- **Re-prompt automatico** al cambio `policyVersion`.
|
|
284
|
+
- **Auto-decline su GPC / DNT** (`navigator.globalPrivacyControl`, `Sec-GPC`) senza UI.
|
|
285
|
+
- **Prova legale**: `consentId` UUID + `timestamp` ISO + `policyVersion` + `source` in localStorage e nel payload mail.
|
|
286
|
+
- **Parità grafica reject/accept** nel banner (Garante 10/06/2021 §4).
|
|
287
|
+
- **Categorie indipendenti**: `necessary` / `statistical` / `marketing`. Default OFF.
|
|
288
|
+
- **Finalità reali nel banner e nella cookie policy**: citano misurazione e/o marketing e profilazione solo se in uso, dedotti da `services[]` e dai tracker `*Legal` / `ConsentGate` montati. Senza `services[]` resta il testo generico (misurazione).
|
|
289
|
+
- **Modale accessibile** (WCAG 2.1 livello A): dialog con focus gestito, Tab confinato, `Esc` chiude senza salvare, interruttori `role="switch"` usabili da tastiera.
|
|
290
|
+
- **Niente cookie wall**: il sito resta fruibile senza consenso.
|
|
291
|
+
- **Zero telemetria** della libreria stessa.
|
|
292
|
+
|
|
293
|
+
---
|
|
294
|
+
|
|
295
|
+
## 10. Service preset (id stringa per `services[]`)
|
|
296
|
+
|
|
297
|
+
| Categoria | Id |
|
|
298
|
+
|---|---|
|
|
299
|
+
| Analytics | `google-analytics`, `microsoft-clarity`, `hotjar` |
|
|
300
|
+
| Marketing | `facebook-pixel`, `google-ads`, `linkedin-insight`, `tiktok-pixel` |
|
|
301
|
+
| Tag manager | `google-tag-manager` |
|
|
302
|
+
| Pagamenti | `stripe`, `paypal` |
|
|
303
|
+
| Contenuti | `youtube`, `google-maps`, `google-fonts` |
|
|
304
|
+
| Form / mail | `contact-form`, `mailchimp`, `newsletter` |
|
|
305
|
+
|
|
306
|
+
Servizio inline custom:
|
|
307
|
+
|
|
308
|
+
```ts
|
|
309
|
+
{
|
|
310
|
+
id: "crm",
|
|
311
|
+
name: "CRM Interno",
|
|
312
|
+
category: "provided", // "automatic" | "provided" | "marketing"
|
|
313
|
+
consentCategory: "necessary", // "necessary" | "statistical" | "marketing"
|
|
314
|
+
purposes: ["Gestione clienti"],
|
|
315
|
+
dataCollected: ["Email", "Nome"],
|
|
316
|
+
}
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
`consentCategory` è la categoria del banner che abilita il servizio e decide quali finalità citano banner e cookie policy (`necessary` = nessun consenso da banner). Se manca viene dedotta da `cookies[].type` e `lawfulBasis`; se non è deducibile il banner resta sul testo generico.
|
|
320
|
+
|
|
321
|
+
`google-tag-manager` è `marketing` perché `GTMLegal` parte col consenso marketing. Se il container carica solo statistiche:
|
|
322
|
+
|
|
323
|
+
```tsx
|
|
324
|
+
services: [{ ...SERVICE_PRESETS["google-tag-manager"], consentCategory: "statistical" }]
|
|
325
|
+
<GTMLegal containerId="GTM-XXXX" category="statistical" />
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
---
|
|
329
|
+
|
|
330
|
+
## 11. API export
|
|
331
|
+
|
|
332
|
+
**`@graffico/legal/server`** — `LegalProvider`, `PrivacyPolicy`, `CookiePolicy`.
|
|
333
|
+
|
|
334
|
+
**`@graffico/legal`** (client) —
|
|
335
|
+
- Tracker: `ConsentModeBoot`, `GoogleAnalyticsLegal`, `GoogleAdsLegal`, `MetaPixelLegal`, `HotjarLegal`, `GTMLegal`, `EmailJSLegal`
|
|
336
|
+
- Hook: `useConsent`, `useConsentCategory`, `useIsHydrated`, `useGAEvent`, `useAdsConversion`, `useMetaEvent`, `useHotjarEvent`, `useHotjarIdentify`, `useEmailJS`, `useT`, `useLegalLanguage`
|
|
337
|
+
- UI: `ConsentBanner`, `PreferenceModal`, `FloatingConsentToggle`, `ConsentGate`, `ConsentCheckbox`, `ServiceGrid`
|
|
338
|
+
- Azioni: `acceptAll`, `declineAll`, `savePreferences`, `resetConsent`, `setModalOpen`, `setLanguage`
|
|
339
|
+
- Primitive: `subscribeConsent`, `getConsentSnapshot`, `CONSENT_TTL_MS`, `SERVICE_PRESETS`
|
|
340
|
+
|
|
341
|
+
**`@graffico/legal/next`** — `withLegal`, `emitNetlifyHeaders`, `buildLegalHeaders`, `buildCspFromConfig`.
|
|
342
|
+
|
|
343
|
+
---
|
|
344
|
+
|
|
345
|
+
## Aggiornare un sito già online
|
|
346
|
+
|
|
347
|
+
Il banner ora cita le finalità reali del sito. Se il sito dichiara `facebook-pixel`, `linkedin-insight`, `tiktok-pixel`, `google-ads`, `google-tag-manager`, `youtube` o `google-maps`, il testo passa da «misurazione» a «(misurazione,) marketing e profilazione»: chi ha cliccato «Accetta» col vecchio testo ha dato il consenso al marketing senza che il banner lo citasse. Insieme all'aggiornamento cambia `policyVersion` nella config del sito (es. `"2026.09"`) e aggiorna `lastUpdated`, così il banner viene riproposto e il consenso raccolto di nuovo. Sugli altri siti non serve.
|
|
348
|
+
|
|
349
|
+
---
|
|
350
|
+
|
|
351
|
+
## Requisiti
|
|
352
|
+
|
|
353
|
+
- React ≥ 18 (App Router consigliato)
|
|
354
|
+
- Tailwind opzionale (la UI usa classi Tailwind)
|
|
355
|
+
- `@emailjs/browser` ≥ 4 — peer optional, solo se usi `EmailJSLegal`
|
|
356
|
+
|
|
357
|
+
---
|
|
358
|
+
|
|
359
|
+
Made by **Graffico Studio**.
|