Adicionado e aprimorado suporte ao Storybook com controles (args/argTypes) para componentes-chave (FloatingPreferencesButton, PreferencesModal) e suporte a tema escuro nas histórias.
Isolamento entre stories via reset de estado (remoção/limpeza de cookie entre stories) e ajustes em .storybook/preview.tsx para compatibilidade com Vite/ESM.
ConsentProvider
blockingStrategy (opt-in) adicionado para permitir overlays de bloqueio controlados pelo provider.
Melhor encaminhamento de props: floatingPreferencesButtonProps agora são repassadas corretamente quando o FloatingPreferencesButton é instanciado automaticamente.
Testes e qualidade
Suíte de testes ampliada: novos testes para DesignContext, useConsent, CategoriesContext, ConsentScriptLoader, cookieUtils, scriptLoader, scriptIntegrations, SafeThemeProvider, logger, ConsentGate, PreferencesModal e FloatingPreferencesButton.
Configuração inicial de mutation testing com Stryker.
Setup de testes atualizado para suprimir logs do developerGuidance durante execução normal e permitir testes dedicados que verifiquem esses logs.
Integração e DX
Quickstart PT/EN e melhorias no README para facilitar adoção e contribuições.
Notas de troubleshooting e documentação adicional sobre Storybook e integração de componentes.
🐛 Correções importantes
FloatingPreferencesButton — props forward
Sintoma: props (tooltip, hideWhenConsented, etc.) não eram aplicadas quando o botão era renderizado automaticamente pelo ConsentProvider.
Solução: ConsentProvider agora encaminha floatingPreferencesButtonProps corretamente para o componente padrão. Stories atualizadas.
Storybook fixes
Removidos arquivos preview.ts que continham JSX; migrado para preview.tsx e ajustadas exports para evitar erros com o bundler (esbuild/vite).
🧪 Testes e estabilidade
Cobertura e robustez
Adicionados testes que validam uso de hooks fora do ConsentProvider (erros esperados), hidratação a partir de cookie, callbacks (onConsentGiven, onPreferencesSaved) e fluxos de UI (abrir/fechar modal, accept/reject).
Ajustes no jest.setup e um jest.console-setup.ts para garantir suprimir logs antes da coleta de módulos, mantendo testes determinísticos.
📚 Documentação
Quickstart & README
Novo Quickstart em PT/EN e simplificações no README com foco em QUICKSTART.
Documentação de uso do Storybook e troubleshooting adicionada em docs.
♻️ Dependências e manutenção
Dev-deps e chores
Atualizações de dependências de desenvolvimento (ex.: jest, @types/jest, typedoc, jest-environment-jsdom) e ajustes na package.json (engine npm atualizado, scripts e chores relacionados ao Storybook).
Limpeza de arquivos redundantes e ajustes de ESLint/preview para Storybook.
Commits representativos
Testes e supressão de logs: fce823a, 333ce0a, a1eea7e
[0.3.1] - 2025-08-13 - CORREÇÕES DE PRODUÇÃO E MELHORIAS DE COMPATIBILIDADE
🛡️ Corrigido - Critical Production Fixes
A) Compatibilidade com ThemeProvider
Erro "Cannot read properties of undefined (reading 'duration')": Implementado sistema de fallbacks seguros para propriedades de tema MUI inexistentes ou indefinidas
Componentes internos não renderizavam: Adicionado SafeThemeProvider interno que garante compatibilidade com diferentes configurações de ThemeProvider do usuário
Conflitos de tema: FloatingPreferencesButton e outros componentes agora usam useThemeWithFallbacks() para acessar propriedades de tema com valores padrão
B) API do FloatingPreferencesButton
"Element type is invalid: expected string but got object": Corrigido erro de renderização no FloatingPreferencesButton
Falta de controle sobre botão flutuante: Adicionada prop disableFloatingPreferencesButton?: boolean no ConsentProvider
Sem API para abrir modal programaticamente:
Novo hook useOpenPreferencesModal() para componentes React
Nova função openPreferencesModal() para uso em JavaScript puro
Integração automática com sistema global para acesso fora do contexto React
C) Exports de TypeScript Ausentes
Adicionados exports públicos para melhor Developer Experience:
CustomCookieBannerProps - para componentes de banner customizados
CustomPreferencesModalProps - para modal de preferências customizado
CustomFloatingPreferencesButtonProps - para botão flutuante customizado
ConsentProviderProps - para tipagem das props do provider principal
✨ Novas Funcionalidades
Sistema de Debug e Troubleshooting
setDebugLogging(enabled: boolean, level?: LogLevel): Função para habilitar logs detalhados em produção quando necessário
Logs automáticos: Sistema de logging que inclui:
Compatibilidade de tema (detection de propriedades MUI faltantes)
Mudanças de estado de consentimento
Operações de cookie (leitura/escrita/remoção)
Renderização de componentes (props e estados)
Integrações de scripts (carregamento/falhas)
Chamadas de API internas
Detecção automática de ambiente: Logs desabilitados automaticamente em produção, habilitados em desenvolvimento
API Melhorada para Controle Programático
useOpenPreferencesModal(): Hook que retorna função para abrir modal de preferências
openPreferencesModal(): Função utilitária para acesso global (fora de componentes React)
Integração com AccessibilityDock: Exemplos de uso em dock de acessibilidade customizado
📚 Documentação
Guia de API v0.3.1+
Novo arquivo: docs/API-v0.3.1.md com exemplos completos
Casos de uso: Next.js 14+, Material-UI, componentes totalmente customizados
Troubleshooting: Guia de resolução dos problemas mais comuns
Migration Guide: Instruções de atualização (sem breaking changes)
Exemplos de Implementação
Componentes customizados: Exemplos completos de CustomCookieBanner, CustomPreferencesModal
Integração com AccessibilityDock: Implementação de botão de preferências em dock customizado
SSR/Next.js: Configuração para evitar flash de conteúdo e hidratação adequada
Debug em produção: Como habilitar logs para troubleshooting quando necessário
🔧 Melhorias Técnicas
Robustez e Estabilidade
SafeThemeProvider: Componente interno que evita erros de tema em diferentes configurações de Material-UI
Fallbacks automáticos: Valores padrão para todas as propriedades de tema acessadas pelos componentes
Detecção de ambiente: Melhorada para funcionar em diferentes build systems e ambientes de execução
Compatibilidade: Testado com Material-UI v5 e Next.js 14+
Developer Experience
Tipos mais precisos: Exports de todos os tipos necessários para customização
Logs informativos: Sistema de debug que facilita identificação de problemas
Documentação expandida: Exemplos práticos e casos de uso reais
Zero breaking changes: Atualização segura desde v0.3.0
🛠️ Contexto de Correção
Estas correções abordam problemas identificados em produção com:
Apps Next.js 14+ usando Material-UI: Conflitos de ThemeProvider resolvidos
Componentes customizados: APIs claras para substituição completa da UI
AccessibilityDock integrations: Controle programático do modal de preferências
Troubleshooting: Sistema de logs para diagnóstico de problemas em produção
📋 Migration from v0.3.0
✅ Zero Breaking Changes: Atualização direta sem modificações necessárias
// Habilitar debug se necessário setDebugLogging(true, LogLevel.DEBUG)
[0.3.0] - 2025-08-12 - DX APRIMORADA E UI AUTOMÁTICA
🚨 MUDANÇAS QUE QUEBRAM A COMPATIBILIDADE
Remoção de Exports Diretos de Componentes UI: CookieBanner e FloatingPreferencesButton não são mais exportados diretamente. Eles agora são gerenciados e renderizados automaticamente pelo ConsentProvider.
Remoção da Prop disableAutomaticModal: Esta prop foi removida do ConsentProvider. O modal de preferências agora é sempre renderizado (seja o padrão ou um componente customizado fornecido) e sua visibilidade é controlada internamente pelo estado isModalOpen.
Tipagem Estrita para Componentes UI Customizados: As props para PreferencesModalComponent, CookieBannerComponent e FloatingPreferencesButtonComponent agora exigem tipos específicos (CustomPreferencesModalProps, CustomCookieBannerProps, CustomFloatingPreferencesButtonProps). Componentes customizados que usavam React.ComponentType<any> precisarão ser atualizados.
Remoção do Hook useConsentComponentProps: Este hook utilitário foi removido, pois os componentes internos agora usam useConsent e useConsentTexts diretamente.
✨ Novas Funcionalidades e Melhorias
Renderização Automática de Componentes UI Padrão: O ConsentProvider agora renderiza automaticamente o CookieBanner (quando necessário) e o FloatingPreferencesButton (após consentimento), reduzindo o boilerplate.
Componentes UI Sobrescrevíveis com Tipagem Clara: Permite que desenvolvedores forneçam seus próprios componentes de banner, modal e botão flutuante com total segurança de tipo.
Controle Simplificado do Modal: A visibilidade do modal é controlada exclusivamente pelo estado interno, eliminando a necessidade da prop disableAutomaticModal.
Carregamento Imediato de Banner e Botão Flutuante: Removido o lazy loading para CookieBanner e FloatingPreferencesButton para garantir visibilidade imediata e evitar falhas de carregamento.
Prop disableDeveloperGuidance: Permite desabilitar os avisos e sugestões para desenvolvedores no console.
Prop reloadOnChange para ConsentScriptLoader: Permite recarregar scripts de integração quando as preferências de consentimento mudam.
Ajuste de Posição da Marca: A marca "fornecido por LÉdipO.eti.br" agora é exibida no canto inferior direito do banner e modal.
[0.2.6] - 2025-08-12 - ESTABILIZAÇÃO E CONFORMIDADE
🛡️ Modificado
Gerenciamento de Estado Unificado: O ConsentProvider foi refatorado para usar uma lógica centralizada (categoryUtils.ts) para criar e validar as preferências de consentimento. Isso elimina inconsistências e garante que o estado do consentimento sempre reflita a configuração do projeto (ProjectCategoriesConfig).
Validação na Hidratação: Ao carregar o estado de um cookie existente, as preferências agora são validadas contra a configuração atual do projeto. Categorias que não existem mais na configuração são removidas, evitando estados inválidos.
✨ Adicionado
Metadados de Auditoria no Cookie: O cookie de consentimento agora armazena um snapshot da configuração de categorias (projectConfig) que estava ativa no momento em que o consentimento foi dado. Isso fortalece a capacidade de auditoria e a conformidade com a LGPD.
📚 Documentação
Consolidação: A pasta docs foi significativamente limpa, com a remoção de múltiplos arquivos redundantes e temporários.
README.md Melhorado: O arquivo README.md principal foi completamente reescrito para seguir um padrão profissional, com estrutura clara, exemplos de código atualizados e badges de status do projeto.
Guia de Conformidade Unificado: O arquivo COMPLIANCE.md agora centraliza as informações sobre as funcionalidades de conformidade da biblioteca e as orientações para desenvolvedores, incorporando conteúdo de outros documentos que foram removidos.
🐛 Corrigido
Consistência do Consentimento: Corrigido o problema onde as ações ACCEPT_ALL e REJECT_ALL não consideravam a configuração completa do projeto, podendo levar a um estado de preferências incorreto.
[0.2.2] - 2025-08-12 - SISTEMA DE ORIENTAÇÕES PARA DESENVOLVEDORES
✨ Adicionado
🚨 Sistema Inteligente de Orientações
Console de Desenvolvimento: Avisos automáticos sobre configuração
⚠️ Avisos: Detecta configuração faltante, inconsistente ou problemática
💡 Sugestões: Recomendações para melhor compliance e UX
🔧 Tabela de Categorias: Lista categorias ativas para orientar UI customizada
Novos Hooks para Componentes Customizados:
useCategories(): Informações completas sobre categorias ativas no projeto
useCategoryStatus(id): Verifica se categoria específica está configurada
Prevenção de Bugs: Evita inconsistências entre configuração e UI
🎨 UI Dinâmica e Inteligente
PreferencesModal Aprimorado: Renderiza automaticamente apenas categorias configuradas
Componentes Adaptativos: UI se ajusta dinamicamente à configuração do projeto
Renderização Condicional: Não exibe categorias não utilizadas no projeto
📋 Configuração Padrão Defensiva
Padrão Inteligente: Quando nenhuma categoria especificada, usa necessary + analytics
Orientação Automática: Avisa sobre uso de configuração padrão em desenvolvimento
Migração Transparente: API de categorias funciona perfeitamente
🔍 Análise e Validação de Configuração
Função analyzeDeveloperConfiguration(): Valida e orienta sobre configuração
Constante DEFAULT_PROJECT_CATEGORIES: Configuração padrão baseada em casos reais
Detecção Automática: Identifica muitas categorias, descrições inadequadas, etc.
🔧 Modificado
ConsentProvider Expandido
Suporte Completo: Prop categories com configuração de categorias padrão e personalizadas
Sistema de Orientações: Log automático de orientações em modo desenvolvimento
Configuração Moderna: Nova estrutura da prop categories para maior flexibilidade
Componentes UI Inteligentes
Inicialização Segura: tempPreferences inicializado corretamente com valores padrão
Sincronização Dinâmica: Estado local sincroniza apenas com categorias ativas
Renderização Otimizada: Loops baseados em toggleableCategories ao invés de hardcode
🐛 Corrigido
React Warning: Eliminado "A component is changing an uncontrolled input to be controlled"
Estado de Input: PreferencesModal inicializa switches com valores controlados
Sincronização: Preferências temporárias sincronizam corretamente com categorias ativas
Performance: Não renderiza componentes para categorias não configuradas
📚 Documentação
Novo arquivo: docs/ORIENTACOES-DESENVOLVIMENTO.md - Guia completo do sistema
README expandido: Exemplos práticos da nova API e componentes dinâmicos
Exemplos de uso: Demonstração de hooks para validação condicional de categorias
Guias de migração: Como usar nova API mantendo compatibilidade
🎯 Benefícios da v0.2.2
Para Desenvolvedores
🚨 Orientação Proativa: Console indica exatamente quais categorias implementar na UI
🐛 Prevenção de Bugs: Validação automática de consistência Configuração ↔ UI
🔧 Flexibilidade Total: APIs antigas funcionam, nova API oferece mais controle
📋 TypeScript Completo: Tipos específicos para cada hook e configuração
Para Compliance LGPD
🎯 Configuração Consciente: Sistema força reflexão sobre quais dados realmente coletar
📝 Documentação Automática: Orientações baseadas na configuração real do projeto
🔍 Auditabilidade: Logs claros mostram decisões de configuração
🛡️ Conformidade Ativa: Alinhamento dinâmico com princípios da ANPD
Para Usuários Finais
⚡ Performance Superior: Interface otimizada mostra apenas categorias relevantes
🎯 Experiência Focada: Usuários não veem opções irrelevantes para o projeto
🔒 Transparência Máxima: Descrições claras apenas de categorias realmente utilizadas
[0.2.1] - 2025-08-12 - CONFORMIDADE LGPD RIGOROSA + SISTEMA DE ORIENTAÇÕES
🚨 NOVO: Sistema de Orientações para Desenvolvedores
A v0.2.1 introduz um sistema inteligente de orientações que guia desenvolvedores sobre configuração adequada e previne inconsistências entre configuração e UI customizada.
🛡️ BREAKING CHANGES - Conformidade ANPD
Cookie de Consentimento Reestruturado
🍪 Estrutura do Cookie: Novo formato com campos obrigatórios para compliance
version: Controle de migração de schema
consentDate: Timestamp da primeira interação
lastUpdate: Timestamp da última modificação
source: Origem da decisão (banner, modal, programmatic)
Removido: isModalOpen (estado de UI não deve ser persistido)
Sistema de Categorias por Projeto
🔧 Nova Prop: categories no ConsentProvider para especificar apenas categorias ativas
📦 Principio da Minimização: Cookie contém apenas categorias realmente utilizadas
⚡ Performance: Redução significativa do tamanho do cookie