@react-lgpd-consent/core 0.5.0

package/dist/index.d.ts

@@ -0,0 +1,3845 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React$1 from 'react';
+
+type GuidanceSeverity = 'info' | 'warning' | 'error';
+interface GuidanceMessage {
+    severity: GuidanceSeverity;
+    message: string;
+    category?: string;
+    actionable?: boolean;
+}
+interface GuidanceConfig {
+    /** Controla se avisos devem ser exibidos */
+    showWarnings?: boolean;
+    /** Controla se sugestões devem ser exibidas */
+    showSuggestions?: boolean;
+    /** Controla se a tabela de categorias deve ser exibida */
+    showCategoriesTable?: boolean;
+    /** Controla se as boas práticas devem ser exibidas */
+    showBestPractices?: boolean;
+    /** Controla se deve exibir score de conformidade */
+    showComplianceScore?: boolean;
+    /** Filtro de severidade mínima para exibir mensagens */
+    minimumSeverity?: GuidanceSeverity;
+    /** Callback personalizado para processar mensagens */
+    messageProcessor?: (messages: GuidanceMessage[]) => void;
+}
+interface DeveloperGuidance {
+    warnings: string[];
+    suggestions: string[];
+    messages: GuidanceMessage[];
+    activeCategoriesInfo: {
+        id: string;
+        name: string;
+        description: string;
+        essential: boolean;
+        uiRequired: boolean;
+        cookies?: string[];
+    }[];
+    usingDefaults: boolean;
+    complianceScore?: number;
+}
+declare const DEFAULT_PROJECT_CATEGORIES: ProjectCategoriesConfig;
+/**
+ * Analisa configuração e integrações implícitas para orientar o dev.
+ *
+ * Since v0.4.0: inclui customCategories.
+ * Since v0.4.1: considera categorias/integrações implícitas e enriquece cookies por categoria.
+ */
+declare function analyzeDeveloperConfiguration(config?: ProjectCategoriesConfig): DeveloperGuidance;
+declare function logDeveloperGuidance(guidance: DeveloperGuidance, disableGuidanceProp?: boolean, config?: GuidanceConfig): void;
+declare function useDeveloperGuidance(config?: ProjectCategoriesConfig, disableGuidanceProp?: boolean, guidanceConfig?: GuidanceConfig): DeveloperGuidance;
+/**
+ * Presets de configuração para diferentes ambientes
+ */
+declare const GUIDANCE_PRESETS: {
+    /** Configuração completa para desenvolvimento */
+    readonly development: {
+        readonly showWarnings: true;
+        readonly showSuggestions: true;
+        readonly showCategoriesTable: true;
+        readonly showBestPractices: true;
+        readonly showComplianceScore: true;
+        readonly minimumSeverity: "info";
+    };
+    /** Configuração silenciosa para produção */
+    readonly production: {
+        readonly showWarnings: false;
+        readonly showSuggestions: false;
+        readonly showCategoriesTable: false;
+        readonly showBestPractices: false;
+        readonly showComplianceScore: false;
+        readonly minimumSeverity: "error";
+    };
+    /** Apenas erros críticos */
+    readonly minimal: {
+        readonly showWarnings: true;
+        readonly showSuggestions: false;
+        readonly showCategoriesTable: false;
+        readonly showBestPractices: false;
+        readonly showComplianceScore: false;
+        readonly minimumSeverity: "error";
+    };
+    /** Focado em conformidade LGPD */
+    readonly compliance: {
+        readonly showWarnings: true;
+        readonly showSuggestions: true;
+        readonly showCategoriesTable: true;
+        readonly showBestPractices: true;
+        readonly showComplianceScore: true;
+        readonly minimumSeverity: "warning";
+    };
+};
+
+/**
+ * @fileoverview
+ * Definições de tipos TypeScript para o sistema de consentimento LGPD/ANPD.
+ *
+ * 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.
+ *
+ * @author Luciano Édipo
+ * @since 0.1.0
+ */
+/**
+ * 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 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
+ * // Categoria padrão da biblioteca
+ * const analyticsCategory: CategoryDefinition = {
+ *   id: 'analytics',
+ *   name: 'Cookies Analíticos',
+ *   description: 'Utilizados para análise de uso do site',
+ *   essential: false,
+ *   cookies: ['_ga', '_ga_*', '_gid']
+ * };
+ *
+ * // Categoria customizada específica do projeto
+ * const chatCategory: CategoryDefinition = {
+ *   id: 'chat',
+ *   name: 'Chat de Suporte',
+ *   description: 'Widget de chat para suporte ao cliente',
+ *   essential: false
+ * };
+ * ```
+ *
+ * @public
+ */
+interface CategoryDefinition {
+    /**
+     * Identificador único da categoria.
+     * @example 'analytics'
+     */
+    id: string;
+    /**
+     * Nome amigável exibido na interface do usuário.
+     * @example 'Cookies Analíticos'
+     */
+    name: string;
+    /**
+     * Descrição detalhada da finalidade da categoria.
+     * @example 'Utilizados para análise de uso e comportamento no site'
+     */
+    description: string;
+    /**
+     * Indica se é uma categoria essencial que não pode ser desabilitada pelo usuário.
+     * @defaultValue false
+     */
+    essential?: boolean;
+    /**
+     * Lista de nomes de cookies ou padrões específicos desta categoria.
+     * @example ['_ga', '_ga_*', '_gid']
+     */
+    cookies?: string[];
+    /**
+     * Metadados detalhados sobre cookies típicos desta categoria.
+     * Não exaustivo; serve para orientar UI e documentação.
+     */
+    cookiesInfo?: CookieDescriptor[];
+}
+/**
+ * Descritor de cookie com metadados úteis para UI/documentação.
+ * @category Types
+ * @since 0.2.0
+ *
+ * @remarks
+ * Mantém compatibilidade com abordagens comuns no mercado.
+ * Fornece informações detalhadas sobre cookies para exibição em interfaces
+ * e documentação de compliance.
+ *
+ * @example
+ * ```typescript
+ * const cookieInfo: CookieDescriptor = {
+ *   name: '_ga',
+ *   purpose: 'analytics',
+ *   duration: '2 years',
+ *   domain: '.example.com',
+ *   provider: 'Google Analytics'
+ * };
+ * ```
+ *
+ * @public
+ */
+interface CookieDescriptor {
+    /**
+     * Identificador ou padrão do cookie.
+     * @example '_ga'
+     */
+    name: string;
+    /**
+     * Finalidade do cookie (opcional).
+     * @example 'analytics'
+     */
+    purpose?: string;
+    /**
+     * Tempo de retenção do cookie (opcional).
+     * @example '2 years'
+     */
+    duration?: string;
+    /**
+     * Domínio associado ao cookie (opcional).
+     * @example '.example.com'
+     */
+    domain?: string;
+    /**
+     * Provedor ou serviço associado ao cookie (opcional).
+     * @example 'Google Analytics'
+     */
+    provider?: string;
+}
+/**
+ * Configuração de categorias ativas no projeto.
+ * @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: 'chat',
+ *       name: 'Chat de Suporte',
+ *       description: 'Widget de chat para suporte ao cliente'
+ *     },
+ *     {
+ *       id: 'abTesting',
+ *       name: 'A/B Testing',
+ *       description: 'Experimentos de interface e funcionalidades'
+ *     }
+ *   ]
+ * };
+ * ```
+ *
+ * @public
+ */
+interface ProjectCategoriesConfig {
+    /**
+     * 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.
+     * @example [{ id: 'chat', name: 'Chat de Suporte', description: 'Widget de chat' }]
+     */
+    customCategories?: CategoryDefinition[];
+}
+/**
+ * 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;
+}
+/**
+ * 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 compatibilidade e migração futura.
+     * @example '1.0'
+     */
+    version: string;
+    /**
+     * Indica se o usuário já prestou consentimento explícito.
+     * @example true
+     */
+    consented: boolean;
+    /**
+     * Preferências detalhadas por categoria de cookies.
+     * Contém apenas as categorias ativas no projeto.
+     */
+    preferences: ConsentPreferences;
+    /**
+     * Timestamp ISO 8601 da primeira interação com o banner de consentimento.
+     * @example '2024-01-15T10:30:00.000Z'
+     */
+    consentDate: string;
+    /**
+     * 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 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 no momento do consentimento.
+     * Útil para detectar mudanças na configuração e solicitar novo consentimento.
+     */
+    projectConfig?: ProjectCategoriesConfig;
+}
+/**
+ * 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 {
+    /**
+     * 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;
+}
+/**
+ * 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 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.
+ * @property declineAll - Texto do botão para recusar todos os cookies.
+ * @property preferences - Texto do botão para abrir preferências.
+ * @property policyLink - (Opcional) Link para política de privacidade.
+ * @property modalTitle - Título do modal de preferências.
+ * @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;
+    acceptAll: string;
+    declineAll: string;
+    preferences: string;
+    policyLink?: string;
+    modalTitle: string;
+    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;
+    userRights?: string;
+    contactInfo?: string;
+    retentionPeriod?: string;
+    lawfulBasis?: string;
+    transferCountries?: string;
+}
+/**
+ * Opções para configuração do cookie de consentimento.
+ * @category Types
+ * @since 0.1.0
+ * @public
+ */
+interface ConsentCookieOptions {
+    /** Nome do cookie. Padrão: 'cookieConsent' */
+    name: string;
+    /** Tempo de expiração em dias. Padrão: 365 */
+    maxAgeDays: number;
+    /** Política SameSite do cookie. */
+    sameSite: 'Lax' | 'Strict';
+    /** Se o cookie deve ser seguro (HTTPS). Padrão: true */
+    secure: boolean;
+    /** Caminho do cookie. Padrão: '/' */
+    path: string;
+}
+/**
+ * Tipo alias para valores de espaçamento que suportam eixos x/y.
+ * @category Types
+ * @since 0.1.3
+ * @remarks
+ * Permite especificar espaçamento como string, número ou objeto com eixos x e y separados.
+ * Útil para configurações de padding e margin em design tokens.
+ * @example
+ * ```typescript
+ * const spacing: SpacingValue = { x: 10, y: 20 };
+ * ```
+ */
+type SpacingValue = string | number | {
+    x?: string | number;
+    y?: string | number;
+};
+/**
+ * Tipo alias para cores com variações.
+ * @category Types
+ * @since 0.1.3
+ * @remarks
+ * Suporta cor simples ou objeto com variações light, main, dark e contrastText.
+ * Compatível com sistemas de design que precisam de paletas completas.
+ * @example
+ * ```typescript
+ * const color: ColorVariant = { main: '#1976d2', dark: '#1565c0' };
+ * ```
+ */
+type ColorVariant = string | {
+    light?: string;
+    main?: string;
+    dark?: string;
+    contrastText?: string;
+};
+/**
+ * Tipo alias para altura com auto.
+ * @category Types
+ * @since 0.1.3
+ * @remarks
+ * Permite 'auto' ou qualquer string válida para altura CSS, com type safety.
+ * Evita valores inválidos através de interseção com Record<never, never>.
+ * @example
+ * ```typescript
+ * const height: HeightValue = 'auto';
+ * const customHeight: HeightValue = '100px';
+ * ```
+ */
+type HeightValue = 'auto' | (string & Record<never, never>);
+/**
+ * Tipo alias para configuração de backdrop.
+ * @category Types
+ * @since 0.1.3
+ * @remarks
+ * Define configuração do backdrop como booleano simples, string de cor ou objeto detalhado
+ * com propriedades como enabled, color, blur e opacity para controle granular.
+ * @example
+ * ```typescript
+ * const backdrop: BackdropConfig = { enabled: true, color: 'rgba(0,0,0,0.5)', blur: '4px' };
+ * ```
+ */
+type BackdropConfig = boolean | string | {
+    enabled?: boolean;
+    color?: string;
+    blur?: string;
+    opacity?: number;
+};
+/**
+ * Tokens de design para customização visual avançada dos componentes.
+ *
+ * Sistema robusto de design tokens que permite controle granular sobre todos os aspectos
+ * visuais da biblioteca. Suporta responsive design, estados interativos, acessibilidade
+ * e temas dark/light.
+ *
+ * @category Types
+ * @since 0.1.3
+ * @version 0.4.1 - Expandido substancialmente com novos tokens
+ * @public
+ *
+ * @example Configuração básica
+ * ```tsx
+ * const tokens: DesignTokens = {
+ *   colors: {
+ *     primary: '#1976d2',
+ *     background: '#ffffff',
+ *     text: '#333333'
+ *   }
+ * }
+ * ```
+ *
+ * @example Configuração avançada com responsive e estados
+ * ```tsx
+ * const advancedTokens: DesignTokens = {
+ *   colors: {
+ *     primary: { light: '#42a5f5', main: '#1976d2', dark: '#1565c0' },
+ *     semantic: {
+ *       error: '#f44336',
+ *       warning: '#ff9800',
+ *       success: '#4caf50',
+ *       info: '#2196f3'
+ *     }
+ *   },
+ *   spacing: {
+ *     responsive: {
+ *       mobile: { padding: '12px', margin: '8px' },
+ *       tablet: { padding: '16px', margin: '12px' },
+ *       desktop: { padding: '24px', margin: '16px' }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+interface DesignTokens {
+    /**
+     * Sistema de cores expandido com suporte a variações e semântica
+     */
+    colors?: {
+        /** Cor primária da aplicação */
+        primary?: ColorVariant;
+        /** Cor secundária */
+        secondary?: ColorVariant;
+        /** Cor de fundo principal */
+        background?: string | {
+            main?: string;
+            paper?: string;
+            overlay?: string;
+            default?: string;
+        };
+        /** Cor do texto */
+        text?: string | {
+            primary?: string;
+            secondary?: string;
+            disabled?: string;
+        };
+        /** Cor da borda */
+        border?: ColorVariant;
+        /** Cores semânticas para estados */
+        semantic?: {
+            error?: string;
+            warning?: string;
+            success?: string;
+            info?: string;
+        };
+        /** Cores específicas para componentes */
+        components?: {
+            banner?: {
+                background?: string;
+                text?: string;
+                border?: string;
+                shadow?: string;
+            };
+            modal?: {
+                background?: string;
+                text?: string;
+                overlay?: string;
+                border?: string;
+            };
+            button?: {
+                primary?: {
+                    background?: string;
+                    text?: string;
+                    hover?: string;
+                };
+                secondary?: {
+                    background?: string;
+                    text?: string;
+                    hover?: string;
+                };
+                outlined?: {
+                    border?: string;
+                    text?: string;
+                    hover?: string;
+                };
+            };
+        };
+    };
+    /**
+     * Sistema tipográfico completo com hierarquia e responsive
+     */
+    typography?: {
+        /** Família de fontes principal */
+        fontFamily?: string | {
+            primary?: string;
+            secondary?: string;
+            monospace?: string;
+        };
+        /** Tamanhos de fonte com hierarchy */
+        fontSize?: {
+            /** Tamanhos para banner */
+            banner?: {
+                title?: string;
+                message?: string;
+                button?: string;
+            };
+            /** Tamanhos para modal */
+            modal?: {
+                title?: string;
+                body?: string;
+                button?: string;
+                caption?: string;
+            };
+            /** Scale tipográfica */
+            scale?: {
+                xs?: string;
+                sm?: string;
+                base?: string;
+                lg?: string;
+                xl?: string;
+                '2xl'?: string;
+                '3xl'?: string;
+            };
+            /** Tamanhos específicos de cabeçalhos */
+            h1?: string;
+            h2?: string;
+            h3?: string;
+            h4?: string;
+            h5?: string;
+            h6?: string;
+        };
+        /** Pesos de fonte */
+        fontWeight?: {
+            light?: number;
+            normal?: number;
+            medium?: number;
+            semibold?: number;
+            bold?: number;
+        };
+        /** Altura de linha */
+        lineHeight?: {
+            tight?: number;
+            normal?: number;
+            relaxed?: number;
+            loose?: number;
+        };
+        /** Espaçamento de letras */
+        letterSpacing?: {
+            tight?: string;
+            normal?: string;
+            wide?: string;
+        };
+    };
+    /**
+     * Sistema de espaçamento e dimensões flexível
+     */
+    spacing?: {
+        /** Valores diretos de espaçamento */
+        xs?: string | number;
+        sm?: string | number;
+        md?: string | number;
+        lg?: string | number;
+        xl?: string | number;
+        /** Escala de espaçamento base */
+        scale?: {
+            xs?: string | number;
+            sm?: string | number;
+            md?: string | number;
+            lg?: string | number;
+            xl?: string | number;
+            '2xl'?: string | number;
+            '3xl'?: string | number;
+        };
+        /** Padding específico por componente */
+        padding?: {
+            banner?: SpacingValue;
+            modal?: SpacingValue;
+            button?: SpacingValue;
+        };
+        /** Margem específica por componente */
+        margin?: {
+            banner?: SpacingValue;
+            modal?: SpacingValue;
+            button?: SpacingValue;
+        };
+        /** Bordas arredondadas */
+        borderRadius?: {
+            banner?: string | number;
+            modal?: string | number;
+            button?: string | number;
+            /** Scale de border radius */
+            scale?: {
+                none?: string | number;
+                sm?: string | number;
+                md?: string | number;
+                lg?: string | number;
+                xl?: string | number;
+                full?: string | number;
+            };
+        };
+        /** Configurações responsive */
+        responsive?: {
+            mobile?: {
+                padding?: string | number;
+                margin?: string | number;
+                borderRadius?: string | number;
+            };
+            tablet?: {
+                padding?: string | number;
+                margin?: string | number;
+                borderRadius?: string | number;
+            };
+            desktop?: {
+                padding?: string | number;
+                margin?: string | number;
+                borderRadius?: string | number;
+            };
+        };
+    };
+    /**
+     * Configurações de layout e posicionamento
+     */
+    layout?: {
+        /** Posição do banner */
+        position?: 'bottom' | 'top' | 'floating' | 'center';
+        /** Larguras por breakpoint */
+        width?: {
+            mobile?: string;
+            tablet?: string;
+            desktop?: string;
+            max?: string;
+        };
+        /** Alturas específicas */
+        height?: {
+            banner?: HeightValue;
+            modal?: HeightValue;
+            button?: HeightValue;
+        };
+        /** Configuração do backdrop */
+        backdrop?: BackdropConfig;
+        /** Z-index para layering */
+        zIndex?: {
+            banner?: number;
+            modal?: number;
+            backdrop?: number;
+            floatingButton?: number;
+        };
+        /** Breakpoints customizados */
+        breakpoints?: {
+            mobile?: string;
+            tablet?: string;
+            desktop?: string;
+            wide?: string;
+        };
+        /** Border radius para componentes */
+        borderRadius?: string | number | {
+            banner?: string | number;
+            modal?: string | number;
+            button?: string | number;
+            scale?: {
+                none?: string | number;
+                sm?: string | number;
+                md?: string | number;
+                lg?: string | number;
+                xl?: string | number;
+                full?: string | number;
+            };
+        };
+    };
+    /**
+     * Efeitos visuais e interações
+     */
+    effects?: {
+        /** Sombras */
+        shadow?: {
+            banner?: string;
+            modal?: string;
+            button?: string;
+            /** Scale de sombras */
+            scale?: {
+                none?: string;
+                sm?: string;
+                md?: string;
+                lg?: string;
+                xl?: string;
+            };
+        };
+        /** Transições e animações */
+        transitions?: {
+            duration?: {
+                fast?: string;
+                normal?: string;
+                slow?: string;
+            };
+            easing?: {
+                linear?: string;
+                easeIn?: string;
+                easeOut?: string;
+                easeInOut?: string;
+            };
+            /** Transições específicas */
+            banner?: {
+                enter?: string;
+                exit?: string;
+            };
+            modal?: {
+                enter?: string;
+                exit?: string;
+            };
+        };
+        /** Blur e filtros */
+        filters?: {
+            backdrop?: string;
+            disabled?: string;
+        };
+    };
+    /**
+     * Configurações de acessibilidade
+     */
+    accessibility?: {
+        /** Contraste mínimo */
+        contrast?: {
+            normal?: number;
+            enhanced?: number;
+        };
+        /** Configurações para motion */
+        motion?: {
+            respectPreferences?: boolean;
+            reducedMotion?: {
+                duration?: string;
+                easing?: string;
+            };
+        };
+        /** Focus indicators */
+        focus?: {
+            color?: string;
+            width?: string;
+            style?: 'solid' | 'dashed' | 'dotted';
+            offset?: string;
+        };
+    };
+    /**
+     * Temas e variações
+     */
+    themes?: {
+        /** Configurações específicas para tema claro */
+        light?: Partial<Omit<DesignTokens, 'themes'>>;
+        /** Configurações específicas para tema escuro */
+        dark?: Partial<Omit<DesignTokens, 'themes'>>;
+        /** Auto-detecção baseada no sistema */
+        auto?: boolean;
+    };
+}
+/**
+ * Propriedades do componente ConsentProvider - configuração principal da biblioteca.
+ * @category Types
+ * @since 0.1.0
+ * @public
+ *
+ * @example Uso básico (configuração mínima):
+ * ```tsx
+ * <ConsentProvider
+ *   categories={{ enabledCategories: ['analytics'] }}
+ * >
+ *   <App />
+ * </ConsentProvider>
+ * ```
+ *
+ * @example Configuração completa com textos ANPD:
+ * ```tsx
+ * <ConsentProvider
+ *   categories={{
+ *     enabledCategories: ['analytics', 'functional'],
+ *   }}
+ *   texts={{
+ *     bannerMessage: 'Utilizamos cookies conforme LGPD...',
+ *     controllerInfo: 'Controlado por: Ministério XYZ - CNPJ: 00.000.000/0001-00',
+ *     dataTypes: 'Coletamos: dados de navegação para análise estatística',
+ *     userRights: 'Direitos: acessar, corrigir, excluir dados',
+ *     contactInfo: 'DPO: dpo@ministerio.gov.br'
+ *   }}
+ *   onConsentGiven={(state) => console.log('Consentimento:', state)}
+ * >
+ *   <App />
+ * </ConsentProvider>
+ * ```
+ */
+interface ConsentProviderProps {
+    /**
+     * Estado inicial do consentimento para hidratação SSR.
+     *
+     * @example
+     * ```tsx
+     * // Em Next.js para evitar flash do banner
+     * <ConsentProvider initialState={{ consented: true, preferences: {...} }}>
+     * ```
+     */
+    initialState?: ConsentState;
+    /**
+     * Configuração das categorias de cookies utilizadas no projeto.
+     * Define quais categorias padrão serão habilitadas.
+     *
+     * @example Apenas analytics:
+     * ```tsx
+     * categories={{ enabledCategories: ['analytics'] }}
+     * ```
+     *
+     * @example Com categoria padrão apenas:
+     * ```tsx
+     * categories={{ enabledCategories: ['analytics', 'marketing'] }}
+     * ```
+     */
+    categories?: ProjectCategoriesConfig;
+    /**
+     * Textos customizados da interface (banner e modal).
+     * Todos os campos são opcionais - valores não fornecidos usam o padrão em português.
+     *
+     * @example Textos básicos:
+     * ```tsx
+     * texts={{
+     *   bannerMessage: 'We use cookies...',
+     *   acceptAll: 'Accept All',
+     *   declineAll: 'Reject'
+     * }}
+     * ```
+     *
+     * @example Textos ANPD para compliance:
+     * ```tsx
+     * texts={{
+     *   controllerInfo: 'Controlado por: Empresa XYZ - CNPJ: 12.345.678/0001-90',
+     *   dataTypes: 'Coletamos: endereço IP, preferências de navegação',
+     *   userRights: 'Você pode solicitar acesso, correção ou exclusão dos seus dados'
+     * }}
+     * ```
+     */
+    texts?: Partial<ConsentTexts>;
+    /**
+     * 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 } }
+     * }}
+     * ```
+     */
+    designTokens?: DesignTokens;
+    /**
+     * Componente customizado para substituir o modal padrão de preferências.
+     * Deve implementar a lógica de consentimento usando as props definidas em `CustomPreferencesModalProps`.
+     */
+    PreferencesModalComponent?: React.ComponentType<CustomPreferencesModalProps>;
+    /** Props adicionais passadas para o modal customizado (repassadas sem transformação). */
+    preferencesModalProps?: Record<string, unknown>;
+    /**
+     * 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`.
+     */
+    CookieBannerComponent?: React.ComponentType<CustomCookieBannerProps>;
+    /** Props adicionais passadas para o banner customizado (repassadas sem transformação). */
+    cookieBannerProps?: Record<string, unknown>;
+    /**
+     * 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 (repassadas sem transformação). */
+    floatingPreferencesButtonProps?: Record<string, unknown>;
+    /**
+     * 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
+     * - `true`: Banner bloqueia interação até decisão (compliance rigorosa)
+     */
+    blocking?: boolean;
+    /**
+     * Estratégia de bloqueio quando `blocking` estiver habilitado.
+     * - 'auto' (padrão):
+     *   - Se usar o banner padrão da lib, o bloqueio visual/funcional fica a cargo do próprio banner.
+     *   - Se usar `CookieBannerComponent` custom, o Provider NÃO cria overlay; o bloqueio fica a cargo do componente custom (compatibilidade atual).
+     * - 'provider': o Provider cria um overlay de bloqueio por cima da aplicação (e abaixo do banner),
+     *   garantindo que cliques sejam bloqueados, independentemente do banner custom implementar ou não esse comportamento.
+     * - 'component': nenhum overlay do Provider; espera-se que o banner (padrão ou custom) trate o bloqueio.
+     *
+     * Observações:
+     * - Visual do overlay do Provider controlado por `designTokens.layout.backdrop`:
+     *   - `false`: overlay transparente (bloqueia cliques sem escurecer — útil quando o app já possui um dark-filter visual próprio).
+     *   - `string` (ex.: 'rgba(0,0,0,0.4)'): overlay com escurecimento gerenciado pela lib.
+     * - A11y: recomenda-se que o banner use semântica de diálogo (role="dialog", aria-modal="true") e trap de foco.
+     */
+    blockingStrategy?: 'auto' | 'provider' | 'component';
+    /** Oculta o branding "fornecido por LÉdipO.eti.br" dos componentes. */
+    hideBranding?: boolean;
+    /**
+     * Callback executado quando usuário dá consentimento pela primeira vez.
+     * Útil para inicializar analytics, registrar evento, etc.
+     *
+     * @example
+     * ```tsx
+     * onConsentGiven={(state) => {
+     *   console.log('Consentimento registrado:', state)
+     *   // Inicializar Google Analytics, etc.
+     * }}
+     * ```
+     */
+    onConsentGiven?: (state: ConsentState) => void;
+    /**
+     * Callback executado quando usuário modifica preferências.
+     * Executado após salvar as mudanças.
+     *
+     * @example
+     * ```tsx
+     * onPreferencesSaved={(prefs) => {
+     *   console.log('Novas preferências:', prefs)
+     *   // Reconfigurar scripts baseado nas preferências
+     * }}
+     * ```
+     */
+    onPreferencesSaved?: (prefs: ConsentPreferences) => void;
+    /**
+     * Configurações do cookie de consentimento.
+     * Valores não fornecidos usam padrões seguros para LGPD.
+     *
+     * @example
+     * ```tsx
+     * cookie={{
+     *   name: 'meuAppConsent',
+     *   maxAgeDays: 180,
+     *   sameSite: 'Strict'
+     * }}
+     * ```
+     */
+    cookie?: Partial<ConsentCookieOptions>;
+    /**
+     * Desabilita os avisos e sugestões para desenvolvedores no console.
+     * Útil para ambientes de produção ou quando os avisos não são desejados.
+     * Por padrão, os avisos já são desabilitados em builds de produção.
+     */
+    disableDeveloperGuidance?: boolean;
+    /**
+     * Desabilita o log automático de descoberta de cookies em modo desenvolvimento.
+     * Mesmo com `disableDeveloperGuidance` ativado, por padrão a descoberta é logada uma vez para ajudar o mapeamento.
+     * Use esta prop para suprimir também esse log experimental.
+     * @since 0.4.1
+     */
+    disableDiscoveryLog?: boolean;
+    /**
+     * Configuração avançada para o sistema de developer guidance.
+     * Permite controle granular sobre quais tipos de guias são exibidos e como.
+     * @since 0.4.1
+     * @example
+     * ```tsx
+     * // Usar preset de desenvolvimento
+     * guidanceConfig={GUIDANCE_PRESETS.development}
+     *
+     * // Configuração personalizada
+     * guidanceConfig={{
+     *   showWarnings: true,
+     *   showComplianceScore: true,
+     *   minimumSeverity: 'warning'
+     * }}
+     * ```
+     */
+    guidanceConfig?: GuidanceConfig;
+    /** Elementos filhos - toda a aplicação que precisa de contexto de consentimento. */
+    children: React.ReactNode;
+}
+/**
+ * Props esperadas por um componente customizado de CookieBanner.
+ * @category Types
+ * @since 0.3.1
+ * @public
+ * 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;
+    /**
+     * Indica se o modo bloqueante está ativo no contexto.
+     * Esta prop é apenas informativa para banners customizados ajustarem sua UI.
+     * O bloqueio funcional pode ser garantido pelo Provider quando `blockingStrategy='provider'`.
+     */
+    blocking?: boolean;
+}
+/**
+ * Props esperadas por um componente customizado de PreferencesModal.
+ * @category Types
+ * @since 0.3.1
+ * @public
+ *
+ * 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.
+ * @category Types
+ * @since 0.3.1
+ * @public
+ * 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.
+ * @category Types
+ * @since 0.1.0
+ * @public
+ */
+interface ConsentContextValue {
+    /** Indica se o usuário consentiu. */
+    consented: boolean;
+    /** Preferências atuais do usuário. */
+    preferences: ConsentPreferences;
+    /** Indica se o modal de preferências está aberto. */
+    isModalOpen?: boolean;
+    /** Aceita todas as categorias de consentimento. */
+    acceptAll: () => void;
+    /** Rejeita todas as categorias de consentimento. */
+    rejectAll: () => void;
+    /**
+     * Define a preferência para uma categoria específica.
+     * Suporta tanto categorias predefinidas quanto customizadas.
+     *
+     * @param cat - ID da categoria (predefinida ou customizada)
+     * @param value - Valor do consentimento para a categoria
+     *
+     * @breakingChange
+     * **v0.4.1**: Parâmetro `cat` mudou de `Category` para `string` para suportar
+     * categorias customizadas. O uso com strings literais continua funcionando.
+     *
+     * @example
+     * ```typescript
+     * // ✅ Continua funcionando (categorias predefinidas)
+     * setPreference('analytics', true)
+     * setPreference('marketing', false)
+     *
+     * // ✅ Novo: categorias customizadas
+     * setPreference('custom-tracking', true)
+     * ```
+     */
+    setPreference: (cat: string, value: boolean) => void;
+    /** Define múltiplas preferências de uma vez e salva. */
+    setPreferences: (preferences: ConsentPreferences) => void;
+    /** Abre o modal de preferências. */
+    openPreferences: () => void;
+    /** Fecha o modal de preferências. */
+    closePreferences: () => void;
+    /** Reseta o consentimento do usuário. */
+    resetConsent: () => void;
+}
+/**
+ * Origem da ação de consentimento que gerou um evento.
+ * @category Types
+ * @since 0.4.5
+ *
+ * @remarks
+ * Utilizado para rastrear a origem da ação de consentimento nos eventos do dataLayer.
+ *
+ * - `'banner'`: Ação realizada através do banner de cookies.
+ * - `'modal'`: Ação realizada através do modal de preferências.
+ * - `'reset'`: Ação de reset de consentimento.
+ * - `'programmatic'`: Ação realizada programaticamente via API.
+ *
+ * @example
+ * ```typescript
+ * const origin: ConsentEventOrigin = 'banner';
+ * ```
+ *
+ * @public
+ */
+type ConsentEventOrigin = 'banner' | 'modal' | 'reset' | 'programmatic';
+/**
+ * Payload do evento `consent_initialized` disparado no dataLayer.
+ * @category Types
+ * @since 0.4.5
+ *
+ * @remarks
+ * Este evento é disparado quando o sistema de consentimento é inicializado.
+ * Útil para rastreamento de primeira visualização e auditoria LGPD.
+ *
+ * @example
+ * ```typescript
+ * // Exemplo de evento no dataLayer
+ * window.dataLayer.push({
+ *   event: 'consent_initialized',
+ *   consent_version: '0.4.5',
+ *   timestamp: '2025-10-25T13:52:33.729Z',
+ *   categories: {
+ *     necessary: true,
+ *     analytics: false,
+ *     marketing: false
+ *   }
+ * });
+ * ```
+ *
+ * @public
+ */
+interface ConsentInitializedEvent {
+    /** Nome do evento (sempre 'consent_initialized') */
+    event: 'consent_initialized';
+    /** Versão da biblioteca react-lgpd-consent */
+    consent_version: string;
+    /** Timestamp ISO 8601 da inicialização */
+    timestamp: string;
+    /** Estado inicial das categorias de consentimento */
+    categories: Record<string, boolean>;
+}
+/**
+ * Payload do evento `consent_updated` disparado no dataLayer.
+ * @category Types
+ * @since 0.4.5
+ *
+ * @remarks
+ * Este evento é disparado sempre que o usuário atualiza suas preferências de consentimento.
+ * Útil para rastreamento, auditoria LGPD e integrações com GTM.
+ *
+ * @example
+ * ```typescript
+ * // Exemplo de evento no dataLayer após aceitar analytics
+ * window.dataLayer.push({
+ *   event: 'consent_updated',
+ *   consent_version: '0.4.5',
+ *   timestamp: '2025-10-25T13:52:33.729Z',
+ *   origin: 'modal',
+ *   categories: {
+ *     necessary: true,
+ *     analytics: true,
+ *     marketing: false
+ *   },
+ *   changed_categories: ['analytics']
+ * });
+ * ```
+ *
+ * @see {@link ConsentEventOrigin} para valores possíveis de `origin`
+ * @public
+ */
+interface ConsentUpdatedEvent {
+    /** Nome do evento (sempre 'consent_updated') */
+    event: 'consent_updated';
+    /** Versão da biblioteca react-lgpd-consent */
+    consent_version: string;
+    /** Timestamp ISO 8601 da atualização */
+    timestamp: string;
+    /** Origem da ação que gerou a atualização */
+    origin: ConsentEventOrigin;
+    /** Estado atualizado das categorias de consentimento */
+    categories: Record<string, boolean>;
+    /** Lista de categorias que foram modificadas nesta atualização */
+    changed_categories: string[];
+}
+/**
+ * União de todos os tipos de eventos de consentimento.
+ * @category Types
+ * @since 0.4.5
+ *
+ * @public
+ */
+type ConsentEvent = ConsentInitializedEvent | ConsentUpdatedEvent;
+
+/**
+ * @component
+ * @category Context
+ * @since 0.1.0
+ * Provider principal da biblioteca. Envolva sua aplicação com este componente para habilitar o gerenciamento de consentimento.
+ *
+ * @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 {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
+ * ```tsx
+ * // Uso básico
+ * <ConsentProvider categories={{ enabledCategories: ['analytics'] }}>
+ *   <MyApp />
+ * </ConsentProvider>
+ * ```
+ *
+ * @example
+ * ```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 ConsentProvider({ initialState, categories, texts: textsProp, designTokens, PreferencesModalComponent, preferencesModalProps, CookieBannerComponent, cookieBannerProps, FloatingPreferencesButtonComponent, floatingPreferencesButtonProps, disableFloatingPreferencesButton, blocking, blockingStrategy, hideBranding: _hideBranding, onConsentGiven, onPreferencesSaved, cookie: cookieOpts, disableDeveloperGuidance, guidanceConfig, children, disableDiscoveryLog, }: Readonly<ConsentProviderProps>): react_jsx_runtime.JSX.Element;
+declare const defaultTexts: ConsentTexts;
+
+/**
+ * @fileoverview
+ * Hooks públicos para interação com o sistema de consentimento LGPD.
+ *
+ * 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.
+ *
+ * @author Luciano Édipo
+ * @since 0.1.0
+ */
+
+/**
+ * Hook principal para acessar e manipular o estado de consentimento de cookies LGPD.
+ *
+ * @remarks
+ * 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.
+ *
+ * ### 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 all  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;
+/**
+ * @function
+ * @category Hooks
+ * @since 0.3.1
+ * Hook para abrir o modal de preferências programaticamente.
+ *
+ * @returns Função para abrir o modal de preferências.
+ *
+ * @remarks
+ * Este hook retorna uma função que pode ser usada para abrir o modal de preferências
+ * de qualquer lugar dentro do contexto do ConsentProvider. É útil para criar botões
+ * customizados ou trigger o modal baseado em eventos específicos.
+ *
+ * @throws {Error} Se usado fora do ConsentProvider
+ *
+ * @example
+ * ```tsx
+ * function CustomButton() {
+ *   const openPreferences = useOpenPreferencesModal();
+ *
+ *   return (
+ *     <button onClick={openPreferences}>
+ *       Configurar Cookies
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useOpenPreferencesModal(): () => void;
+/**
+ * @function
+ * @category Utils
+ * @since 0.3.1
+ * Função global para abrir o modal de preferências de fora do contexto React.
+ *
+ * @remarks
+ * Esta função permite abrir o modal de preferências de código JavaScript puro,
+ * sem precisar estar dentro do contexto React. É útil para integração com
+ * código legado ou bibliotecas de terceiros.
+ *
+ * A função é automaticamente registrada pelo ConsentProvider e limpa quando
+ * o provider é desmontado.
+ *
+ * @example
+ * ```javascript
+ * // Em código JavaScript puro
+ * window.openPreferencesModal?.();
+ *
+ * // Ou importando diretamente
+ * import { openPreferencesModal } from 'react-lgpd-consent';
+ * openPreferencesModal();
+ * ```
+ */
+declare function openPreferencesModal(): void;
+
+/**
+ * @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;
+};
+
+/**
+ * Provider que envolve a árvore de componentes para fornecer tokens de design via contexto.
+ *
+ * @remarks
+ * Use este provider no topo da aplicação ou seção onde os componentes de consentimento
+ * precisam acessar tokens de design. Permite overrides globais de design sem alterar
+ * os componentes individuais, mantendo tree-shaking e performance.
+ *
+ * @param tokens - Tokens de design opcionais para customização (cores, layouts, etc.)
+ * @param children - Componentes filhos que terão acesso aos tokens via contexto
+ *
+ * @example Uso básico com tokens padrão
+ * ```tsx
+ * import { DesignProvider } from './context/DesignContext';
+ *
+ * function App() {
+ *   return (
+ *     <DesignProvider>
+ *       <CookieBanner />
+ *     </DesignProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example Customização de cores
+ * ```tsx
+ * const customTokens = {
+ *   colors: {
+ *     primary: '#ff0000',
+ *     secondary: '#00ff00'
+ *   }
+ * };
+ *
+ * function App() {
+ *   return (
+ *     <DesignProvider tokens={customTokens}>
+ *       <PreferencesModal />
+ *     </DesignProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @component
+ * @category Context
+ * @since 0.1.0
+ */
+declare function DesignProvider({ tokens, children, }: Readonly<{
+    tokens?: DesignTokens;
+    children: React$1.ReactNode;
+}>): react_jsx_runtime.JSX.Element;
+/**
+ * Hook para acessar os tokens de design do contexto atual.
+ *
+ * @remarks
+ * Retorna os tokens de design fornecidos pelo DesignProvider mais próximo na árvore de componentes.
+ * Se nenhum provider for encontrado ou tokens não forem definidos, retorna undefined.
+ * Os componentes usam este hook para aplicar estilos consistentes via MUI `sx` ou outros mecanismos.
+ *
+ * @returns Os tokens de design atuais ou undefined se não houver provider ou tokens
+ *
+ * @throws {Error} Se usado fora de um DesignProvider (embora não lance erro, retorna undefined)
+ *
+ * @example Acesso a tokens em componente
+ * ```tsx
+ * import { useDesignTokens } from './context/DesignContext';
+ *
+ * function CustomButton() {
+ *   const tokens = useDesignTokens();
+ *   const primaryColor = tokens?.colors?.primary || '#default';
+ *
+ *   return (
+ *     <button style={{ backgroundColor: primaryColor }}>
+ *       Botão Customizado
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @example Uso defensivo com fallbacks
+ * ```tsx
+ * function ThemedComponent() {
+ *   const tokens = useDesignTokens();
+ *
+ *   return (
+ *     <div style={{
+ *       color: tokens?.colors?.text || '#333',
+ *       fontSize: tokens?.typography?.fontSize || '16px'
+ *     }}>
+ *       Conteúdo temático
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @hook
+ * @category Hooks
+ * @since 0.1.0
+ */
+declare function useDesignTokens(): DesignTokens | undefined;
+
+/**
+ * ConsentGate - renderiza children apenas se houver consentimento para a categoria.
+ *
+ * @remarks
+ * Não usa React.memo pois o estado de preferências muda dinamicamente
+ * e o componente precisa re-renderizar quando as preferências mudam.
+ * A lógica é leve o suficiente para não justificar memoização.
+ */
+declare function ConsentGate(props: Readonly<{
+    category: string;
+    children: React$1.ReactNode;
+}>): react_jsx_runtime.JSX.Element | null;
+
+/** @module src/utils/scriptLoader */
+/**
+ * @category Utils
+ * @since 0.1.0
+ * Utilitários para carregamento dinâmico e seguro de scripts externos no DOM.
+ *
+ * Fornece funções para carregar scripts de terceiros de forma condicional ao consentimento LGPD,
+ * garantindo compatibilidade SSR e verificações de permissões por categoria.
+ */
+/**
+ * @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 {string | null} [category=null] A categoria de consentimento exigida para o script. Suporta tanto categorias predefinidas quanto customizadas. 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?: string | null, attrs?: Record<string, string>): Promise<void>;
+
+/**
+ * Utilitários para descoberta e categorização de cookies em tempo de execução (experimental).
+ *
+ * Fornece funções para detectar cookies presentes no navegador, identificar o cookie de consentimento
+ * e atribuir cookies descobertos a categorias LGPD usando heurísticas baseadas em padrões conhecidos.
+ *
+ * @category Utils
+ * @since 0.4.1
+ * @remarks Funcionalidades experimentais para auxiliar no mapeamento de cookies em conformidade com LGPD.
+ *          Recomenda-se uso em desenvolvimento para inspeção manual e merge com catálogo existente.
+ */
+
+/**
+ * Descobre cookies em tempo de execução no navegador (experimental).
+ *
+ * - Lê `document.cookie` com segurança (SSR-safe)
+ * - Retorna lista de cookies detectados (apenas nomes)
+ * - Salva em `globalThis.__LGPD_DISCOVERED_COOKIES__` para inspeção/manual merge
+ *
+ * @category Utils
+ * @since 0.4.1
+ */
+declare function discoverRuntimeCookies(): CookieDescriptor[];
+/**
+ * Tenta detectar o nome do cookie de consentimento pela estrutura JSON armazenada.
+ * Retorna o nome se for encontrado, caso contrário `null`.
+ * @category Utils
+ * @since 0.4.1
+ */
+declare function detectConsentCookieName(): string | null;
+/**
+ * Heurística simples para atribuir cookies descobertos a categorias LGPD (experimental).
+ *
+ * - Usa padrões conhecidos por categoria
+ * - Ignora `cookieConsent` (já tratado como necessary)
+ * - Pode opcionalmente registrar overrides de catálogo por categoria
+ *
+ * @param discovered Lista de cookies descobertos (opcional: usa global se ausente)
+ * @param registerOverrides Se `true`, registra em `setCookieCatalogOverrides`
+ * @returns Mapa categoria -> descritores atribuídos
+ * @category Utils
+ * @since 0.4.1
+ */
+declare function categorizeDiscoveredCookies(discovered?: CookieDescriptor[], registerOverrides?: boolean): Record<Category, CookieDescriptor[]>;
+
+/**
+ * @fileoverview
+ * Integrações nativas de scripts (GA, GTM, Facebook Pixel, Hotjar, Mixpanel, Clarity, Intercom, Zendesk, UserWay)
+ * com categorias LGPD padrão, cookies típicos e pontos de extensão para URLs.
+ *
+ * Princípios:
+ * - Cada integração define uma categoria padrão (mais aderente ao uso no mercado)
+ * - Cada cookie típico aparece em uma única categoria por padrão
+ * - URLs possuem valores default atualizados e podem ser sobrescritos via `scriptUrl`
+ * - SSR-safe: toda execução que toca `window` é protegida
+ */
+/**
+ * Integração de script de terceiros condicionada a consentimento.
+ *
+ * @category Utils
+ * @since 0.2.0
+ *
+ * @remarks
+ * **Breaking Change em v0.4.1**: O campo `category` mudou de `Category` para `string`
+ * para suportar categorias customizadas. Código existente usando strings literais
+ * continua funcionando sem alterações.
+ *
+ * @example
+ * ```typescript
+ * const integration: ScriptIntegration = {
+ *   id: 'my-script',
+ *   category: 'analytics',
+ *   src: 'https://example.com/script.js',
+ *   cookies: ['_example'],
+ *   init: () => console.log('Script initialized')
+ * }
+ * ```
+ */
+interface ScriptIntegration {
+    /** Identificador único da integração */
+    id: string;
+    /**
+     * Categoria LGPD à qual o script pertence.
+     * Suporta tanto categorias predefinidas quanto customizadas.
+     */
+    category: string;
+    /** Nome legível da integração (opcional) */
+    name?: string;
+    /** URL do script a ser carregado */
+    src: string;
+    /** Se o script deve ser carregado de forma assíncrona */
+    async?: boolean;
+    /** Se o script deve ser deferido */
+    defer?: boolean;
+    /** Configuração específica da integração */
+    config?: Record<string, unknown>;
+    /** Função de inicialização executada após carregamento do script */
+    init?: () => void;
+    /** Atributos HTML adicionais para a tag script */
+    attrs?: Record<string, string>;
+    /** Lista de cookies que o script pode definir */
+    cookies?: string[];
+    /** Informações detalhadas dos cookies (nome, finalidade, duração, fornecedor) */
+    cookiesInfo?: Array<{
+        name: string;
+        purpose: string;
+        duration: string;
+        provider: string;
+    }>;
+}
+/**
+ * Configuração para integração do Google Analytics (GA4).
+ *
+ * @category Utils
+ * @since 0.2.0
+ *
+ * @example
+ * ```typescript
+ * const config: GoogleAnalyticsConfig = {
+ *   measurementId: 'G-XXXXXXXXXX',
+ *   config: { anonymize_ip: true }
+ * }
+ * ```
+ */
+interface GoogleAnalyticsConfig {
+    /** ID de medição do GA4 (formato: G-XXXXXXXXXX) */
+    measurementId: string;
+    /** Configurações adicionais para o gtag */
+    config?: Record<string, unknown>;
+    /** URL do script GA4. Se omitido usa o padrão oficial. */
+    scriptUrl?: string;
+}
+/**
+ * Configuração para integração do Google Tag Manager (GTM).
+ *
+ * @category Utils
+ * @since 0.2.0
+ *
+ * @example
+ * ```typescript
+ * const config: GoogleTagManagerConfig = {
+ *   containerId: 'GTM-XXXXXXX',
+ *   dataLayerName: 'customDataLayer'
+ * }
+ * ```
+ */
+interface GoogleTagManagerConfig {
+    /** ID do container GTM (formato: GTM-XXXXXXX) */
+    containerId: string;
+    /** Nome customizado para o dataLayer. Padrão: 'dataLayer' */
+    dataLayerName?: string;
+    /** URL do script GTM. Se omitido usa o padrão oficial. */
+    scriptUrl?: string;
+}
+/**
+ * Configuração para integração do UserWay (Acessibilidade).
+ *
+ * @category Utils
+ * @since 0.2.0
+ *
+ * @example
+ * ```typescript
+ * const config: UserWayConfig = {
+ *   accountId: 'XXXXXXXXXX'
+ * }
+ * ```
+ */
+interface UserWayConfig {
+    /** ID da conta UserWay */
+    accountId: string;
+    /** URL do script UserWay. Se omitido usa o padrão oficial. */
+    scriptUrl?: string;
+}
+/**
+ * Cria integração do Google Analytics (GA4).
+ * Configura o gtag e inicializa o tracking com o measurement ID fornecido.
+ *
+ * @category Utils
+ * @param config - Configuração do Google Analytics
+ * @returns Integração configurada para o GA4
+ * @since 0.2.0
+ *
+ * @example
+ * ```typescript
+ * const ga = createGoogleAnalyticsIntegration({
+ *   measurementId: 'G-XXXXXXXXXX',
+ *   config: { anonymize_ip: true }
+ * })
+ * ```
+ *
+ * @remarks
+ * - Define cookies: _ga, _ga_*, _gid
+ * - Categoria padrão: 'analytics'
+ * - SSR-safe: verifica disponibilidade do window
+ */
+declare function createGoogleAnalyticsIntegration(config: GoogleAnalyticsConfig): ScriptIntegration;
+/**
+ * Cria integração do Google Tag Manager (GTM).
+ * Configura o dataLayer e inicializa o container GTM.
+ *
+ * @category Utils
+ * @param config - Configuração do Google Tag Manager
+ * @returns Integração configurada para o GTM
+ * @since 0.2.0
+ *
+ * @example
+ * ```typescript
+ * const gtm = createGoogleTagManagerIntegration({
+ *   containerId: 'GTM-XXXXXXX',
+ *   dataLayerName: 'myDataLayer'
+ * })
+ * ```
+ *
+ * @remarks
+ * - Define cookies: _gcl_au
+ * - Categoria padrão: 'analytics'
+ * - SSR-safe: verifica disponibilidade do window
+ */
+declare function createGoogleTagManagerIntegration(config: GoogleTagManagerConfig): ScriptIntegration;
+/**
+ * Cria integração do UserWay (Acessibilidade).
+ * Configura o widget de acessibilidade UserWay.
+ *
+ * @category Utils
+ * @param config - Configuração do UserWay
+ * @returns Integração configurada para o UserWay
+ * @since 0.2.0
+ *
+ * @example
+ * ```typescript
+ * const userway = createUserWayIntegration({
+ *   accountId: 'XXXXXXXXXX'
+ * })
+ * ```
+ *
+ * @remarks
+ * - Define cookies: _userway_*
+ * - Categoria padrão: 'functional'
+ * - SSR-safe: verifica disponibilidade do window
+ */
+declare function createUserWayIntegration(config: UserWayConfig): ScriptIntegration;
+/**
+ * Funções fábricas para integrações comuns.
+ * Fornece acesso direto às funções de criação de integrações pré-configuradas.
+ *
+ * @category Utils
+ * @since 0.2.0
+ *
+ * @example
+ * ```typescript
+ * const ga = COMMON_INTEGRATIONS.googleAnalytics({ measurementId: 'G-XXXXXXXXXX' })
+ * ```
+ */
+declare const COMMON_INTEGRATIONS: {
+    googleAnalytics: typeof createGoogleAnalyticsIntegration;
+    googleTagManager: typeof createGoogleTagManagerIntegration;
+    userway: typeof createUserWayIntegration;
+};
+/**
+ * Configuração para integração do Facebook Pixel.
+ *
+ * @category Utils
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const config: FacebookPixelConfig = {
+ *   pixelId: '1234567890123456',
+ *   autoTrack: true,
+ *   advancedMatching: { email: 'user@example.com' }
+ * }
+ * ```
+ */
+interface FacebookPixelConfig {
+    /** ID do pixel do Facebook */
+    pixelId: string;
+    /** Se deve rastrear PageView automaticamente. Padrão: true */
+    autoTrack?: boolean;
+    /** Configuração de correspondência avançada */
+    advancedMatching?: Record<string, unknown>;
+    /** URL do script do Pixel. Se omitido usa o padrão oficial. */
+    scriptUrl?: string;
+}
+/**
+ * Configuração para integração do Hotjar.
+ *
+ * @category Utils
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const config: HotjarConfig = {
+ *   siteId: '1234567',
+ *   version: 6,
+ *   debug: false
+ * }
+ * ```
+ */
+interface HotjarConfig {
+    /** ID do site no Hotjar */
+    siteId: string;
+    /** Versão do script Hotjar. Padrão: 6 */
+    version?: number;
+    /** Ativar modo debug. Padrão: false */
+    debug?: boolean;
+    /** URL do script Hotjar. Se omitido usa o padrão oficial. */
+    scriptUrl?: string;
+}
+/**
+ * Configuração para integração do Mixpanel.
+ *
+ * @category Utils
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const config: MixpanelConfig = {
+ *   token: 'your-project-token',
+ *   config: { debug: true },
+ *   api_host: 'https://api.mixpanel.com'
+ * }
+ * ```
+ */
+interface MixpanelConfig {
+    /** Token do projeto Mixpanel */
+    token: string;
+    /** Configurações adicionais do Mixpanel */
+    config?: Record<string, unknown>;
+    /** Host customizado da API Mixpanel */
+    api_host?: string;
+    /** URL do script Mixpanel. Se omitido usa o padrão oficial. */
+    scriptUrl?: string;
+}
+/**
+ * Configuração para integração do Microsoft Clarity.
+ *
+ * @category Utils
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const config: ClarityConfig = {
+ *   projectId: 'abcdefghij',
+ *   upload: true
+ * }
+ * ```
+ */
+interface ClarityConfig {
+    /** ID do projeto no Microsoft Clarity */
+    projectId: string;
+    /** Configuração de upload de dados. Padrão: indefinido */
+    upload?: boolean;
+    /** URL do script Clarity. Se omitido usa o padrão oficial. */
+    scriptUrl?: string;
+}
+/**
+ * Configuração para integração do Intercom.
+ *
+ * @category Utils
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const config: IntercomConfig = {
+ *   app_id: 'your-app-id'
+ * }
+ * ```
+ */
+interface IntercomConfig {
+    /** ID da aplicação Intercom */
+    app_id: string;
+    /** URL do script Intercom. Se omitido usa o padrão oficial. */
+    scriptUrl?: string;
+}
+/**
+ * Configuração para integração do Zendesk Chat.
+ *
+ * @category Utils
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const config: ZendeskConfig = {
+ *   key: 'your-zendesk-key'
+ * }
+ * ```
+ */
+interface ZendeskConfig {
+    /** Chave de identificação do Zendesk */
+    key: string;
+    /** URL do script Zendesk. Se omitido usa o padrão oficial. */
+    scriptUrl?: string;
+}
+/**
+ * Cria integração do Facebook Pixel.
+ * Configura o fbq e inicializa o pixel com tracking automático opcional.
+ *
+ * @category Utils
+ * @param config - Configuração do Facebook Pixel
+ * @returns Integração configurada para o Facebook Pixel
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const pixel = createFacebookPixelIntegration({
+ *   pixelId: '1234567890123456',
+ *   autoTrack: true
+ * })
+ * ```
+ *
+ * @remarks
+ * - Define cookies: _fbp, fr
+ * - Categoria padrão: 'marketing'
+ * - SSR-safe: verifica disponibilidade do window
+ */
+declare function createFacebookPixelIntegration(config: FacebookPixelConfig): ScriptIntegration;
+/**
+ * Cria integração do Hotjar.
+ * Configura as configurações do Hotjar e inicializa o tracking de heatmaps e gravações.
+ *
+ * @category Utils
+ * @param config - Configuração do Hotjar
+ * @returns Integração configurada para o Hotjar
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const hotjar = createHotjarIntegration({
+ *   siteId: '1234567',
+ *   debug: true
+ * })
+ * ```
+ *
+ * @remarks
+ * - Define cookies: _hjSession_*, _hjSessionUser_*, _hjFirstSeen, _hjIncludedInSessionSample, _hjAbsoluteSessionInProgress
+ * - Categoria padrão: 'analytics'
+ * - SSR-safe: verifica disponibilidade do window
+ */
+declare function createHotjarIntegration(config: HotjarConfig): ScriptIntegration;
+/**
+ * Cria integração do Mixpanel.
+ * Configura e inicializa o Mixpanel para analytics de eventos.
+ *
+ * @category Utils
+ * @param config - Configuração do Mixpanel
+ * @returns Integração configurada para o Mixpanel
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const mixpanel = createMixpanelIntegration({
+ *   token: 'your-project-token',
+ *   config: { debug: true }
+ * })
+ * ```
+ *
+ * @remarks
+ * - Define cookies: mp_*
+ * - Categoria padrão: 'analytics'
+ * - SSR-safe: verifica disponibilidade do window
+ * - Inclui tratamento de erro na inicialização
+ */
+declare function createMixpanelIntegration(config: MixpanelConfig): ScriptIntegration;
+/**
+ * Cria integração do Microsoft Clarity.
+ * Configura o Microsoft Clarity para heatmaps e analytics de comportamento.
+ *
+ * @category Utils
+ * @param config - Configuração do Microsoft Clarity
+ * @returns Integração configurada para o Clarity
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const clarity = createClarityIntegration({
+ *   projectId: 'abcdefghij',
+ *   upload: false
+ * })
+ * ```
+ *
+ * @remarks
+ * - Define cookies: _clck, _clsk, CLID, ANONCHK, MR, MUID, SM
+ * - Categoria padrão: 'analytics'
+ * - SSR-safe: verifica disponibilidade do window
+ * - Configuração de upload opcional
+ */
+declare function createClarityIntegration(config: ClarityConfig): ScriptIntegration;
+/**
+ * Cria integração do Intercom.
+ * Configura o widget de chat e suporte do Intercom.
+ *
+ * @category Utils
+ * @param config - Configuração do Intercom
+ * @returns Integração configurada para o Intercom
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const intercom = createIntercomIntegration({
+ *   app_id: 'your-app-id'
+ * })
+ * ```
+ *
+ * @remarks
+ * - Define cookies: intercom-id-*, intercom-session-*
+ * - Categoria padrão: 'functional'
+ * - SSR-safe: verifica disponibilidade do window
+ * - Inclui tratamento de erro na inicialização
+ */
+declare function createIntercomIntegration(config: IntercomConfig): ScriptIntegration;
+/**
+ * Cria integração do Zendesk Chat.
+ * Configura o widget de chat e suporte do Zendesk.
+ *
+ * @category Utils
+ * @param config - Configuração do Zendesk Chat
+ * @returns Integração configurada para o Zendesk Chat
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const zendesk = createZendeskChatIntegration({
+ *   key: 'your-zendesk-key'
+ * })
+ * ```
+ *
+ * @remarks
+ * - Define cookies: __zlcmid, _zendesk_shared_session
+ * - Categoria padrão: 'functional'
+ * - SSR-safe: verifica disponibilidade do window
+ * - Inclui tratamento de erro na identificação
+ */
+declare function createZendeskChatIntegration(config: ZendeskConfig): ScriptIntegration;
+/**
+ * Configuração para conjunto de integrações de e-commerce.
+ * Define configurações opcionais para múltiplas integrações otimizadas para e-commerce.
+ *
+ * @category Utils
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const config: ECommerceConfig = {
+ *   googleAnalytics: { measurementId: 'G-XXXXXXXXXX' },
+ *   facebookPixel: { pixelId: '1234567890123456' }
+ * }
+ * ```
+ */
+interface ECommerceConfig {
+    /** Configuração do Google Analytics */
+    googleAnalytics?: GoogleAnalyticsConfig;
+    /** Configuração do Facebook Pixel */
+    facebookPixel?: FacebookPixelConfig;
+    /** Configuração do Hotjar */
+    hotjar?: HotjarConfig;
+    /** Configuração do UserWay */
+    userway?: UserWayConfig;
+}
+/**
+ * Configuração para conjunto de integrações de SaaS.
+ * Define configurações opcionais para múltiplas integrações otimizadas para SaaS.
+ *
+ * @category Utils
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const config: SaaSConfig = {
+ *   googleAnalytics: { measurementId: 'G-XXXXXXXXXX' },
+ *   mixpanel: { token: 'your-token' },
+ *   intercom: { app_id: 'your-app-id' }
+ * }
+ * ```
+ */
+interface SaaSConfig {
+    /** Configuração do Google Analytics */
+    googleAnalytics?: GoogleAnalyticsConfig;
+    /** Configuração do Mixpanel */
+    mixpanel?: MixpanelConfig;
+    /** Configuração do Intercom */
+    intercom?: IntercomConfig;
+    /** Configuração do Hotjar */
+    hotjar?: HotjarConfig;
+}
+/**
+ * Configuração para conjunto de integrações corporativas.
+ * Define configurações opcionais para múltiplas integrações otimizadas para ambientes corporativos.
+ *
+ * @category Utils
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const config: CorporateConfig = {
+ *   googleAnalytics: { measurementId: 'G-XXXXXXXXXX' },
+ *   clarity: { projectId: 'abcdefghij' },
+ *   userway: { accountId: 'XXXXXXXXXX' }
+ * }
+ * ```
+ */
+interface CorporateConfig {
+    /** Configuração do Google Analytics */
+    googleAnalytics?: GoogleAnalyticsConfig;
+    /** Configuração do Microsoft Clarity */
+    clarity?: ClarityConfig;
+    /** Configuração do Zendesk Chat */
+    zendesk?: ZendeskConfig;
+    /** Configuração do UserWay */
+    userway?: UserWayConfig;
+}
+/**
+ * Cria conjunto de integrações otimizado para e-commerce.
+ * Combina analytics de conversão, remarketing e acessibilidade.
+ *
+ * @category Utils
+ * @param cfg - Configuração das integrações de e-commerce
+ * @returns Array de integrações configuradas
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const integrations = createECommerceIntegrations({
+ *   googleAnalytics: { measurementId: 'G-XXXXXXXXXX' },
+ *   facebookPixel: { pixelId: '1234567890123456' }
+ * })
+ * ```
+ *
+ * @remarks
+ * Combina categorias: analytics, marketing, functional
+ */
+declare function createECommerceIntegrations(cfg: ECommerceConfig): ScriptIntegration[];
+/**
+ * Cria conjunto de integrações otimizado para SaaS.
+ * Combina analytics de produto, suporte ao cliente e comportamento do usuário.
+ *
+ * @category Utils
+ * @param cfg - Configuração das integrações de SaaS
+ * @returns Array de integrações configuradas
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const integrations = createSaaSIntegrations({
+ *   googleAnalytics: { measurementId: 'G-XXXXXXXXXX' },
+ *   mixpanel: { token: 'your-project-token' },
+ *   intercom: { app_id: 'your-app-id' }
+ * })
+ * ```
+ *
+ * @remarks
+ * Combina categorias: analytics, functional
+ */
+declare function createSaaSIntegrations(cfg: SaaSConfig): ScriptIntegration[];
+/**
+ * Cria conjunto de integrações otimizado para ambientes corporativos.
+ * Combina analytics empresariais, compliance e suporte corporativo.
+ *
+ * @category Utils
+ * @param cfg - Configuração das integrações corporativas
+ * @returns Array de integrações configuradas
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const integrations = createCorporateIntegrations({
+ *   googleAnalytics: { measurementId: 'G-XXXXXXXXXX' },
+ *   clarity: { projectId: 'abcdefghij' },
+ *   userway: { accountId: 'XXXXXXXXXX' }
+ * })
+ * ```
+ *
+ * @remarks
+ * Combina categorias: analytics, functional
+ */
+declare function createCorporateIntegrations(cfg: CorporateConfig): ScriptIntegration[];
+/**
+ * Templates pré-configurados de integrações por tipo de negócio.
+ * Define integrações essenciais e opcionais para cada contexto.
+ *
+ * @category Utils
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * const template = INTEGRATION_TEMPLATES.ecommerce
+ * console.log(template.essential) // ['google-analytics', 'facebook-pixel']
+ * console.log(template.categories) // ['analytics', 'marketing', 'functional']
+ * ```
+ *
+ * @remarks
+ * Cada template define:
+ * - essential: integrações obrigatórias/recomendadas
+ * - optional: integrações complementares
+ * - categories: categorias LGPD utilizadas
+ */
+declare const INTEGRATION_TEMPLATES: {
+    ecommerce: {
+        essential: string[];
+        optional: string[];
+        categories: string[];
+    };
+    saas: {
+        essential: string[];
+        optional: string[];
+        categories: string[];
+    };
+    corporate: {
+        essential: string[];
+        optional: string[];
+        categories: string[];
+    };
+};
+/**
+ * Sugere categorias LGPD apropriadas para um script baseado no nome/tipo.
+ * Utiliza heurísticas para classificar scripts desconhecidos.
+ *
+ * @category Utils
+ * @param name - Nome ou identificador do script
+ * @returns Array de categorias sugeridas
+ * @since 0.4.1
+ *
+ * @example
+ * ```typescript
+ * suggestCategoryForScript('facebook-pixel') // ['marketing']
+ * suggestCategoryForScript('hotjar') // ['analytics']
+ * suggestCategoryForScript('intercom-chat') // ['functional']
+ * suggestCategoryForScript('unknown-script') // ['analytics']
+ * ```
+ *
+ * @remarks
+ * Heurísticas aplicadas:
+ * - Scripts de ads/marketing → 'marketing'
+ * - Scripts de analytics/tracking → 'analytics'
+ * - Scripts de chat/suporte → 'functional'
+ * - Padrão para desconhecidos → 'analytics'
+ */
+declare function suggestCategoryForScript(name: string): string[];
+
+/**
+ * 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
+ * @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
+ * const loadScript = useConsentScriptLoader();
+ *
+ * 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>;
+
+/**
+ * @file autoConfigureCategories.ts
+ * @description Sistema inteligente de auto-habilitação de categorias baseado nas integrações utilizadas
+ * @since 0.4.1
+ */
+
+/**
+ * @interface CategoryAutoConfigResult
+ * Resultado da análise e auto-configuração de categorias
+ */
+interface CategoryAutoConfigResult {
+    /** Configuração original fornecida pelo desenvolvedor */
+    originalConfig: ProjectCategoriesConfig;
+    /** Configuração ajustada automaticamente pela biblioteca */
+    adjustedConfig: ProjectCategoriesConfig;
+    /** Categorias que foram automaticamente habilitadas */
+    autoEnabledCategories: string[];
+    /** Categorias requeridas pelas integrações mas não habilitadas */
+    missingCategories: string[];
+    /** Se algum ajuste foi necessário */
+    wasAdjusted: boolean;
+    /** Integrações que requerem cada categoria */
+    categoryIntegrations: Record<string, string[]>;
+}
+/**
+ * @function
+ * @category Utils
+ * @since 0.4.1
+ * Analisa as integrações fornecidas e determina quais categorias são necessárias.
+ *
+ * @param integrations Array de integrações de script
+ * @returns Record mapeando categoria para nomes das integrações que a utilizam
+ */
+declare function analyzeIntegrationCategories(integrations: ScriptIntegration[]): Record<string, string[]>;
+/**
+ * @function
+ * @category Utils
+ * @since 0.4.1
+ * Configura automaticamente as categorias necessárias baseado nas integrações utilizadas.
+ *
+ * Esta função implementa o comportamento inteligente da biblioteca:
+ * 1. Detecta categorias requeridas pelas integrações
+ * 2. Auto-habilita categorias em falta (modo padrão)
+ * 3. Ou apenas avisa sobre categorias em falta (modo warning-only)
+ * 4. Loga no console em modo DEV
+ *
+ * @param originalConfig Configuração original do ConsentProvider
+ * @param integrations Array de integrações que serão utilizadas
+ * @param options Opções de comportamento
+ * @returns Resultado da análise e configuração automática
+ */
+declare function autoConfigureCategories(originalConfig: ProjectCategoriesConfig | undefined, integrations: ScriptIntegration[], options?: {
+    /** Se true, apenas avisa mas não modifica a config (padrão: false - auto-habilita) */
+    warningOnly?: boolean;
+    /** Se true, desabilita logs no console (padrão: false) */
+    silent?: boolean;
+}): CategoryAutoConfigResult;
+/**
+ * @function
+ * @category Utils
+ * @since 0.4.1
+ * Valida se todas as integrações têm suas categorias habilitadas.
+ * Útil para validação em tempo de execução.
+ *
+ * @param integrations Array de integrações
+ * @param enabledCategories Array de categorias habilitadas
+ * @returns true se todas as categorias necessárias estão habilitadas
+ */
+declare function validateIntegrationCategories(integrations: ScriptIntegration[], enabledCategories: string[]): boolean;
+/**
+ * @function
+ * @category Utils
+ * @since 0.4.1
+ * Extrai categorias únicas de um array de integrações
+ *
+ * @param integrations Array de integrações
+ * @returns Array de categorias únicas
+ */
+declare function extractCategoriesFromIntegrations(integrations: ScriptIntegration[]): string[];
+/**
+ * @function
+ * @category Utils
+ * @since 0.4.1
+ * Valida se integrações estão sendo incorretamente classificadas como "necessary".
+ *
+ * Esta função protege contra violações de GDPR/LGPD identificando scripts que
+ * NUNCA devem ser considerados estritamente necessários.
+ *
+ * @param integrations Array de integrações para validar
+ * @param enabledCategories Categorias habilitadas na configuração
+ * @returns Lista de avisos sobre classificações incorretas
+ *
+ * @example
+ * ```typescript
+ * const warnings = validateNecessaryClassification([
+ *   createGoogleAnalyticsIntegration({...}), // ❌ NUNCA é necessary
+ *   createCustomIntegration({...})           // ✅ Pode ser necessary se apropriado
+ * ], ['necessary', 'analytics'])
+ *
+ * if (warnings.length > 0) {
+ *   console.warn('Scripts incorretamente classificados como necessary:', warnings)
+ * }
+ * ```
+ */
+declare function validateNecessaryClassification(integrations: ScriptIntegration[], enabledCategories: Category[]): string[];
+
+/**
+ * @fileoverview
+ * Sistema de textos expandido com suporte avançado a internacionalização,
+ * contextos específicos e variações de tom.
+ *
+ * @author Luciano Édipo
+ * @since 0.4.1
+ */
+
+/**
+ * Tipo auxiliar para variações de texto.
+ *
+ * Define um subconjunto opcional dos textos principais do banner e modal,
+ * permitindo variações de t    es: {
+      bannerMessage: 'Utilizamos cookies para mejorar su experiencia y mostrar contenido personalizado.', (formal, casual, etc.) sem sobrescrever todos os textos.
+ *
+ * @category Types
+ * @since 0.4.1
+ */
+type TextVariant = Partial<Pick<ConsentTexts, 'bannerMessage' | 'acceptAll' | 'declineAll' | 'modalTitle'>>;
+/**
+ * Tipo auxiliar para textos de idioma.
+ *
+ * Define um subconjunto dos textos principais, excluindo propriedades específicas de internacionalização
+ * e contextos, para uso em configurações multilíngues.
+ *
+ * @category Types
+ * @since 0.4.1
+ */
+type LanguageTexts = Partial<Omit<ConsentTexts, 'i18n' | 'variants' | 'contexts'>>;
+/**
+ * Sistema de textos avançado com suporte a internacionalização e contextos específicos.
+ *
+ * Interface expandida que permite personalização granular de todas as mensagens da biblioteca.
+ * Suporta múltiplos idiomas, contextos específicos (e-commerce, SaaS, governo), variações
+ * de tom, e compliance completo com LGPD/ANPD.
+ *
+ * @category Types
+ * @since 0.4.1
+ * @version 0.4.1 - Nova interface com suporte avançado a i18n e contextos
+ *
+ * @example Configuração multilíngue
+ * ```typescript
+ * const multiLangTexts: AdvancedConsentTexts = {
+ *   // Herda de ConsentTexts básico
+ *   bannerMessage: 'Utilizamos cookies para melhorar sua experiência.',
+ *   acceptAll: 'Aceitar todos',
+ *   declineAll: 'Recusar',
+ *   preferences: 'Preferências',
+ *   modalTitle: 'Preferências de Cookies',
+ *   modalIntro: 'Personalize suas preferências de cookies.',
+ *   save: 'Salvar',
+ *   necessaryAlwaysOn: 'Cookies necessários (sempre ativos)',
+ *
+ *   // Textos expandidos
+ *   variants: {
+ *     formal: {
+ *       bannerMessage: 'Este sítio utiliza cookies para otimizar a experiência de navegação.',
+ *       acceptAll: 'Concordar com todos os cookies'
+ *     },
+ *     casual: {
+ *       bannerMessage: '🍪 Olá! Usamos cookies para tornar tudo mais gostoso aqui.',
+ *       acceptAll: 'Aceitar tudo'
+ *     }
+ *   },
+ *
+ *   // Internacionalização
+ *   i18n: {
+ *     en: {
+ *       bannerMessage: 'We use cookies to enhance your experience.',
+ *       acceptAll: 'Accept All',
+ *       declineAll: 'Decline'
+ *     },
+ *     es: {
+ *       bannerMessage: 'Utilizamos cookies para mejorar su experiencia.',
+ *       acceptAll: 'Aceptar Todo',
+ *       declineAll: 'Rechazar'
+ *     }
+ *   }
+ * }
+ * ```
+ */
+interface AdvancedConsentTexts extends ConsentTexts {
+    /** Texto para confirmar ação */
+    confirm?: string;
+    /** Texto para cancelar ação */
+    cancel?: string;
+    /** Texto de carregamento */
+    loading?: string;
+    /** Textos específicos para cada categoria de cookie */
+    categories?: {
+        necessary?: {
+            name?: string;
+            description?: string;
+            examples?: string;
+        };
+        analytics?: {
+            name?: string;
+            description?: string;
+            examples?: string;
+        };
+        marketing?: {
+            name?: string;
+            description?: string;
+            examples?: string;
+        };
+        functional?: {
+            name?: string;
+            description?: string;
+            examples?: string;
+        };
+        performance?: {
+            name?: string;
+            description?: string;
+            examples?: string;
+        };
+    };
+    /** Mensagens de feedback ao usuário */
+    feedback?: {
+        /** Preferências salvas com sucesso */
+        saveSuccess?: string;
+        /** Erro ao salvar preferências */
+        saveError?: string;
+        /** Consentimento atualizado */
+        consentUpdated?: string;
+        /** Cookies rejeitados */
+        cookiesRejected?: string;
+        /** Configurações resetadas */
+        settingsReset?: string;
+    };
+    /** Labels ARIA e textos para leitores de tela */
+    accessibility?: {
+        /** Label do banner para leitores de tela */
+        bannerLabel?: string;
+        /** Label do modal para leitores de tela */
+        modalLabel?: string;
+        /** Instrução de navegação por teclado */
+        keyboardNavigation?: string;
+        /** Estado do toggle de categoria */
+        toggleState?: {
+            enabled?: string;
+            disabled?: string;
+        };
+        /** Região live para anúncios dinâmicos */
+        liveRegion?: string;
+    };
+    /** Textos otimizados para diferentes contextos */
+    contexts?: {
+        /** Contexto e-commerce */
+        ecommerce?: {
+            cartAbandonment?: string;
+            personalizedOffers?: string;
+            paymentSecurity?: string;
+            productRecommendations?: string;
+        };
+        /** Contexto SaaS */
+        saas?: {
+            userAnalytics?: string;
+            performanceMonitoring?: string;
+            featureUsage?: string;
+            customerSupport?: string;
+        };
+        /** Contexto governamental */
+        government?: {
+            citizenServices?: string;
+            dataProtection?: string;
+            transparency?: string;
+            accessibility?: string;
+        };
+        /** Contexto educacional */
+        education?: {
+            studentProgress?: string;
+            learningAnalytics?: string;
+            accessibility?: string;
+            parentalConsent?: string;
+        };
+    };
+    /** Diferentes variações de tom para a mesma mensagem */
+    variants?: {
+        /** Tom formal/profissional */
+        formal?: TextVariant;
+        /** Tom casual/amigável */
+        casual?: TextVariant;
+        /** Tom conciso/direto */
+        concise?: TextVariant;
+        /** Tom detalhado/explicativo */
+        detailed?: TextVariant;
+    };
+    /** Suporte a múltiplos idiomas */
+    i18n?: {
+        /** Textos em inglês */
+        en?: LanguageTexts;
+        /** Textos em espanhol */
+        es?: LanguageTexts;
+        /** Textos em francês */
+        fr?: LanguageTexts;
+        /** Textos em alemão */
+        de?: LanguageTexts;
+        /** Textos em italiano */
+        it?: LanguageTexts;
+    };
+    /** Informações técnicas sobre cookies */
+    technical?: {
+        /** Explicação sobre cookies de sessão */
+        sessionCookies?: string;
+        /** Explicação sobre cookies persistentes */
+        persistentCookies?: string;
+        /** Explicação sobre cookies de terceiros */
+        thirdPartyCookies?: string;
+        /** Como desabilitar cookies no navegador */
+        browserSettings?: string;
+        /** Impacto de desabilitar cookies */
+        disablingImpact?: string;
+    };
+    /** Cabeçalhos para tabela de detalhes de cookies */
+    cookieDetails?: {
+        tableHeaders?: {
+            name?: string;
+            purpose?: string;
+            duration?: string;
+            provider?: string;
+            type?: string;
+        };
+        /** Texto quando não há cookies para mostrar */
+        noCookies?: string;
+        /** Botão para expandir/colapsar detalhes */
+        toggleDetails?: {
+            expand?: string;
+            collapse?: string;
+        };
+    };
+}
+/**
+ * Textos padrão expandidos para diferentes contextos e idiomas.
+ *
+ * @category Utils
+ * @since 0.4.1
+ */
+declare const EXPANDED_DEFAULT_TEXTS: Partial<AdvancedConsentTexts>;
+/**
+ * Utilitário para resolver textos baseado em idioma, contexto e variação.
+ *
+ * @category Utils
+ * @since 0.4.1
+ *
+ * @param texts - Textos avançados configurados
+ * @param options - Opções de resolução
+ * @returns Textos resolvidos para o contexto
+ */
+declare function resolveTexts(texts: AdvancedConsentTexts, options?: {
+    language?: 'pt' | 'en' | 'es' | 'fr' | 'de' | 'it';
+    context?: 'ecommerce' | 'saas' | 'government' | 'education';
+    variant?: 'formal' | 'casual' | 'concise' | 'detailed';
+}): ConsentTexts;
+/**
+ * Templates pré-configurados para diferentes contextos.
+ *
+ * @category Utils
+ * @since 0.4.1
+ */
+declare const TEXT_TEMPLATES: {
+    readonly ecommerce: AdvancedConsentTexts;
+    readonly saas: AdvancedConsentTexts;
+    readonly government: AdvancedConsentTexts;
+};
+
+/**
+ * @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
+}
+/**
+ * Classe responsável pelo sistema de logging da biblioteca react-lgpd-consent.
+ * Fornece métodos para registrar mensagens em diferentes níveis de severidade,
+ * com suporte a grupos, tabelas e logs específicos para eventos da biblioteca.
+ *
+ * @category Utils
+ * @since 0.3.1
+ *
+ * @remarks
+ * - Logs são habilitados por padrão em desenvolvimento e desabilitados em produção.
+ * - Usa prefixo '[react-lgpd-consent]' para identificação.
+ * - Métodos específicos como `componentRender` e `apiUsage` são utilizados para análises de uso.
+ * - Em produção, apenas logs de erro (ERROR) são exibidos por padrão.
+ */
+declare class ConsentLogger {
+    private static readonly IS_DEVELOPMENT;
+    private static readonly IS_PRODUCTION;
+    private static readonly LOG_PREFIX;
+    private enabled;
+    private level;
+    /**
+     * Habilita ou desabilita o sistema de logging.
+     * @param {boolean} enabled Se `true`, os logs serão exibidos; caso contrário, serão suprimidos.
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Define o nível mínimo de severidade para os logs.
+     * Mensagens com severidade menor que o nível definido não serão exibidas.
+     * @param {LogLevel} level O nível mínimo de severidade (ex: `LogLevel.DEBUG` para ver todos os logs).
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Registra uma mensagem de erro.
+     * @param {...unknown[]} args Argumentos a serem logados.
+     */
+    error(...args: unknown[]): void;
+    /**
+     * Registra uma mensagem de aviso.
+     * Suprimido em produção por padrão (apenas se logging estiver explicitamente habilitado).
+     * @param {...unknown[]} args Argumentos a serem logados.
+     */
+    warn(...args: unknown[]): void;
+    /**
+     * Registra uma mensagem informativa.
+     * Suprimido em produção por padrão.
+     * @param {...unknown[]} args Argumentos a serem logados.
+     */
+    info(...args: unknown[]): void;
+    /**
+     * Registra uma mensagem de depuração.
+     * Sempre suprimido em produção.
+     * @param {...unknown[]} args Argumentos a serem logados.
+     */
+    debug(...args: unknown[]): void;
+    /**
+     * Inicia um grupo de logs no console.
+     * Suprimido em produção.
+     * @param {...unknown[]} args Argumentos para o título do grupo.
+     */
+    group(...args: unknown[]): void;
+    /**
+     * Finaliza o grupo de logs mais recente no console.
+     * Suprimido em produção.
+     */
+    groupEnd(): void;
+    /**
+     * Exibe dados tabulares no console.
+     * Suprimido em produção.
+     * @param {unknown} tabularData Dados a serem exibidos na tabela.
+     * @param {string[]} [properties] Propriedades opcionais para exibir.
+     */
+    table(tabularData: unknown, properties?: string[]): void;
+    /**
+     * Registra informações sobre a compatibilidade do tema Material-UI.
+     * @param {unknown} themeInfo Objeto potencialmente parcial do tema (inspeção segura).
+     */
+    themeCompatibility(themeInfo: unknown): void;
+    /**
+     * Registra mudanças no estado de consentimento.
+     * @param {string} action Ação que causou a mudança de estado.
+     * @param {{ consented?: boolean; isModalOpen?: boolean; preferences?: Record<string, unknown> }} state Estado atual.
+     */
+    consentState(action: string, state: {
+        consented?: boolean;
+        isModalOpen?: boolean;
+        preferences?: Record<string, unknown>;
+    }): void;
+    /**
+     * Registra operações de cookie (leitura, escrita, remoção).
+     * @param {'read' | 'write' | 'delete'} operation Tipo de operação.
+     * @param {string} cookieName Nome do cookie.
+     * @param {unknown} [data] Dados associados, se aplicável.
+     */
+    cookieOperation(operation: 'read' | 'write' | 'delete', cookieName: string, data?: unknown): void;
+    /**
+     * Registra a renderização de um componente.
+     * @param {string} componentName Nome do componente.
+     * @param {Record<string, unknown>} [props] Propriedades do componente.
+     */
+    componentRender(componentName: string, props?: Record<string, unknown>): void;
+    /**
+     * Registra o status de carregamento de scripts de integração.
+     * @param {string} scriptName O nome do script.
+     * @param {'load' | 'remove'} action A ação realizada (carregar ou remover).
+     * @param {boolean} success Se a operação foi bem-sucedida.
+     */
+    scriptIntegration(scriptName: string, action: 'load' | 'remove', success: boolean): void;
+    /**
+     * Registra chamadas à API interna da biblioteca.
+     * @param {string} method Nome do método da API chamado.
+     * @param {unknown} [params] Parâmetros passados para o método.
+     */
+    apiUsage(method: string, params?: unknown): void;
+}
+declare const logger: ConsentLogger;
+/**
+ * @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;
+
+interface CookieCatalogOverrides {
+    byCategory?: Record<string, CookieDescriptor[]>;
+    byIntegration?: Record<string, CookieDescriptor[]>;
+}
+interface CookieCategoryOverrides {
+    [cookieNameOrPattern: string]: Category;
+}
+declare function setCookieCatalogOverrides(overrides: CookieCatalogOverrides): void;
+declare function setCookieCategoryOverrides(map: CookieCategoryOverrides): void;
+declare function getCookiesInfoForCategory(categoryId: Category, usedIntegrations: string[]): CookieDescriptor[];
+
+/** @module src/utils/categoryUtils */
+/**
+ * @category Utils
+ * @since 0.2.0
+ * Utilitários para gerenciamento de categorias de consentimento LGPD.
+ *
+ * Fornece funções para criar, validar e recuperar definições de categorias de cookies,
+ * garantindo conformidade com a LGPD e suporte a categorias customizadas.
+ */
+
+/**
+ * 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 (tanto categorias padrão
+ * em `enabledCategories` quanto `customCategories`), alinhando-se ao princípio de minimização de dados da LGPD.
+ *
+ * Since v0.4.0: inclui categorias de `config.customCategories` na inicialização.
+ * @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 }
+ *
+ * // Inclui categorias customizadas
+ * const initialWithCustom = createProjectPreferences({
+ *   enabledCategories: ['analytics'],
+ *   customCategories: [
+ *     { id: 'abTesting', name: 'AB Testing', description: 'Experimentos de interface' },
+ *   ],
+ * })
+ * // Result: { necessary: true, analytics: false, abTesting: 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.
+ *
+ * Since v0.4.0: reconhece `config.customCategories` como válidas ao validar.
+ * @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, incluindo quaisquer `customCategories`
+ * definidas no `ConsentProvider`.
+ *
+ * Since v0.4.0: inclui categorias definidas em `config.customCategories`.
+ * @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[];
+
+/**
+ * @fileoverview
+ * Utilitários para disparar eventos de consentimento no dataLayer (Google Tag Manager).
+ *
+ * Este módulo fornece funções para enviar eventos padronizados de consentimento ao dataLayer,
+ * facilitando integração com Google Tag Manager e auditoria LGPD.
+ *
+ * @author Luciano Édipo
+ * @since 0.4.5
+ * @category Utils
+ */
+
+/**
+ * Declaração do tipo dataLayer para TypeScript.
+ * @internal
+ */
+declare global {
+    interface Window {
+        dataLayer?: Array<ConsentEvent | Record<string, unknown>>;
+    }
+}
+/**
+ * Dispara o evento `consent_initialized` no dataLayer.
+ *
+ * @param categories - Estado inicial das categorias de consentimento
+ *
+ * @remarks
+ * Este evento é disparado automaticamente quando o ConsentProvider é montado.
+ * Útil para rastreamento de primeira visualização e auditoria LGPD.
+ *
+ * @example
+ * ```typescript
+ * pushConsentInitializedEvent({
+ *   necessary: true,
+ *   analytics: false,
+ *   marketing: false
+ * });
+ *
+ * // Resultado no dataLayer:
+ * // {
+ * //   event: 'consent_initialized',
+ * //   consent_version: '0.4.5',
+ * //   timestamp: '2025-10-25T13:52:33.729Z',
+ * //   categories: { necessary: true, analytics: false, marketing: false }
+ * // }
+ * ```
+ *
+ * @category Utils
+ * @since 0.4.5
+ * @public
+ */
+declare function pushConsentInitializedEvent(categories: ConsentPreferences): void;
+/**
+ * Dispara o evento `consent_updated` no dataLayer.
+ *
+ * @param categories - Estado atualizado das categorias de consentimento
+ * @param origin - Origem da ação (banner, modal, reset, programmatic)
+ * @param previousCategories - Estado anterior das categorias (opcional, para calcular mudanças)
+ *
+ * @remarks
+ * Este evento é disparado sempre que o usuário atualiza suas preferências.
+ * Inclui a origem da ação e lista de categorias modificadas.
+ *
+ * @example
+ * ```typescript
+ * // Usuário aceitou analytics no modal
+ * pushConsentUpdatedEvent(
+ *   { necessary: true, analytics: true, marketing: false },
+ *   'modal',
+ *   { necessary: true, analytics: false, marketing: false }
+ * );
+ *
+ * // Resultado no dataLayer:
+ * // {
+ * //   event: 'consent_updated',
+ * //   consent_version: '0.4.5',
+ * //   timestamp: '2025-10-25T13:52:33.729Z',
+ * //   origin: 'modal',
+ * //   categories: { necessary: true, analytics: true, marketing: false },
+ * //   changed_categories: ['analytics']
+ * // }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Reset de consentimento
+ * pushConsentUpdatedEvent(
+ *   { necessary: true, analytics: false, marketing: false },
+ *   'reset'
+ * );
+ * ```
+ *
+ * @category Utils
+ * @since 0.4.5
+ * @public
+ */
+declare function pushConsentUpdatedEvent(categories: ConsentPreferences, origin: ConsentEventOrigin, previousCategories?: ConsentPreferences): void;
+/**
+ * Hook helper para facilitar uso em componentes React.
+ * Retorna funções de disparo de eventos prontas para uso.
+ *
+ * @returns Objeto com funções de disparo de eventos
+ *
+ * @example
+ * ```typescript
+ * function MyComponent() {
+ *   const { pushInitialized, pushUpdated } = useDataLayerEvents();
+ *
+ *   useEffect(() => {
+ *     pushInitialized({ necessary: true, analytics: false });
+ *   }, []);
+ *
+ *   const handleAcceptAll = () => {
+ *     const newPrefs = { necessary: true, analytics: true, marketing: true };
+ *     pushUpdated(newPrefs, 'banner');
+ *   };
+ * }
+ * ```
+ *
+ * @category Hooks
+ * @since 0.4.5
+ * @public
+ */
+declare function useDataLayerEvents(): {
+    pushInitialized: typeof pushConsentInitializedEvent;
+    pushUpdated: typeof pushConsentUpdatedEvent;
+};
+
+export { type AdvancedConsentTexts, COMMON_INTEGRATIONS, type CategoriesContextValue, type Category, type CategoryAutoConfigResult, type CategoryDefinition, type ClarityConfig, type ConsentContextValue, type ConsentCookieData, type ConsentCookieOptions, type ConsentEvent, type ConsentEventOrigin, ConsentGate, type ConsentInitializedEvent, type ConsentPreferences, ConsentProvider, type ConsentProviderProps, ConsentScriptLoader, type ConsentScriptLoaderProps, type ConsentState, type ConsentTexts, type ConsentUpdatedEvent, type CookieDescriptor, type CorporateConfig, type CustomCookieBannerProps, type CustomFloatingPreferencesButtonProps, type CustomPreferencesModalProps, DEFAULT_PROJECT_CATEGORIES, DesignProvider, type DesignTokens, type DeveloperGuidance, type ECommerceConfig, EXPANDED_DEFAULT_TEXTS, type FacebookPixelConfig, GUIDANCE_PRESETS, type GoogleAnalyticsConfig, type GoogleTagManagerConfig, type GuidanceConfig, type GuidanceMessage, type GuidanceSeverity, type HotjarConfig, INTEGRATION_TEMPLATES, type IntercomConfig, LogLevel, type MixpanelConfig, type ProjectCategoriesConfig, type SaaSConfig, type ScriptIntegration, TEXT_TEMPLATES, type UserWayConfig, type ZendeskConfig, analyzeDeveloperConfiguration, analyzeIntegrationCategories, autoConfigureCategories, categorizeDiscoveredCookies, createClarityIntegration, createCorporateIntegrations, createECommerceIntegrations, createFacebookPixelIntegration, createGoogleAnalyticsIntegration, createGoogleTagManagerIntegration, createHotjarIntegration, createIntercomIntegration, createMixpanelIntegration, createProjectPreferences, createSaaSIntegrations, createUserWayIntegration, createZendeskChatIntegration, defaultTexts, detectConsentCookieName, discoverRuntimeCookies, extractCategoriesFromIntegrations, getAllProjectCategories, getCookiesInfoForCategory, loadScript, logDeveloperGuidance, logger, openPreferencesModal, pushConsentInitializedEvent, pushConsentUpdatedEvent, resolveTexts, setCookieCatalogOverrides, setCookieCategoryOverrides, setDebugLogging, suggestCategoryForScript, useCategories, useCategoryStatus, useConsent, useConsentHydration, useConsentScriptLoader, useConsentTexts, useDataLayerEvents, useDesignTokens, useDeveloperGuidance, useOpenPreferencesModal, validateIntegrationCategories, validateNecessaryClassification, validateProjectPreferences };