react-lgpd-consent 0.3.6 → 0.4.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { DialogProps } from '@mui/material/Dialog';
-import * as React$1 from 'react';
 import { Theme } from '@mui/material/styles';
+import * as React$1 from 'react';
 import { PaperProps } from '@mui/material/Paper';
 import { SnackbarProps } from '@mui/material/Snackbar';
 import { FabProps } from '@mui/material/Fab';
@@ -81,6 +81,7 @@ type Category = 'necessary' | 'analytics' | 'functional' | 'marketing' | 'social
  *
  * @example
  * ```typescript
+ * // Categoria padrão da biblioteca
  * const analyticsCategory: CategoryDefinition = {
  *   id: 'analytics',
  *   name: 'Cookies Analíticos',
@@ -88,6 +89,14 @@ type Category = 'necessary' | 'analytics' | 'functional' | 'marketing' | 'social
  *   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
@@ -144,11 +153,18 @@ interface CategoryDefinition {
  * // Configuração com categorias customizadas
  * const config: ProjectCategoriesConfig = {
  *   enabledCategories: ['analytics'],
- *   customCategories: [{
- *     id: 'support',
- *     name: 'Suporte',
- *     description: 'Cookies para sistema de suporte ao cliente'
- *   }]
+ *   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'
+ *     }
+ *   ]
  * };
  * ```
  *
@@ -164,6 +180,7 @@ interface ProjectCategoriesConfig {
     /**
      * 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[];
 }
@@ -653,18 +670,23 @@ interface ConsentProviderProps {
      */
     texts?: Partial<ConsentTexts>;
     /**
-     * Tema customizado Material-UI aplicado aos componentes.
-     * Aceita qualquer objeto que será passado para ThemeProvider.
+     * Tema Material-UI a ser aplicado aos componentes via ThemeProvider.
+     *
+     * Observação importante: a biblioteca NÃO cria/mescla tema automaticamente.
+     * Se você fornecer um `theme` aqui, ele será repassado diretamente ao `ThemeProvider`.
+     * Se não fornecer, a lib não envolverá com `ThemeProvider` e herdará o tema do app.
      *
      * @example
      * ```tsx
-     * theme={{
-     *   palette: { primary: { main: '#1976d2' } },
-     *   components: { MuiButton: { styleOverrides: { root: { borderRadius: 8 } } } }
-     * }}
+     * import { createTheme } from '@mui/material/styles'
+     * const appTheme = createTheme({ palette: { primary: { main: '#1976d2' } } })
+     *
+     * <ConsentProvider theme={appTheme}>
+     *   <App />
+     * </ConsentProvider>
      * ```
      */
-    theme?: any;
+    theme?: Theme;
     /**
      * Tokens de design para customização visual avançada.
      * Oferece controle direto sobre cores, fontes, espaçamento e layout.
@@ -684,24 +706,24 @@ interface ConsentProviderProps {
      * Deve implementar a lógica de consentimento usando as props definidas em `CustomPreferencesModalProps`.
      */
     PreferencesModalComponent?: React.ComponentType<CustomPreferencesModalProps>;
-    /** Props adicionais passadas para o modal customizado. */
-    preferencesModalProps?: Record<string, any>;
+    /** 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. */
-    cookieBannerProps?: Record<string, any>;
+    /** 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. */
-    floatingPreferencesButtonProps?: Record<string, any>;
+    /** 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.
@@ -1521,6 +1543,8 @@ declare const DEFAULT_PROJECT_CATEGORIES: ProjectCategoriesConfig;
  *
  * @param {ProjectCategoriesConfig} [config] A configuração de categorias fornecida pelo desenvolvedor. Se não for fornecida, a configuração padrão será utilizada.
  * @returns {DeveloperGuidance} Um objeto `DeveloperGuidance` com a análise da configuração.
+ *
+ * Since v0.4.0: inclui `customCategories` em `activeCategoriesInfo` (com `uiRequired=false` se `essential=true`).
  */
 declare function analyzeDeveloperConfiguration(config?: ProjectCategoriesConfig): DeveloperGuidance;
 
@@ -1600,7 +1624,7 @@ declare function ConsentGate(props: Readonly<{
  *
  * @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 {'analytics' | 'marketing' | null} [category=null] A categoria de consentimento exigida para o script. Se o consentimento para esta categoria não for dado, o script não será carregado.
+ * @param {import('../types/types').Category | null} [category=null] A categoria de consentimento exigida para o script. 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
@@ -1611,7 +1635,8 @@ declare function ConsentGate(props: Readonly<{
  *   .catch(error => console.error('Erro ao carregar script:', error))
  * ```
  */
-declare function loadScript(id: string, src: string, category?: 'analytics' | 'marketing' | null, attrs?: Record<string, string>): Promise<void>;
+
+declare function loadScript(id: string, src: string, category?: Category | null, attrs?: Record<string, string>): Promise<void>;
 
 /**
  * @constant
@@ -1637,13 +1662,19 @@ declare const defaultConsentTheme: () => Theme;
 
 /**
  * @interface ScriptIntegration
- * Define a estrutura de um objeto de integração de script, usado para carregar scripts de terceiros condicionalmente.
+ * Estrutura de uma integração de script de terceiros a ser carregada condicionalmente conforme o consentimento.
+ *
+ * @remarks
+ * - `category` é um `Category` tipado (ex.: 'analytics', 'marketing').
+ * - `init` roda após o script ser inserido no DOM e carregado.
+ * - `attrs` é repassado como atributos HTML da tag `<script>`.
  */
+
 interface ScriptIntegration {
     /** Um ID único para esta integração de script. */
     id: string;
-    /** A categoria de consentimento necessária para que este script seja carregado (ex: 'analytics', 'marketing'). */
-    category: string;
+    /** Categoria de consentimento necessária para carregar o script. */
+    category: Category;
     /** A URL do script a ser carregado. */
     src: string;
     /** Uma função opcional a ser executada após o script ser carregado e inicializado no DOM. */
@@ -1658,8 +1689,8 @@ interface ScriptIntegration {
 interface GoogleAnalyticsConfig {
     /** O ID de medição do GA4 (ex: 'G-XXXXXXXXXX'). */
     measurementId: string;
-    /** Um objeto opcional de configuração adicional a ser passado para o comando `gtag('config')`. */
-    config?: any;
+    /** Objeto opcional repassado para `gtag('config')`. */
+    config?: Record<string, unknown>;
 }
 /**
  * @interface GoogleTagManagerConfig
@@ -1683,30 +1714,30 @@ interface UserWayConfig {
  * @function
  * @category Utils
  * @since 0.2.0
- * Cria um objeto de integração para o Google Analytics 4 (GA4).
+ * Cria uma integração para Google Analytics 4 (GA4).
  *
- * @param {GoogleAnalyticsConfig} config A configuração do GA4, incluindo o `measurementId`.
- * @returns {ScriptIntegration} Um objeto `ScriptIntegration` configurado para o GA4.
+ * @param {GoogleAnalyticsConfig} config Configuração com `measurementId` e `config` opcional.
+ * @returns {ScriptIntegration} Integração tipada com `category: 'analytics'`.
  */
 declare function createGoogleAnalyticsIntegration(config: GoogleAnalyticsConfig): ScriptIntegration;
 /**
  * @function
  * @category Utils
  * @since 0.2.0
- * Cria um objeto de integração para o Google Tag Manager (GTM).
+ * Cria uma integração para Google Tag Manager (GTM).
  *
- * @param {GoogleTagManagerConfig} config A configuração do GTM, incluindo o `containerId`.
- * @returns {ScriptIntegration} Um objeto `ScriptIntegration` configurado para o GTM.
+ * @param {GoogleTagManagerConfig} config Configuração com `containerId` e `dataLayerName` opcional.
+ * @returns {ScriptIntegration} Integração tipada com `category: 'analytics'`.
  */
 declare function createGoogleTagManagerIntegration(config: GoogleTagManagerConfig): ScriptIntegration;
 /**
  * @function
  * @category Utils
  * @since 0.2.0
- * Cria um objeto de integração para o widget de acessibilidade UserWay.
+ * Cria uma integração para o widget de acessibilidade UserWay.
  *
- * @param {UserWayConfig} config A configuração do UserWay, incluindo o `accountId`.
- * @returns {ScriptIntegration} Um objeto `ScriptIntegration` configurado para o UserWay.
+ * @param {UserWayConfig} config Configuração com `accountId`.
+ * @returns {ScriptIntegration} Integração tipada com `category: 'functional'`.
  */
 declare function createUserWayIntegration(config: UserWayConfig): ScriptIntegration;
 /**
@@ -2101,8 +2132,10 @@ declare function FloatingPreferencesButton({ position, offset, icon, tooltip, Fa
  * @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, alinhando-se ao princípio
- * de minimização de dados da LGPD.
+ * 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
@@ -2111,6 +2144,15 @@ declare function FloatingPreferencesButton({ position, offset, icon, tooltip, Fa
  * })
  * // 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'] },
@@ -2131,6 +2173,8 @@ declare function createProjectPreferences(config?: ProjectCategoriesConfig, defa
  * 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 }
@@ -2149,7 +2193,10 @@ declare function validateProjectPreferences(preferences: ConsentPreferences, con
  * @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.
+ * 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'] }

package/dist/index.js

@@ -19,7 +19,7 @@ import {
   useConsentTexts,
   useOpenPreferencesModal,
   validateProjectPreferences
-} from "./chunk-MHCQFGRJ.js";
+} from "./chunk-B5FNONG3.js";
 
 // src/utils/ConsentGate.tsx
 import { Fragment, jsx } from "react/jsx-runtime";
@@ -152,13 +152,7 @@ function ConsentScriptLoader({
       const alreadyLoaded = loadedScripts.current.has(integration.id);
       if (shouldLoad && (!alreadyLoaded || reloadOnChange)) {
         try {
-          await loadScript(
-            integration.id,
-            integration.src,
-            integration.category,
-            // Categoria dinâmica
-            integration.attrs
-          );
+          await loadScript(integration.id, integration.src, integration.category, integration.attrs);
           if (integration.init) {
             integration.init();
           }
@@ -187,13 +181,7 @@ function useConsentScriptLoader() {
         return false;
       }
       try {
-        await loadScript(
-          integration.id,
-          integration.src,
-          integration.category,
-          // Categoria dinâmica
-          integration.attrs
-        );
+        await loadScript(integration.id, integration.src, integration.category, integration.attrs);
         if (integration.init) {
           integration.init();
         }
@@ -215,14 +203,14 @@ function createGoogleAnalyticsIntegration(config) {
     src: `https://www.googletagmanager.com/gtag/js?id=${config.measurementId}`,
     init: () => {
       if (typeof window !== "undefined") {
-        let gtag2 = function(...args) {
-          window.dataLayer.push(...args);
+        const w = window;
+        w.dataLayer = w.dataLayer ?? [];
+        const gtag = (...args) => {
+          w.dataLayer.push(...args);
         };
-        var gtag = gtag2;
-        window.dataLayer = window.dataLayer || [];
-        window.gtag = gtag2;
-        gtag2("js", /* @__PURE__ */ new Date());
-        gtag2("config", config.measurementId, config.config || {});
+        w.gtag = gtag;
+        gtag("js", /* @__PURE__ */ new Date());
+        gtag("config", config.measurementId, config.config ?? {});
       }
     },
     attrs: { async: "true" }
@@ -236,8 +224,10 @@ function createGoogleTagManagerIntegration(config) {
     init: () => {
       if (typeof window !== "undefined") {
         const dataLayerName = config.dataLayerName || "dataLayer";
-        window[dataLayerName] = window[dataLayerName] || [];
-        window[dataLayerName].push({
+        const w = window;
+        const layer = w[dataLayerName] ?? [];
+        w[dataLayerName] = layer;
+        layer.push({
           "gtm.start": (/* @__PURE__ */ new Date()).getTime(),
           event: "gtm.js"
         });
@@ -252,8 +242,9 @@ function createUserWayIntegration(config) {
     src: "https://cdn.userway.org/widget.js",
     init: () => {
       if (typeof window !== "undefined") {
-        window.UserWayWidgetApp = window.UserWayWidgetApp || {};
-        window.UserWayWidgetApp.accountId = config.accountId;
+        const w = window;
+        w.UserWayWidgetApp = w.UserWayWidgetApp || {};
+        w.UserWayWidgetApp.accountId = config.accountId;
       }
     },
     attrs: { "data-account": config.accountId }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-lgpd-consent",
-  "version": "0.3.6",
+  "version": "0.4.0",
   "description": "Biblioteca de consentimento LGPD, integrações nativas e sistema extensível para React.",
   "keywords": [
     "lgpd",
@@ -54,14 +54,15 @@
     "CHANGELOG.md"
   ],
   "engines": {
-    "node": ">=18.18"
+    "node": ">=20.0.0"
   },
-  "packageManager": "npm@10.9.3",
+  "packageManager": "npm@11.6.0",
   "scripts": {
     "clean": "rimraf node_modules package-lock.json dist docs storybook-static .cache .stryker-tmp",
     "build": "cross-env NODE_ENV=production tsup src/index.ts --format esm,cjs --dts --clean",
     "dev": "cross-env NODE_ENV=development tsup src/index.ts --format esm,cjs --dts --watch",
-    "lint": "eslint . --ext .ts,.tsx",
+    "lint": "eslint \"**/*.{ts,tsx}\" --cache",
+    "lint:ci": "eslint \"**/*.{ts,tsx}\" --cache --max-warnings=0",
     "format": "prettier --write \"src/**/*.{ts,tsx,json,md}\" \"eslint.config.js\"",
     "type-check": "tsc --noEmit",
     "test": "jest --config jest.config.ts",
@@ -95,47 +96,48 @@
     "js-cookie": "^3.0.5"
   },
   "devDependencies": {
-    "@chromatic-com/storybook": "^4.1.1",
-    "@emotion/react": "^11.14.0",
-    "@emotion/styled": "^11.14.1",
-    "@eslint/compat": "^1.3.2",
-    "@mui/icons-material": "^7.3.1",
-    "@mui/material": "^7.3.1",
-    "@storybook/addon-a11y": "^9.1.3",
-    "@storybook/addon-docs": "^9.1.3",
-    "@storybook/addon-vitest": "^9.1.3",
-    "@storybook/react-vite": "^9.1.3",
-    "@stryker-mutator/core": "^9.0.1",
-    "@stryker-mutator/jest-runner": "^9.0.1",
-    "@testing-library/dom": "^10.4.1",
-    "@testing-library/jest-dom": "^6.8.0",
-    "@testing-library/react": "^16.3.0",
-    "@testing-library/user-event": "^14.6.1",
-    "@types/jest": "^30.0.0",
-    "@types/js-cookie": "^3.0.6",
-    "@types/node": "^24.3.0",
-    "@types/react": "^19.1.12",
-    "@types/react-dom": "^19.1.9",
-    "@typescript-eslint/eslint-plugin": "^8.41.0",
-    "@typescript-eslint/parser": "^8.41.0",
-    "cross-env": "^10.0.0",
-    "eslint": "^9.34.0",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-jest": "^29.0.1",
-    "eslint-plugin-react-hooks": "^5.2.0",
-    "eslint-plugin-storybook": "^9.1.3",
-    "jest": "^30.1.1",
-    "jest-environment-jsdom": "^30.1.1",
-    "prettier": "^3.6.2",
-    "react": "^19.1.1",
-    "react-dom": "^19.1.1",
-    "rimraf": "^6.0.1",
-    "storybook": "^9.1.3",
-    "ts-jest": "^29.4.1",
-    "ts-node": "^10.9.2",
-    "tsup": "^8.5.0",
-    "typedoc": "^0.28.11",
-    "typescript": "^5.9.2",
-    "typescript-eslint": "^8.41.0"
+    "@chromatic-com/storybook": "4.1.1",
+    "@emotion/react": "11.14.0",
+    "@emotion/styled": "11.14.1",
+    "@eslint/compat": "1.3.2",
+    "@mui/icons-material": "7.3.2",
+    "@mui/material": "7.3.2",
+    "@storybook/addon-a11y": "9.1.7",
+    "@storybook/addon-docs": "9.1.7",
+    "@storybook/addon-vitest": "9.1.7",
+    "@storybook/react-vite": "9.1.7",
+    "@stryker-mutator/core": "9.1.1",
+    "@stryker-mutator/jest-runner": "9.1.1",
+    "@testing-library/dom": "10.4.1",
+    "@testing-library/jest-dom": "6.8.0",
+    "@testing-library/react": "16.3.0",
+    "@testing-library/user-event": "14.6.1",
+    "@types/jest": "30.0.0",
+    "@types/js-cookie": "3.0.6",
+    "@types/node": "24.5.2",
+    "@types/react": "19.1.13",
+    "@types/react-dom": "19.1.9",
+    "@typescript-eslint/eslint-plugin": "8.44.0",
+    "@typescript-eslint/parser": "8.44.0",
+    "cross-env": "10.0.0",
+    "eslint": "9.36.0",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-plugin-jest": "29.0.1",
+    "eslint-plugin-react-hooks": "5.2.0",
+    "eslint-plugin-storybook": "9.1.7",
+    "globals": "^16.4.0",
+    "jest": "30.1.3",
+    "jest-environment-jsdom": "30.1.2",
+    "prettier": "3.6.2",
+    "react": "19.1.1",
+    "react-dom": "19.1.1",
+    "rimraf": "6.0.1",
+    "storybook": "9.1.7",
+    "ts-jest": "29.4.4",
+    "ts-node": "10.9.2",
+    "tsup": "8.5.0",
+    "typedoc": "0.28.13",
+    "typescript": "5.9.2",
+    "typescript-eslint": "8.44.0"
   }
 }