react-lgpd-consent 0.3.3 → 0.3.5

package/CHANGELOG.md

@@ -4,6 +4,71 @@ Todas as mudanças notáveis neste projeto serão documentadas neste arquivo.
 
 O formato é baseado em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.0.0/), e este projeto segue [Semantic Versioning](https://semver.org/lang/pt-BR/).
 
+## [Unreleased]
+
+### ✨ Novas funcionalidades e melhorias
+
+- Storybook
+  - 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`.
+
+### 🛠️ Correção crítica: Herança de ThemeProvider (v0.3.5)
+
+- **Corrigido:** A biblioteca não deve criar ou impor um `ThemeProvider` global por si só. Agora o `ConsentProvider` herda o theme do app consumidor quando um `ThemeProvider` do MUI estiver presente. O Provider só envolverá com `ThemeProvider` se a prop `theme` for explicitamente fornecida.
+- **Motivação:** Evitar conflitos de contexto MUI/Emotion, regressões visuais e problemas em SSR causados por criação de tema no escopo de módulo.
+- **Export:** `createDefaultConsentTheme()` foi adicionada como fábrica para quem precisar de um fallback explícito. Há também um getter compat (deprecated) `defaultConsentTheme()` que retorna uma nova instância quando chamada.
+- **Compatibilidade:** Uso padrão continua igual — se seu app fornece um `ThemeProvider` e você passa o mesmo theme para `ConsentProvider` (ou não passa `theme`), tudo continuará funcionando normalmente.
+
+Referência: issues/PR relacionadas e notas de release serão adicionadas no branch de release.
+
+### ♻️ 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`
+- Storybook / docs: `8f8c388`, `6e09058`, `329682c`, `9b1d977`, `adf0d49`
+- Provider features: `967d278` (blockingStrategy)
+- Quickstart / README: `db03ae3`
+- Dependências / chores: `27339e7`, `3b7fdba`, `11c3602`
+
 ## [0.3.1] - 2025-08-13 - CORREÇÕES DE PRODUÇÃO E MELHORIAS DE COMPATIBILIDADE
 
 ### 🛡️ **Corrigido - Critical Production Fixes**
@@ -294,7 +359,7 @@ A v0.2.1 introduz um **sistema inteligente de orientações** que guia desenvolv
 
 ### 📋 **Documentação**
 
-- **📋 CONFORMIDADE-LGPD.md**: Guia completo de implementação conforme ANPD
+- **📋 CONFORMIDADE.md**: Guia completo de implementação conforme ANPD
 - **🔄 Migração**: Instruções detalhadas v0.2.0 → v0.2.1
 - **🏛️ Exemplos**: Casos de uso governamentais e corporativos
 
@@ -458,8 +523,6 @@ A v0.2.1 introduz um **sistema inteligente de orientações** que guia desenvolv
 
 ---
 
-## [Unreleased]
-
 ### 🔮 Futuro (v0.4.0+)
 
 - [ ] Modal detalhado com lista de cookies

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 @lucianoedipo
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 @lucianoedipo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/QUICKSTART.en.md

@@ -0,0 +1,245 @@
+# 🚀 Quickstart
+
+This quickstart gives everything you need to integrate `react-lgpd-consent` into a React project fast.
+
+## 📦 Installation
+
+```bash
+npm install react-lgpd-consent
+# or
+yarn add react-lgpd-consent
+```
+
+### Peer dependencies
+
+```bash
+npm install @mui/material @mui/icons-material @emotion/react @emotion/styled
+```
+
+## 🎯 Basic Usage (30 seconds)
+
+```tsx
+import React from 'react'
+import { ConsentProvider } from 'react-lgpd-consent'
+
+function App() {
+  return (
+    <ConsentProvider
+      categories={{
+        enabledCategories: ['analytics', 'marketing'],
+      }}
+    >
+      <main>
+        <h1>My Application</h1>
+      </main>
+    </ConsentProvider>
+  )
+}
+
+export default App
+```
+
+## 🧭 Storybook — quick note
+
+This repository ships an interactive Storybook playground used for manual testing and visual exploration of components. Quick commands:
+
+- Run locally (development):
+
+```bash
+npm run storybook
+```
+
+- Build static Storybook (for publishing to GitHub Pages):
+
+```bash
+npm run build-storybook
+```
+
+Notes:
+- The Storybook preview (`.storybook/preview.tsx`) applies a clean environment between stories (it removes the consent cookie and performs defensive DOM cleanup). Check that file when creating stories that rely on a clean initial state.
+
+
+## 📋 ConsentProvider props (summary)
+
+This is a condensed reference of the most commonly-used props. For a full typed table, see the TypeScript API docs.
+
+- `categories` (required) — Project categories configuration (e.g. enabledCategories: ["analytics"]).
+- `texts` — Partial object to override UI texts.
+- `theme` — Material-UI theme for consent components.
+- `designTokens` — Advanced visual tokens (colors, spacing, backdrop).
+- `blocking` (boolean) — If true, provider will block interaction until user acts.
+- `blockingStrategy` (`"auto" | "provider" | "component"`) — How overlay is managed.
+- `hideBranding` (boolean) — Hide library branding.
+- `onConsentGiven` — Callback when user gives consent for the first time.
+- `onPreferencesSaved` — Callback when preferences are saved.
+- `CookieBannerComponent`, `PreferencesModalComponent`, `FloatingPreferencesButtonComponent` — Replace UI components.
+- `cookie` — Customize cookie name, maxAge, domain, secure, sameSite.
+
+## 🎨 Custom components (TypeScript)
+
+### Custom Cookie Banner
+
+```tsx
+import React from 'react'
+import { ConsentProvider, type CustomCookieBannerProps } from 'react-lgpd-consent'
+
+const MyBanner: React.FC<CustomCookieBannerProps> = ({
+  consented,
+  acceptAll,
+  rejectAll,
+  openPreferences,
+  texts,
+  blocking,
+}) => {
+  return (
+    <div style={{ position: 'fixed', bottom: 0, left: 0, right: 0, background: '#222', color: 'white', padding: '1rem' }}>
+      <p>{texts.bannerMessage}</p>
+      <div style={{ display: 'flex', gap: '1rem', marginTop: '1rem' }}>
+        <button onClick={acceptAll}>{texts.acceptAll}</button>
+        <button onClick={rejectAll}>{texts.declineAll}</button>
+        <button onClick={openPreferences}>{texts.preferences}</button>
+      </div>
+    </div>
+  )
+}
+
+function App() {
+  return (
+    <ConsentProvider categories={{ enabledCategories: ['analytics'] }} CookieBannerComponent={MyBanner} blocking>
+      <main>My App</main>
+    </ConsentProvider>
+  )
+}
+```
+
+### Custom Preferences Modal
+
+```tsx
+import React from 'react'
+import { ConsentProvider, type CustomPreferencesModalProps } from 'react-lgpd-consent'
+
+const MyModal: React.FC<CustomPreferencesModalProps> = ({ preferences, setPreferences, closePreferences, isModalOpen, texts }) => {
+  if (!isModalOpen) return null
+
+  return (
+    <div style={{ position: 'fixed', inset: '20% 25%', background: 'white', borderRadius: 8, padding: '1.5rem', zIndex: 2000 }}>
+      <h2>{texts.modalTitle}</h2>
+      <p>{texts.modalIntro}</p>
+
+      {Object.entries(preferences).map(([category, enabled]) => (
+        <label key={category} style={{ display: 'block', margin: '0.5rem 0' }}>
+          <input
+            type="checkbox"
+            checked={enabled}
+            onChange={(e) => setPreferences({ ...preferences, [category]: e.target.checked })}
+            disabled={category === 'necessary'}
+          />{' '}
+          {category === 'necessary' ? texts.necessaryAlwaysOn : `Cookies ${category}`}
+        </label>
+      ))}
+
+      <div style={{ display: 'flex', gap: '1rem', justifyContent: 'flex-end', marginTop: '1rem' }}>
+        <button onClick={closePreferences}>Cancel</button>
+        <button onClick={closePreferences}>{texts.save}</button>
+      </div>
+    </div>
+  )
+}
+
+function App() {
+  return (
+    <ConsentProvider categories={{ enabledCategories: ['analytics', 'marketing'] }} PreferencesModalComponent={MyModal}>
+      <main>My App</main>
+    </ConsentProvider>
+  )
+}
+```
+
+## 🎮 Programmatic control
+
+### React hook: `useOpenPreferencesModal`
+
+```tsx
+import React from 'react'
+import { useOpenPreferencesModal, useConsent } from 'react-lgpd-consent'
+
+function MyComponent() {
+  const openPreferences = useOpenPreferencesModal()
+  const { preferences, acceptAll, rejectAll } = useConsent()
+
+  return (
+    <div>
+      <h3>Analytics: {preferences.analytics ? 'enabled' : 'disabled'}</h3>
+      <button onClick={openPreferences}>⚙️ Manage preferences</button>
+      <button onClick={acceptAll}>✅ Accept all</button>
+      <button onClick={rejectAll}>❌ Reject all</button>
+    </div>
+  )
+}
+```
+
+### Global: `window.openPreferencesModal` (for plain JS)
+
+```html
+<button onclick="window.openPreferencesModal?.()">Configure cookies</button>
+
+<script>
+  if (typeof window.openPreferencesModal === 'function') {
+    console.log('Consent system available')
+  }
+</script>
+```
+
+## 🐛 Debug system
+
+```tsx
+import { setDebugLogging, LogLevel } from 'react-lgpd-consent'
+
+// enable verbose debug locally
+setDebugLogging(true, LogLevel.DEBUG)
+
+// quieter in staging
+setDebugLogging(true, LogLevel.INFO)
+
+// errors only
+setDebugLogging(true, LogLevel.ERROR)
+
+// disable
+setDebugLogging(false)
+```
+
+Use the `useConsent` hook to inspect runtime state (preferences, consented) and optionally render a small debug panel in dev mode.
+
+## 🎨 Material-UI Theme integration
+
+Wrap your app with MUI `ThemeProvider` and optionally pass a `theme` prop to `ConsentProvider` to style consent components.
+
+## 🔧 Advanced
+
+- `designTokens` for low-level visual control (colors, spacing, backdrop)
+- `cookie` to customize name, maxAge, domain, secure, sameSite
+- `blocking` + `blockingStrategy` to control overlay behavior
+
+## 🚀 Common use cases
+
+- E-commerce: analytics + marketing integrations
+- Blog: only analytics
+- Enterprise: strict blocking and auditing via `onPreferencesSaved`
+
+## 🆘 Troubleshooting
+
+- "ConsentProvider must be used within ConsentProvider": ensure hooks are called inside provider tree.
+- Banner not showing: clear consent cookie, check z-index and config.
+- TypeScript types: set `moduleResolution` or `skipLibCheck` in `tsconfig` if needed.
+
+## 📚 Next steps
+
+- API docs: `API.md`
+- LGPD compliance guide: `CONFORMIDADE.md`
+- Integrations: `INTEGRACOES.md`
+- Example app: `example/`
+
+
+---
+
+Tip: enable debug logs during development with `setDebugLogging(true, LogLevel.DEBUG)` to see runtime behavior.