react-lgpd-consent 0.3.0 → 0.3.2

package/dist/index.d.cts

@@ -2,174 +2,457 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import { DialogProps } from '@mui/material/Dialog';
 import * as React$1 from 'react';
 import * as _mui_material_styles from '@mui/material/styles';
+import { PaperProps } from '@mui/material/Paper';
+import { SnackbarProps } from '@mui/material/Snackbar';
+import { FabProps } from '@mui/material/Fab';
 
 /**
- * Props para o componente PreferencesModal.
- *
- * @property DialogProps Props opcionais para customizar o Dialog do Material-UI.
- * @property hideBranding Se true, oculta o branding "fornecido por LÉdipO.eti.br".
+ * @interface PreferencesModalProps
+ * Propriedades para customizar o componente `PreferencesModal`.
  */
 interface PreferencesModalProps {
+    /** Propriedades opcionais para customizar o componente `Dialog` do Material-UI. */
     DialogProps?: Partial<DialogProps>;
+    /** Se `true`, oculta a marca "fornecido por LÉdipO.eti.br" no modal. Padrão: `false`. */
     hideBranding?: boolean;
 }
 /**
- * Modal de preferências de cookies.
- *
- * Permite ao usuário ajustar suas preferências de consentimento para cookies analíticos e de marketing.
- * Utiliza Material-UI Dialog, switches para cada categoria e textos customizáveis via contexto.
- * Acessível, responsivo e compatível com SSR.
- *
- * @param props Props do modal, incluindo customização do Dialog e opção de ocultar branding.
+ * O `PreferencesModal` é o componente de UI que permite ao usuário ajustar suas preferências de consentimento.
+ * @component
+ * @category Components
+ * @since 0.1.0
+ * @remarks
+ * Este modal é renderizado automaticamente pelo `ConsentProvider` quando o usuário clica para gerenciar as preferências.
+ * Você pode substituí-lo passando seu próprio componente para a prop `PreferencesModalComponent`
+ * no `ConsentProvider` para ter controle total sobre a aparência e o comportamento do modal.
+ * @param {Readonly<PreferencesModalProps>} props As propriedades para customizar o modal.
+ * @returns {JSX.Element} O componente do modal de preferências.
+ * @example
+ * ```tsx
+ * <PreferencesModal DialogProps={{ maxWidth: 'md' }} hideBranding={true} />
+ * ```
  */
 declare function PreferencesModal({ DialogProps, hideBranding, }: Readonly<PreferencesModalProps>): react_jsx_runtime.JSX.Element;
 
 /**
- * Integrações nativas com scripts de terceiros.
- * Facilita o carregamento automático baseado em consentimento.
- */
-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.
- *
- * @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.
+ * @fileoverview
+ * Definições de tipos TypeScript para o sistema de consentimento LGPD/ANPD.
  *
- * @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 (widget de acessibilidade).
- * A categoria padrão foi alterada para 'functional', por ser mais apropriada.
+ * Este arquivo contém todas as interfaces, tipos e estruturas de dados utilizadas
+ * pela biblioteca react-lgpd-consent, incluindo definições de categorias,
+ * estado de consentimento, configurações e textos da interface.
  *
- * @param config Configuração do UserWay, contendo o `accountId`.
- * @returns Um objeto de integração de script.
+ * @author Luciano Édipo
+ * @since 0.1.0
  */
-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;
-};
-
 /**
  * Tipos de categorias padrão de consentimento para cookies, conforme definido pela ANPD.
+ * @category Types
+ * @since 0.2.0
  *
  * @remarks
  * Use este tipo para identificar as categorias principais de cookies suportadas nativamente pela biblioteca.
+ * Cada categoria representa um tipo específico de processamento de dados:
+ *
  * - `'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.
+ *
+ * @example
+ * ```typescript
+ * const categories: Category[] = ['analytics', 'marketing'];
+ * ```
+ *
+ * @public
  */
 type Category = 'necessary' | 'analytics' | 'functional' | 'marketing' | 'social' | 'personalization';
 /**
- * Definição detalhada de uma categoria de cookie.
+ * Definição detalhada de uma categoria de cookie para uso interno.
+ * @category Types
+ * @since 0.2.0
+ *
+ * @remarks
+ * Esta interface define a estrutura completa de uma categoria de cookies,
+ * incluindo metadados e configurações específicas para processamento
+ * e exibição na interface do usuário.
+ *
+ * @example
+ * ```typescript
+ * const analyticsCategory: CategoryDefinition = {
+ *   id: 'analytics',
+ *   name: 'Cookies Analíticos',
+ *   description: 'Utilizados para análise de uso do site',
+ *   essential: false,
+ *   cookies: ['_ga', '_ga_*', '_gid']
+ * };
+ * ```
+ *
+ * @public
  */
 interface CategoryDefinition {
-    /** ID único da categoria */
+    /**
+     * Identificador único da categoria.
+     * @example 'analytics'
+     */
     id: string;
-    /** Nome amigável exibido na interface */
+    /**
+     * Nome amigável exibido na interface do usuário.
+     * @example 'Cookies Analíticos'
+     */
     name: string;
-    /** Descrição detalhada da categoria */
+    /**
+     * Descrição detalhada da finalidade da categoria.
+     * @example 'Utilizados para análise de uso e comportamento no site'
+     */
     description: string;
-    /** Se é uma categoria essencial (não pode ser desabilitada) */
+    /**
+     * Indica se é uma categoria essencial que não pode ser desabilitada pelo usuário.
+     * @defaultValue false
+     */
     essential?: boolean;
-    /** Scripts/cookies específicos desta categoria */
+    /**
+     * Lista de nomes de cookies ou padrões específicos desta categoria.
+     * @example ['_ga', '_ga_*', '_gid']
+     */
     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.
+ * @category Types
+ * @since 0.2.0
+ *
+ * @remarks
+ * Define quais categorias fixas serão usadas (além de 'necessary' que é sempre incluída)
+ * e permite extensão com categorias customizadas específicas do projeto.
+ *
+ * A categoria 'necessary' é sempre incluída automaticamente e não precisa ser
+ * especificada em `enabledCategories`.
+ *
+ * @example
+ * ```typescript
+ * // Configuração básica
+ * const config: ProjectCategoriesConfig = {
+ *   enabledCategories: ['analytics', 'marketing']
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Configuração com categorias customizadas
+ * const config: ProjectCategoriesConfig = {
+ *   enabledCategories: ['analytics'],
+ *   customCategories: [{
+ *     id: 'support',
+ *     name: 'Suporte',
+ *     description: 'Cookies para sistema de suporte ao cliente'
+ *   }]
+ * };
+ * ```
+ *
+ * @public
  */
 interface ProjectCategoriesConfig {
-    /** Categorias padrão que serão ativadas (necessary sempre incluída automaticamente) */
+    /**
+     * Categorias padrão que serão ativadas.
+     * A categoria 'necessary' é sempre incluída automaticamente.
+     * @example ['analytics', 'marketing']
+     */
     enabledCategories?: Category[];
+    /**
+     * Categorias customizadas específicas do projeto.
+     * Permite extensão além das categorias padrão da biblioteca.
+     */
+    customCategories?: CategoryDefinition[];
 }
 /**
- * Preferências de consentimento do usuário.
- * Contém apenas as categorias realmente utilizadas no projeto.
+ * Preferências de consentimento do usuário por categoria.
+ * @category Types
+ * @since 0.1.0
+ *
+ * @remarks
+ * Contém o estado de consentimento para cada categoria ativa no projeto.
+ * A categoria 'necessary' está sempre presente e definida como `true`,
+ * pois cookies essenciais não podem ser desabilitados pelo usuário.
+ *
+ * ### Comportamento Dinâmico
+ * - As chaves são determinadas pela configuração de `enabledCategories` no `ConsentProvider`
+ * - Categorias não habilitadas no projeto não aparecem no objeto
+ * - TypeScript infere automaticamente as chaves baseado na configuração
+ * - Estado é persistido no cookie e restaurado em novas sessões
+ *
+ * ### Valores e Significados
+ * - `true`: Usuário consentiu explicitamente para a categoria
+ * - `false`: Usuário rejeitou explicitamente a categoria
+ * - Ausência da chave: Categoria não está habilitada no projeto
+ *
+ * ### Integração com Scripts
+ * - Use com `ConsentScriptLoader` para carregamento condicional
+ * - Estado é automaticamente reativo - mudanças atualizam scripts
+ * - Compatível com Google Analytics Enhanced Consent Mode
+ * - Suporta integração com ferramentas de tag management
+ *
+ * @example Configuração típica
+ * ```typescript
+ * const preferences: ConsentPreferences = {
+ *   necessary: true,    // Sempre true (cookies essenciais)
+ *   analytics: false,   // Usuário rejeitou análise
+ *   marketing: true     // Usuário aceitou marketing
+ * };
+ * ```
+ *
+ * @example Integração condicional com features
+ * ```typescript
+ * function MyComponent() {
+ *   const { preferences } = useConsent();
+ *
+ *   return (
+ *     <div>
+ *       {preferences.analytics && <AnalyticsComponent />}
+ *       {preferences.marketing && <PersonalizationEngine />}
+ *       {preferences.functional && <ChatWidget />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Verificação programática de múltiplas categorias
+ * ```typescript
+ * function hasConsentForFeature(preferences: ConsentPreferences): boolean {
+ *   // Feature requer analytics OU marketing
+ *   return preferences.analytics || preferences.marketing;
+ * }
+ *
+ * function hasFullConsent(preferences: ConsentPreferences): boolean {
+ *   // Verificar se todas as categorias opcionais foram aceitas
+ *   const optionalCategories = Object.keys(preferences).filter(key => key !== 'necessary');
+ *   return optionalCategories.every(key => preferences[key] === true);
+ * }
+ * ```
+ *
+ * @public
  */
 interface ConsentPreferences {
+    /**
+     * Categoria de cookies necessários - sempre presente e verdadeira.
+     * Cookies essenciais não podem ser desabilitados pelo usuário.
+     */
     necessary: boolean;
+    /**
+     * Estado de consentimento para outras categorias ativas no projeto.
+     * As chaves correspondem aos IDs das categorias configuradas.
+     */
     [key: string]: boolean;
 }
 /**
- * Dados do cookie de consentimento em conformidade com LGPD/ANPD.
- * Contém apenas informações essenciais para compliance e funcionamento.
+ * Estrutura do cookie de consentimento em conformidade com LGPD/ANPD.
+ * @category Types
+ * @since 0.2.1
+ *
+ * @remarks
+ * Esta interface define o formato do cookie persistido no navegador do usuário,
+ * contendo todas as informações necessárias para compliance com a LGPD e
+ * para o funcionamento correto da biblioteca.
+ *
+ * **Importante**: A estrutura utiliza um formato JSON simples e legível, projetado
+ * para ser autoexplicativo e atender diretamente aos requisitos da LGPD para sites
+ * de primeira parte (first-party contexts).
+ *
+ * **Não implementa IAB TCF**: Este formato **não** segue o padrão IAB Transparency
+ * and Consent Framework (TCF), que é mais complexo e voltado para o ecossistema
+ * de publicidade programática (ad-tech). A adoção do TCF pode ser uma evolução
+ * futura da biblioteca.
+ *
+ * @example
+ * ```typescript
+ * const cookieData: ConsentCookieData = {
+ *   version: '1.0',
+ *   consented: true,
+ *   preferences: {
+ *     necessary: true,
+ *     analytics: true,
+ *     marketing: false
+ *   },
+ *   consentDate: '2024-01-15T10:30:00.000Z',
+ *   lastUpdate: '2024-01-15T10:30:00.000Z',
+ *   source: 'banner',
+ *   projectConfig: {
+ *     enabledCategories: ['analytics', 'marketing']
+ *   }
+ * };
+ * ```
+ *
+ * @see {@link https://www.planalto.gov.br/ccivil_03/_ato2015-2018/2018/lei/l13709.htm | LGPD - Lei 13.709/2018}
+ * @see {@link https://www.gov.br/anpd/pt-br/documentos-e-publicacoes/guia-orientativo-cookies-e-protecao-de-dados-pessoais.pdf | Guia de Cookies ANPD}
+ *
+ * @public
  */
 interface ConsentCookieData {
-    /** Versão do esquema do cookie para migração futura */
+    /**
+     * Versão do esquema do cookie para compatibilidade e migração futura.
+     * @example '1.0'
+     */
     version: string;
-    /** Se o usuário já prestou consentimento */
+    /**
+     * Indica se o usuário já prestou consentimento explícito.
+     * @example true
+     */
     consented: boolean;
-    /** Preferências por categoria (apenas categorias ativas) */
+    /**
+     * Preferências detalhadas por categoria de cookies.
+     * Contém apenas as categorias ativas no projeto.
+     */
     preferences: ConsentPreferences;
-    /** Timestamp ISO da primeira interação com o banner */
+    /**
+     * Timestamp ISO 8601 da primeira interação com o banner de consentimento.
+     * @example '2024-01-15T10:30:00.000Z'
+     */
     consentDate: string;
-    /** Timestamp ISO da última modificação das preferências */
+    /**
+     * Timestamp ISO 8601 da última modificação das preferências.
+     * Atualizado sempre que o usuário muda suas preferências.
+     * @example '2024-01-15T10:30:00.000Z'
+     */
     lastUpdate: string;
-    /** Origem da decisão de consentimento */
+    /**
+     * Origem da decisão de consentimento para auditoria.
+     * - 'banner': Decisão tomada no banner principal
+     * - 'modal': Decisão tomada no modal de preferências
+     * - 'programmatic': Decisão tomada via API programática
+     */
     source: 'banner' | 'modal' | 'programmatic';
-    /** Snapshot da configuração de categorias usada para este consentimento */
+    /**
+     * Snapshot da configuração de categorias no momento do consentimento.
+     * Útil para detectar mudanças na configuração e solicitar novo consentimento.
+     */
     projectConfig?: ProjectCategoriesConfig;
 }
 /**
- * Estado interno completo do consentimento (memória + UI).
- * Inclui dados persistidos + estado da interface.
+ * Estado interno completo do sistema de consentimento.
+ * @category Types
+ * @since 0.1.0
+ *
+ * @remarks
+ * Estende {@link ConsentCookieData} com informações de estado da interface
+ * que não são persistidas no cookie, como o estado de abertura do modal.
+ *
+ * Este é o estado completo mantido em memória pelo React Context e
+ * utilizado por todos os componentes da biblioteca.
+ *
+ * ### Dados Persistidos vs. Temporários
+ * - **Persistidos**: Herdados de `ConsentCookieData` - salvos no cookie
+ * - **Temporários**: `isModalOpen` - apenas em memória durante a sessão
+ *
+ * ### Ciclo de Vida do Estado
+ * 1. **Inicialização**: Estado padrão ou lido do cookie
+ * 2. **Hidratação**: Restauração do cookie no lado cliente (SSR)
+ * 3. **Interação**: Usuário modifica preferências via UI
+ * 4. **Persistência**: Estado é salvo no cookie automaticamente
+ * 5. **Sincronização**: Componentes reagem às mudanças via Context
+ *
+ * ### Performance e Reatividade
+ * - Estado é imutável - mudanças criam novo objeto
+ * - Optimized com `useMemo` para evitar re-renders desnecessários
+ * - Subscriber pattern para notificações de mudança
+ * - Integração automática com React DevTools
+ *
+ * @example Estado típico com consentimento dado
+ * ```typescript
+ * const state: ConsentState = {
+ *   version: '1.0',
+ *   consented: true,
+ *   preferences: { necessary: true, analytics: true, marketing: false },
+ *   consentDate: '2024-01-15T10:30:00.000Z',
+ *   lastUpdate: '2024-01-15T10:30:00.000Z',
+ *   source: 'banner',
+ *   projectConfig: { enabledCategories: ['analytics', 'marketing'] },
+ *   isModalOpen: false  // Estado da UI não persistido
+ * };
+ * ```
+ *
+ * @example Estado inicial antes do consentimento
+ * ```typescript
+ * const initialState: ConsentState = {
+ *   version: '1.0',
+ *   consented: false,
+ *   preferences: { necessary: true }, // Apenas essenciais
+ *   isModalOpen: false
+ *   // consentDate, lastUpdate, source serão definidos após consentimento
+ * };
+ * ```
+ *
+ * @example Uso em componente para verificação de estado
+ * ```typescript
+ * function ConsentAwareComponent() {
+ *   const { consented, preferences, isModalOpen } = useConsent();
+ *
+ *   if (!consented) {
+ *     return <div>Aguardando decisão do usuário sobre cookies...</div>;
+ *   }
+ *
+ *   if (isModalOpen) {
+ *     return <div>Modal de preferências está aberto</div>;
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       Analytics ativo: {preferences.analytics ? 'Sim' : 'Não'}
+ *       Marketing ativo: {preferences.marketing ? 'Sim' : 'Não'}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link ConsentCookieData} - Interface base com dados persistidos
+ * @see {@link useConsent} - Hook para acessar este estado
+ * @see {@link ConsentProvider} - Provider que mantém este estado
+ *
+ * @public
  */
 interface ConsentState extends ConsentCookieData {
-    /** Se o modal de preferências está aberto (NÃO persistido) */
+    /**
+     * Estado de abertura do modal de preferências.
+     * Esta informação não é persistida no cookie, apenas mantida em memória.
+     * @defaultValue false
+     */
     isModalOpen?: boolean;
 }
 /**
- * Textos utilizados na interface de consentimento.
+ * Interface de textos personalizáveis para todos os componentes da UI de consentimento LGPD.
+ * @category Types
+ * @since 0.1.0
  *
  * @remarks
  * Esta interface define todos os textos exibidos na UI do banner e modal de consentimento.
- * Os campos opcionais permitem adequação à ANPD e customização conforme necessidade do projeto.
+ * Os campos opcionais permitem adequação completa aos requisitos da ANPD e customização
+ * conforme necessidade específica do projeto. Todos os campos possuem valores padrão em português.
+ *
+ * A interface é dividida em três seções:
+ * - **Textos básicos**: Elementos essenciais do banner e modal (obrigatórios)
+ * - **Textos alternativos**: Variações para UI customizada (opcionais)
+ * - **Textos ANPD expandidos**: Informações de compliance com LGPD (opcionais)
+ *
+ * @example Configuração básica em inglês
+ * ```typescript
+ * const customTexts: Partial<ConsentTexts> = {
+ *   bannerMessage: 'We use cookies to enhance your experience.',
+ *   acceptAll: 'Accept All',
+ *   declineAll: 'Reject All',
+ *   preferences: 'Preferences'
+ * };
+ * ```
+ *
+ * @example Configuração completa ANPD
+ * ```typescript
+ * const anpdTexts: Partial<ConsentTexts> = {
+ *   controllerInfo: 'Controlado por: Empresa XYZ - CNPJ: 12.345.678/0001-90',
+ *   dataTypes: 'Coletamos: endereço IP, preferências de navegação, dados de uso',
+ *   userRights: 'Você pode solicitar acesso, correção ou exclusão dos seus dados',
+ *   contactInfo: 'DPO: dpo@empresa.com.br | Tel: (11) 1234-5678'
+ * };
+ * ```
  *
  * @property bannerMessage - Mensagem principal exibida no banner de consentimento.
  * @property acceptAll - Texto do botão para aceitar todos os cookies.
@@ -180,11 +463,26 @@ interface ConsentState extends ConsentCookieData {
  * @property modalIntro - Texto introdutório do modal.
  * @property save - Texto do botão para salvar preferências.
  * @property necessaryAlwaysOn - Texto explicativo para cookies necessários.
+ * @property preferencesButton - (Opcional) Texto alternativo para botão de preferências.
+ * @property preferencesTitle - (Opcional) Título alternativo do modal.
+ * @property preferencesDescription - (Opcional) Descrição do modal.
+ * @property close - (Opcional) Texto do botão fechar.
+ * @property accept - (Opcional) Texto alternativo aceitar.
+ * @property reject - (Opcional) Texto alternativo rejeitar.
+ * @property brandingPoweredBy - (Opcional) Texto "fornecido por".
  * @property controllerInfo - (Opcional) Informação sobre o controlador dos dados.
  * @property dataTypes - (Opcional) Tipos de dados coletados.
  * @property thirdPartySharing - (Opcional) Compartilhamento com terceiros.
  * @property userRights - (Opcional) Direitos do titular dos dados.
  * @property contactInfo - (Opcional) Informações de contato do DPO.
+ * @property retentionPeriod - (Opcional) Prazo de armazenamento dos dados.
+ * @property lawfulBasis - (Opcional) Base legal para o processamento.
+ * @property transferCountries - (Opcional) Países para transferência de dados.
+ *
+ * @see {@link ConsentProvider} - Para usar os textos personalizados
+ * @see {@link useConsentTexts} - Hook para acessar textos no contexto
+ *
+ * @public
  */
 interface ConsentTexts {
     bannerMessage: string;
@@ -196,6 +494,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;
@@ -207,6 +512,8 @@ interface ConsentTexts {
 }
 /**
  * Opções para configuração do cookie de consentimento.
+ * @category Types
+ * @since 0.1.0
  */
 interface ConsentCookieOptions {
     /** Nome do cookie. Padrão: 'cookieConsent' */
@@ -222,6 +529,8 @@ interface ConsentCookieOptions {
 }
 /**
  * Tokens de design para customização visual avançada dos componentes.
+ * @category Types
+ * @since 0.1.3
  * Permite um controle mais direto sobre a aparência sem a necessidade de `sx` props complexas.
  */
 interface DesignTokens {
@@ -263,6 +572,8 @@ interface DesignTokens {
 }
 /**
  * Propriedades do componente ConsentProvider - configuração principal da biblioteca.
+ * @category Types
+ * @since 0.1.0
  *
  * @example Uso básico (configuração mínima):
  * ```tsx
@@ -368,20 +679,6 @@ interface ConsentProviderProps {
      * ```
      */
     designTokens?: DesignTokens;
-    /**
-     * 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 substituir o modal padrão de preferências.
      * Deve implementar a lógica de consentimento usando as props definidas em `CustomPreferencesModalProps`.
@@ -469,6 +766,8 @@ interface ConsentProviderProps {
 }
 /**
  * Props esperadas por um componente customizado de CookieBanner.
+ * @category Types
+ * @since 0.3.1
  * Fornece acesso ao estado de consentimento e ações necessárias para o banner.
  */
 interface CustomCookieBannerProps {
@@ -480,6 +779,8 @@ interface CustomCookieBannerProps {
 }
 /**
  * Props esperadas por um componente customizado de PreferencesModal.
+ * @category Types
+ * @since 0.3.1
  *
  * 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.
@@ -499,6 +800,8 @@ interface CustomPreferencesModalProps {
 }
 /**
  * Props esperadas por um componente customizado de FloatingPreferencesButton.
+ * @category Types
+ * @since 0.3.1
  * Fornece acesso às ações de abertura do modal e ao estado de consentimento.
  */
 interface CustomFloatingPreferencesButtonProps {
@@ -507,6 +810,8 @@ interface CustomFloatingPreferencesButtonProps {
 }
 /**
  * Valor do contexto de consentimento, incluindo estado e métodos de manipulação.
+ * @category Types
+ * @since 0.1.0
  */
 interface ConsentContextValue {
     /** Indica se o usuário consentiu. */
@@ -532,190 +837,1300 @@ interface ConsentContextValue {
 }
 
 /**
- * Provider principal do contexto de consentimento LGPD.
+ * @component
+ * @category Context
+ * @since 0.1.0
+ * Provider principal da biblioteca. Envolva sua aplicação com este componente para habilitar o gerenciamento de consentimento.
  *
- * Gerencia o estado global de consentimento de cookies, preferências do usuário,
- * textos customizáveis e integração com SSR. Permite customização do modal de preferências,
- * callbacks externos e opções de cookie.
+ * @remarks
+ * Este provider gerencia o estado de consentimento, renderiza a UI (banner, modal) e fornece o contexto para todos os hooks, como o `useConsent`.
+ * A configuração é feita através de props, permitindo desde um uso "zero-config" (além da prop obrigatória `categories`) até customizações avançadas.
  *
- * @param props Propriedades do ConsentProvider (ver ConsentProviderProps)
- * @returns JSX.Element
+ * @param {Readonly<ConsentProviderProps>} props - As propriedades para configurar o provider.
+ * @param {ProjectCategoriesConfig} props.categories - **Obrigatório**. Define as categorias de cookies que seu projeto utiliza, em conformidade com o princípio de minimização da LGPD.
+ * @param {Partial<ConsentTexts>} [props.texts] - Objeto para customizar todos os textos exibidos na UI.
+ * @param {boolean} [props.blocking=false] - Se `true`, exibe um overlay que impede a interação com o site até uma decisão do usuário.
+ * @param {(state: ConsentState) => void} [props.onConsentGiven] - Callback executado na primeira vez que o usuário dá o consentimento.
+ * @param {(prefs: ConsentPreferences) => void} [props.onPreferencesSaved] - Callback executado sempre que o usuário salva novas preferências.
+ * @param {boolean} [props.disableDeveloperGuidance=false] - Desativa as mensagens de orientação no console em ambiente de desenvolvimento.
+ * @param {boolean} [props.disableFloatingPreferencesButton=false] - Desabilita o botão flutuante para reabrir as preferências.
+ * @param {React.ComponentType<CustomCookieBannerProps>} [props.CookieBannerComponent] - Permite substituir o componente de banner padrão por um customizado.
+ * @param {React.ComponentType<CustomPreferencesModalProps>} [props.PreferencesModalComponent] - Permite substituir o modal de preferências padrão por um customizado.
+ * @param {any} [props.theme] - Objeto de tema do Material-UI para estilizar os componentes padrão.
+ * @param {ConsentState} [props.initialState] - Estado inicial para hidratação em SSR, evitando o "flash" do banner.
+ * @param {Partial<ConsentCookieOptions>} [props.cookie] - Opções para customizar o nome, duração e outros atributos do cookie de consentimento.
+ * @param {React.ReactNode} props.children - A aplicação ou parte dela que terá acesso ao contexto de consentimento.
  *
  * @example
- * <ConsentProvider>
- *   <App />
+ * ```tsx
+ * // Uso básico
+ * <ConsentProvider categories={{ enabledCategories: ['analytics'] }}>
+ *   <MyApp />
  * </ConsentProvider>
- */
-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.
- *
- * Retorna o estado atual do consentimento, preferências do usuário e métodos para
- * aceitar, recusar, modificar ou resetar consentimentos. Ideal para integração
- * com componentes customizados ou lógica de negócio.
- *
- * @returns {ConsentContextValue} Estado e ações do consentimento.
+ * ```
  *
  * @example
- * const {
- *   consented,
- *   preferences,
- *   acceptAll,
- *   rejectAll,
- *   setPreference,
- *   openPreferences,
- *   closePreferences,
- *   resetConsent,
- * } = useConsent();
- */
-declare function useConsent(): ConsentContextValue;
-/**
- * Hook para acessar textos customizados do ConsentProvider.
- * Útil para componentes personalizados que precisam dos textos configurados.
- */
-declare function useConsentTexts(): ConsentTexts;
-/**
- * Hook para verificar se a hidratação do cookie foi concluída.
- * Útil para evitar flash do banner antes de verificar cookies existentes.
- */
-declare function useConsentHydration(): boolean;
-
-/**
- * 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 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'];
-}
-/**
- * Hook para acessar informações sobre categorias ativas.
- * Usado por componentes UI para renderizar adequadamente.
- */
-declare function useCategories(): CategoriesContextValue;
-/**
- * Hook de conveniência para verificar se uma categoria específica está ativa.
+ * ```tsx
+ * // Uso avançado com UI customizada e callbacks
+ * <ConsentProvider
+ *   categories={{ enabledCategories: ['analytics', 'marketing'] }}
+ *   blocking={true}
+ *   texts={{ bannerMessage: 'Usamos cookies!' }}
+ *   onPreferencesSaved={(prefs) => console.log('Preferências salvas:', prefs)}
+ *   CookieBannerComponent={MeuBannerCustomizado}
+ * >
+ *   <MyApp />
+ * </ConsentProvider>
+ * ```
  */
-declare function useCategoryStatus(categoryId: string): {
-    isActive: boolean;
-    isEssential: boolean;
-    needsToggle: boolean;
-    name: string | undefined;
-    description: string | undefined;
-};
-
-declare function ConsentGate(props: Readonly<{
-    category: string;
-    children: React$1.ReactNode;
-}>): react_jsx_runtime.JSX.Element | null;
+declare function ConsentProvider({ initialState, categories, texts: textsProp, theme, designTokens, PreferencesModalComponent, preferencesModalProps, CookieBannerComponent, cookieBannerProps, FloatingPreferencesButtonComponent, floatingPreferencesButtonProps, disableFloatingPreferencesButton, hideBranding, onConsentGiven, onPreferencesSaved, cookie: cookieOpts, disableDeveloperGuidance, children, }: Readonly<ConsentProviderProps>): react_jsx_runtime.JSX.Element;
+declare const defaultTexts: ConsentTexts;
 
 /**
- * Carrega dinamicamente um script externo após o consentimento do usuário ser finalizado.
+ * @fileoverview
+ * Hooks públicos para interação com o sistema de consentimento LGPD.
  *
- * Aguarda até que o usuário tome uma decisão definitiva (banner fechado ou preferências salvas)
- * antes de inserir o script na página. Permite restringir o carregamento por categoria de consentimento.
+ * Este módulo exporta os hooks principais que devem ser usados pelos desenvolvedores
+ * para acessar e manipular o estado de consentimento em seus componentes React.
  *
- * @param id - Identificador único do elemento script a ser criado.
- * @param src - URL do script externo.
- * @param category - Categoria de consentimento exigida para o script ('analytics', 'marketing' ou null).
- * @param attrs - Atributos adicionais a serem aplicados ao elemento script.
- * @returns Promise que resolve quando o script é carregado ou rejeita se o consentimento não for dado.
+ * @author Luciano Édipo
+ * @since 0.1.0
  */
-declare function loadScript(id: string, src: string, category?: 'analytics' | 'marketing' | null, attrs?: Record<string, string>): Promise<void>;
 
 /**
- * Tema padrão utilizado pelos componentes de consentimento da biblioteca.
- *
- * Inclui configurações de cores, tipografia e estilos para componentes Material-UI,
- * garantindo aparência consistente e acessível conforme guidelines LGPD.
+ * Hook principal para acessar e manipular o estado de consentimento de cookies LGPD.
  *
  * @remarks
- * Pode ser sobrescrito via ThemeProvider externo se necessário.
- */
-declare const defaultConsentTheme: _mui_material_styles.Theme;
-
-/**
- * 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.
+ * Este é o hook mais importante da biblioteca para interagir com o sistema de consentimento.
+ * Ele provê acesso completo ao estado atual do consentimento e às funções para modificar esse estado.
  *
- * @example
- * ```tsx
- * const integrations = [
- *   createGoogleAnalyticsIntegration({ measurementId: 'GA_ID' }),
- *   createUserWayIntegration({ accountId: 'USERWAY_ID' })
- * ]
+ * ### Estado Disponível
+ * - **`consented`**: `boolean` - Indica se o usuário já deu alguma resposta (aceitar/rejeitar)
+ * - **`preferences`**: `CategoryPreferences` - Objeto com estado de cada categoria de cookie
+ * - **`isModalOpen`**: `boolean` - Indica se o modal de preferências está aberto
+ *
+ * ### Ações Disponíveis
+ * - **`acceptAll()`**: Aceita todas as categorias configuradas
+ * - **`rejectAll()`**: Rejeita todas as categorias (exceto necessary)
+ * - **`setPreference(category, enabled)`**: Define uma categoria específica
+ * - **`setPreferences(preferences)`**: Define múltiplas categorias de uma vez
+ * - **`openPreferences()`**: Abre o modal de preferências
+ * - **`closePreferences()`**: Fecha o modal de preferências
+ * - **`resetConsent()`**: Limpa todo consentimento (volta ao estado inicial)
+ *
+ * ### Performance e SSR
+ * - O hook é otimizado com `useMemo` interno para evitar re-renders desnecessários
+ * - Compatível com SSR (Next.js, Remix) - estado é hidratado após montagem no cliente
+ * - Estado inicial é sempre `{ consented: false }` no servidor para evitar hydration mismatches
+ *
+ * ### Integração com Scripts
+ * - Use junto com `ConsentScriptLoader` para carregamento condicional de scripts
+ * - Estado `preferences` pode ser usado para ativar/desativar recursos condicionalmente
+ * - Mudanças no consentimento são automaticamente persistidas em cookies
+ *
+ * @returns Um objeto contendo o estado completo e as ações de consentimento
+ *
+ * @throws {Error} Se usado fora do ConsentProvider - verifique se o componente está dentro de `<ConsentProvider>`
+ *
+ * @example Hook básico para verificar consentimento
+ * ```tsx
+ * function MyComponent() {
+ *   const { consented, preferences, acceptAll, rejectAll } = useConsent();
+ *
+ *   if (!consented) {
+ *     return <p>Aguardando decisão do usuário...</p>;
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <p>Analytics: {preferences.analytics ? 'Ativo' : 'Inativo'}</p>
+ *       <button onClick={rejectAll}>Rejeitar Todos</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Controle granular de categorias
+ * ```tsx
+ * function AdvancedSettings() {
+ *   const { preferences, setPreference } = useConsent();
+ *
+ *   return (
+ *     <div>
+ *       <label>
+ *         <input
+ *           type="checkbox"
+ *           checked={preferences.marketing}
+ *           onChange={(e) => setPreference('marketing', e.target.checked)}
+ *         />
+ *         Cookies de Marketing
+ *       </label>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Integração condicional com Google Analytics
+ * ```tsx
+ * function AnalyticsComponent() {
+ *   const { consented, preferences } = useConsent();
+ *
+ *   React.useEffect(() => {
+ *     if (consented && preferences.analytics) {
+ *       // Inicializar Google Analytics
+ *       gtag('config', 'GA_MEASUREMENT_ID');
+ *       gtag('event', 'consent_granted', {
+ *         ad_storage: preferences.marketing ? 'granted' : 'denied',
+ *         analytics_storage: 'granted'
+ *       });
+ *     }
+ *   }, [consented, preferences]);
+ *
+ *   return null; // Componente só para lógica
+ * }
+ * ```
+ *
+ * @example Uso avançado com múltiplas preferências
+ * ```tsx
+ * function BulkPreferencesControl() {
+ *   const { setPreferences, preferences, consented } = useConsent();
+ *
+ *   const handleSavePreferences = () => {
+ *     setPreferences({
+ *       necessary: true,    // Sempre true
+ *       analytics: true,
+ *       marketing: false,
+ *       functional: true,
+ *       performance: false
+ *     });
+ *   };
+ *
+ *   return (
+ *     <button onClick={handleSavePreferences} disabled={!consented}>
+ *       Salvar Minhas Preferências
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @example Componente com estado de carregamento
+ * ```tsx
+ * function ConsentAwareFeature() {
+ *   const { consented, preferences } = useConsent();
+ *   const canShowFeature = consented && preferences.functional;
+ *
+ *   if (!consented) {
+ *     return <div>⏳ Aguardando decisão sobre cookies...</div>;
+ *   }
+ *
+ *   if (!preferences.functional) {
+ *     return (
+ *       <div>
+ *         ❌ Este recurso requer cookies funcionais.
+ *         <button onClick={() => window.openPreferencesModal?.()}>
+ *           Alterar Preferências
+ *         </button>
+ *       </div>
+ *     );
+ *   }
+ *
+ *   return <div>✅ Recurso ativo com consentimento!</div>;
+ * }
+ * ```
+ *
+ * @see {@link ConsentProvider} - Provider que deve envolver os componentes
+ * @see {@link ConsentContextValue} - Tipo do valor retornado
+ *
+ * @public
+ * @since 0.1.0
+ */
+declare function useConsent(): ConsentContextValue;
+/**
+ * Hook para acessar os textos personalizáveis da interface de consentimento.
+ *
+ * @remarks
+ * Este hook retorna o objeto completo de textos configurados no `ConsentProvider`.
+ * Os textos incluem tanto os valores padrão em português quanto as customizações
+ * fornecidas via prop `texts`. É útil para criar componentes personalizados
+ * que mantêm consistência com a configuração de textos do projeto.
+ *
+ * ### Textos Básicos Incluídos
+ * - `bannerMessage`: Mensagem principal do banner
+ * - `acceptAll`, `declineAll`, `preferences`: Textos dos botões
+ * - `modalTitle`, `modalIntro`: Cabeçalho do modal
+ * - `save`, `close`: Ações do modal
+ *
+ * ### Textos de Conformidade LGPD/ANPD (Opcionais)
+ * - `controllerInfo`: Informações do controlador de dados
+ * - `dataTypes`: Tipos de dados coletados
+ * - `thirdPartySharing`: Compartilhamento com terceiros
+ * - `userRights`: Direitos do titular dos dados
+ * - `contactInfo`: Contato do DPO (Data Protection Officer)
+ *
+ * ### Personalização e Internacionalização
+ * - Padrão em português brasileiro
+ * - Suporte completo a customização via `ConsentProvider.texts`
+ * - Tipagem TypeScript completa para IntelliSense
+ * - Fallback automático para textos padrão quando não customizados
+ *
+ * @returns O objeto completo de textos da interface, mesclando padrões com customizações
+ *
+ * @throws {Error} Se usado fora do ConsentProvider - verifique se está dentro de `<ConsentProvider>`
+ *
+ * @example Usar textos em componente customizado
+ * ```tsx
+ * function CustomBanner() {
+ *   const texts = useConsentTexts();
+ *
+ *   return (
+ *     <div className="custom-banner">
+ *       <p>{texts.bannerMessage}</p>
+ *       <button>{texts.acceptAll}</button>
+ *       <button>{texts.declineAll}</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Acessar textos ANPD específicos
+ * ```tsx
+ * function ComplianceInfo() {
+ *   const texts = useConsentTexts();
+ *
+ *   return (
+ *     <div>
+ *       {texts.controllerInfo && <p>{texts.controllerInfo}</p>}
+ *       {texts.userRights && <p>{texts.userRights}</p>}
+ *       {texts.contactInfo && <p>{texts.contactInfo}</p>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Modal customizado com textos consistentes
+ * ```tsx
+ * function CustomPreferencesModal() {
+ *   const texts = useConsentTexts();
+ *   const { preferences, setPreference, closePreferences } = useConsent();
+ *
+ *   return (
+ *     <div className="custom-modal">
+ *       <h2>{texts.preferencesTitle || texts.modalTitle}</h2>
+ *       <p>{texts.preferencesDescription || texts.modalIntro}</p>
+ *
+ *       <label>
+ *         <input
+ *           type="checkbox"
+ *           checked={preferences.analytics}
+ *           onChange={(e) => setPreference('analytics', e.target.checked)}
+ *         />
+ *         Cookies Analíticos
+ *       </label>
+ *
+ *       <div className="modal-actions">
+ *         <button onClick={closePreferences}>{texts.close}</button>
+ *         <button>{texts.save}</button>
+ *       </div>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Componente multilíngue com fallbacks
+ * ```tsx
+ * function MultiLanguageBanner() {
+ *   const texts = useConsentTexts();
+ *   const [language, setLanguage] = useState('pt');
+ *
+ *   // Usar textos customizados baseado no idioma
+ *   const message = language === 'en'
+ *     ? 'We use cookies to improve your experience'
+ *     : texts.bannerMessage;
+ *
+ *   const acceptText = language === 'en' ? 'Accept All' : texts.acceptAll;
+ *
+ *   return (
+ *     <div>
+ *       <select onChange={(e) => setLanguage(e.target.value)}>
+ *         <option value="pt">Português</option>
+ *         <option value="en">English</option>
+ *       </select>
+ *       <p>{message}</p>
+ *       <button>{acceptText}</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link ConsentTexts} - Interface completa dos textos
+ * @see {@link ConsentProvider} - Para configurar textos personalizados
+ *
+ * @public
+ * @since 0.1.0
+ */
+declare function useConsentTexts(): ConsentTexts;
+/**
+ * Hook para verificar se a hidratação do estado de consentimento foi concluída.
+ *
+ * @remarks
+ * Em aplicações com Server-Side Rendering (SSR) como Next.js, o estado inicial
+ * é sempre `false` no servidor para evitar diferenças de hidratação. Este hook
+ * permite saber quando a biblioteca já leu o cookie do navegador e atualizou
+ * o estado, evitando o "flash" do banner ou comportamentos inconsistentes.
+ *
+ * ### Casos de Uso Principais
+ * - **Mostrar loading states** enquanto carrega o estado real do cookie
+ * - **Evitar flash of unstyled content (FOUC)** com banners aparecendo/sumindo
+ * - **Sincronizar componentes** que dependem do estado de consentimento
+ * - **Inicializar scripts condicionalmente** apenas após hidratação
+ *
+ * ### Funcionamento Técnico
+ * - No servidor (SSR): sempre retorna `false`
+ * - No cliente: retorna `false` até o `useEffect` ler o cookie
+ * - Após leitura do cookie: retorna `true` permanentemente
+ * - Performance: otimizado para evitar re-renders desnecessários
+ *
+ * ### Frameworks Suportados
+ * - **Next.js**: App Router e Pages Router
+ * - **Remix**: SSR completo
+ * - **Gatsby**: Static Generation + hidratação
+ * - **Vite SSR**: Server-side rendering
+ * - **Create React App**: Client-side only (sempre `true`)
+ *
+ * @returns `true` se a hidratação do cookie foi concluída, `false` durante SSR ou antes da hidratação
+ *
+ * @example Evitar flash do banner
+ * ```tsx
+ * function App() {
+ *   const { consented } = useConsent();
+ *   const isHydrated = useConsentHydration();
+ *
+ *   // Não mostrar nada até hidratar
+ *   if (!isHydrated) {
+ *     return <div>Carregando...</div>;
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       {!consented && <span>Banner aparecerá agora</span>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Controlar carregamento de scripts
+ * ```tsx
+ * function Analytics() {
+ *   const { preferences } = useConsent();
+ *   const isHydrated = useConsentHydration();
+ *
+ *   React.useEffect(() => {
+ *     if (isHydrated && preferences.analytics) {
+ *       // Só carrega analytics após hidratação
+ *       loadGoogleAnalytics();
+ *     }
+ *   }, [isHydrated, preferences.analytics]);
+ *
+ *   return null;
+ * }
+ * ```
+ *
+ * @example Componente com loading state elegante
+ * ```tsx
+ * function ConsentDependentFeature() {
+ *   const { consented, preferences } = useConsent();
+ *   const isHydrated = useConsentHydration();
+ *
+ *   // Estados de loading
+ *   if (!isHydrated) {
+ *     return <div className="shimmer">Carregando preferências...</div>;
+ *   }
+ *
+ *   // Estado não consentido
+ *   if (!consented) {
+ *     return (
+ *       <div className="consent-required">
+ *         <p>Configure suas preferências de cookies para usar este recurso.</p>
+ *       </div>
+ *     );
+ *   }
+ *
+ *   // Estado com consentimento específico
+ *   if (!preferences.functional) {
+ *     return (
+ *       <div className="consent-partial">
+ *         <p>Este recurso requer cookies funcionais.</p>
+ *         <button onClick={() => window.openPreferencesModal?.()}>
+ *           Alterar Preferências
+ *         </button>
+ *       </div>
+ *     );
+ *   }
+ *
+ *   return <div>🚀 Recurso funcionando com consentimento!</div>;
+ * }
+ * ```
+ *
+ * @example Next.js - Prevenção de hydration mismatch
+ * ```typescript
+ * // pages/_app.tsx
+ * function MyApp(props: any) {
+ *   const isHydrated = useConsentHydration();
+ *
+ *   // Só renderiza componentes de consentimento após hidratação
+ *   // para evitar diferenças entre servidor e cliente
+ *   return (
+ *     // ConsentProvider envolve tudo
+ *     // Component com props normalmente
+ *     // CookieBanner só se isHydrated for true
+ *     // FloatingPreferencesButton só se isHydrated for true
+ *   );
+ * }
+ * ```
+ *
+ * @example Hook customizado para features condicionais
+ * ```tsx
+ * function useConsentAwareFeature(requiredCategory: string) {
+ *   const { consented, preferences } = useConsent();
+ *   const isHydrated = useConsentHydration();
+ *
+ *   const isEnabled = React.useMemo(() => {
+ *     if (!isHydrated) return false; // Loading
+ *     if (!consented) return false;  // No consent
+ *     return preferences[requiredCategory] === true;
+ *   }, [isHydrated, consented, preferences, requiredCategory]);
+ *
+ *   return {
+ *     isEnabled,
+ *     isLoading: !isHydrated,
+ *     hasConsented: consented,
+ *     preferences
+ *   };
+ * }
+ *
+ * // Uso do hook customizado
+ * function MyFeature() {
+ *   const { isEnabled, isLoading } = useConsentAwareFeature('analytics');
+ *
+ *   if (isLoading) return <Skeleton />;
+ *   if (!isEnabled) return <ConsentRequired />;
+ *
+ *   return <AnalyticsChart />;
+ * }
+ * ```
+ *
+ * @see {@link ConsentProvider} - Para configuração SSR
+ *
+ * @public
+ * @since 0.1.0
+ */
+declare function useConsentHydration(): boolean;
+/**
+ * Hook que retorna uma função para abrir o modal de preferências de forma programática.
+ * @hook
+ * @category Hooks
+ * @since 0.3.1+
+ * @remarks
+ * Este hook oferece uma maneira ReactJS-idiomática de abrir o modal de preferências
+ * em qualquer lugar da aplicação. Diferente do botão flutuante padrão, permite
+ * controle total sobre quando e como o modal é acionado.
+ *
+ * ### Casos de Uso Principais
+ * - **Links no footer/header**: "Configurações de Cookies", "Preferências"
+ * - **Botões customizados**: Design próprio para abrir preferências
+ * - **Fluxos condicionais**: Abrir modal baseado em ações do usuário
+ * - **Integração com menus**: Adicionar item de menu para configurações
+ *
+ * ### Vantagens sobre função global
+ * - **Type-safe**: TypeScript com tipagem completa
+ * - **React-friendly**: Integra com ciclo de vida dos componentes
+ * - **Automático**: Sem necessidade de verificar se ConsentProvider existe
+ * - **Testável**: Fácil de mockar em testes unitários
+ *
+ * ### Performance
+ * - Função estável: não causa re-renders quando usada como dependency
+ * - Memoizada internamente para otimização
+ * - Sem overhead: apenas proxy para ação interna do contexto
+ *
+ * @returns Uma função estável que abre o modal de preferências quando chamada
+ *
+ * @throws {Error} Se usado fora do ConsentProvider - verifique se está dentro de `<ConsentProvider>`
+ *
+ * @example Hook básico no footer
+ * ```tsx
+ * function MeuFooter() {
+ *   const abrirModal = useOpenPreferencesModal();
+ *
+ *   return (
+ *     <footer>
+ *       <a href="#" onClick={abrirModal}>
+ *         Configurações de Cookies
+ *       </a>
+ *     </footer>
+ *   );
+ * }
+ * ```
+ *
+ * @example Botão customizado com ícone
+ * ```tsx
+ * import { Settings } from '@mui/icons-material';
+ *
+ * function CustomPreferencesButton() {
+ *   const openModal = useOpenPreferencesModal();
+ *
+ *   return (
+ *     <button
+ *       onClick={openModal}
+ *       className="preferences-btn"
+ *       aria-label="Configurar cookies"
+ *     >
+ *       <Settings /> Cookies
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @example Menu dropdown com opções
+ * ```tsx
+ * function UserMenu() {
+ *   const openPreferences = useOpenPreferencesModal();
+ *   const [menuOpen, setMenuOpen] = useState(false);
+ *
+ *   return (
+ *     <div className="user-menu">
+ *       <button onClick={() => setMenuOpen(!menuOpen)}>
+ *         Menu ▼
+ *       </button>
+ *       {menuOpen && (
+ *         <ul>
+ *           <li><a href="/profile">Meu Perfil</a></li>
+ *           <li><a href="/settings">Configurações</a></li>
+ *           <li>
+ *             <button onClick={openPreferences}>
+ *               Preferências de Cookies
+ *             </button>
+ *           </li>
+ *         </ul>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Integração com router para mudança de página
+ * ```tsx
+ * function CookieSettingsPage() {
+ *   const openModal = useOpenPreferencesModal();
+ *   const navigate = useNavigate(); // React Router
+ *
+ *   React.useEffect(() => {
+ *     // Abre modal automaticamente na página de configurações
+ *     openModal();
+ *   }, [openModal]);
+ *
+ *   const handleModalClose = () => {
+ *     // Volta para página anterior quando modal fechar
+ *     navigate(-1);
+ *   };
+ *
+ *   return <div>Configurações de cookies carregando...</div>;
+ * }
+ * ```
+ *
+ * @example Hook condicional com verificação de consentimento
+ * ```tsx
+ * function SmartCookieButton() {
+ *   const { consented } = useConsent();
+ *   const openPreferences = useOpenPreferencesModal();
+ *
+ *   // Se usuário já deu consentimento, mostra "Alterar"
+ *   // Se não deu consentimento, mostra "Configurar"
+ *   const buttonText = consented ? 'Alterar Preferências' : 'Configurar Cookies';
+ *   const buttonIcon = consented ? '⚙️' : '🍪';
+ *
+ *   return (
+ *     <button
+ *       onClick={openPreferences}
+ *       className={consented ? 'modify-btn' : 'setup-btn'}
+ *     >
+ *       {buttonIcon} {buttonText}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useOpenPreferencesModal(): () => void;
+declare function openPreferencesModal(): void;
+
+/**
+ * @interface DeveloperGuidance
+ * Define a estrutura do objeto de orientação para desenvolvedores, contendo avisos, sugestões e informações sobre categorias ativas.
+ */
+interface DeveloperGuidance {
+    /** Um array de strings, cada uma representando um aviso sobre a configuração. */
+    warnings: string[];
+    /** Um array de strings, cada uma representando uma sugestão para melhorar a conformidade ou UX. */
+    suggestions: string[];
+    /** Um array de objetos, cada um descrevendo uma categoria de cookie ativa e suas propriedades relevantes para a UI. */
+    activeCategoriesInfo: {
+        id: string;
+        name: string;
+        description: string;
+        essential: boolean;
+        uiRequired: boolean;
+    }[];
+    /** Indica se a configuração padrão da biblioteca está sendo utilizada (quando nenhuma configuração explícita é fornecida). */
+    usingDefaults: boolean;
+}
+/**
+ * @constant
+ * @category Utils
+ * @since 0.2.2
+ * Configuração padrão de categorias de cookies utilizada quando o desenvolvedor não especifica nenhuma configuração.
+ * Inclui apenas a categoria 'analytics' além da 'necessary' (que é sempre incluída).
+ */
+declare const DEFAULT_PROJECT_CATEGORIES: ProjectCategoriesConfig;
+/**
+ * @function
+ * @category Utils
+ * @since 0.2.2
+ * Analisa a configuração de categorias do projeto e gera um objeto de orientação para o desenvolvedor.
+ * Este objeto contém avisos, sugestões e informações detalhadas sobre as categorias ativas.
+ *
+ * @param {ProjectCategoriesConfig} [config] A configuração de categorias fornecida pelo desenvolvedor. Se não for fornecida, a configuração padrão será utilizada.
+ * @returns {DeveloperGuidance} Um objeto `DeveloperGuidance` com a análise da configuração.
+ */
+declare function analyzeDeveloperConfiguration(config?: ProjectCategoriesConfig): DeveloperGuidance;
+
+/**
+ * @interface CategoriesContextValue
+ * O valor fornecido pelo `CategoriesContext`, contendo informações sobre as categorias de cookies ativas no projeto.
+ */
+interface CategoriesContextValue {
+    /** A configuração final das categorias, incluindo padrões aplicados. */
+    config: ProjectCategoriesConfig;
+    /** Análise e orientações para desenvolvedores, incluindo avisos e sugestões. */
+    guidance: DeveloperGuidance;
+    /** Um array de categorias que requerem um toggle na UI de preferências (não essenciais). */
+    toggleableCategories: DeveloperGuidance['activeCategoriesInfo'];
+    /** Um array contendo todas as categorias ativas no projeto (essenciais e não essenciais). */
+    allCategories: DeveloperGuidance['activeCategoriesInfo'];
+}
+/**
+ * @hook
+ * @category Hooks
+ * @since 0.2.2
+ * Hook para acessar informações sobre as categorias de cookies ativas no projeto.
+ *
+ * @remarks
+ * Este hook deve ser usado dentro do `ConsentProvider` (que internamente renderiza o `CategoriesProvider`).
+ * Ele é útil para construir componentes de UI customizados que precisam se adaptar dinamicamente às categorias configuradas.
+ *
+ * @returns {CategoriesContextValue} Um objeto contendo a configuração, orientações e listas de categorias.
+ *
+ * @throws {Error} Se usado fora do `CategoriesProvider`.
+ */
+declare function useCategories(): CategoriesContextValue;
+/**
+ * @hook
+ * @category Hooks
+ * @since 0.2.2
+ * Hook de conveniência para verificar o status de uma categoria de cookie específica.
+ *
+ * @param {string} categoryId O ID da categoria a ser verificada (ex: 'analytics', 'necessary').
+ * @returns {object} Um objeto com o status da categoria:
+ * - `isActive`: `true` se a categoria está configurada e ativa no projeto.
+ * - `isEssential`: `true` se a categoria é essencial (não pode ser desativada pelo usuário).
+ * - `needsToggle`: `true` se a categoria requer um controle (switch) na UI de preferências.
+ * - `name`: O nome amigável da categoria.
+ * - `description`: A descrição da categoria.
+ * @example
+ * ```tsx
+ * const analyticsStatus = useCategoryStatus('analytics')
+ * if (analyticsStatus.isActive && analyticsStatus.needsToggle) {
+ *   // Renderizar switch para analytics
+ * }
+ * ```
+ */
+declare function useCategoryStatus(categoryId: string): {
+    isActive: boolean;
+    isEssential: boolean;
+    needsToggle: boolean;
+    name: string | undefined;
+    description: string | undefined;
+};
+
+declare function ConsentGate(props: Readonly<{
+    category: string;
+    children: React$1.ReactNode;
+}>): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * @function
+ * @category Utils
+ * @since 0.1.0
+ * Carrega dinamicamente um script externo no DOM.
+ *
+ * @remarks
+ * Esta função é utilizada internamente pela biblioteca para carregar scripts de integração
+ * após o consentimento do usuário. Ela garante que o script só seja inserido na página
+ * se o consentimento for dado e o contexto estiver disponível.
+ *
+ * @param {string} id Um identificador único para o elemento `<script>` a ser criado.
+ * @param {string} src A URL do script externo a ser carregado.
+ * @param {'analytics' | 'marketing' | null} [category=null] A categoria de consentimento exigida para o script. Se o consentimento para esta categoria não for dado, o script não será carregado.
+ * @param {Record<string, string>} [attrs={}] Atributos adicionais a serem aplicados ao elemento `<script>` (ex: `{ async: 'true' }`).
+ * @returns {Promise<void>} Uma Promise que resolve quando o script é carregado com sucesso, ou rejeita se o consentimento não for dado ou ocorrer um erro de carregamento.
+ * @example
+ * ```ts
+ * // Carregar um script de analytics após o consentimento
+ * loadScript('my-analytics-script', 'https://example.com/analytics.js', 'analytics')
+ *   .then(() => console.log('Script de analytics carregado!'))
+ *   .catch(error => console.error('Erro ao carregar script:', error))
+ * ```
+ */
+declare function loadScript(id: string, src: string, category?: 'analytics' | 'marketing' | null, attrs?: Record<string, string>): Promise<void>;
+
+/**
+ * @constant
+ * @category Utils
+ * @since 0.1.0
+ * Tema padrão utilizado pelos componentes de consentimento da biblioteca.
+ *
+ * Inclui configurações de cores, tipografia e estilos para componentes Material-UI,
+ * garantindo aparência consistente e acessível conforme guidelines LGPD.
+ *
+ * @remarks
+ * Pode ser sobrescrito via ThemeProvider externo se necessário.
+ */
+declare const defaultConsentTheme: _mui_material_styles.Theme;
+
+/**
+ * @interface ScriptIntegration
+ * Define a estrutura de um objeto de integração de script, usado para carregar scripts de terceiros condicionalmente.
+ */
+interface ScriptIntegration {
+    /** Um ID único para esta integração de script. */
+    id: string;
+    /** A categoria de consentimento necessária para que este script seja carregado (ex: 'analytics', 'marketing'). */
+    category: string;
+    /** A URL do script a ser carregado. */
+    src: string;
+    /** Uma função opcional a ser executada após o script ser carregado e inicializado no DOM. */
+    init?: () => void;
+    /** Um objeto de atributos HTML a serem adicionados à tag `<script>` (ex: `{ async: 'true' }`). */
+    attrs?: Record<string, string>;
+}
+/**
+ * @interface GoogleAnalyticsConfig
+ * Configuração específica para a integração com o Google Analytics 4 (GA4).
+ */
+interface GoogleAnalyticsConfig {
+    /** O ID de medição do GA4 (ex: 'G-XXXXXXXXXX'). */
+    measurementId: string;
+    /** Um objeto opcional de configuração adicional a ser passado para o comando `gtag('config')`. */
+    config?: any;
+}
+/**
+ * @interface GoogleTagManagerConfig
+ * Configuração específica para a integração com o Google Tag Manager (GTM).
+ */
+interface GoogleTagManagerConfig {
+    /** O ID do contêiner do GTM (ex: 'GTM-XXXXXXX'). */
+    containerId: string;
+    /** O nome da camada de dados (dataLayer) a ser usada. Padrão: 'dataLayer'. */
+    dataLayerName?: string;
+}
+/**
+ * @interface UserWayConfig
+ * Configuração específica para a integração com o widget de acessibilidade UserWay.
+ */
+interface UserWayConfig {
+    /** O ID da conta UserWay. */
+    accountId: string;
+}
+/**
+ * @function
+ * @category Utils
+ * @since 0.2.0
+ * Cria um objeto de integração para o Google Analytics 4 (GA4).
+ *
+ * @param {GoogleAnalyticsConfig} config A configuração do GA4, incluindo o `measurementId`.
+ * @returns {ScriptIntegration} Um objeto `ScriptIntegration` configurado para o GA4.
+ */
+declare function createGoogleAnalyticsIntegration(config: GoogleAnalyticsConfig): ScriptIntegration;
+/**
+ * @function
+ * @category Utils
+ * @since 0.2.0
+ * Cria um objeto de integração para o Google Tag Manager (GTM).
+ *
+ * @param {GoogleTagManagerConfig} config A configuração do GTM, incluindo o `containerId`.
+ * @returns {ScriptIntegration} Um objeto `ScriptIntegration` configurado para o GTM.
+ */
+declare function createGoogleTagManagerIntegration(config: GoogleTagManagerConfig): ScriptIntegration;
+/**
+ * @function
+ * @category Utils
+ * @since 0.2.0
+ * Cria um objeto de integração para o widget de acessibilidade UserWay.
+ *
+ * @param {UserWayConfig} config A configuração do UserWay, incluindo o `accountId`.
+ * @returns {ScriptIntegration} Um objeto `ScriptIntegration` configurado para o UserWay.
+ */
+declare function createUserWayIntegration(config: UserWayConfig): ScriptIntegration;
+/**
+ * @constant
+ * @category Utils
+ * @since 0.2.0
+ * Objeto contendo as factory functions para as integrações pré-configuradas mais comuns.
+ *
+ * @example
+ * ```tsx
+ * import { COMMON_INTEGRATIONS } from 'react-lgpd-consent';
+ * const gaIntegration = COMMON_INTEGRATIONS.googleAnalytics({ measurementId: 'G-XYZ' });
+ * ```
+ */
+declare const COMMON_INTEGRATIONS: {
+    googleAnalytics: typeof createGoogleAnalyticsIntegration;
+    googleTagManager: typeof createGoogleTagManagerIntegration;
+    userway: typeof createUserWayIntegration;
+};
+
+/**
+ * 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;
+}
+/**
+ * @component
+ * @category Utils
+ * @since 0.2.0
+ * Componente que não renderiza UI, mas gerencia o carregamento de scripts de terceiros
+ * (como Google Analytics) com base nas preferências de consentimento do usuário.
+ *
+ * @param props As propriedades do componente.
+ * @param {ScriptIntegration[]} props.integrations Um array de objetos de integração de script. Use as factory functions (`createGoogleAnalyticsIntegration`, etc.) para criar.
+ * @param {boolean} [props.reloadOnChange=false] Se `true`, recarrega os scripts se as preferências de consentimento mudarem.
+ *
+ * @example
+ * ```tsx
+ * const integrations = [
+ *   createGoogleAnalyticsIntegration({ measurementId: 'GA_ID' }),
+ *   createFacebookPixelIntegration({ pixelId: 'PIXEL_ID' })
+ * ];
  *
  * <ConsentScriptLoader integrations={integrations} />
  * ```
  */
 declare function ConsentScriptLoader({ integrations, reloadOnChange, }: Readonly<ConsentScriptLoaderProps>): null;
 /**
- * Hook para carregamento manual de scripts baseado no consentimento.
+ * @hook
+ * @category Hooks
+ * @since 0.2.0
+ * Hook para carregamento programático de um script baseado no consentimento.
+ *
+ * @returns Uma função assíncrona que recebe um objeto de integração de script e tenta carregá-lo.
+ * Retorna `true` em caso de sucesso e `false` em caso de falha (por falta de consentimento ou erro de rede).
  *
  * @example
  * ```tsx
- * function MyComponent() {
- *   const loadConsentScript = useConsentScriptLoader()
+ * const loadScript = useConsentScriptLoader();
  *
- *   React.useEffect(() => {
- *     loadConsentScript({
- *       id: 'my-script',
- *       category: 'analytics',
- *       src: 'https://example.com/script.js'
- *     })
- *   }, [])
- * }
+ * useEffect(() => {
+ *   const handleUserAction = async () => {
+ *     const hotjarIntegration = { id: 'hotjar', category: 'analytics', src: '...' };
+ *     const success = await loadScript(hotjarIntegration);
+ *     if (success) {
+ *       console.log('Hotjar carregado com sucesso!');
+ *     }
+ *   };
+ *
+ *   // Exemplo: carregar script após uma ação específica do usuário
+ *   myButton.addEventListener('click', handleUserAction);
+ * }, [loadScript]);
  * ```
  */
 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, DEFAULT_PROJECT_CATEGORIES, type DeveloperGuidance, type GoogleAnalyticsConfig, type GoogleTagManagerConfig, PreferencesModal, type ProjectCategoriesConfig, type ScriptIntegration, type UserWayConfig, analyzeDeveloperConfiguration, createGoogleAnalyticsIntegration, createGoogleTagManagerIntegration, createUserWayIntegration, defaultConsentTheme, loadScript, useCategories, useCategoryStatus, useConsent, useConsentHydration, useConsentScriptLoader, useConsentTexts };
+/**
+ * @enum LogLevel
+ * @category Utils
+ * @since 0.3.1
+ * Define os níveis de severidade para os logs da biblioteca.
+ */
+declare enum LogLevel {
+    /** Mensagens de erro críticas. */
+    ERROR = 0,
+    /** Mensagens de aviso sobre possíveis problemas. */
+    WARN = 1,
+    /** Mensagens informativas sobre o fluxo da aplicação. */
+    INFO = 2,
+    /** Mensagens detalhadas para depuração. */
+    DEBUG = 3
+}
+/**
+ * @function
+ * @category Utils
+ * @since 0.3.1
+ * Habilita ou desabilita o sistema de logging de debug da biblioteca externamente.
+ * Útil para troubleshooting em produção quando necessário, pois os logs são desabilitados por padrão em builds de produção.
+ *
+ * @param {boolean} enabled Se `true`, os logs serão exibidos; caso contrário, serão suprimidos.
+ * @param {LogLevel} [level=LogLevel.INFO] O nível mínimo de severidade para os logs. Padrão: `LogLevel.INFO`.
+ *
+ * @example
+ * ```typescript
+ * import { setDebugLogging, LogLevel } from 'react-lgpd-consent';
+ *
+ * // Habilitar logs detalhados em desenvolvimento
+ * setDebugLogging(true, LogLevel.DEBUG);
+ *
+ * // Desabilitar todos os logs em produção (já é o padrão, mas pode ser forçado)
+ * setDebugLogging(false);
+ * ```
+ */
+declare function setDebugLogging(enabled: boolean, level?: LogLevel): void;
+
+/**
+ * Propriedades para customizar o comportamento e aparência do componente CookieBanner.
+ *
+ * @remarks
+ * Esta interface permite controle completo sobre o banner de consentimento, desde
+ * o comportamento de exibição até a customização visual avançada. O banner pode
+ * operar em dois modos principais: bloqueante (modal) ou não-bloqueante (snackbar).
+ *
+ * ### Modos de Exibição
+ * - **Bloqueante** (`blocking: true`): Banner como modal sobreposto, impede interação
+ * - **Não-bloqueante** (`blocking: false`): Banner como snackbar, permite navegação
+ *
+ * ### Integração com Material-UI
+ * - Suporte completo a theming via `ThemeProvider`
+ * - Props diretas para componentes internos (`SnackbarProps`, `PaperProps`)
+ * - Compatibilidade com design tokens customizados
+ * - Responsividade automática em diferentes viewport sizes
+ *
+ * ### Debug e Desenvolvimento
+ * - Prop `debug` força exibição independente do estado de consentimento
+ * - Logging automático de interações do usuário quando ativo
+ * - Suporte a React DevTools para inspecionar props
+ *
+ * @example Configuração básica
+ * ```tsx
+ * <CookieBanner
+ *   policyLinkUrl="/privacy-policy"
+ *   blocking={false}
+ * />
+ * ```
+ *
+ * @example Configuração avançada com customização
+ * ```tsx
+ * <CookieBanner
+ *   policyLinkUrl="https://example.com/cookies"
+ *   blocking={true}
+ *   hideBranding={true}
+ *   debug={process.env.NODE_ENV === 'development'}
+ *   SnackbarProps={{
+ *     anchorOrigin: { vertical: 'top', horizontal: 'center' }
+ *   }}
+ *   PaperProps={{
+ *     elevation: 8,
+ *     sx: { borderRadius: 2 }
+ *   }}
+ * />
+ * ```
+ *
+ * @public
+ * @since 0.1.0
+ */
+interface CookieBannerProps {
+    /**
+     * URL para a política de privacidade ou cookies do site.
+     *
+     * @remarks
+     * Quando fornecida, aparece como link "Política de Privacidade" no banner.
+     * Link abre em nova aba/janela (`target="_blank"`) por segurança.
+     *
+     * @example "/privacy-policy" | "https://example.com/cookies"
+     */
+    policyLinkUrl?: string;
+    /**
+     * Força exibição do banner em modo de debug, independente do consentimento.
+     *
+     * @remarks
+     * Útil durante desenvolvimento para testar diferentes estados visuais.
+     * **Nunca deixe `true` em produção** - causará exibição permanente do banner.
+     *
+     * @defaultValue false
+     */
+    debug?: boolean;
+    /**
+     * Controla se o banner bloqueia interação com o restante da página.
+     *
+     * @remarks
+     * - `true`: Banner como modal/overlay, bloqueia interação até decisão
+     * - `false`: Banner como snackbar, permite navegação normal
+     *
+     * Banner bloqueante é mais eficaz para compliance, mas pode afetar UX.
+     *
+     * @defaultValue true
+     */
+    blocking?: boolean;
+    /**
+     * Oculta a marca "fornecido por LÉdipO.eti.br" no banner.
+     *
+     * @remarks
+     * A biblioteca é open-source e gratuita. O branding é uma forma de apoiar
+     * o projeto, mas pode ser removido se necessário para sua marca.
+     *
+     * @defaultValue false
+     */
+    hideBranding?: boolean;
+    /**
+     * Propriedades personalizadas para o componente Snackbar (modo não-bloqueante).
+     *
+     * @remarks
+     * Aplica-se apenas quando `blocking={false}`. Permite customização completa
+     * da posição, animação e comportamento do snackbar do Material-UI.
+     *
+     * @example
+     * ```tsx
+     * SnackbarProps={{
+     *   anchorOrigin: { vertical: 'top', horizontal: 'center' },
+     *   autoHideDuration: null, // Banner fica até decisão do usuário
+     *   TransitionComponent: Slide
+     * }}
+     * ```
+     */
+    SnackbarProps?: Partial<SnackbarProps>;
+    /**
+     * Propriedades personalizadas para o componente Paper que envolve o conteúdo.
+     *
+     * @remarks
+     * Permite customização avançada da aparência: elevação, bordas, cores, etc.
+     * Aplicado em ambos os modos (bloqueante e não-bloqueante).
+     *
+     * @example
+     * ```tsx
+     * PaperProps={{
+     *   elevation: 12,
+     *   sx: {
+     *     borderRadius: '16px',
+     *     border: '2px solid',
+     *     borderColor: 'primary.main'
+     *   }
+     * }}
+     * ```
+     */
+    PaperProps?: Partial<PaperProps>;
+}
+/**
+ * Banner principal de consentimento LGPD que solicita decisão do usuário sobre cookies.
+ * @component
+ * @category Components
+ * @remarks
+ * O CookieBanner é o ponto de entrada principal para interação com o sistema de consentimento.
+ * Aparece automaticamente quando o usuário ainda não tomou decisão sobre cookies,
+ * oferecendo opções claras de aceitar, rejeitar ou personalizar preferências.
+ *
+ * ### Funcionalidades Principais
+ * - **Exibição condicional**: Aparece apenas se usuário não deu consentimento
+ * - **Duas modalidades**: Bloqueante (modal) ou não-bloqueante (snackbar)
+ * - **Ações do usuário**: Aceitar tudo, rejeitar tudo, ou abrir preferências
+ * - **Link para política**: Opção de link para política de privacidade
+ * - **Branding opcional**: Marca discreta "fornecido por LÉdipO.eti.br"
+ * - **Totalmente customizável**: Via props, tokens de design ou componente próprio
+ *
+ * ### Estados de Exibição
+ * - **Não exibido**: Usuário já consentiu ou ainda hidratando (SSR)
+ * - **Snackbar**: Modo não-bloqueante, permite interação com a página
+ * - **Modal**: Modo bloqueante, impede interação até decisão
+ * - **Debug**: Sempre visível independente do estado (desenvolvimento)
+ *
+ * ### Integração com Sistema
+ * - Conecta automaticamente com `ConsentProvider`
+ * - Usa textos do `useConsentTexts()` para i18n
+ * - Aplica design tokens do `useDesignTokens()`
+ * - Registra todas as interações via sistema de logging
+ * - Suporte completo a SSR com hidratação segura
+ *
+ * ### Substituição Personalizada
+ * Para controle total, use `CookieBannerComponent` no ConsentProvider:
+ *
+ * ```tsx
+ * function CustomBanner() {
+ *   const { acceptAll, rejectAll } = useConsent();
+ *   return <div>Meu banner customizado</div>;
+ * }
+ *
+ * <ConsentProvider CookieBannerComponent={CustomBanner}>
+ * ```
+ *
+ * @param props - Propriedades para customizar comportamento e aparência do banner
+ * @returns Banner de consentimento ou `null` se não deve ser exibido
+ *
+ * @example Uso básico (renderizado automaticamente pelo ConsentProvider)
+ * ```typescript
+ * // ConsentProvider renderiza CookieBanner automaticamente
+ * function App() {
+ *   return (
+ *     // ConsentProvider envolve a aplicação
+ *     // CookieBanner aparece quando necessário
+ *   );
+ * }
+ * ```
+ *
+ * @example Customização via props no ConsentProvider
+ * ```typescript
+ * // Configuração com propriedades customizadas
+ * const bannerProps = {
+ *   policyLinkUrl: "/privacy",
+ *   blocking: false,
+ *   hideBranding: true
+ * };
+ *
+ * // ConsentProvider com cookieBannerProps
+ * ```
+ *
+ * @example Uso manual com customização avançada
+ * ```typescript
+ * function App() {
+ *   const bannerConfig = {
+ *     policyLinkUrl: "https://example.com/cookies",
+ *     blocking: true,
+ *     PaperProps: { elevation: 8 },
+ *     SnackbarProps: { anchorOrigin: { vertical: 'top' as const } }
+ *   };
+ *
+ *   // Renderização manual com config avançada
+ *   return null; // CookieBanner com bannerConfig
+ * }
+ * ```
+ *
+ * @see {@link ConsentProvider} - Provider que renderiza este componente automaticamente
+ * @see {@link useConsent} - Hook para acessar funções de consentimento
+ * @see {@link useConsentTexts} - Hook para textos personalizáveis
+ * @see {@link CookieBannerProps} - Interface completa de propriedades
+ *
+ * @public
+ * @since 0.1.0
+ */
+declare function CookieBanner({ policyLinkUrl, debug, blocking, hideBranding, SnackbarProps, PaperProps, }: Readonly<CookieBannerProps>): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * 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;
+}
+/**
+ * @component
+ * @category Components
+ * @since 0.3.0
+ * Botão flutuante para abrir o modal de preferências de cookies.
+ *
+ * @remarks
+ * Este componente é renderizado automaticamente pelo `ConsentProvider` após o consentimento inicial.
+ * Ele permite ao usuário acessar rapidamente as configurações de consentimento LGPD a qualquer momento.
+ * Você pode substituí-lo passando seu próprio componente para a prop `FloatingPreferencesButtonComponent`
+ * no `ConsentProvider`.
+ *
+ * @param {Readonly<FloatingPreferencesButtonProps>} props As propriedades para customizar o botão.
+ * @returns {JSX.Element | null} O componente do botão flutuante ou `null` se não for necessário exibi-lo.
+ */
+declare function FloatingPreferencesButton({ position, offset, icon, tooltip, FabProps, hideWhenConsented, }: Readonly<FloatingPreferencesButtonProps>): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Cria um objeto de preferências de consentimento inicial baseado na configuração de categorias do projeto.
+ * @category Utils
+ * @since 0.2.0
+ * @param config A configuração de categorias do projeto. Se não fornecida, um padrão será usado.
+ * @param defaultValue O valor padrão para categorias não essenciais. Por padrão, `false` para conformidade LGPD (rejeitar por padrão).
+ * @returns Um objeto `ConsentPreferences` com as categorias e seus valores iniciais.
+ * @remarks
+ * Esta função é crucial para inicializar o estado de consentimento. Ela garante que apenas as categorias
+ * definidas no `ConsentProvider` sejam incluídas no objeto de preferências, alinhando-se ao princípio
+ * de minimização de dados da LGPD.
+ * @example
+ * ```ts
+ * // Gera preferências com 'analytics' e 'marketing' desabilitados por padrão
+ * const initialPrefs = createProjectPreferences({
+ *   enabledCategories: ['analytics', 'marketing']
+ * })
+ * // Result: { necessary: true, analytics: false, marketing: false }
+ *
+ * // Gera preferências com todas as categorias habilitadas
+ * const allAcceptedPrefs = createProjectPreferences(
+ *   { enabledCategories: ['analytics', 'marketing'] },
+ *   true
+ * )
+ * // Result: { necessary: true, analytics: true, marketing: true }
+ * ```
+ */
+declare function createProjectPreferences(config?: ProjectCategoriesConfig, defaultValue?: boolean): ConsentPreferences;
+/**
+ * Valida um objeto de preferências de consentimento, removendo categorias que não estão permitidas pela configuração do projeto.
+ * @category Utils
+ * @since 0.2.6
+ * @param preferences O objeto de preferências a ser validado.
+ * @param config A configuração de categorias do projeto. Se não fornecida, um padrão será usado.
+ * @returns Um novo objeto `ConsentPreferences` contendo apenas categorias válidas.
+ * @remarks
+ * Garante a integridade dos dados ao carregar o estado de um cookie. Se a configuração do projeto mudou
+ * (ex: uma categoria foi removida), esta função limpa as preferências obsoletas do estado,
+ * evitando inconsistências.
+ * @example
+ * ```ts
+ * const savedPrefs = { necessary: true, analytics: true, oldCategory: false }
+ * const currentConfig = { enabledCategories: ['analytics'] }
+ *
+ * const validPrefs = validateProjectPreferences(savedPrefs, currentConfig)
+ * // Result: { necessary: true, analytics: true }
+ * ```
+ */
+declare function validateProjectPreferences(preferences: ConsentPreferences, config?: ProjectCategoriesConfig): ConsentPreferences;
+/**
+ * Retorna um array com as definições detalhadas de todas as categorias de cookies ativas no projeto.
+ * @category Utils
+ * @since 0.2.2
+ * @param config A configuração de categorias do projeto. Se não fornecida, um padrão será usado.
+ * @returns Um array de objetos `CategoryDefinition`.
+ * @remarks
+ * Útil para construir UIs de preferência customizadas, pois fornece os nomes e descrições
+ * de todas as categorias que devem ser exibidas ao usuário.
+ * @example
+ * ```ts
+ * const config = { enabledCategories: ['analytics'] }
+ * const categories = getAllProjectCategories(config)
+ * // Result:
+ * // [
+ * //   { id: 'necessary', name: 'Necessários', ... },
+ * //   { id: 'analytics', name: 'Análise e Estatísticas', ... }
+ * // ]
+ * ```
+ */
+declare function getAllProjectCategories(config?: ProjectCategoriesConfig): CategoryDefinition[];
+
+export { COMMON_INTEGRATIONS, type CategoriesContextValue, type Category, type CategoryDefinition, type ConsentContextValue, type ConsentCookieData, type ConsentCookieOptions, ConsentGate, type ConsentPreferences, ConsentProvider, type ConsentProviderProps, ConsentScriptLoader, type ConsentScriptLoaderProps, type ConsentState, type ConsentTexts, CookieBanner, type CookieBannerProps, type CustomCookieBannerProps, type CustomFloatingPreferencesButtonProps, type CustomPreferencesModalProps, DEFAULT_PROJECT_CATEGORIES, type DesignTokens, type DeveloperGuidance, FloatingPreferencesButton, type FloatingPreferencesButtonProps, type GoogleAnalyticsConfig, type GoogleTagManagerConfig, LogLevel, PreferencesModal, type PreferencesModalProps, type ProjectCategoriesConfig, type ScriptIntegration, type UserWayConfig, analyzeDeveloperConfiguration, createGoogleAnalyticsIntegration, createGoogleTagManagerIntegration, createProjectPreferences, createUserWayIntegration, defaultConsentTheme, defaultTexts, getAllProjectCategories, loadScript, openPreferencesModal, setDebugLogging, useCategories, useCategoryStatus, useConsent, useConsentHydration, useConsentScriptLoader, useConsentTexts, useOpenPreferencesModal, validateProjectPreferences };