react-lgpd-consent 0.3.6 → 0.4.0

package/dist/index.cjs

@@ -86,6 +86,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(
@@ -100,9 +111,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) {
@@ -250,7 +262,7 @@ var init_logger = __esm({
       }
       /**
        * 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 */) {
@@ -259,7 +271,7 @@ var init_logger = __esm({
       }
       /**
        * 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 */) {
@@ -268,7 +280,7 @@ var init_logger = __esm({
       }
       /**
        * 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 */) {
@@ -277,7 +289,7 @@ var init_logger = __esm({
       }
       /**
        * 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 */) {
@@ -286,7 +298,7 @@ var init_logger = __esm({
       }
       /**
        * 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 */) {
@@ -303,8 +315,8 @@ var init_logger = __esm({
       }
       /**
        * 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 */) {
@@ -313,21 +325,27 @@ var init_logger = __esm({
       }
       /**
        * 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}]:`, {
@@ -338,9 +356,9 @@ var init_logger = __esm({
       }
       /**
        * 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}:`, {
@@ -351,8 +369,8 @@ var init_logger = __esm({
       }
       /**
        * 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}]:`, {
@@ -371,8 +389,8 @@ var init_logger = __esm({
       }
       /**
        * 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);
@@ -419,8 +437,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",
@@ -498,6 +516,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) {
@@ -511,6 +535,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) {
@@ -528,6 +559,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) {
@@ -1169,12 +1206,17 @@ function ConsentProvider({
           }
         ) : (
           // Encaminha `floatingPreferencesButtonProps` para o componente padrão
-          /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(FloatingPreferencesButton, { ...floatingPreferencesButtonProps })
+          /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(
+            FloatingPreferencesButton,
+            {
+              ...floatingPreferencesButtonProps ?? {}
+            }
+          )
         ))
       ]
     }
   ) }) }) }) }) });
-  if (theme) {
+  if (mergedTheme) {
     return /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(import_styles2.ThemeProvider, { theme: mergedTheme, children: content });
   }
   return content;
@@ -1592,13 +1634,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();
           }
@@ -1627,13 +1663,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();
         }
@@ -1655,14 +1685,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" }
@@ -1676,8 +1706,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"
         });
@@ -1692,8 +1724,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/dist/index.d.cts

@@ -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'] }