react-lgpd-consent 0.2.0 → 0.2.2

package/dist/index.d.cts

@@ -183,25 +183,48 @@ interface CategoryDefinition {
     cookies?: string[];
 }
 /**
- * Preferências de consentimento do usuário para cada categoria.
- * Baseado nas categorias do Guia da ANPD, mas extensível.
+ * Configuração de categorias ativas no projeto.
+ * Define quais categorias fixas serão usadas (além de necessary)
+ * e quais categorias customizadas serão adicionadas.
+ */
+interface ProjectCategoriesConfig {
+    /** Categorias padrão que serão ativadas (necessary sempre incluída automaticamente) */
+    enabledCategories?: Category[];
+    /** Categorias customizadas específicas do projeto */
+    customCategories?: CategoryDefinition[];
+}
+/**
+ * Preferências de consentimento do usuário.
+ * Contém apenas as categorias realmente utilizadas no projeto.
  */
 interface ConsentPreferences {
     necessary: boolean;
-    analytics: boolean;
-    functional: boolean;
-    marketing: boolean;
-    social: boolean;
-    personalization: boolean;
     [key: string]: boolean;
 }
 /**
- * Estado geral do consentimento, incluindo se o usuário consentiu,
- * suas preferências e se o modal está aberto.
+ * Dados do cookie de consentimento em conformidade com LGPD/ANPD.
+ * Contém apenas informações essenciais para compliance e funcionamento.
  */
-interface ConsentState {
+interface ConsentCookieData {
+    /** Versão do esquema do cookie para migração futura */
+    version: string;
+    /** Se o usuário já prestou consentimento */
     consented: boolean;
+    /** Preferências por categoria (apenas categorias ativas) */
     preferences: ConsentPreferences;
+    /** Timestamp ISO da primeira interação com o banner */
+    consentDate: string;
+    /** Timestamp ISO da última modificação das preferências */
+    lastUpdate: string;
+    /** Origem da decisão de consentimento */
+    source: 'banner' | 'modal' | 'programmatic';
+}
+/**
+ * Estado interno completo do consentimento (memória + UI).
+ * Inclui dados persistidos + estado da interface.
+ */
+interface ConsentState extends ConsentCookieData {
+    /** Se o modal de preferências está aberto (NÃO persistido) */
     isModalOpen?: boolean;
 }
 /**
@@ -264,13 +287,18 @@ interface ConsentCookieOptions {
  * Propriedades aceitas pelo componente ConsentProvider.
  */
 interface ConsentProviderProps {
-    /** Estado inicial do consentimento. */
+    /** Estado inicial do consentimento (para SSR). */
     initialState?: ConsentState;
+    /** Configuração de categorias ativas no projeto. */
+    categories?: ProjectCategoriesConfig;
     /** Textos customizados para a interface. */
     texts?: Partial<ConsentTexts>;
     /** Tema customizado para os componentes MUI. Aceita qualquer propriedade. */
     theme?: any;
-    /** Categorias customizadas de cookies (complementa as padrão). */
+    /**
+     * @deprecated Use `categories.customCategories` em vez disso.
+     * Categorias customizadas de cookies (complementa as padrão).
+     */
     customCategories?: CategoryDefinition[];
     /** Integrações nativas de scripts (Google Analytics, etc.). */
     scriptIntegrations?: ScriptIntegration[];
@@ -280,6 +308,8 @@ interface ConsentProviderProps {
     preferencesModalProps?: Record<string, any>;
     /** Desabilita o modal automático (para usar componente totalmente customizado). */
     disableAutomaticModal?: boolean;
+    /** Comportamento do banner: true = bloqueia até decisão, false = não bloqueia */
+    blocking?: boolean;
     /** Esconde branding "fornecido por LÉdipO.eti.br". */
     hideBranding?: boolean;
     /** Callback chamado quando o consentimento é dado. */
@@ -332,7 +362,9 @@ interface ConsentContextValue {
  *   <App />
  * </ConsentProvider>
  */
-declare function ConsentProvider({ initialState, texts: textsProp, theme, customCategories, scriptIntegrations, PreferencesModalComponent, preferencesModalProps, disableAutomaticModal, hideBranding, onConsentGiven, onPreferencesSaved, cookie: cookieOpts, children, }: Readonly<ConsentProviderProps>): react_jsx_runtime.JSX.Element;
+declare function ConsentProvider({ initialState, categories, // NOVO: configuração completa de categorias
+texts: textsProp, theme, customCategories, // LEGACY: compatibilidade
+scriptIntegrations, PreferencesModalComponent, preferencesModalProps, disableAutomaticModal, hideBranding, onConsentGiven, onPreferencesSaved, cookie: cookieOpts, children, }: Readonly<ConsentProviderProps>): react_jsx_runtime.JSX.Element;
 
 /**
  * Hook principal para acessar e manipular o estado de consentimento de cookies.
@@ -368,14 +400,73 @@ declare function useConsentTexts(): ConsentTexts;
 declare function useConsentHydration(): boolean;
 
 /**
- * Hook para acessar as categorias customizadas.
- * Retorna apenas as categorias customizadas (não as padrão analytics/marketing).
+ * Sistema de orientações para developers sobre configuração de categorias.
+ * Ajuda a manter coerência entre configuração da lib e componentes customizados.
+ */
+interface DeveloperGuidance {
+    /** Avisos sobre configuração inconsistente */
+    warnings: string[];
+    /** Sugestões de melhoria */
+    suggestions: string[];
+    /** Informações sobre categorias ativas */
+    activeCategoriesInfo: {
+        id: string;
+        name: string;
+        description: string;
+        essential: boolean;
+        uiRequired: boolean;
+    }[];
+    /** Se usa configuração padrão (não explícita) */
+    usingDefaults: boolean;
+}
+/**
+ * Configuração padrão quando developer não especifica categorias.
+ * Baseado nas necessidades mais comuns em conformidade LGPD.
  */
-declare function useCustomCategories(): CategoryDefinition[];
+declare const DEFAULT_PROJECT_CATEGORIES: ProjectCategoriesConfig;
+/**
+ * Analisa configuração do projeto e retorna orientações para o developer.
+ */
+declare function analyzeDeveloperConfiguration(config?: ProjectCategoriesConfig): DeveloperGuidance;
+
+/**
+ * Context para informações sobre categorias ativas no projeto.
+ * Fornece orientações e validações para components UI.
+ */
+interface CategoriesContextValue {
+    /** Configuração final das categorias (com padrão aplicado) */
+    config: ProjectCategoriesConfig;
+    /** Análise e orientações para developers */
+    guidance: DeveloperGuidance;
+    /** Categorias que precisam de toggle na UI */
+    toggleableCategories: DeveloperGuidance['activeCategoriesInfo'];
+    /** Todas as categorias ativas */
+    allCategories: DeveloperGuidance['activeCategoriesInfo'];
+    /** LEGACY: Apenas categorias customizadas (backward compatibility) */
+    legacyCategories: CategoryDefinition[];
+}
+/**
+ * Hook para acessar informações sobre categorias ativas.
+ * Usado por componentes UI para renderizar adequadamente.
+ */
+declare function useCategories(): CategoriesContextValue;
 /**
- * Hook para obter todas as categorias (padrão + customizadas).
+ * Hook de conveniência para verificar se uma categoria específica está ativa.
  */
-declare function useAllCategories(): CategoryDefinition[];
+declare function useCategoryStatus(categoryId: string): {
+    isActive: boolean;
+    isEssential: boolean;
+    needsToggle: boolean;
+    name: string | undefined;
+    description: string | undefined;
+};
+/**
+ * LEGACY: Hook para acessar as categorias customizadas.
+ * Mantido para backward compatibility.
+ *
+ * @deprecated Use useCategories() ao invés disso para acesso completo às categorias.
+ */
+declare function useCustomCategories(): CategoryDefinition[];
 
 declare function ConsentGate(props: Readonly<{
     category: string;
@@ -452,4 +543,4 @@ declare function ConsentScriptLoader({ integrations, reloadOnChange, }: Readonly
  */
 declare function useConsentScriptLoader(): (integration: ScriptIntegration) => Promise<boolean>;
 
-export { COMMON_INTEGRATIONS, type Category, type CategoryDefinition, type ConsentCookieOptions, ConsentGate, type ConsentPreferences, ConsentProvider, ConsentScriptLoader, type ConsentState, type ConsentTexts, CookieBanner, FloatingPreferencesButton, type GoogleAnalyticsConfig, type GoogleTagManagerConfig, PreferencesModal, type ScriptIntegration, type UserWayConfig, createGoogleAnalyticsIntegration, createGoogleTagManagerIntegration, createUserWayIntegration, defaultConsentTheme, loadScript, useAllCategories, useConsent, useConsentHydration, useConsentScriptLoader, useConsentTexts, useCustomCategories };
+export { COMMON_INTEGRATIONS, type Category, type CategoryDefinition, type ConsentCookieOptions, ConsentGate, type ConsentPreferences, ConsentProvider, ConsentScriptLoader, type ConsentState, type ConsentTexts, CookieBanner, DEFAULT_PROJECT_CATEGORIES, type DeveloperGuidance, FloatingPreferencesButton, type GoogleAnalyticsConfig, type GoogleTagManagerConfig, PreferencesModal, type ProjectCategoriesConfig, type ScriptIntegration, type UserWayConfig, analyzeDeveloperConfiguration, createGoogleAnalyticsIntegration, createGoogleTagManagerIntegration, createUserWayIntegration, defaultConsentTheme, loadScript, useCategories, useCategoryStatus, useConsent, useConsentHydration, useConsentScriptLoader, useConsentTexts, useCustomCategories };

package/dist/index.d.ts

@@ -183,25 +183,48 @@ interface CategoryDefinition {
     cookies?: string[];
 }
 /**
- * Preferências de consentimento do usuário para cada categoria.
- * Baseado nas categorias do Guia da ANPD, mas extensível.
+ * Configuração de categorias ativas no projeto.
+ * Define quais categorias fixas serão usadas (além de necessary)
+ * e quais categorias customizadas serão adicionadas.
+ */
+interface ProjectCategoriesConfig {
+    /** Categorias padrão que serão ativadas (necessary sempre incluída automaticamente) */
+    enabledCategories?: Category[];
+    /** Categorias customizadas específicas do projeto */
+    customCategories?: CategoryDefinition[];
+}
+/**
+ * Preferências de consentimento do usuário.
+ * Contém apenas as categorias realmente utilizadas no projeto.
  */
 interface ConsentPreferences {
     necessary: boolean;
-    analytics: boolean;
-    functional: boolean;
-    marketing: boolean;
-    social: boolean;
-    personalization: boolean;
     [key: string]: boolean;
 }
 /**
- * Estado geral do consentimento, incluindo se o usuário consentiu,
- * suas preferências e se o modal está aberto.
+ * Dados do cookie de consentimento em conformidade com LGPD/ANPD.
+ * Contém apenas informações essenciais para compliance e funcionamento.
  */
-interface ConsentState {
+interface ConsentCookieData {
+    /** Versão do esquema do cookie para migração futura */
+    version: string;
+    /** Se o usuário já prestou consentimento */
     consented: boolean;
+    /** Preferências por categoria (apenas categorias ativas) */
     preferences: ConsentPreferences;
+    /** Timestamp ISO da primeira interação com o banner */
+    consentDate: string;
+    /** Timestamp ISO da última modificação das preferências */
+    lastUpdate: string;
+    /** Origem da decisão de consentimento */
+    source: 'banner' | 'modal' | 'programmatic';
+}
+/**
+ * Estado interno completo do consentimento (memória + UI).
+ * Inclui dados persistidos + estado da interface.
+ */
+interface ConsentState extends ConsentCookieData {
+    /** Se o modal de preferências está aberto (NÃO persistido) */
     isModalOpen?: boolean;
 }
 /**
@@ -264,13 +287,18 @@ interface ConsentCookieOptions {
  * Propriedades aceitas pelo componente ConsentProvider.
  */
 interface ConsentProviderProps {
-    /** Estado inicial do consentimento. */
+    /** Estado inicial do consentimento (para SSR). */
     initialState?: ConsentState;
+    /** Configuração de categorias ativas no projeto. */
+    categories?: ProjectCategoriesConfig;
     /** Textos customizados para a interface. */
     texts?: Partial<ConsentTexts>;
     /** Tema customizado para os componentes MUI. Aceita qualquer propriedade. */
     theme?: any;
-    /** Categorias customizadas de cookies (complementa as padrão). */
+    /**
+     * @deprecated Use `categories.customCategories` em vez disso.
+     * Categorias customizadas de cookies (complementa as padrão).
+     */
     customCategories?: CategoryDefinition[];
     /** Integrações nativas de scripts (Google Analytics, etc.). */
     scriptIntegrations?: ScriptIntegration[];
@@ -280,6 +308,8 @@ interface ConsentProviderProps {
     preferencesModalProps?: Record<string, any>;
     /** Desabilita o modal automático (para usar componente totalmente customizado). */
     disableAutomaticModal?: boolean;
+    /** Comportamento do banner: true = bloqueia até decisão, false = não bloqueia */
+    blocking?: boolean;
     /** Esconde branding "fornecido por LÉdipO.eti.br". */
     hideBranding?: boolean;
     /** Callback chamado quando o consentimento é dado. */
@@ -332,7 +362,9 @@ interface ConsentContextValue {
  *   <App />
  * </ConsentProvider>
  */
-declare function ConsentProvider({ initialState, texts: textsProp, theme, customCategories, scriptIntegrations, PreferencesModalComponent, preferencesModalProps, disableAutomaticModal, hideBranding, onConsentGiven, onPreferencesSaved, cookie: cookieOpts, children, }: Readonly<ConsentProviderProps>): react_jsx_runtime.JSX.Element;
+declare function ConsentProvider({ initialState, categories, // NOVO: configuração completa de categorias
+texts: textsProp, theme, customCategories, // LEGACY: compatibilidade
+scriptIntegrations, PreferencesModalComponent, preferencesModalProps, disableAutomaticModal, hideBranding, onConsentGiven, onPreferencesSaved, cookie: cookieOpts, children, }: Readonly<ConsentProviderProps>): react_jsx_runtime.JSX.Element;
 
 /**
  * Hook principal para acessar e manipular o estado de consentimento de cookies.
@@ -368,14 +400,73 @@ declare function useConsentTexts(): ConsentTexts;
 declare function useConsentHydration(): boolean;
 
 /**
- * Hook para acessar as categorias customizadas.
- * Retorna apenas as categorias customizadas (não as padrão analytics/marketing).
+ * Sistema de orientações para developers sobre configuração de categorias.
+ * Ajuda a manter coerência entre configuração da lib e componentes customizados.
+ */
+interface DeveloperGuidance {
+    /** Avisos sobre configuração inconsistente */
+    warnings: string[];
+    /** Sugestões de melhoria */
+    suggestions: string[];
+    /** Informações sobre categorias ativas */
+    activeCategoriesInfo: {
+        id: string;
+        name: string;
+        description: string;
+        essential: boolean;
+        uiRequired: boolean;
+    }[];
+    /** Se usa configuração padrão (não explícita) */
+    usingDefaults: boolean;
+}
+/**
+ * Configuração padrão quando developer não especifica categorias.
+ * Baseado nas necessidades mais comuns em conformidade LGPD.
  */
-declare function useCustomCategories(): CategoryDefinition[];
+declare const DEFAULT_PROJECT_CATEGORIES: ProjectCategoriesConfig;
+/**
+ * Analisa configuração do projeto e retorna orientações para o developer.
+ */
+declare function analyzeDeveloperConfiguration(config?: ProjectCategoriesConfig): DeveloperGuidance;
+
+/**
+ * Context para informações sobre categorias ativas no projeto.
+ * Fornece orientações e validações para components UI.
+ */
+interface CategoriesContextValue {
+    /** Configuração final das categorias (com padrão aplicado) */
+    config: ProjectCategoriesConfig;
+    /** Análise e orientações para developers */
+    guidance: DeveloperGuidance;
+    /** Categorias que precisam de toggle na UI */
+    toggleableCategories: DeveloperGuidance['activeCategoriesInfo'];
+    /** Todas as categorias ativas */
+    allCategories: DeveloperGuidance['activeCategoriesInfo'];
+    /** LEGACY: Apenas categorias customizadas (backward compatibility) */
+    legacyCategories: CategoryDefinition[];
+}
+/**
+ * Hook para acessar informações sobre categorias ativas.
+ * Usado por componentes UI para renderizar adequadamente.
+ */
+declare function useCategories(): CategoriesContextValue;
 /**
- * Hook para obter todas as categorias (padrão + customizadas).
+ * Hook de conveniência para verificar se uma categoria específica está ativa.
  */
-declare function useAllCategories(): CategoryDefinition[];
+declare function useCategoryStatus(categoryId: string): {
+    isActive: boolean;
+    isEssential: boolean;
+    needsToggle: boolean;
+    name: string | undefined;
+    description: string | undefined;
+};
+/**
+ * LEGACY: Hook para acessar as categorias customizadas.
+ * Mantido para backward compatibility.
+ *
+ * @deprecated Use useCategories() ao invés disso para acesso completo às categorias.
+ */
+declare function useCustomCategories(): CategoryDefinition[];
 
 declare function ConsentGate(props: Readonly<{
     category: string;
@@ -452,4 +543,4 @@ declare function ConsentScriptLoader({ integrations, reloadOnChange, }: Readonly
  */
 declare function useConsentScriptLoader(): (integration: ScriptIntegration) => Promise<boolean>;
 
-export { COMMON_INTEGRATIONS, type Category, type CategoryDefinition, type ConsentCookieOptions, ConsentGate, type ConsentPreferences, ConsentProvider, ConsentScriptLoader, type ConsentState, type ConsentTexts, CookieBanner, FloatingPreferencesButton, type GoogleAnalyticsConfig, type GoogleTagManagerConfig, PreferencesModal, type ScriptIntegration, type UserWayConfig, createGoogleAnalyticsIntegration, createGoogleTagManagerIntegration, createUserWayIntegration, defaultConsentTheme, loadScript, useAllCategories, useConsent, useConsentHydration, useConsentScriptLoader, useConsentTexts, useCustomCategories };
+export { COMMON_INTEGRATIONS, type Category, type CategoryDefinition, type ConsentCookieOptions, ConsentGate, type ConsentPreferences, ConsentProvider, ConsentScriptLoader, type ConsentState, type ConsentTexts, CookieBanner, DEFAULT_PROJECT_CATEGORIES, type DeveloperGuidance, FloatingPreferencesButton, type GoogleAnalyticsConfig, type GoogleTagManagerConfig, PreferencesModal, type ProjectCategoriesConfig, type ScriptIntegration, type UserWayConfig, analyzeDeveloperConfiguration, createGoogleAnalyticsIntegration, createGoogleTagManagerIntegration, createUserWayIntegration, defaultConsentTheme, loadScript, useCategories, useCategoryStatus, useConsent, useConsentHydration, useConsentScriptLoader, useConsentTexts, useCustomCategories };

package/dist/index.js

@@ -1,14 +1,17 @@
 import {
   Branding,
   ConsentProvider,
+  DEFAULT_PROJECT_CATEGORIES,
   PreferencesModal,
+  analyzeDeveloperConfiguration,
   defaultConsentTheme,
-  useAllCategories,
+  useCategories,
+  useCategoryStatus,
   useConsent,
   useConsentHydration,
   useConsentTexts,
   useCustomCategories
-} from "./chunk-JTPCDTOQ.js";
+} from "./chunk-JAX63PBG.js";
 
 // src/components/CookieBanner.tsx
 import Button from "@mui/material/Button";
@@ -361,14 +364,17 @@ export {
   ConsentProvider,
   ConsentScriptLoader,
   CookieBanner,
+  DEFAULT_PROJECT_CATEGORIES,
   FloatingPreferencesButton,
   PreferencesModal,
+  analyzeDeveloperConfiguration,
   createGoogleAnalyticsIntegration,
   createGoogleTagManagerIntegration,
   createUserWayIntegration,
   defaultConsentTheme,
   loadScript,
-  useAllCategories,
+  useCategories,
+  useCategoryStatus,
   useConsent,
   useConsentHydration,
   useConsentScriptLoader,

package/package.json

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