react-lgpd-consent 0.7.1 → 0.7.2

package/API.md

@@ -30,6 +30,7 @@ Este documento é a referência técnica oficial para a API da biblioteca `react
 | `createClarityIntegration`          | Função     | (v0.4.1) Integração nativa com Microsoft Clarity.                                |
 | `createIntercomIntegration`         | Função     | (v0.4.1) Integração nativa com Intercom (chat).                                  |
 | `createZendeskChatIntegration`      | Função     | (v0.4.1) Integração nativa com Zendesk Chat.                                     |
+| `createSuggestedIntegration`        | Função     | (v0.7.2) Cria integração customizada com categoria sugerida automaticamente.    |
 | `suggestCategoryForScript`          | Função     | (v0.4.1) Sugere categoria(s) LGPD para um script conhecido.                      |
 | `discoverRuntimeCookies`            | Função     | (v0.4.1) Descobre cookies em tempo real no navegador.                            |
 | `categorizeDiscoveredCookies`       | Função     | (v0.4.1) Categoriza cookies descobertos usando padrões LGPD.                     |
@@ -45,10 +46,63 @@ Este documento é a referência técnica oficial para a API da biblioteca `react
 | `createSaaSIntegrations`            | Função     | (v0.4.1) Cria integrações comuns para SaaS.                                      |
 | `createCorporateIntegrations`       | Função     | (v0.4.1) Cria integrações comuns para ambientes corporativos.                    |
 | `INTEGRATION_TEMPLATES`             | Constante  | (v0.4.1) Presets com IDs essenciais/opcionais e categorias por tipo de negócio.  |
+| `SuggestedIntegrationConfig`        | Tipo       | (v0.7.2) Configuração para integração customizada com categoria sugerida.        |
 | `setDebugLogging`                   | Função     | Habilita/desabilita o logging de debug da biblioteca.                           |
 
 ---
 
+## ESM/CJS e Testes (Jest/Vitest)
+
+O pacote publica **dual build** (ESM + CJS) via `exports`:
+
+```json
+{
+  ".": { "import": "./dist/index.js", "require": "./dist/index.cjs" },
+  "./core": { "import": "./dist/core.js", "require": "./dist/core.cjs" },
+  "./mui": { "import": "./dist/mui.js", "require": "./dist/mui.cjs" },
+  "./integrations": { "import": "./dist/integrations.js", "require": "./dist/integrations.cjs" }
+}
+```
+
+### Jest (CJS) com babel-jest
+
+```js
+// jest.config.cjs
+module.exports = {
+  testEnvironment: 'jsdom',
+  transform: {
+    '^.+\\.(t|j)sx?$': ['babel-jest', { presets: ['@babel/preset-env', '@babel/preset-react', '@babel/preset-typescript'] }],
+  },
+  transformIgnorePatterns: ['/node_modules/(?!react-lgpd-consent|@react-lgpd-consent)/'],
+}
+```
+
+### Vitest (Vite)
+
+```ts
+// vitest.config.ts
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    environment: 'jsdom',
+    deps: {
+      inline: ['react-lgpd-consent', '@react-lgpd-consent/core', '@react-lgpd-consent/mui'],
+    },
+  },
+})
+```
+
+### Importações recomendadas
+
+```ts
+import { ConsentProvider } from 'react-lgpd-consent'
+import { ConsentProvider as ConsentProviderHeadless } from 'react-lgpd-consent/core'
+import { createGoogleAnalyticsIntegration } from 'react-lgpd-consent/integrations'
+```
+
+---
+
 ## Componentes
 
 ### `<ConsentProvider />`
@@ -76,7 +130,9 @@ function App() {
 | Prop | Tipo | Descrição |
 | --- | --- | --- |
 | `categories` | `ProjectCategoriesConfig` | **Obrigatório.** Fonte única de verdade sobre as categorias habilitadas; usada por UI, hooks e integrações. |
-| `texts` | `Partial<ConsentTexts>` | Customiza todos os textos exibidos (banner, modal, botão). |
+| `texts` | `Partial<AdvancedConsentTexts>` | Customiza todos os textos exibidos (banner, modal, botão). |
+| `language` | `'pt' \| 'en' \| 'es' \| 'fr' \| 'de' \| 'it'` | Resolve textos via i18n no Provider. |
+| `textVariant` | `'formal' \| 'casual' \| 'concise' \| 'detailed'` | Aplica variação de tom sobre os textos base. |
 | `designTokens` | `DesignTokens` | Ajuste visual granular (cores, spacing, tipografia, overlays). |
 | `blocking` | `boolean` | Ativa overlay bloqueante até o usuário decidir. Padrão: `false`. |
 | `blockingStrategy` | `'auto' \| 'provider' \| 'component'` | Controla quem desenha o overlay quando `blocking` está ativo. |
@@ -586,7 +642,7 @@ Para customizações avançadas e tipagem, você pode importar os seguintes tipo
 - `CustomPreferencesModalProps`: Props passadas para um modal de preferências customizado.
 - `ConsentState`: Objeto que representa o estado completo do consentimento do usuário.
 - `ConsentPreferences`: Objeto com as preferências de consentimento para cada categoria.
-- `ConsentTexts`: Objeto com todos os textos customizáveis da UI.
+- `ConsentTexts`: Tipo base com textos essenciais da UI (pt-BR).
 - `Category`: Objeto que representa a definição de uma categoria de cookie.
 ### Exemplos de categorias (mínimo e completo)
 

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.7.2
+
+### Patch Changes
+
+- [#134](https://github.com/lucianoedipo/react-lgpd-consent/pull/134) [`44b885b`](https://github.com/lucianoedipo/react-lgpd-consent/commit/44b885b7c81f1cb5822e2dcfde2975e69e8d4893) Thanks [@github-actions](https://github.com/apps/github-actions)! - ### Correções
+  - 1d15920 fix: corrigir formatação da verificação de múltiplas versões do React
+
+  ### Funcionalidades
+  - d641639 feat: adicionar gerenciamento de eventos para categorias obrigatórias no CategoriesProvider
+  - b04c00b feat: add tests for CookieBanner, FloatingPreferencesButton, and PreferencesModal components
+  - b04c00b Introduce interactive changeset script for easier versioning in monorepos.
+
+  ### Refactors e compatibilidade
+  - ef2968a refactor: replace direct document and window references with globalThis for better compatibility
+  - ef2968a Updated scriptLoader, cookieDiscovery, cookieUtils, dataLayerEvents, developerGuidance, peerDepsCheck, scriptIntegrations, and scriptLoader files to use globalThis.document and globalThis.window.
+  - ef2968a Improved cookie handling functions to check for document and window availability using globalThis.
+  - ef2968a Enhanced tests to reference globalThis for consistency.
+  - ef2968a Cleaned up code formatting and comments for clarity.
+  - b04c00b Refactor coverage check script to use node imports.
+  - b04c00b Adjust TypeDoc script for ESM compatibility.
+  - 3af2fcb Fix path resolution in tsconfig for better module imports.
+
+  ### Testes
+  - b04c00b Implement tests for CookieBanner to verify rendering based on consent and debug mode.
+  - b04c00b Enhance FloatingPreferencesButton tests to check for localized text via props.
+  - b04c00b Extend PreferencesModal tests to cover temporary preference resets, active scripts rendering, and custom text application.
+
+  ### Documentação
+  - d430eef docs: atualizar instruções para agentes com visão geral do projeto e comandos essenciais
+  - d430eef Updated documentation to reflect changes in globalThis usage.
+  - d430eef Update API documentation to include new integration functions and ESM/CJS testing configurations.
+
+- Updated dependencies [[`44b885b`](https://github.com/lucianoedipo/react-lgpd-consent/commit/44b885b7c81f1cb5822e2dcfde2975e69e8d4893)]:
+  - @react-lgpd-consent/core@0.7.2
+  - @react-lgpd-consent/mui@0.7.2
+
 ## 0.7.1
 
 ### Patch Changes
@@ -362,7 +398,7 @@
   - **Correção crítica**: `loadScript` agora aguarda dinamicamente o consentimento em vez de rejeitar imediatamente, permitindo que scripts carreguem quando preferências mudarem
   - Cleanup automático do registro ao completar/falhar carregamento
   - Adicionados testes extensivos: `ConsentScriptLoader.strictmode.test.tsx` e `scriptLoader.strictmode.test.ts`
-  - Documentação completa em `docs/REACT19-STRICTMODE.md`
+  - Documentação completa em `REACT19-STRICTMODE.md`
   - Todos os 302 testes passando, incluindo 5 novos testes de StrictMode
 
   **Breaking Changes:** Nenhuma - totalmente retrocompatível

package/INTEGRACOES.md

@@ -6,6 +6,12 @@ A biblioteca oferece integrações nativas para as ferramentas mais comuns, elim
 
 O componente `ConsentScriptLoader` gerencia o carregamento desses scripts automaticamente, disparando-os apenas quando o usuário concede consentimento para a categoria correspondente.
 
+### ✅ Regras de Configuração (RN)
+
+- **Categoria padrão com override**: cada integração define uma categoria padrão, mas o consumidor pode sobrescrever via `category` no config.
+- **Config obrigatória**: se um campo obrigatório estiver vazio (ex.: `measurementId`, `containerId`, `pixelId`), a integração **não executa**. Em **dev** é logado erro; em **prod** não há log.
+- **DataLayer**: se `globalThis.window.dataLayer` não existir, a biblioteca cria `[]`; se existir e tiver `push`, usa como está; se existir sem `push`, não sobrescreve e avisa em dev.
+
 ### ✨ Novidades v0.7.1
 
 - **🎯 Google Consent Mode v2 Automático**: GA4 e GTM agora implementam Consent Mode v2 automaticamente:
@@ -173,6 +179,7 @@ const integrations = [createUserWayIntegration({ accountId: 'USERWAY_ACCOUNT_ID'
 Para simplificar a configuração de múltiplas integrações, a biblioteca oferece templates e funções de ajuda.
 
 - `suggestCategoryForScript(name: string)`: Sugere a categoria LGPD apropriada para um nome de script conhecido.
+- `createSuggestedIntegration(config)`: Cria integração customizada com categoria sugerida automaticamente (pode sobrescrever com `category`).
 - `createECommerceIntegrations`, `createSaaSIntegrations`, `createCorporateIntegrations`: Templates de negócio que agrupam as integrações mais comuns para cada setor.
 - `INTEGRATION_TEMPLATES`: Constante com presets de IDs e categorias para cada template.
 
@@ -201,6 +208,19 @@ function App() {
 }
 ```
 
+### Exemplo de integração sugerida (custom)
+
+```tsx
+import { createSuggestedIntegration } from 'react-lgpd-consent'
+
+const integrations = [
+  createSuggestedIntegration({
+    id: 'custom-chat',
+    src: 'https://example.com/chat.js',
+  }),
+]
+```
+
 ---
 
 ## 🔎 Descoberta Automática de Cookies (Experimental v0.4.1)
@@ -253,6 +273,12 @@ interface ScriptIntegration {
 
 A partir da versão **0.4.5**, a biblioteca dispara automaticamente eventos padronizados no `dataLayer` para facilitar rastreamento, auditoria LGPD e integrações com o Google Tag Manager.
 
+### Comportamento do `dataLayer`
+
+- Se `globalThis.window.dataLayer` não existir, a biblioteca cria `[]`.
+- Se existir e tiver `push`, o array/objeto é usado como está.
+- Se existir sem `push`, a biblioteca não sobrescreve e avisa em dev.
+
 ### Eventos Disponíveis
 
 #### 1. `consent_initialized`
@@ -458,7 +484,7 @@ import { googleAnalytics4Integration } from './integrations'
     console.log('Mudança:', { current, previous })
 
     // Exemplo: disparar evento no dataLayer
-    window.dataLayer?.push({
+    globalThis.window?.dataLayer?.push({
       event: 'consent_preferences_updated',
       consent_analytics: current.preferences.analytics,
       consent_marketing: current.preferences.marketing,

package/QUICKSTART.en.md

@@ -273,13 +273,13 @@ function MyComponent() {
 }
 ```
 
-### Global: `window.openPreferencesModal` (for plain JS)
+### Global: `globalThis.window.openPreferencesModal` (for plain JS)
 
 ```html
-<button onclick="window.openPreferencesModal?.()">Configure cookies</button>
+<button onclick="globalThis.window?.openPreferencesModal?.()">Configure cookies</button>
 
 <script>
-  if (typeof window.openPreferencesModal === 'function') {
+  if (typeof globalThis.window?.openPreferencesModal === 'function') {
     console.log('Consent system available')
   }
 </script>

package/QUICKSTART.md

@@ -257,7 +257,13 @@ function BootstrapConsentMode() {
   React.useEffect(() => {
     const w = window as any
     w.dataLayer = w.dataLayer ?? []
-    w.gtag = w.gtag ?? ((...args: any[]) => w.dataLayer.push(args))
+    w.gtag =
+      w.gtag ??
+      ((...args: any[]) => {
+        if (typeof w.dataLayer?.push === 'function') {
+          w.dataLayer.push(args)
+        }
+      })
     w.gtag('consent', 'default', {
       ad_storage: 'denied',
       ad_user_data: 'denied',
@@ -486,7 +492,11 @@ function ComplianceWrapper({ children }: { children: React.ReactNode }) {
       }}
       onConsentVersionChange={({ previousKey, nextKey, resetConsent }) => {
         console.info('[consent] versão atualizada', { previousKey, nextKey })
-        window.dataLayer?.push({ event: 'consent_version_bumped', previousKey, nextKey })
+        globalThis.window?.dataLayer?.push({
+          event: 'consent_version_bumped',
+          previousKey,
+          nextKey,
+        })
         localStorage.removeItem('marketing-optins')
         resetConsent()
       }}
@@ -948,24 +958,24 @@ function MeuComponente() {
 }
 ```
 
-### window.openPreferencesModal (JavaScript Puro)
+### globalThis.window.openPreferencesModal (JavaScript Puro)
 
 ```html
 <!-- Em templates HTML, emails ou widgets externos -->
-<button onclick="window.openPreferencesModal?.()">Configurar Cookies</button>
+<button onclick="globalThis.window?.openPreferencesModal?.()">Configurar Cookies</button>
 
 <script>
   // Ou em JavaScript puro
   function abrirConfiguracoesCookies() {
-    if (window.openPreferencesModal) {
-      window.openPreferencesModal()
+    if (globalThis.window?.openPreferencesModal) {
+      globalThis.window.openPreferencesModal()
     } else {
       console.warn('Sistema de consentimento não carregado')
     }
   }
 
   // Verificar se função está disponível
-  if (typeof window.openPreferencesModal === 'function') {
+  if (typeof globalThis.window?.openPreferencesModal === 'function') {
     console.log('✅ Sistema de consentimento disponível')
   }
 </script>

package/README.en.md

@@ -76,7 +76,7 @@ function Analytics() {
       src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"
       strategy="afterInteractive"
     >
-      {`window.dataLayer = window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'GA_MEASUREMENT_ID');`}
+      {`globalThis.window && (globalThis.window.dataLayer = globalThis.window.dataLayer || []); function gtag(){ if (typeof globalThis.window?.dataLayer?.push === 'function') { globalThis.window.dataLayer.push(arguments) } } gtag('js', new Date()); gtag('config', 'GA_MEASUREMENT_ID');`}
     </ConsentScriptLoader>
   )
 }
@@ -174,4 +174,3 @@ MIT © Luciano Edipo — see the `LICENSE` file.
 ---
 
 If you want the Portuguese README, see `README.md` in the same package.
-

package/README.md

@@ -76,7 +76,7 @@ function Analytics() {
       src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"
       strategy="afterInteractive"
     >
-      {`window.dataLayer = window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'GA_MEASUREMENT_ID');`}
+      {`globalThis.window && (globalThis.window.dataLayer = globalThis.window.dataLayer ?? []); function gtag(){ if (typeof globalThis.window?.dataLayer?.push === 'function') { globalThis.window.dataLayer.push(arguments) } } gtag('js', new Date()); gtag('config', 'GA_MEASUREMENT_ID');`}
     </ConsentScriptLoader>
   )
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-lgpd-consent",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "Biblioteca de consentimento LGPD, integrações nativas e sistema extensível para React.",
   "keywords": [
     "lgpd",
@@ -94,8 +94,8 @@
     }
   },
   "dependencies": {
-    "@react-lgpd-consent/core": "^0.7.1",
-    "@react-lgpd-consent/mui": "^0.7.1"
+    "@react-lgpd-consent/core": "^0.7.2",
+    "@react-lgpd-consent/mui": "^0.7.2"
   },
   "size-limit": [
     {