react-lgpd-consent 0.3.6 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,37 @@ 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/).
 
+## [0.4.0] - 2025-09-09 — Custom categories
+
+### Added
+- Support for `customCategories` in `ConsentProvider.categories`.
+  - Included in preferences initialization and validation.
+  - Shown in the Preferences modal (with name/description).
+  - Exposed via developer guidance/context for custom UIs.
+- Quickstart PT/EN sections with `customCategories` examples.
+- Storybook story: WithCustomCategories.
+
+### Notes
+- Non-breaking change; existing configurations continue to work.
+
+## [0.3.7] - 2025-09-08 - Testes de UI e carregamento de scripts
+
+### 🧪 Novos testes e cobertura
+
+- CookieBanner
+  - Testes para renderização condicional em modos bloqueante (overlay) e não-bloqueante (Snackbar)
+  - Verificação de abertura do modal ao clicar em “Preferências” e persistência ao clicar em “Recusar”
+- ConsentScriptLoader / Hook
+  - Gating por consentimento e categoria; não carrega scripts quando não consentido ou categoria desabilitada
+  - Tratamento de erros (log `logger.error` quando `loadScript` rejeita)
+  - `reloadOnChange` reexecuta o carregamento ao reabilitar a categoria; default não recarrega
+- Integrações de script
+  - Verificação de `attrs` em integrações (GA define `async: 'true'`)
+
+### 🔧 Interno
+
+- Aumento da estabilidade para refatorações futuras na camada de UI e utilitários de carregamento.
+
 ## [0.3.6] - 2025-08-28 - Correção crítica: Herança de ThemeProvider
 
 ### ✨ Novas funcionalidades e melhorias

package/QUICKSTART.en.md

@@ -39,6 +39,49 @@ function App() {
 export default App
 ```
 
+## 🧩 Custom categories (customCategories)
+Available since v0.4.0.
+
+Add project-specific categories (e.g., support chat, video players, A/B testing):
+
+```tsx
+<ConsentProvider
+  categories={{
+    enabledCategories: ['analytics'],
+    customCategories: [
+      { id: 'chat', name: 'Support Chat', description: 'Chat widget' },
+      { id: 'video', name: 'Video', description: 'Embedded players' },
+      { id: 'abTesting', name: 'A/B Testing', description: 'Interface experiments' },
+    ],
+  }}
+>
+  <App />
+</ConsentProvider>
+```
+
+### Using custom categories in your code
+
+```tsx
+import { useConsent } from 'react-lgpd-consent'
+
+function MyComponent() {
+  const { consent } = useConsent()
+
+  // Check if user consented to specific categories
+  const canShowChat = consent?.preferences?.chat === true
+  const canLoadVideos = consent?.preferences?.video === true
+  const canRunABTests = consent?.preferences?.abTesting === true
+
+  return (
+    <div>
+      {canShowChat && <ChatWidget />}
+      {canLoadVideos && <VideoPlayer src="..." />}
+      {canRunABTests && <ABTestVariant />}
+    </div>
+  )
+}
+```
+
 ## 🧭 Storybook — quick note
 
 This repository ships an interactive Storybook playground used for manual testing and visual exploration of components. Quick commands:

package/QUICKSTART.md

@@ -62,6 +62,49 @@ export default App
 
 ````
 
+## 🧩 Categorias customizadas (customCategories)
+Disponível a partir da v0.4.0.
+
+Adicione categorias específicas do seu projeto (ex.: chat de suporte, players de vídeo, AB testing):
+
+```tsx
+<ConsentProvider
+  categories={{
+    enabledCategories: ['analytics'],
+    customCategories: [
+      { id: 'chat', name: 'Chat de Suporte', description: 'Widget de chat' },
+      { id: 'video', name: 'Vídeo', description: 'Players incorporados' },
+      { id: 'abTesting', name: 'A/B Testing', description: 'Experimentos de interface' },
+    ],
+  }}
+>
+  <App />
+</ConsentProvider>
+```
+
+### Usando categorias customizadas no seu código
+
+```tsx
+import { useConsent } from 'react-lgpd-consent'
+
+function MyComponent() {
+  const { consent } = useConsent()
+
+  // Verificar se o usuário consentiu com categorias específicas
+  const canShowChat = consent?.preferences?.chat === true
+  const canLoadVideos = consent?.preferences?.video === true
+  const canRunABTests = consent?.preferences?.abTesting === true
+
+  return (
+    <div>
+      {canShowChat && <ChatWidget />}
+      {canLoadVideos && <VideoPlayer src="..." />}
+      {canRunABTests && <ABTestVariant />}
+    </div>
+  )
+}
+```
+
 ## 📋 Tabela Completa de Props do ConsentProvider
 
 | Prop                                 | Tipo                                                        | Obrigatória | Padrão              | Descrição                                      |

package/README.en.md

@@ -63,6 +63,7 @@ export default function App() {
 - For full guides, TypeScript examples, props table and integrations see:
 -
 - **[QUICKSTART.en.md](./QUICKSTART.en.md)** (recommended)
+  - New in v0.4.0: `customCategories` support — see the “Custom categories (customCategories)” section in the Quickstart.
 - **[Docs / API](./API.md)**
 - **[LGPD Compliance](./CONFORMIDADE.md)**
 - **[Integrations](./INTEGRACOES.md)**

package/README.md

@@ -87,6 +87,7 @@ Para mais detalhes sobre customização, hooks e funcionalidades, consulte os se
 ### 📋 Documentação Principal
 
 - **[📚 Guia de Início Rápido (`QUICKSTART.md`)](./QUICKSTART.md)**: Tutorial passo a passo com exemplos práticos, tabela completa de props, debugging e integrações.
+  - Novo na v0.4.0: suporte a `customCategories` — veja a seção “Categorias customizadas (customCategories)” no Quickstart.
 - **[Guia da API (`API.md`)](./API.md)**: Referência completa de todos os componentes, hooks e tipos.
 - **[Guia de Conformidade (`CONFORMIDADE.md`)](./CONFORMIDADE.md)**: Detalhes sobre as funcionalidades de conformidade com a LGPD.
 - **[Guia de Integrações (`INTEGRACOES.md`)](./INTEGRACOES.md)**: Como usar as integrações nativas e criar as suas.

package/dist/{PreferencesModal-KAZMVPBD.js → PreferencesModal-D2SEVH3N.js}

@@ -1,6 +1,6 @@
 import {
   PreferencesModal
-} from "./chunk-MHCQFGRJ.js";
+} from "./chunk-B5FNONG3.js";
 export {
   PreferencesModal
 };

package/dist/{chunk-MHCQFGRJ.js → chunk-B5FNONG3.js}

@@ -73,6 +73,17 @@ function analyzeDeveloperConfiguration(config) {
       });
     }
   });
+  const custom = finalConfig.customCategories || [];
+  custom.forEach((cat) => {
+    if (!cat?.id || cat.id === "necessary") return;
+    guidance.activeCategoriesInfo.push({
+      id: cat.id,
+      name: cat.name,
+      description: cat.description,
+      essential: !!cat.essential,
+      uiRequired: !cat.essential
+    });
+  });
   const totalToggleable = guidance.activeCategoriesInfo.filter((c) => c.uiRequired).length;
   if (totalToggleable === 0) {
     guidance.suggestions.push(
@@ -87,9 +98,10 @@ function analyzeDeveloperConfiguration(config) {
   return guidance;
 }
 function logDeveloperGuidance(guidance, disableGuidanceProp) {
-  const nodeEnv = typeof globalThis.process !== "undefined" ? globalThis.process.env?.NODE_ENV : void 0;
-  const isProd = nodeEnv === "production" || globalThis.__LGPD_PRODUCTION__ === true && typeof globalThis !== "undefined";
-  const isDisabled = !!disableGuidanceProp || globalThis.__LGPD_DISABLE_GUIDANCE__ === true && typeof globalThis !== "undefined";
+  const gt = globalThis;
+  const nodeEnv = typeof gt.process !== "undefined" ? gt.process?.env?.NODE_ENV : void 0;
+  const isProd = nodeEnv === "production" || gt.__LGPD_PRODUCTION__ === true;
+  const isDisabled = !!disableGuidanceProp || gt.__LGPD_DISABLE_GUIDANCE__ === true;
   if (isProd || isDisabled) return;
   const PREFIX = "[\u{1F36A} LGPD-CONSENT]";
   if (guidance.warnings.length > 0) {
@@ -217,7 +229,7 @@ var _ConsentLogger = class _ConsentLogger {
   }
   /**
    * Registra uma mensagem de erro.
-   * @param {...any[]} args Os argumentos a serem logados.
+   * @param {...unknown[]} args Argumentos a serem logados.
    */
   error(...args) {
     if (this.enabled && this.level >= 0 /* ERROR */) {
@@ -226,7 +238,7 @@ var _ConsentLogger = class _ConsentLogger {
   }
   /**
    * Registra uma mensagem de aviso.
-   * @param {...any[]} args Os argumentos a serem logados.
+   * @param {...unknown[]} args Argumentos a serem logados.
    */
   warn(...args) {
     if (this.enabled && this.level >= 1 /* WARN */) {
@@ -235,7 +247,7 @@ var _ConsentLogger = class _ConsentLogger {
   }
   /**
    * Registra uma mensagem informativa.
-   * @param {...any[]} args Os argumentos a serem logados.
+   * @param {...unknown[]} args Argumentos a serem logados.
    */
   info(...args) {
     if (this.enabled && this.level >= 2 /* INFO */) {
@@ -244,7 +256,7 @@ var _ConsentLogger = class _ConsentLogger {
   }
   /**
    * Registra uma mensagem de depuração.
-   * @param {...any[]} args Os argumentos a serem logados.
+   * @param {...unknown[]} args Argumentos a serem logados.
    */
   debug(...args) {
     if (this.enabled && this.level >= 3 /* DEBUG */) {
@@ -253,7 +265,7 @@ var _ConsentLogger = class _ConsentLogger {
   }
   /**
    * Inicia um grupo de logs no console.
-   * @param {...any[]} args Os argumentos para o título do grupo.
+   * @param {...unknown[]} args Argumentos para o título do grupo.
    */
   group(...args) {
     if (this.enabled && this.level >= 3 /* DEBUG */) {
@@ -270,8 +282,8 @@ var _ConsentLogger = class _ConsentLogger {
   }
   /**
    * Exibe dados tabulares no console.
-   * @param {any} tabularData Os dados a serem exibidos na tabela.
-   * @param {string[]} [properties] Um array opcional de propriedades para exibir.
+   * @param {unknown} tabularData Dados a serem exibidos na tabela.
+   * @param {string[]} [properties] Propriedades opcionais para exibir.
    */
   table(tabularData, properties) {
     if (this.enabled && this.level >= 3 /* DEBUG */) {
@@ -280,21 +292,27 @@ var _ConsentLogger = class _ConsentLogger {
   }
   /**
    * Registra informações sobre a compatibilidade do tema Material-UI.
-   * @param {any} themeInfo Objeto com informações do tema.
+   * @param {unknown} themeInfo Objeto potencialmente parcial do tema (inspeção segura).
    */
   themeCompatibility(themeInfo) {
+    const isRecord = (v) => typeof v === "object" && v !== null;
+    const theme = isRecord(themeInfo) ? themeInfo : void 0;
+    const palette = theme && isRecord(theme["palette"]) ? theme["palette"] : void 0;
+    const primary = palette && isRecord(palette["primary"]);
+    const transitions = theme && isRecord(theme["transitions"]) ? theme["transitions"] : void 0;
+    const duration = transitions && isRecord(transitions["duration"]);
     this.debug("Theme compatibility check:", {
-      hasTheme: !!themeInfo,
-      hasPalette: !!themeInfo?.palette,
-      hasPrimary: !!themeInfo?.palette?.primary,
-      hasTransitions: !!themeInfo?.transitions,
-      hasDuration: !!themeInfo?.transitions?.duration
+      hasTheme: !!theme,
+      hasPalette: !!palette,
+      hasPrimary: !!primary,
+      hasTransitions: !!transitions,
+      hasDuration: !!duration
     });
   }
   /**
    * Registra mudanças no estado de consentimento.
-   * @param {string} action A ação que causou a mudança de estado.
-   * @param {any} state O estado atual do 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, state) {
     this.debug(`Consent state change [${action}]:`, {
@@ -305,9 +323,9 @@ var _ConsentLogger = class _ConsentLogger {
   }
   /**
    * Registra operações de cookie (leitura, escrita, remoção).
-   * @param {'read' | 'write' | 'delete'} operation O tipo de operação de cookie.
-   * @param {string} cookieName O nome do cookie.
-   * @param {any} [data] Os dados do cookie, se aplicável.
+   * @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, cookieName, data) {
     this.debug(`Cookie ${operation}:`, {
@@ -318,8 +336,8 @@ var _ConsentLogger = class _ConsentLogger {
   }
   /**
    * Registra a renderização de um componente.
-   * @param {string} componentName O nome do componente.
-   * @param {any} [props] As propriedades do componente.
+   * @param {string} componentName Nome do componente.
+   * @param {Record<string, unknown>} [props] Propriedades do componente.
    */
   componentRender(componentName, props) {
     this.debug(`Component render [${componentName}]:`, {
@@ -338,8 +356,8 @@ var _ConsentLogger = class _ConsentLogger {
   }
   /**
    * Registra chamadas à API interna da biblioteca.
-   * @param {string} method O nome do método da API chamado.
-   * @param {any} [params] Os parâmetros passados para o método.
+   * @param {string} method Nome do método da API chamado.
+   * @param {unknown} [params] Parâmetros passados para o método.
    */
   apiUsage(method, params) {
     this.debug(`API call [${method}]:`, params);
@@ -397,8 +415,8 @@ function migrateLegacyCookie(legacyData) {
     const now = (/* @__PURE__ */ new Date()).toISOString();
     return {
       version: COOKIE_SCHEMA_VERSION,
-      consented: legacyData.consented || false,
-      preferences: legacyData.preferences || { necessary: true },
+      consented: Boolean(legacyData.consented) || false,
+      preferences: legacyData.preferences && typeof legacyData.preferences === "object" ? legacyData.preferences : { necessary: true },
       consentDate: now,
       lastUpdate: now,
       source: "banner",
@@ -460,6 +478,12 @@ function createProjectPreferences(config, defaultValue = false) {
       preferences[category] = defaultValue;
     }
   });
+  const custom = config?.customCategories || [];
+  custom.forEach((cat) => {
+    if (cat.id && cat.id !== "necessary") {
+      preferences[cat.id] = defaultValue;
+    }
+  });
   return preferences;
 }
 function validateProjectPreferences(preferences, config) {
@@ -473,6 +497,13 @@ function validateProjectPreferences(preferences, config) {
       validPreferences[category] = preferences[category];
     }
   });
+  const custom = config?.customCategories || [];
+  custom.forEach((cat) => {
+    const id = cat.id;
+    if (id && id !== "necessary" && preferences[id] !== void 0) {
+      validPreferences[id] = preferences[id];
+    }
+  });
   return validPreferences;
 }
 function getAllProjectCategories(config) {
@@ -490,6 +521,12 @@ function getAllProjectCategories(config) {
       allCategories.push(getDefaultCategoryDefinition(category));
     }
   });
+  const custom = config?.customCategories || [];
+  custom.forEach((cat) => {
+    if (cat.id && cat.id !== "necessary") {
+      allCategories.push({ ...cat, essential: !!cat.essential });
+    }
+  });
   return allCategories;
 }
 function getDefaultCategoryDefinition(category) {
@@ -848,7 +885,7 @@ function FloatingPreferencesButton({
 // src/context/ConsentContext.tsx
 import { jsx as jsx6, jsxs as jsxs3 } from "react/jsx-runtime";
 var PreferencesModal = React4.lazy(
-  () => import("./PreferencesModal-KAZMVPBD.js").then((m) => ({
+  () => import("./PreferencesModal-D2SEVH3N.js").then((m) => ({
     default: m.PreferencesModal
   }))
 );
@@ -1142,12 +1179,17 @@ function ConsentProvider({
           }
         ) : (
           // Encaminha `floatingPreferencesButtonProps` para o componente padrão
-          /* @__PURE__ */ jsx6(FloatingPreferencesButton, { ...floatingPreferencesButtonProps })
+          /* @__PURE__ */ jsx6(
+            FloatingPreferencesButton,
+            {
+              ...floatingPreferencesButtonProps ?? {}
+            }
+          )
         ))
       ]
     }
   ) }) }) }) }) });
-  if (theme) {
+  if (mergedTheme) {
     return /* @__PURE__ */ jsx6(ThemeProvider, { theme: mergedTheme, children: content });
   }
   return content;