react-lgpd-consent 0.1.13 → 0.2.1

package/dist/index.d.cts

@@ -100,24 +100,131 @@ interface FloatingPreferencesButtonProps {
 declare function FloatingPreferencesButton({ position, offset, icon, tooltip, FabProps, hideWhenConsented, }: Readonly<FloatingPreferencesButtonProps>): react_jsx_runtime.JSX.Element | null;
 
 /**
- * Categoria de consentimento para cookies.
- * Pode ser 'analytics' ou 'marketing'.
+ * Integrações nativas com scripts de terceiros.
+ * Facilita o carregamento automático baseado em consentimento.
  */
-type Category = 'analytics' | 'marketing';
+interface ScriptIntegration {
+    /** ID único da integração */
+    id: string;
+    /** Categoria de consentimento necessária */
+    category: string;
+    /** URL do script */
+    src: string;
+    /** Função de inicialização após carregamento */
+    init?: () => void;
+    /** Atributos adicionais do script */
+    attrs?: Record<string, string>;
+}
+/**
+ * Configuração para Google Analytics 4.
+ */
+interface GoogleAnalyticsConfig {
+    measurementId: string;
+    config?: any;
+}
+/**
+ * Configuração para Google Tag Manager.
+ */
+interface GoogleTagManagerConfig {
+    containerId: string;
+    dataLayerName?: string;
+}
+/**
+ * Configuração para UserWay (acessibilidade).
+ */
+interface UserWayConfig {
+    accountId: string;
+}
+/**
+ * Cria integração para Google Analytics 4.
+ */
+declare function createGoogleAnalyticsIntegration(config: GoogleAnalyticsConfig): ScriptIntegration;
+/**
+ * Cria integração para Google Tag Manager.
+ */
+declare function createGoogleTagManagerIntegration(config: GoogleTagManagerConfig): ScriptIntegration;
 /**
- * Preferências de consentimento do usuário para cada categoria.
+ * Cria integração para UserWay (acessibilidade).
+ */
+declare function createUserWayIntegration(config: UserWayConfig): ScriptIntegration;
+/**
+ * Integrações pré-configuradas mais comuns.
+ */
+declare const COMMON_INTEGRATIONS: {
+    googleAnalytics: typeof createGoogleAnalyticsIntegration;
+    googleTagManager: typeof createGoogleTagManagerIntegration;
+    userway: typeof createUserWayIntegration;
+};
+
+/**
+ * Categorias padrão de consentimento para cookies baseadas no Guia da ANPD.
+ *
+ * - necessary: Cookies essenciais (sempre ativos)
+ * - analytics: Análise e estatísticas
+ * - functional: Funcionalidades extras
+ * - marketing: Publicidade e marketing
+ * - social: Integração com redes sociais
+ * - personalization: Personalização de conteúdo
+ */
+type Category = 'necessary' | 'analytics' | 'functional' | 'marketing' | 'social' | 'personalization';
+/**
+ * Definição detalhada de uma categoria de cookie.
+ */
+interface CategoryDefinition {
+    /** ID único da categoria */
+    id: string;
+    /** Nome amigável exibido na interface */
+    name: string;
+    /** Descrição detalhada da categoria */
+    description: string;
+    /** Se é uma categoria essencial (não pode ser desabilitada) */
+    essential?: boolean;
+    /** Scripts/cookies específicos desta categoria */
+    cookies?: string[];
+}
+/**
+ * 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 {
-    analytics: boolean;
-    marketing: boolean;
+    necessary: 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;
 }
 /**
@@ -152,6 +259,14 @@ interface ConsentTexts {
     modalIntro: string;
     save: string;
     necessaryAlwaysOn: string;
+    controllerInfo?: string;
+    dataTypes?: string;
+    thirdPartySharing?: string;
+    userRights?: string;
+    contactInfo?: string;
+    retentionPeriod?: string;
+    lawfulBasis?: string;
+    transferCountries?: string;
 }
 /**
  * Opções para configuração do cookie de consentimento.
@@ -172,18 +287,29 @@ 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. */
+    /** Tema customizado para os componentes MUI. Aceita qualquer propriedade. */
     theme?: any;
+    /**
+     * @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[];
     /** Componente customizado para modal de preferências. */
     PreferencesModalComponent?: React.ComponentType<any>;
     /** Props adicionais para o modal customizado. */
     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. */
@@ -236,7 +362,7 @@ interface ConsentContextValue {
  *   <App />
  * </ConsentProvider>
  */
-declare function ConsentProvider({ initialState, texts: textsProp, theme, PreferencesModalComponent, preferencesModalProps, disableAutomaticModal, hideBranding, onConsentGiven, onPreferencesSaved, cookie: cookieOpts, children, }: Readonly<ConsentProviderProps>): react_jsx_runtime.JSX.Element;
+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;
 
 /**
  * Hook principal para acessar e manipular o estado de consentimento de cookies.
@@ -271,8 +397,18 @@ 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).
+ */
+declare function useCustomCategories(): CategoryDefinition[];
+/**
+ * Hook para obter todas as categorias (padrão + customizadas).
+ */
+declare function useAllCategories(): CategoryDefinition[];
+
 declare function ConsentGate(props: Readonly<{
-    category: Category;
+    category: string;
     children: React$1.ReactNode;
 }>): react_jsx_runtime.JSX.Element | null;
 
@@ -301,4 +437,49 @@ declare function loadScript(id: string, src: string, category?: 'analytics' | 'm
  */
 declare const defaultConsentTheme: _mui_material_styles.Theme;
 
-export { type Category, type ConsentCookieOptions, ConsentGate, type ConsentPreferences, ConsentProvider, type ConsentState, type ConsentTexts, CookieBanner, FloatingPreferencesButton, PreferencesModal, defaultConsentTheme, loadScript, useConsent, useConsentHydration, useConsentTexts };
+/**
+ * Componente que carrega scripts automaticamente baseado no consentimento.
+ * Facilita integração com ferramentas como Google Analytics, Tag Manager, etc.
+ */
+
+interface ConsentScriptLoaderProps {
+    /** Lista de integrações de scripts para carregar baseado no consentimento */
+    integrations: ScriptIntegration[];
+    /** Se true, força recarregamento se consentimento mudar */
+    reloadOnChange?: boolean;
+}
+/**
+ * Componente para carregamento automático de scripts baseado no consentimento.
+ *
+ * @example
+ * ```tsx
+ * const integrations = [
+ *   createGoogleAnalyticsIntegration({ measurementId: 'GA_ID' }),
+ *   createUserWayIntegration({ accountId: 'USERWAY_ID' })
+ * ]
+ *
+ * <ConsentScriptLoader integrations={integrations} />
+ * ```
+ */
+declare function ConsentScriptLoader({ integrations, reloadOnChange, }: Readonly<ConsentScriptLoaderProps>): null;
+/**
+ * Hook para carregamento manual de scripts baseado no consentimento.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const loadConsentScript = useConsentScriptLoader()
+ *
+ *   React.useEffect(() => {
+ *     loadConsentScript({
+ *       id: 'my-script',
+ *       category: 'analytics',
+ *       src: 'https://example.com/script.js'
+ *     })
+ *   }, [])
+ * }
+ * ```
+ */
+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 };

package/dist/index.d.ts

@@ -100,24 +100,131 @@ interface FloatingPreferencesButtonProps {
 declare function FloatingPreferencesButton({ position, offset, icon, tooltip, FabProps, hideWhenConsented, }: Readonly<FloatingPreferencesButtonProps>): react_jsx_runtime.JSX.Element | null;
 
 /**
- * Categoria de consentimento para cookies.
- * Pode ser 'analytics' ou 'marketing'.
+ * Integrações nativas com scripts de terceiros.
+ * Facilita o carregamento automático baseado em consentimento.
  */
-type Category = 'analytics' | 'marketing';
+interface ScriptIntegration {
+    /** ID único da integração */
+    id: string;
+    /** Categoria de consentimento necessária */
+    category: string;
+    /** URL do script */
+    src: string;
+    /** Função de inicialização após carregamento */
+    init?: () => void;
+    /** Atributos adicionais do script */
+    attrs?: Record<string, string>;
+}
+/**
+ * Configuração para Google Analytics 4.
+ */
+interface GoogleAnalyticsConfig {
+    measurementId: string;
+    config?: any;
+}
+/**
+ * Configuração para Google Tag Manager.
+ */
+interface GoogleTagManagerConfig {
+    containerId: string;
+    dataLayerName?: string;
+}
+/**
+ * Configuração para UserWay (acessibilidade).
+ */
+interface UserWayConfig {
+    accountId: string;
+}
+/**
+ * Cria integração para Google Analytics 4.
+ */
+declare function createGoogleAnalyticsIntegration(config: GoogleAnalyticsConfig): ScriptIntegration;
+/**
+ * Cria integração para Google Tag Manager.
+ */
+declare function createGoogleTagManagerIntegration(config: GoogleTagManagerConfig): ScriptIntegration;
 /**
- * Preferências de consentimento do usuário para cada categoria.
+ * Cria integração para UserWay (acessibilidade).
+ */
+declare function createUserWayIntegration(config: UserWayConfig): ScriptIntegration;
+/**
+ * Integrações pré-configuradas mais comuns.
+ */
+declare const COMMON_INTEGRATIONS: {
+    googleAnalytics: typeof createGoogleAnalyticsIntegration;
+    googleTagManager: typeof createGoogleTagManagerIntegration;
+    userway: typeof createUserWayIntegration;
+};
+
+/**
+ * Categorias padrão de consentimento para cookies baseadas no Guia da ANPD.
+ *
+ * - necessary: Cookies essenciais (sempre ativos)
+ * - analytics: Análise e estatísticas
+ * - functional: Funcionalidades extras
+ * - marketing: Publicidade e marketing
+ * - social: Integração com redes sociais
+ * - personalization: Personalização de conteúdo
+ */
+type Category = 'necessary' | 'analytics' | 'functional' | 'marketing' | 'social' | 'personalization';
+/**
+ * Definição detalhada de uma categoria de cookie.
+ */
+interface CategoryDefinition {
+    /** ID único da categoria */
+    id: string;
+    /** Nome amigável exibido na interface */
+    name: string;
+    /** Descrição detalhada da categoria */
+    description: string;
+    /** Se é uma categoria essencial (não pode ser desabilitada) */
+    essential?: boolean;
+    /** Scripts/cookies específicos desta categoria */
+    cookies?: string[];
+}
+/**
+ * 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 {
-    analytics: boolean;
-    marketing: boolean;
+    necessary: 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;
 }
 /**
@@ -152,6 +259,14 @@ interface ConsentTexts {
     modalIntro: string;
     save: string;
     necessaryAlwaysOn: string;
+    controllerInfo?: string;
+    dataTypes?: string;
+    thirdPartySharing?: string;
+    userRights?: string;
+    contactInfo?: string;
+    retentionPeriod?: string;
+    lawfulBasis?: string;
+    transferCountries?: string;
 }
 /**
  * Opções para configuração do cookie de consentimento.
@@ -172,18 +287,29 @@ 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. */
+    /** Tema customizado para os componentes MUI. Aceita qualquer propriedade. */
     theme?: any;
+    /**
+     * @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[];
     /** Componente customizado para modal de preferências. */
     PreferencesModalComponent?: React.ComponentType<any>;
     /** Props adicionais para o modal customizado. */
     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. */
@@ -236,7 +362,7 @@ interface ConsentContextValue {
  *   <App />
  * </ConsentProvider>
  */
-declare function ConsentProvider({ initialState, texts: textsProp, theme, PreferencesModalComponent, preferencesModalProps, disableAutomaticModal, hideBranding, onConsentGiven, onPreferencesSaved, cookie: cookieOpts, children, }: Readonly<ConsentProviderProps>): react_jsx_runtime.JSX.Element;
+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;
 
 /**
  * Hook principal para acessar e manipular o estado de consentimento de cookies.
@@ -271,8 +397,18 @@ 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).
+ */
+declare function useCustomCategories(): CategoryDefinition[];
+/**
+ * Hook para obter todas as categorias (padrão + customizadas).
+ */
+declare function useAllCategories(): CategoryDefinition[];
+
 declare function ConsentGate(props: Readonly<{
-    category: Category;
+    category: string;
     children: React$1.ReactNode;
 }>): react_jsx_runtime.JSX.Element | null;
 
@@ -301,4 +437,49 @@ declare function loadScript(id: string, src: string, category?: 'analytics' | 'm
  */
 declare const defaultConsentTheme: _mui_material_styles.Theme;
 
-export { type Category, type ConsentCookieOptions, ConsentGate, type ConsentPreferences, ConsentProvider, type ConsentState, type ConsentTexts, CookieBanner, FloatingPreferencesButton, PreferencesModal, defaultConsentTheme, loadScript, useConsent, useConsentHydration, useConsentTexts };
+/**
+ * Componente que carrega scripts automaticamente baseado no consentimento.
+ * Facilita integração com ferramentas como Google Analytics, Tag Manager, etc.
+ */
+
+interface ConsentScriptLoaderProps {
+    /** Lista de integrações de scripts para carregar baseado no consentimento */
+    integrations: ScriptIntegration[];
+    /** Se true, força recarregamento se consentimento mudar */
+    reloadOnChange?: boolean;
+}
+/**
+ * Componente para carregamento automático de scripts baseado no consentimento.
+ *
+ * @example
+ * ```tsx
+ * const integrations = [
+ *   createGoogleAnalyticsIntegration({ measurementId: 'GA_ID' }),
+ *   createUserWayIntegration({ accountId: 'USERWAY_ID' })
+ * ]
+ *
+ * <ConsentScriptLoader integrations={integrations} />
+ * ```
+ */
+declare function ConsentScriptLoader({ integrations, reloadOnChange, }: Readonly<ConsentScriptLoaderProps>): null;
+/**
+ * Hook para carregamento manual de scripts baseado no consentimento.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const loadConsentScript = useConsentScriptLoader()
+ *
+ *   React.useEffect(() => {
+ *     loadConsentScript({
+ *       id: 'my-script',
+ *       category: 'analytics',
+ *       src: 'https://example.com/script.js'
+ *     })
+ *   }, [])
+ * }
+ * ```
+ */
+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 };