react-lgpd-consent 0.2.2 → 0.2.3

package/dist/{PreferencesModal-UL552BFP.js → PreferencesModal-UMNANMVX.js}

@@ -1,6 +1,6 @@
 import {
   PreferencesModal
-} from "./chunk-JAX63PBG.js";
+} from "./chunk-E763JXNL.js";
 export {
   PreferencesModal
 };

package/dist/{chunk-JAX63PBG.js → chunk-E763JXNL.js}

@@ -113,33 +113,63 @@ function analyzeDeveloperConfiguration(config) {
   return guidance;
 }
 function logDeveloperGuidance(guidance) {
-  const isProduction = typeof globalThis !== "undefined" && globalThis.__LGPD_PRODUCTION__ || typeof window !== "undefined" && !window.__LGPD_DEV__;
-  if (isProduction) return;
-  if (guidance.warnings.length > 0) {
-    console.group("\u{1F7E8} LGPD-CONSENT: Avisos de Configura\xE7\xE3o");
-    guidance.warnings.forEach((warning) => console.warn(warning));
-    console.groupEnd();
-  }
-  if (guidance.suggestions.length > 0) {
-    console.group("\u{1F4A1} LGPD-CONSENT: Sugest\xF5es");
-    guidance.suggestions.forEach((suggestion) => console.info(suggestion));
-    console.groupEnd();
-  }
-  if (guidance.usingDefaults) {
+  try {
+    const isProduction = (
+      // 1. NODE_ENV de bundlers (Vite, webpack, etc.)
+      typeof globalThis.process !== "undefined" && globalThis.process.env?.NODE_ENV === "production" || // 2. Vite/bundler env vars (apenas em ESM)
+      typeof globalThis !== "undefined" && typeof globalThis.import !== "undefined" && globalThis.import.meta?.env?.PROD === true || // 3. Flag customizada para desabilitar logs
+      typeof globalThis !== "undefined" && globalThis.__LGPD_PRODUCTION__ || // 4. Flag de desenvolvimento desabilitada
+      typeof window !== "undefined" && window.__LGPD_DISABLE_GUIDANCE__
+    );
+    if (isProduction) return;
+    const PREFIX = "[\u{1F36A} LGPD-CONSENT]";
+    if (guidance.warnings.length > 0) {
+      console.group(`${PREFIX} \u26A0\uFE0F  Avisos de Configura\xE7\xE3o`);
+      guidance.warnings.forEach(
+        (warning) => console.warn(`${PREFIX} ${warning}`)
+      );
+      console.groupEnd();
+    }
+    if (guidance.suggestions.length > 0) {
+      console.group(`${PREFIX} \u{1F4A1} Sugest\xF5es`);
+      guidance.suggestions.forEach(
+        (suggestion) => console.info(`${PREFIX} ${suggestion}`)
+      );
+      console.groupEnd();
+    }
+    if (guidance.usingDefaults) {
+      console.info(
+        `${PREFIX} \u{1F4CB} Usando configura\xE7\xE3o padr\xE3o. Para personalizar, use a prop "categories" no ConsentProvider.`
+      );
+    }
+    console.group(`${PREFIX} \u{1F527} Categorias Ativas (para UI customizada)`);
+    console.table(
+      guidance.activeCategoriesInfo.map((cat) => ({
+        ID: cat.id,
+        Nome: cat.name,
+        "Toggle UI?": cat.uiRequired ? "\u2705 SIM" : "\u274C N\xC3O (sempre ativo)",
+        "Essencial?": cat.essential ? "\u{1F512} SIM" : "\u2699\uFE0F N\xC3O"
+      }))
+    );
     console.info(
-      '\u{1F4CB} LGPD-CONSENT: Usando configura\xE7\xE3o padr\xE3o. Para personalizar, use a prop "categories" no ConsentProvider.'
+      `${PREFIX} \u2139\uFE0F  Use estes dados para criar componentes customizados adequados.`
     );
+    console.groupEnd();
+  } catch (error) {
+    if (typeof console !== "undefined" && console.warn) {
+      console.warn(
+        "[\u{1F36A} LGPD-CONSENT] Sistema de orienta\xE7\xF5es encontrou erro:",
+        error
+      );
+    }
   }
-  console.group("\u{1F527} LGPD-CONSENT: Categorias Ativas (para UI customizada)");
-  console.table(
-    guidance.activeCategoriesInfo.map((cat) => ({
-      ID: cat.id,
-      Nome: cat.name,
-      "Toggle UI?": cat.uiRequired ? "\u2705 SIM" : "\u274C N\xC3O (sempre ativo)",
-      "Essencial?": cat.essential ? "\u{1F512} SIM" : "\u2699\uFE0F N\xC3O"
-    }))
-  );
-  console.groupEnd();
+}
+function useDeveloperGuidance(config) {
+  const guidance = analyzeDeveloperConfiguration(config);
+  React.useEffect(() => {
+    logDeveloperGuidance(guidance);
+  }, [JSON.stringify(config)]);
+  return guidance;
 }
 
 // src/context/CategoriesContext.tsx
@@ -359,7 +389,7 @@ var defaultConsentTheme = createTheme({
 // src/context/ConsentContext.tsx
 import { jsx as jsx2, jsxs } from "react/jsx-runtime";
 var PreferencesModal = React3.lazy(
-  () => import("./PreferencesModal-UL552BFP.js").then((m) => ({
+  () => import("./PreferencesModal-UMNANMVX.js").then((m) => ({
     default: m.PreferencesModal
   }))
 );
@@ -524,6 +554,7 @@ function ConsentProvider({
     }
     return void 0;
   }, [categories, customCategories]);
+  useDeveloperGuidance(finalCategoriesConfig);
   const boot = React3.useMemo(() => {
     if (initialState) return { ...initialState, isModalOpen: false };
     return createFullConsentState(

package/dist/index.cjs

@@ -280,33 +280,63 @@ function analyzeDeveloperConfiguration(config) {
   return guidance;
 }
 function logDeveloperGuidance(guidance) {
-  const isProduction = typeof globalThis !== "undefined" && globalThis.__LGPD_PRODUCTION__ || typeof window !== "undefined" && !window.__LGPD_DEV__;
-  if (isProduction) return;
-  if (guidance.warnings.length > 0) {
-    console.group("\u{1F7E8} LGPD-CONSENT: Avisos de Configura\xE7\xE3o");
-    guidance.warnings.forEach((warning) => console.warn(warning));
-    console.groupEnd();
-  }
-  if (guidance.suggestions.length > 0) {
-    console.group("\u{1F4A1} LGPD-CONSENT: Sugest\xF5es");
-    guidance.suggestions.forEach((suggestion) => console.info(suggestion));
-    console.groupEnd();
-  }
-  if (guidance.usingDefaults) {
+  try {
+    const isProduction = (
+      // 1. NODE_ENV de bundlers (Vite, webpack, etc.)
+      typeof globalThis.process !== "undefined" && globalThis.process.env?.NODE_ENV === "production" || // 2. Vite/bundler env vars (apenas em ESM)
+      typeof globalThis !== "undefined" && typeof globalThis.import !== "undefined" && globalThis.import.meta?.env?.PROD === true || // 3. Flag customizada para desabilitar logs
+      typeof globalThis !== "undefined" && globalThis.__LGPD_PRODUCTION__ || // 4. Flag de desenvolvimento desabilitada
+      typeof window !== "undefined" && window.__LGPD_DISABLE_GUIDANCE__
+    );
+    if (isProduction) return;
+    const PREFIX = "[\u{1F36A} LGPD-CONSENT]";
+    if (guidance.warnings.length > 0) {
+      console.group(`${PREFIX} \u26A0\uFE0F  Avisos de Configura\xE7\xE3o`);
+      guidance.warnings.forEach(
+        (warning) => console.warn(`${PREFIX} ${warning}`)
+      );
+      console.groupEnd();
+    }
+    if (guidance.suggestions.length > 0) {
+      console.group(`${PREFIX} \u{1F4A1} Sugest\xF5es`);
+      guidance.suggestions.forEach(
+        (suggestion) => console.info(`${PREFIX} ${suggestion}`)
+      );
+      console.groupEnd();
+    }
+    if (guidance.usingDefaults) {
+      console.info(
+        `${PREFIX} \u{1F4CB} Usando configura\xE7\xE3o padr\xE3o. Para personalizar, use a prop "categories" no ConsentProvider.`
+      );
+    }
+    console.group(`${PREFIX} \u{1F527} Categorias Ativas (para UI customizada)`);
+    console.table(
+      guidance.activeCategoriesInfo.map((cat) => ({
+        ID: cat.id,
+        Nome: cat.name,
+        "Toggle UI?": cat.uiRequired ? "\u2705 SIM" : "\u274C N\xC3O (sempre ativo)",
+        "Essencial?": cat.essential ? "\u{1F512} SIM" : "\u2699\uFE0F N\xC3O"
+      }))
+    );
     console.info(
-      '\u{1F4CB} LGPD-CONSENT: Usando configura\xE7\xE3o padr\xE3o. Para personalizar, use a prop "categories" no ConsentProvider.'
+      `${PREFIX} \u2139\uFE0F  Use estes dados para criar componentes customizados adequados.`
     );
+    console.groupEnd();
+  } catch (error) {
+    if (typeof console !== "undefined" && console.warn) {
+      console.warn(
+        "[\u{1F36A} LGPD-CONSENT] Sistema de orienta\xE7\xF5es encontrou erro:",
+        error
+      );
+    }
   }
-  console.group("\u{1F527} LGPD-CONSENT: Categorias Ativas (para UI customizada)");
-  console.table(
-    guidance.activeCategoriesInfo.map((cat) => ({
-      ID: cat.id,
-      Nome: cat.name,
-      "Toggle UI?": cat.uiRequired ? "\u2705 SIM" : "\u274C N\xC3O (sempre ativo)",
-      "Essencial?": cat.essential ? "\u{1F512} SIM" : "\u2699\uFE0F N\xC3O"
-    }))
-  );
-  console.groupEnd();
+}
+function useDeveloperGuidance(config) {
+  const guidance = analyzeDeveloperConfiguration(config);
+  React.useEffect(() => {
+    logDeveloperGuidance(guidance);
+  }, [JSON.stringify(config)]);
+  return guidance;
 }
 var React, DEFAULT_PROJECT_CATEGORIES;
 var init_developerGuidance = __esm({
@@ -691,6 +721,7 @@ function ConsentProvider({
     }
     return void 0;
   }, [categories, customCategories]);
+  useDeveloperGuidance(finalCategoriesConfig);
   const boot = React3.useMemo(() => {
     if (initialState) return { ...initialState, isModalOpen: false };
     return createFullConsentState(
@@ -793,6 +824,7 @@ var init_ConsentContext = __esm({
     init_cookieUtils();
     init_theme();
     init_CategoriesContext();
+    init_developerGuidance();
     import_jsx_runtime4 = require("react/jsx-runtime");
     PreferencesModal2 = React3.lazy(
       () => Promise.resolve().then(() => (init_PreferencesModal(), PreferencesModal_exports)).then((m) => ({

package/dist/index.d.cts

@@ -284,41 +284,192 @@ interface ConsentCookieOptions {
     path: string;
 }
 /**
- * Propriedades aceitas pelo componente ConsentProvider.
+ * Propriedades do componente ConsentProvider - configuração principal da biblioteca.
+ *
+ * @example Uso básico (configuração mínima):
+ * ```tsx
+ * <ConsentProvider
+ *   categories={{ enabledCategories: ['analytics'] }}
+ * >
+ *   <App />
+ * </ConsentProvider>
+ * ```
+ *
+ * @example Configuração completa com textos ANPD:
+ * ```tsx
+ * <ConsentProvider
+ *   categories={{
+ *     enabledCategories: ['analytics', 'functional'],
+ *     customCategories: [{
+ *       id: 'governo',
+ *       name: 'Cookies Governamentais',
+ *       description: 'Coleta para estatísticas públicas',
+ *       essential: false
+ *     }]
+ *   }}
+ *   texts={{
+ *     bannerMessage: 'Utilizamos cookies conforme LGPD...',
+ *     controllerInfo: 'Controlado por: Ministério XYZ - CNPJ: 00.000.000/0001-00',
+ *     dataTypes: 'Coletamos: dados de navegação para análise estatística',
+ *     userRights: 'Direitos: acessar, corrigir, excluir dados',
+ *     contactInfo: 'DPO: dpo@ministerio.gov.br'
+ *   }}
+ *   onConsentGiven={(state) => console.log('Consentimento:', state)}
+ * >
+ *   <App />
+ * </ConsentProvider>
+ * ```
  */
 interface ConsentProviderProps {
-    /** Estado inicial do consentimento (para SSR). */
+    /**
+     * Estado inicial do consentimento para hidratação SSR.
+     *
+     * @example
+     * ```tsx
+     * // Em Next.js para evitar flash do banner
+     * <ConsentProvider initialState={{ consented: true, preferences: {...} }}>
+     * ```
+     */
     initialState?: ConsentState;
-    /** Configuração de categorias ativas no projeto. */
+    /**
+     * Configuração das categorias de cookies utilizadas no projeto.
+     * Define quais categorias padrão serão habilitadas e categorias customizadas.
+     *
+     * @example Apenas analytics:
+     * ```tsx
+     * categories={{ enabledCategories: ['analytics'] }}
+     * ```
+     *
+     * @example Com categoria customizada:
+     * ```tsx
+     * categories={{
+     *   enabledCategories: ['analytics', 'marketing'],
+     *   customCategories: [{
+     *     id: 'pesquisa',
+     *     name: 'Cookies de Pesquisa',
+     *     description: 'Coleta feedback e opinião dos usuários',
+     *     essential: false
+     *   }]
+     * }}
+     * ```
+     */
     categories?: ProjectCategoriesConfig;
-    /** Textos customizados para a interface. */
+    /**
+     * Textos customizados da interface (banner e modal).
+     * Todos os campos são opcionais - valores não fornecidos usam o padrão em português.
+     *
+     * @example Textos básicos:
+     * ```tsx
+     * texts={{
+     *   bannerMessage: 'We use cookies...',
+     *   acceptAll: 'Accept All',
+     *   declineAll: 'Reject'
+     * }}
+     * ```
+     *
+     * @example Textos ANPD para compliance:
+     * ```tsx
+     * texts={{
+     *   controllerInfo: 'Controlado por: Empresa XYZ - CNPJ: 12.345.678/0001-90',
+     *   dataTypes: 'Coletamos: endereço IP, preferências de navegação',
+     *   userRights: 'Você pode solicitar acesso, correção ou exclusão dos dados'
+     * }}
+     * ```
+     */
     texts?: Partial<ConsentTexts>;
-    /** Tema customizado para os componentes MUI. Aceita qualquer propriedade. */
+    /**
+     * Tema customizado Material-UI aplicado aos componentes.
+     * Aceita qualquer objeto que será passado para ThemeProvider.
+     *
+     * @example
+     * ```tsx
+     * theme={{
+     *   palette: { primary: { main: '#1976d2' } },
+     *   components: { MuiButton: { styleOverrides: { root: { borderRadius: 8 } } } }
+     * }}
+     * ```
+     */
     theme?: any;
     /**
-     * @deprecated Use `categories.customCategories` em vez disso.
-     * Categorias customizadas de cookies (complementa as padrão).
+     * @deprecated Usar `categories.customCategories` em vez disso.
+     * Mantido para compatibilidade com v0.1.x
      */
     customCategories?: CategoryDefinition[];
-    /** Integrações nativas de scripts (Google Analytics, etc.). */
+    /**
+     * Integrações nativas de scripts terceiros (Google Analytics, etc.).
+     * Scripts são carregados automaticamente baseado no consentimento.
+     *
+     * @example
+     * ```tsx
+     * import { createGoogleAnalyticsIntegration } from 'react-lgpd-consent'
+     *
+     * scriptIntegrations={[
+     *   createGoogleAnalyticsIntegration('GA_MEASUREMENT_ID')
+     * ]}
+     * ```
+     */
     scriptIntegrations?: ScriptIntegration[];
-    /** Componente customizado para modal de preferências. */
+    /**
+     * Componente customizado para substituir o modal padrão de preferências.
+     * Deve implementar a lógica de consentimento usando os hooks da biblioteca.
+     */
     PreferencesModalComponent?: React.ComponentType<any>;
-    /** Props adicionais para o modal customizado. */
+    /** Props adicionais passadas para o modal customizado. */
     preferencesModalProps?: Record<string, any>;
-    /** Desabilita o modal automático (para usar componente totalmente customizado). */
+    /**
+     * Desabilita o modal automático de preferências.
+     * Útil quando se quer controle total sobre quando/como exibir as opções.
+     */
     disableAutomaticModal?: boolean;
-    /** Comportamento do banner: true = bloqueia até decisão, false = não bloqueia */
+    /**
+     * Comportamento do banner de consentimento:
+     * - `false` (padrão): Banner não-intrusivo, usuário pode navegar livremente
+     * - `true`: Banner bloqueia interação até decisão (compliance rigorosa)
+     */
     blocking?: boolean;
-    /** Esconde branding "fornecido por LÉdipO.eti.br". */
+    /** Oculta o branding "fornecido por LÉdipO.eti.br" dos componentes. */
     hideBranding?: boolean;
-    /** Callback chamado quando o consentimento é dado. */
+    /**
+     * Callback executado quando usuário dá consentimento pela primeira vez.
+     * Útil para inicializar analytics, registrar evento, etc.
+     *
+     * @example
+     * ```tsx
+     * onConsentGiven={(state) => {
+     *   console.log('Consentimento registrado:', state)
+     *   // Inicializar Google Analytics, etc.
+     * }}
+     * ```
+     */
     onConsentGiven?: (state: ConsentState) => void;
-    /** Callback chamado ao salvar preferências. */
+    /**
+     * Callback executado quando usuário modifica preferências.
+     * Executado após salvar as mudanças.
+     *
+     * @example
+     * ```tsx
+     * onPreferencesSaved={(prefs) => {
+     *   console.log('Novas preferências:', prefs)
+     *   // Reconfigurar scripts baseado nas preferências
+     * }}
+     * ```
+     */
     onPreferencesSaved?: (prefs: ConsentPreferences) => void;
-    /** Configurações customizadas do cookie. */
+    /**
+     * Configurações do cookie de consentimento.
+     * Valores não fornecidos usam padrões seguros para LGPD.
+     *
+     * @example
+     * ```tsx
+     * cookie={{
+     *   name: 'meuAppConsent',
+     *   maxAgeDays: 180,
+     *   sameSite: 'Strict'
+     * }}
+     * ```
+     */
     cookie?: Partial<ConsentCookieOptions>;
-    /** Elementos filhos do provider. */
+    /** Elementos filhos - toda a aplicação que precisa de contexto de consentimento. */
     children: React.ReactNode;
 }
 /**

package/dist/index.d.ts

@@ -284,41 +284,192 @@ interface ConsentCookieOptions {
     path: string;
 }
 /**
- * Propriedades aceitas pelo componente ConsentProvider.
+ * Propriedades do componente ConsentProvider - configuração principal da biblioteca.
+ *
+ * @example Uso básico (configuração mínima):
+ * ```tsx
+ * <ConsentProvider
+ *   categories={{ enabledCategories: ['analytics'] }}
+ * >
+ *   <App />
+ * </ConsentProvider>
+ * ```
+ *
+ * @example Configuração completa com textos ANPD:
+ * ```tsx
+ * <ConsentProvider
+ *   categories={{
+ *     enabledCategories: ['analytics', 'functional'],
+ *     customCategories: [{
+ *       id: 'governo',
+ *       name: 'Cookies Governamentais',
+ *       description: 'Coleta para estatísticas públicas',
+ *       essential: false
+ *     }]
+ *   }}
+ *   texts={{
+ *     bannerMessage: 'Utilizamos cookies conforme LGPD...',
+ *     controllerInfo: 'Controlado por: Ministério XYZ - CNPJ: 00.000.000/0001-00',
+ *     dataTypes: 'Coletamos: dados de navegação para análise estatística',
+ *     userRights: 'Direitos: acessar, corrigir, excluir dados',
+ *     contactInfo: 'DPO: dpo@ministerio.gov.br'
+ *   }}
+ *   onConsentGiven={(state) => console.log('Consentimento:', state)}
+ * >
+ *   <App />
+ * </ConsentProvider>
+ * ```
  */
 interface ConsentProviderProps {
-    /** Estado inicial do consentimento (para SSR). */
+    /**
+     * Estado inicial do consentimento para hidratação SSR.
+     *
+     * @example
+     * ```tsx
+     * // Em Next.js para evitar flash do banner
+     * <ConsentProvider initialState={{ consented: true, preferences: {...} }}>
+     * ```
+     */
     initialState?: ConsentState;
-    /** Configuração de categorias ativas no projeto. */
+    /**
+     * Configuração das categorias de cookies utilizadas no projeto.
+     * Define quais categorias padrão serão habilitadas e categorias customizadas.
+     *
+     * @example Apenas analytics:
+     * ```tsx
+     * categories={{ enabledCategories: ['analytics'] }}
+     * ```
+     *
+     * @example Com categoria customizada:
+     * ```tsx
+     * categories={{
+     *   enabledCategories: ['analytics', 'marketing'],
+     *   customCategories: [{
+     *     id: 'pesquisa',
+     *     name: 'Cookies de Pesquisa',
+     *     description: 'Coleta feedback e opinião dos usuários',
+     *     essential: false
+     *   }]
+     * }}
+     * ```
+     */
     categories?: ProjectCategoriesConfig;
-    /** Textos customizados para a interface. */
+    /**
+     * Textos customizados da interface (banner e modal).
+     * Todos os campos são opcionais - valores não fornecidos usam o padrão em português.
+     *
+     * @example Textos básicos:
+     * ```tsx
+     * texts={{
+     *   bannerMessage: 'We use cookies...',
+     *   acceptAll: 'Accept All',
+     *   declineAll: 'Reject'
+     * }}
+     * ```
+     *
+     * @example Textos ANPD para compliance:
+     * ```tsx
+     * texts={{
+     *   controllerInfo: 'Controlado por: Empresa XYZ - CNPJ: 12.345.678/0001-90',
+     *   dataTypes: 'Coletamos: endereço IP, preferências de navegação',
+     *   userRights: 'Você pode solicitar acesso, correção ou exclusão dos dados'
+     * }}
+     * ```
+     */
     texts?: Partial<ConsentTexts>;
-    /** Tema customizado para os componentes MUI. Aceita qualquer propriedade. */
+    /**
+     * Tema customizado Material-UI aplicado aos componentes.
+     * Aceita qualquer objeto que será passado para ThemeProvider.
+     *
+     * @example
+     * ```tsx
+     * theme={{
+     *   palette: { primary: { main: '#1976d2' } },
+     *   components: { MuiButton: { styleOverrides: { root: { borderRadius: 8 } } } }
+     * }}
+     * ```
+     */
     theme?: any;
     /**
-     * @deprecated Use `categories.customCategories` em vez disso.
-     * Categorias customizadas de cookies (complementa as padrão).
+     * @deprecated Usar `categories.customCategories` em vez disso.
+     * Mantido para compatibilidade com v0.1.x
      */
     customCategories?: CategoryDefinition[];
-    /** Integrações nativas de scripts (Google Analytics, etc.). */
+    /**
+     * Integrações nativas de scripts terceiros (Google Analytics, etc.).
+     * Scripts são carregados automaticamente baseado no consentimento.
+     *
+     * @example
+     * ```tsx
+     * import { createGoogleAnalyticsIntegration } from 'react-lgpd-consent'
+     *
+     * scriptIntegrations={[
+     *   createGoogleAnalyticsIntegration('GA_MEASUREMENT_ID')
+     * ]}
+     * ```
+     */
     scriptIntegrations?: ScriptIntegration[];
-    /** Componente customizado para modal de preferências. */
+    /**
+     * Componente customizado para substituir o modal padrão de preferências.
+     * Deve implementar a lógica de consentimento usando os hooks da biblioteca.
+     */
     PreferencesModalComponent?: React.ComponentType<any>;
-    /** Props adicionais para o modal customizado. */
+    /** Props adicionais passadas para o modal customizado. */
     preferencesModalProps?: Record<string, any>;
-    /** Desabilita o modal automático (para usar componente totalmente customizado). */
+    /**
+     * Desabilita o modal automático de preferências.
+     * Útil quando se quer controle total sobre quando/como exibir as opções.
+     */
     disableAutomaticModal?: boolean;
-    /** Comportamento do banner: true = bloqueia até decisão, false = não bloqueia */
+    /**
+     * Comportamento do banner de consentimento:
+     * - `false` (padrão): Banner não-intrusivo, usuário pode navegar livremente
+     * - `true`: Banner bloqueia interação até decisão (compliance rigorosa)
+     */
     blocking?: boolean;
-    /** Esconde branding "fornecido por LÉdipO.eti.br". */
+    /** Oculta o branding "fornecido por LÉdipO.eti.br" dos componentes. */
     hideBranding?: boolean;
-    /** Callback chamado quando o consentimento é dado. */
+    /**
+     * Callback executado quando usuário dá consentimento pela primeira vez.
+     * Útil para inicializar analytics, registrar evento, etc.
+     *
+     * @example
+     * ```tsx
+     * onConsentGiven={(state) => {
+     *   console.log('Consentimento registrado:', state)
+     *   // Inicializar Google Analytics, etc.
+     * }}
+     * ```
+     */
     onConsentGiven?: (state: ConsentState) => void;
-    /** Callback chamado ao salvar preferências. */
+    /**
+     * Callback executado quando usuário modifica preferências.
+     * Executado após salvar as mudanças.
+     *
+     * @example
+     * ```tsx
+     * onPreferencesSaved={(prefs) => {
+     *   console.log('Novas preferências:', prefs)
+     *   // Reconfigurar scripts baseado nas preferências
+     * }}
+     * ```
+     */
     onPreferencesSaved?: (prefs: ConsentPreferences) => void;
-    /** Configurações customizadas do cookie. */
+    /**
+     * Configurações do cookie de consentimento.
+     * Valores não fornecidos usam padrões seguros para LGPD.
+     *
+     * @example
+     * ```tsx
+     * cookie={{
+     *   name: 'meuAppConsent',
+     *   maxAgeDays: 180,
+     *   sameSite: 'Strict'
+     * }}
+     * ```
+     */
     cookie?: Partial<ConsentCookieOptions>;
-    /** Elementos filhos do provider. */
+    /** Elementos filhos - toda a aplicação que precisa de contexto de consentimento. */
     children: React.ReactNode;
 }
 /**

package/dist/index.js

@@ -11,7 +11,7 @@ import {
   useConsentHydration,
   useConsentTexts,
   useCustomCategories
-} from "./chunk-JAX63PBG.js";
+} from "./chunk-E763JXNL.js";
 
 // src/components/CookieBanner.tsx
 import Button from "@mui/material/Button";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-lgpd-consent",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Biblioteca completa de consentimento LGPD com 6 categorias ANPD, integrações nativas e sistema extensível para React.",
   "keywords": [
     "lgpd",