@graffico/legal 0.1.10 → 0.2.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/README.md CHANGED
@@ -1,138 +1,159 @@
1
- # @graffico/legal
2
-
3
- Una soluzione premium, completa e GDPR compliant per la gestione dei consensi e delle informative legali in applicazioni React/Next.js.
4
-
5
- ## Caratteristiche principali
6
-
7
- - 🛡️ **GDPR Ready**: Gestione granulare dei consensi, documentazione delle finalità e prove legali del consenso (Consent ID).
8
- - 🎨 **Premium UI**: Design moderno, pulito e altamente personalizzabile.
9
- - 🌓 **Temi Dinamici**: Supporto per modalità Dark/Light e personalizzazione del colore primario.
10
- - 🌍 **Service Presets**: Oltre 15 servizi comuni già pre-configurati.
11
-
12
- ## Servizi Supportati (Presets)
13
-
14
- Puoi aggiungere questi servizi semplicemente inserendo il loro ID nell'array `services`:
15
-
16
- - **Analytics**: `google-analytics`, `facebook-pixel`, `linkedin-insight`, `tiktok-pixel`, `microsoft-clarity`, `hotjar`, `google-tag-manager`.
17
- - **Pagamenti**: `stripe`, `paypal`.
18
- - **Contenuti**: `youtube`, `google-maps`, `google-fonts`.
19
- - **Marketing/CRM**: `mailchimp`, `newsletter`, `contact-form`.
20
-
21
- _Puoi anche definire servizi personalizzati passando un oggetto `LegalService` completo._
22
-
23
- - 📱 **Mobile First**: Layout ottimizzato per ogni dispositivo con paginazione intelligente per elenchi servizi lunghi.
24
-
25
- ## Installazione
26
-
27
- ```bash
28
- npm install @graffico/legal
29
- # oppure
30
- pnpm add @graffico/legal
31
- ```
32
-
33
- ## Guida all'uso
34
-
35
- ### 1. Configurazione
36
-
37
- Definisci i dati della tua azienda:
38
-
39
- ```tsx
40
- import { CompanyConfig } from "@graffico/legal";
41
-
42
- const legalConfig: CompanyConfig = {
43
- name: "Mia Azienda",
44
- domain: "azienda.it",
45
- owners: "Nome Proprietario",
46
- addresses: "Via Roma 1, Milano",
47
- vatNumbers: "01234567890",
48
- email: "privacy@azienda.it",
49
- services: [
50
- "google-analytics", // Preset ID
51
- "facebook-pixel", // Preset ID
52
- {
53
- id: "servizio-custom",
54
- name: "Il Mio CRM",
55
- category: "provided", // 'automatic' | 'provided' | 'marketing'
56
- purposes: ["Gestione Utenti", "Invio Newsletter"],
57
- dataCollected: ["Email", "Nome", "Dati di Navigazione"],
58
- }, // Servizio definito manualmente
59
- ],
60
- theme: "dark",
61
- primaryColor: "#2c5282",
62
- };
63
- ```
64
-
65
- ### Servizi Personalizzati
66
-
67
- La libreria è estensibile. Se un servizio non è tra i preset, puoi passare un oggetto che segue l'interfaccia `LegalService`:
68
-
69
- ```tsx
70
- const customService = {
71
- id: "crm-aziendale",
72
- name: "CRM Interno",
73
- category: "provided", // 'automatic' (tracking/pixel), 'provided' (moduli/form), 'marketing' (ADV)
74
- purposes: ["Gestione Clienti"],
75
- dataCollected: ["Email", "Nome"],
76
- };
77
- ```
78
-
79
- ### 2. Provider e Banner (Layout)
80
-
81
- Avvolgi la tua applicazione con il `LegalProvider` e aggiungi il `ConsentBanner` nel tuo layout principale.
82
-
83
- ```tsx
84
- // app/layout.tsx (Next.js App Router)
85
- import { LegalProvider, ConsentBanner } from "@graffico/legal";
86
-
87
- export default function RootLayout({ children }) {
88
- return (
89
- <html>
90
- <body>
91
- <LegalProvider config={legalConfig}>
92
- {children}
93
- <ConsentBanner />
94
- </LegalProvider>
95
- </body>
96
- </html>
97
- );
98
- }
99
- ```
100
-
101
- ### 3. Pagine Privacy e Cookie
102
-
103
- Crea le rotte per le tue informative in modo semplicissimo:
104
-
105
- ```tsx
106
- // app/privacy-policy/page.tsx
107
- import { PrivacyPolicy } from "@graffico/legal";
108
-
109
- export default function Page() {
110
- return <PrivacyPolicy />;
111
- }
112
-
113
- // app/cookie-policy/page.tsx
114
- import { CookiePolicy } from "@graffico/legal";
115
-
116
- export default function Page() {
117
- return <CookiePolicy />;
118
- }
119
- ```
120
-
121
- ## Componenti Inclusi
122
-
123
- - `LegalProvider`: Gestore dello stato dei consensi.
124
- - `ConsentBanner`: Banner iniziale per l'accettazione dei cookie.
125
- - `PreferenceModal`: Modal per la personalizzazione granulare (aperto automaticamente dal banner).
126
- - `PrivacyPolicy`: Pagina completa di Privacy Policy.
127
- - `CookiePolicy`: Pagina completa di Cookie Policy con Centro Preferenze integrato.
128
- - `ServiceGrid`: Griglia interattiva dei servizi utilizzati.
129
- - `FloatingConsentToggle`: Pulsante flottante per riaprire le preferenze (appare solo dopo il consenso).
130
-
131
- ## Requisiti
132
-
133
- - React 18+
134
- - TailwindCSS (opzionale per l'applicazione ospitante, la libreria gestisce i propri stili).
135
-
136
- ---
137
-
138
- Generato con ❤️ da **Graffico Studio**
1
+ # @graffico/legal
2
+
3
+ GDPR compliance per React/Next.js. Banner, modale preferenze, privacy & cookie policy server-rendered, oltre 15 service preset.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ pnpm add @graffico/legal
9
+ ```
10
+
11
+ ## Setup
12
+
13
+ `app/layout.tsx` — server component, **niente `"use client"`**:
14
+
15
+ ```tsx
16
+ import { LegalProvider } from "@graffico/legal/server";
17
+
18
+ const legalConfig = {
19
+ name: "Mia Azienda",
20
+ domain: "azienda.it",
21
+ owners: "Nome Proprietario",
22
+ addresses: "Via Roma 1, Milano",
23
+ vatNumbers: "01234567890",
24
+ email: "privacy@azienda.it",
25
+ services: ["google-analytics", "facebook-pixel"],
26
+ primaryColor: "#2c5282",
27
+ language: "it",
28
+ };
29
+
30
+ export default function RootLayout({ children }) {
31
+ return (
32
+ <html>
33
+ <body>
34
+ <LegalProvider config={legalConfig}>{children}</LegalProvider>
35
+ </body>
36
+ </html>
37
+ );
38
+ }
39
+ ```
40
+
41
+ `<LegalProvider>` monta automaticamente banner, modale preferenze e toggle flottante.
42
+
43
+ ## Pagine
44
+
45
+ ```tsx
46
+ // app/privacy-policy/page.tsx
47
+ import { PrivacyPolicy } from "@graffico/legal/server";
48
+ export default () => <PrivacyPolicy config={legalConfig} />;
49
+ ```
50
+
51
+ ```tsx
52
+ // app/cookie-policy/page.tsx
53
+ import { CookiePolicy } from "@graffico/legal/server";
54
+ export default () => <CookiePolicy config={legalConfig} />;
55
+ ```
56
+
57
+ ## i18n dinamico (opzionale)
58
+
59
+ Se l'app cambia lingua a runtime (es. con i18next), aggiungi un bridge:
60
+
61
+ ```tsx
62
+ // components/legal-i18n-bridge.tsx
63
+ "use client";
64
+ import { useEffect } from "react";
65
+ import { setLanguage } from "@graffico/legal";
66
+ import i18n from "@/i18n";
67
+
68
+ export function LegalI18nBridge() {
69
+ useEffect(() => {
70
+ const sync = () => setLanguage(i18n.language);
71
+ sync();
72
+ i18n.on("languageChanged", sync);
73
+ return () => i18n.off("languageChanged", sync);
74
+ }, []);
75
+ return null;
76
+ }
77
+ ```
78
+
79
+ Inseriscilo come figlio del provider:
80
+
81
+ ```tsx
82
+ <LegalProvider config={legalConfig}>
83
+ <LegalI18nBridge />
84
+ {children}
85
+ </LegalProvider>
86
+ ```
87
+
88
+ ## Service preset
89
+
90
+ Inserisci l'id come stringa nell'array `services`:
91
+
92
+ | Categoria | Preset disponibili |
93
+ |-----------|--------------------|
94
+ | Analytics | `google-analytics`, `facebook-pixel`, `linkedin-insight`, `tiktok-pixel`, `microsoft-clarity`, `hotjar`, `google-tag-manager` |
95
+ | Pagamenti | `stripe`, `paypal` |
96
+ | Contenuti | `youtube`, `google-maps`, `google-fonts` |
97
+ | Marketing | `mailchimp`, `newsletter`, `contact-form` |
98
+
99
+ Servizio custom inline:
100
+
101
+ ```tsx
102
+ {
103
+ id: "crm",
104
+ name: "CRM Interno",
105
+ category: "provided", // "automatic" | "provided" | "marketing"
106
+ purposes: ["Gestione Clienti"],
107
+ dataCollected: ["Email", "Nome"],
108
+ }
109
+ ```
110
+
111
+ ## API
112
+
113
+ ### Entry `@graffico/legal/server` (server)
114
+
115
+ | Export | Tipo |
116
+ |--------|------|
117
+ | `LegalProvider` | Wrapper root, monta context + banner |
118
+ | `PrivacyPolicy` | Pagina privacy policy |
119
+ | `CookiePolicy` | Pagina cookie policy |
120
+
121
+ ### Entry `@graffico/legal` (client)
122
+
123
+ | Export | Tipo |
124
+ |--------|------|
125
+ | `useLegalLanguage` | Lingua corrente |
126
+ | `useConsent` | Stato consenso (`{ statistical, marketing, ... }`) |
127
+ | `useShowBanner`, `useModalOpen`, `useT` | Hook UI |
128
+ | `useLegalConfig`, `useLegalConfigOptional` | Config dal context |
129
+ | `setLanguage`, `acceptAll`, `declineAll`, `savePreferences`, `resetConsent`, `setModalOpen` | Azioni store |
130
+ | `ConsentBanner`, `PreferenceModal`, `FloatingConsentToggle`, `ServiceGrid` | Componenti, già montati dal provider |
131
+ | `SERVICE_PRESETS`, `resolveService`, `DEFAULT_PRIMARY_COLOR` | Utility |
132
+
133
+ ## Configurazione
134
+
135
+ ```ts
136
+ interface CompanyConfig {
137
+ name: string;
138
+ domain: string;
139
+ owners: string;
140
+ addresses: string | string[];
141
+ vatNumbers: string | string[];
142
+ email: string;
143
+ services?: ServiceReference[];
144
+ togglePosition?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
145
+ lastUpdated?: string;
146
+ theme?: "light" | "dark";
147
+ primaryColor?: string;
148
+ language?: "it" | "en";
149
+ }
150
+ ```
151
+
152
+ ## Requisiti
153
+
154
+ - React 18+ (Next.js App Router consigliato)
155
+ - TailwindCSS opzionale; la lib usa classi Tailwind, integrazione via `content` oppure rimpiazzo con CSS proprio.
156
+
157
+ ---
158
+
159
+ Made by **Graffico Studio**.
package/dist/index.d.ts CHANGED
@@ -1,6 +1,21 @@
1
1
  import * as react_jsx_runtime from 'react/jsx-runtime';
2
2
  import { ReactNode } from 'react';
3
3
 
4
+ /**
5
+ * Banner di consenso GDPR mostrato finché l'utente non sceglie le preferenze.
6
+ */
7
+ declare const ConsentBanner: () => react_jsx_runtime.JSX.Element;
8
+
9
+ /**
10
+ * Modale per regolare in dettaglio le preferenze per categoria di tracker.
11
+ */
12
+ declare const PreferenceModal: () => react_jsx_runtime.JSX.Element | null;
13
+
14
+ /**
15
+ * Pulsante flottante che riapre il modale dopo che il consenso è stato dato.
16
+ */
17
+ declare const FloatingConsentToggle: () => react_jsx_runtime.JSX.Element | null;
18
+
4
19
  declare const TRANSLATIONS: {
5
20
  it: {
6
21
  legal: string;
@@ -121,6 +136,7 @@ declare const TRANSLATIONS: {
121
136
  contactForm: string;
122
137
  youtubeWidget: string;
123
138
  googleMapsWidget: string;
139
+ noActiveService: string;
124
140
  };
125
141
  en: {
126
142
  legal: string;
@@ -241,9 +257,13 @@ declare const TRANSLATIONS: {
241
257
  contactForm: string;
242
258
  youtubeWidget: string;
243
259
  googleMapsWidget: string;
260
+ noActiveService: string;
244
261
  };
245
262
  };
246
263
 
264
+ /**
265
+ * Tracker o servizio terzo dichiarato in cookie/privacy policy.
266
+ */
247
267
  interface LegalService {
248
268
  id: string;
249
269
  name: string;
@@ -252,8 +272,17 @@ interface LegalService {
252
272
  purposes: string[];
253
273
  dataCollected: string[];
254
274
  }
275
+ /**
276
+ * Riferimento a un servizio: id di un preset oppure servizio inline.
277
+ */
255
278
  type ServiceReference = string | LegalService;
279
+ /**
280
+ * Posizione del toggle floating per riaprire le preferenze.
281
+ */
256
282
  type TogglePosition = "bottom-right" | "bottom-left" | "top-right" | "top-left";
283
+ /**
284
+ * Configurazione del titolare e branding mostrati nelle policy.
285
+ */
257
286
  interface CompanyConfig {
258
287
  name: string;
259
288
  domain: string;
@@ -268,6 +297,9 @@ interface CompanyConfig {
268
297
  primaryColor?: string;
269
298
  language?: "it" | "en";
270
299
  }
300
+ /**
301
+ * Stato di consenso persistito per categoria, con prova legale (id + timestamp).
302
+ */
271
303
  interface ConsentState {
272
304
  necessary: boolean;
273
305
  statistical: boolean;
@@ -275,37 +307,116 @@ interface ConsentState {
275
307
  consentId?: string;
276
308
  timestamp?: string;
277
309
  }
278
- interface LegalContextType {
279
- config: CompanyConfig;
280
- consent: ConsentState;
281
- showBanner: boolean;
282
- isModalOpen: boolean;
283
- setModalOpen: (open: boolean) => void;
284
- acceptAll: () => void;
285
- declineAll: () => void;
286
- savePreferences: (prefs: ConsentState) => void;
287
- resetConsent: () => void;
288
- t: (key: keyof (typeof TRANSLATIONS)["it"]) => string;
289
- }
290
- declare const LegalProvider: ({ children, config, }: {
291
- children: ReactNode;
292
- config: CompanyConfig;
293
- }) => react_jsx_runtime.JSX.Element | null;
294
- declare const useLegal: () => LegalContextType;
310
+ /**
311
+ * Codice lingua supportato dalla libreria.
312
+ */
313
+ type Language = "it" | "en";
314
+ /**
315
+ * Chiave di traduzione disponibile in entrambe le lingue.
316
+ */
317
+ type TranslationKey = keyof (typeof TRANSLATIONS)["it"];
318
+ /**
319
+ * Funzione che risolve una chiave di traduzione nella lingua corrente.
320
+ */
321
+ type Translator = (key: TranslationKey) => string;
295
322
 
296
- declare const ConsentBanner: () => react_jsx_runtime.JSX.Element;
323
+ interface ServiceGridProps {
324
+ config?: CompanyConfig;
325
+ language?: Language;
326
+ }
327
+ /**
328
+ * Griglia paginata dei servizi terzi: divide tra dati raccolti automaticamente e forniti.
329
+ */
330
+ declare const ServiceGrid: ({ config: configProp, language: langProp, }?: ServiceGridProps) => react_jsx_runtime.JSX.Element | null;
297
331
 
298
- declare const ServiceGrid: () => react_jsx_runtime.JSX.Element;
332
+ interface Props {
333
+ language: Language;
334
+ primaryColor: string;
335
+ }
336
+ /**
337
+ * Card "centro preferenze" della cookie policy: gestisci o resetta consenso.
338
+ */
339
+ declare function PreferenceCard({ language, primaryColor }: Props): react_jsx_runtime.JSX.Element;
299
340
 
300
- declare const PreferenceModal: () => react_jsx_runtime.JSX.Element | null;
341
+ /**
342
+ * Lingua corrente normalizzata, reattiva ai cambi via bridge i18n.
343
+ */
344
+ declare const useLegalLanguage: () => Language;
345
+ /**
346
+ * Stato di consenso corrente (necessary/statistical/marketing + prova legale).
347
+ */
348
+ declare const useConsent: () => ConsentState;
349
+ /**
350
+ * Indica se il banner di consenso è da mostrare (post-hydration).
351
+ */
352
+ declare const useShowBanner: () => boolean;
353
+ /**
354
+ * Indica se il modale delle preferenze è aperto.
355
+ */
356
+ declare const useModalOpen: () => boolean;
357
+ /**
358
+ * Traduttore reattivo per la lingua corrente.
359
+ */
360
+ declare function useT(): Translator;
301
361
 
302
- declare const FloatingConsentToggle: () => react_jsx_runtime.JSX.Element | null;
303
-
304
- declare const PrivacyPolicy: () => react_jsx_runtime.JSX.Element;
362
+ /**
363
+ * Boundary client root: espone la config via context, idrata il consenso
364
+ * persistito al mount e tiene sincronizzata la lingua dello store.
365
+ */
366
+ declare function LegalConfigProvider({ config, children, }: {
367
+ config: CompanyConfig;
368
+ children: ReactNode;
369
+ }): react_jsx_runtime.JSX.Element;
370
+ /**
371
+ * Hook che legge la `CompanyConfig` dal context, errore se non avvolto.
372
+ */
373
+ declare function useLegalConfig(): CompanyConfig;
374
+ /**
375
+ * Variante non-throwing: restituisce `null` se il provider non è montato.
376
+ */
377
+ declare function useLegalConfigOptional(): CompanyConfig | null;
305
378
 
306
- declare const CookiePolicy: () => react_jsx_runtime.JSX.Element;
379
+ /**
380
+ * Aggiorna la lingua corrente normalizzando un codice arbitrario.
381
+ */
382
+ declare function setLanguage(lang: string | undefined | null): void;
383
+ /**
384
+ * Carica il consenso da localStorage al mount; mostra il banner se assente.
385
+ */
386
+ declare function hydrateFromStorage(initialLanguage?: Language): void;
387
+ /**
388
+ * Persiste le preferenze e marca prova legale (consentId + timestamp).
389
+ */
390
+ declare function savePreferences(prefs: ConsentState): void;
391
+ /**
392
+ * Accetta tutte le categorie e chiude il banner.
393
+ */
394
+ declare function acceptAll(): void;
395
+ /**
396
+ * Rifiuta tutte le categorie opzionali e chiude il banner.
397
+ */
398
+ declare function declineAll(): void;
399
+ /**
400
+ * Cancella il consenso persistito e riapre il banner iniziale.
401
+ */
402
+ declare function resetConsent(): void;
403
+ /**
404
+ * Apre o chiude il modale delle preferenze.
405
+ */
406
+ declare function setModalOpen(open: boolean): void;
307
407
 
408
+ /**
409
+ * Catalogo di servizi pre-configurati identificati per id (es. "google-analytics").
410
+ */
308
411
  declare const SERVICE_PRESETS: Record<string, LegalService>;
412
+ /**
413
+ * Risolve un riferimento (id stringa o oggetto inline) in un `LegalService` completo.
414
+ */
309
415
  declare const resolveService: (ref: string | LegalService) => LegalService;
310
416
 
311
- export { type CompanyConfig, ConsentBanner, type ConsentState, CookiePolicy, FloatingConsentToggle, LegalProvider, type LegalService, PreferenceModal, PrivacyPolicy, SERVICE_PRESETS, ServiceGrid, type ServiceReference, type TogglePosition, resolveService, useLegal };
417
+ /**
418
+ * Colore primario di default, usato quando `config.primaryColor` non è impostato.
419
+ */
420
+ declare const DEFAULT_PRIMARY_COLOR = "#2c5282";
421
+
422
+ export { type CompanyConfig, ConsentBanner, type ConsentState, DEFAULT_PRIMARY_COLOR, FloatingConsentToggle, type Language, LegalConfigProvider, type LegalService, PreferenceCard, PreferenceModal, SERVICE_PRESETS, ServiceGrid, type ServiceReference, type TogglePosition, type TranslationKey, type Translator, acceptAll, declineAll, hydrateFromStorage, resetConsent, resolveService, savePreferences, setLanguage, setModalOpen, useConsent, useLegalConfig, useLegalConfigOptional, useLegalLanguage, useModalOpen, useShowBanner, useT };