react-lgpd-consent 0.2.5 → 0.3.1

package/dist/index.d.ts

@@ -1,44 +1,8 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { PaperProps } from '@mui/material/Paper';
-import { SnackbarProps } from '@mui/material/Snackbar';
 import { DialogProps } from '@mui/material/Dialog';
-import { FabProps } from '@mui/material/Fab';
 import * as React$1 from 'react';
 import * as _mui_material_styles from '@mui/material/styles';
 
-/**
- * Props para o componente CookieBanner.
- *
- * @property policyLinkUrl URL da política de privacidade (opcional).
- * @property debug Força exibição do banner para QA/debug (opcional).
- * @property blocking Se true, bloqueia interação até decisão do usuário (default: true).
- * @property hideBranding Se true, oculta o branding "fornecido por LÉdipO.eti.br" (opcional).
- * @property SnackbarProps Props adicionais para o componente MUI Snackbar (opcional).
- * @property PaperProps Props adicionais para o componente MUI Paper (opcional).
- */
-interface CookieBannerProps {
-    policyLinkUrl?: string;
-    debug?: boolean;
-    blocking?: boolean;
-    hideBranding?: boolean;
-    SnackbarProps?: Partial<SnackbarProps>;
-    PaperProps?: Partial<PaperProps>;
-}
-/**
- * Banner de consentimento de cookies conforme LGPD.
- *
- * Exibe mensagem informativa, botões de ação e link para política de privacidade.
- * Compatível com modo bloqueante (overlay) e não bloqueante (Snackbar).
- *
- * - Textos em pt-BR, customizáveis via contexto.
- * - Acessível e responsivo.
- * - Branding opcional.
- *
- * @param props Propriedades do banner de consentimento.
- */
-declare function CookieBanner({ policyLinkUrl, debug, blocking, // Por padrão, bloqueia até decisão
-hideBranding, SnackbarProps, PaperProps, }: Readonly<CookieBannerProps>): react_jsx_runtime.JSX.Element | null;
-
 /**
  * Props para o componente PreferencesModal.
  *
@@ -60,45 +24,6 @@ interface PreferencesModalProps {
  */
 declare function PreferencesModal({ DialogProps, hideBranding, }: Readonly<PreferencesModalProps>): react_jsx_runtime.JSX.Element;
 
-/**
- * Props para o componente FloatingPreferencesButton.
- *
- * Permite configurar posição, ícone, tooltip, e comportamento de exibição do botão flutuante
- * para abrir o modal de preferências de cookies LGPD.
- *
- * Todos os campos são opcionais e possuem valores padrão.
- */
-interface FloatingPreferencesButtonProps {
-    /** Posição do botão flutuante. Padrão: 'bottom-right' */
-    position?: 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right';
-    /** Offset da borda em pixels. Padrão: 24 */
-    offset?: number;
-    /** Ícone customizado. Padrão: CookieOutlined */
-    icon?: React.ReactNode;
-    /** Tooltip customizado exibido ao passar o mouse */
-    tooltip?: string;
-    /** Props adicionais para o Fab do MUI */
-    FabProps?: Partial<FabProps>;
-    /** Se deve esconder quando consentimento já foi dado. Padrão: false */
-    hideWhenConsented?: boolean;
-}
-/**
- * Botão flutuante para abrir o modal de preferências de cookies.
- *
- * Permite ao usuário acessar rapidamente as configurações de consentimento LGPD.
- * Pode ser posicionado em qualquer canto da tela e customizado via props.
- *
- * @param position Posição do botão na tela. Padrão: 'bottom-right'.
- * @param offset Distância da borda em pixels. Padrão: 24.
- * @param icon Ícone customizado para o botão. Padrão: CookieOutlined.
- * @param tooltip Texto do tooltip exibido ao passar o mouse. Padrão: 'Gerenciar Preferências de Cookies'.
- * @param FabProps Props adicionais para o componente Fab do MUI.
- * @param hideWhenConsented Se verdadeiro, esconde o botão após consentimento. Padrão: false.
- *
- * @returns JSX.Element | null
- */
-declare function FloatingPreferencesButton({ position, offset, icon, tooltip, FabProps, hideWhenConsented, }: Readonly<FloatingPreferencesButtonProps>): react_jsx_runtime.JSX.Element | null;
-
 /**
  * Integrações nativas com scripts de terceiros.
  * Facilita o carregamento automático baseado em consentimento.
@@ -137,14 +62,24 @@ interface UserWayConfig {
 }
 /**
  * Cria integração para Google Analytics 4.
+ *
+ * @param config Configuração do Google Analytics, contendo o `measurementId`.
+ * @returns Um objeto de integração de script para ser usado com `ConsentScriptLoader`.
  */
 declare function createGoogleAnalyticsIntegration(config: GoogleAnalyticsConfig): ScriptIntegration;
 /**
  * Cria integração para Google Tag Manager.
+ *
+ * @param config Configuração do GTM, contendo o `containerId`.
+ * @returns Um objeto de integração de script.
  */
 declare function createGoogleTagManagerIntegration(config: GoogleTagManagerConfig): ScriptIntegration;
 /**
- * Cria integração para UserWay (acessibilidade).
+ * Cria integração para UserWay (widget de acessibilidade).
+ * A categoria padrão foi alterada para 'functional', por ser mais apropriada.
+ *
+ * @param config Configuração do UserWay, contendo o `accountId`.
+ * @returns Um objeto de integração de script.
  */
 declare function createUserWayIntegration(config: UserWayConfig): ScriptIntegration;
 /**
@@ -157,14 +92,16 @@ declare const COMMON_INTEGRATIONS: {
 };
 
 /**
- * Categorias padrão de consentimento para cookies baseadas no Guia da ANPD.
+ * Tipos de categorias padrão de consentimento para cookies, conforme definido pela 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
+ * @remarks
+ * Use este tipo para identificar as categorias principais de cookies suportadas nativamente pela biblioteca.
+ * - `'necessary'`: Cookies essenciais para funcionamento do site (sempre ativos).
+ * - `'analytics'`: Cookies para análise e estatísticas de uso.
+ * - `'functional'`: Cookies para funcionalidades extras e preferências do usuário.
+ * - `'marketing'`: Cookies para publicidade e marketing direcionado.
+ * - `'social'`: Cookies para integração com redes sociais.
+ * - `'personalization'`: Cookies para personalização de conteúdo e experiência.
  */
 type Category = 'necessary' | 'analytics' | 'functional' | 'marketing' | 'social' | 'personalization';
 /**
@@ -190,8 +127,6 @@ interface CategoryDefinition {
 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.
@@ -218,6 +153,8 @@ interface ConsentCookieData {
     lastUpdate: string;
     /** Origem da decisão de consentimento */
     source: 'banner' | 'modal' | 'programmatic';
+    /** Snapshot da configuração de categorias usada para este consentimento */
+    projectConfig?: ProjectCategoriesConfig;
 }
 /**
  * Estado interno completo do consentimento (memória + UI).
@@ -259,6 +196,13 @@ interface ConsentTexts {
     modalIntro: string;
     save: string;
     necessaryAlwaysOn: string;
+    preferencesButton?: string;
+    preferencesTitle?: string;
+    preferencesDescription?: string;
+    close?: string;
+    accept?: string;
+    reject?: string;
+    brandingPoweredBy?: string;
     controllerInfo?: string;
     dataTypes?: string;
     thirdPartySharing?: string;
@@ -283,6 +227,47 @@ interface ConsentCookieOptions {
     /** Caminho do cookie. Padrão: '/' */
     path: string;
 }
+/**
+ * Tokens de design para customização visual avançada dos componentes.
+ * Permite um controle mais direto sobre a aparência sem a necessidade de `sx` props complexas.
+ */
+interface DesignTokens {
+    colors?: {
+        background?: string;
+        text?: string;
+        primary?: string;
+        secondary?: string;
+    };
+    typography?: {
+        fontFamily?: string;
+        fontSize?: {
+            banner?: string;
+            modal?: string;
+        };
+        fontWeight?: {
+            normal?: number;
+            bold?: number;
+        };
+    };
+    spacing?: {
+        padding?: {
+            banner?: string | number;
+            modal?: string | number;
+        };
+        borderRadius?: {
+            banner?: string | number;
+            modal?: string | number;
+        };
+    };
+    layout?: {
+        position?: 'bottom' | 'top' | 'floating';
+        width?: {
+            mobile?: string;
+            desktop?: string;
+        };
+        backdrop?: boolean;
+    };
+}
 /**
  * Propriedades do componente ConsentProvider - configuração principal da biblioteca.
  *
@@ -300,12 +285,6 @@ interface ConsentCookieOptions {
  * <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...',
@@ -333,24 +312,16 @@ interface ConsentProviderProps {
     initialState?: ConsentState;
     /**
      * Configuração das categorias de cookies utilizadas no projeto.
-     * Define quais categorias padrão serão habilitadas e categorias customizadas.
+     * Define quais categorias padrão serão habilitadas.
      *
      * @example Apenas analytics:
      * ```tsx
      * categories={{ enabledCategories: ['analytics'] }}
      * ```
      *
-     * @example Com categoria customizada:
+     * @example Com categoria padrão apenas:
      * ```tsx
-     * categories={{
-     *   enabledCategories: ['analytics', 'marketing'],
-     *   customCategories: [{
-     *     id: 'pesquisa',
-     *     name: 'Cookies de Pesquisa',
-     *     description: 'Coleta feedback e opinião dos usuários',
-     *     essential: false
-     *   }]
-     * }}
+     * categories={{ enabledCategories: ['analytics', 'marketing'] }}
      * ```
      */
     categories?: ProjectCategoriesConfig;
@@ -391,10 +362,19 @@ interface ConsentProviderProps {
      */
     theme?: any;
     /**
-     * @deprecated Usar `categories.customCategories` em vez disso.
-     * Mantido para compatibilidade com v0.1.x
+     * Tokens de design para customização visual avançada.
+     * Oferece controle direto sobre cores, fontes, espaçamento e layout.
+     *
+     * @example
+     * ```tsx
+     * designTokens={{
+     *   colors: { background: '#000', text: '#fff' },
+     *   typography: { fontFamily: ''Inter', sans-serif' },
+     *   spacing: { borderRadius: { banner: 0 } }
+     * }}
+     * ```
      */
-    customCategories?: CategoryDefinition[];
+    designTokens?: DesignTokens;
     /**
      * Integrações nativas de scripts terceiros (Google Analytics, etc.).
      * Scripts são carregados automaticamente baseado no consentimento.
@@ -411,16 +391,32 @@ interface ConsentProviderProps {
     scriptIntegrations?: ScriptIntegration[];
     /**
      * Componente customizado para substituir o modal padrão de preferências.
-     * Deve implementar a lógica de consentimento usando os hooks da biblioteca.
+     * Deve implementar a lógica de consentimento usando as props definidas em `CustomPreferencesModalProps`.
      */
-    PreferencesModalComponent?: React.ComponentType<any>;
+    PreferencesModalComponent?: React.ComponentType<CustomPreferencesModalProps>;
     /** Props adicionais passadas para o modal customizado. */
     preferencesModalProps?: Record<string, any>;
     /**
-     * Desabilita o modal automático de preferências.
-     * Útil quando se quer controle total sobre quando/como exibir as opções.
+     * Componente customizado para substituir o banner padrão de cookies.
+     * Se não fornecido, o `CookieBanner` padrão será renderizado.
+     * Deve implementar a lógica de consentimento usando as props definidas em `CustomCookieBannerProps`.
      */
-    disableAutomaticModal?: boolean;
+    CookieBannerComponent?: React.ComponentType<CustomCookieBannerProps>;
+    /** Props adicionais passadas para o banner customizado. */
+    cookieBannerProps?: Record<string, any>;
+    /**
+     * Componente customizado para substituir o botão flutuante de preferências.
+     * Se não fornecido, o `FloatingPreferencesButton` padrão será renderizado.
+     * Deve implementar a lógica de consentimento usando as props definidas em `CustomFloatingPreferencesButtonProps`.
+     */
+    FloatingPreferencesButtonComponent?: React.ComponentType<CustomFloatingPreferencesButtonProps>;
+    /** Props adicionais passadas para o botão flutuante customizado. */
+    floatingPreferencesButtonProps?: Record<string, any>;
+    /**
+     * Desabilita o botão flutuante de preferências.
+     * Útil quando o usuário da lib quer ter controle total sobre o acesso às preferências.
+     */
+    disableFloatingPreferencesButton?: boolean;
     /**
      * Comportamento do banner de consentimento:
      * - `false` (padrão): Banner não-intrusivo, usuário pode navegar livremente
@@ -478,6 +474,44 @@ interface ConsentProviderProps {
     /** Elementos filhos - toda a aplicação que precisa de contexto de consentimento. */
     children: React.ReactNode;
 }
+/**
+ * Props esperadas por um componente customizado de CookieBanner.
+ * Fornece acesso ao estado de consentimento e ações necessárias para o banner.
+ */
+interface CustomCookieBannerProps {
+    consented: boolean;
+    acceptAll: () => void;
+    rejectAll: () => void;
+    openPreferences: () => void;
+    texts: ConsentTexts;
+}
+/**
+ * Props esperadas por um componente customizado de PreferencesModal.
+ *
+ * Fornece acesso às preferências atuais do usuário, funções para atualizar e salvar preferências,
+ * fechar o modal e textos customizados da interface.
+ *
+ * @property preferences Preferências atuais de consentimento do usuário.
+ * @property setPreferences Função para atualizar e salvar as preferências.
+ * @property closePreferences Função para fechar o modal de preferências.
+ * @property isModalOpen Indica se o modal está aberto (opcional).
+ * @property texts Textos customizados da interface de consentimento.
+ */
+interface CustomPreferencesModalProps {
+    preferences: ConsentPreferences;
+    setPreferences: (preferences: ConsentPreferences) => void;
+    closePreferences: () => void;
+    isModalOpen?: boolean;
+    texts: ConsentTexts;
+}
+/**
+ * Props esperadas por um componente customizado de FloatingPreferencesButton.
+ * Fornece acesso às ações de abertura do modal e ao estado de consentimento.
+ */
+interface CustomFloatingPreferencesButtonProps {
+    openPreferences: () => void;
+    consented: boolean;
+}
 /**
  * Valor do contexto de consentimento, incluindo estado e métodos de manipulação.
  */
@@ -519,11 +553,9 @@ interface ConsentContextValue {
  *   <App />
  * </ConsentProvider>
  */
-declare function ConsentProvider({ initialState, categories, // NOVO: configuração completa de categorias
-texts: textsProp, theme, customCategories, // LEGACY: compatibilidade
-scriptIntegrations, // eslint-disable-line no-unused-vars
-PreferencesModalComponent, preferencesModalProps, disableAutomaticModal, hideBranding, onConsentGiven, onPreferencesSaved, cookie: cookieOpts, disableDeveloperGuidance, // NOVO: desabilita avisos de dev
-children, }: Readonly<ConsentProviderProps>): react_jsx_runtime.JSX.Element;
+declare function ConsentProvider({ initialState, categories, // Nova prop para configuração de categorias
+texts: textsProp, theme, designTokens, scriptIntegrations, // eslint-disable-line no-unused-vars
+PreferencesModalComponent, preferencesModalProps, CookieBannerComponent, cookieBannerProps, FloatingPreferencesButtonComponent, floatingPreferencesButtonProps, disableFloatingPreferencesButton, hideBranding, onConsentGiven, onPreferencesSaved, cookie: cookieOpts, disableDeveloperGuidance, children, }: Readonly<ConsentProviderProps>): react_jsx_runtime.JSX.Element;
 
 /**
  * Hook principal para acessar e manipular o estado de consentimento de cookies.
@@ -557,6 +589,27 @@ declare function useConsentTexts(): ConsentTexts;
  * Útil para evitar flash do banner antes de verificar cookies existentes.
  */
 declare function useConsentHydration(): boolean;
+/**
+ * Hook para abrir o modal de preferências programaticamente.
+ * Útil quando você tem controle customizado sobre como o modal é aberto.
+ *
+ * @returns Função para abrir o modal de preferências.
+ *
+ * @example
+ * ```tsx
+ * function CustomAccessibilityDock() {
+ *   const openPreferencesModal = useOpenPreferencesModal()
+ *
+ *   return (
+ *     <button onClick={openPreferencesModal}>
+ *       ⚙️ Configurar Cookies
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
+declare function useOpenPreferencesModal(): () => void;
+declare function openPreferencesModal(): void;
 
 /**
  * Sistema de orientações para developers sobre configuração de categorias.
@@ -601,8 +654,6 @@ interface CategoriesContextValue {
     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.
@@ -619,13 +670,6 @@ declare function useCategoryStatus(categoryId: string): {
     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;
@@ -702,4 +746,28 @@ 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, 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 };
+/**
+ * Sistema de logging interno da biblioteca para facilitar debug e troubleshooting.
+ * Os logs são desabilitados automaticamente em production builds.
+ */
+declare enum LogLevel {
+    ERROR = 0,
+    WARN = 1,
+    INFO = 2,
+    DEBUG = 3
+}
+/**
+ * Função para habilitar/desabilitar logs de debug externamente.
+ * Útil para troubleshooting em produção quando necessário.
+ *
+ * @example
+ * ```typescript
+ * import { setDebugLogging } from 'react-lgpd-consent'
+ *
+ * // Habilitar logs detalhados
+ * setDebugLogging(true, LogLevel.DEBUG)
+ * ```
+ */
+declare function setDebugLogging(enabled: boolean, level?: LogLevel): void;
+
+export { COMMON_INTEGRATIONS, type Category, type CategoryDefinition, type ConsentCookieOptions, ConsentGate, type ConsentPreferences, ConsentProvider, type ConsentProviderProps, ConsentScriptLoader, type ConsentState, type ConsentTexts, type CustomCookieBannerProps, type CustomFloatingPreferencesButtonProps, type CustomPreferencesModalProps, DEFAULT_PROJECT_CATEGORIES, type DeveloperGuidance, type GoogleAnalyticsConfig, type GoogleTagManagerConfig, LogLevel, PreferencesModal, type ProjectCategoriesConfig, type ScriptIntegration, type UserWayConfig, analyzeDeveloperConfiguration, createGoogleAnalyticsIntegration, createGoogleTagManagerIntegration, createUserWayIntegration, defaultConsentTheme, loadScript, openPreferencesModal, setDebugLogging, useCategories, useCategoryStatus, useConsent, useConsentHydration, useConsentScriptLoader, useConsentTexts, useOpenPreferencesModal };