react-lgpd-consent 0.3.7 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,19 @@ 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

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-3KKTKVII.js → PreferencesModal-D2SEVH3N.js}

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

package/dist/{chunk-TKN3PNIW.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(
@@ -467,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) {
@@ -480,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) {
@@ -497,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) {
@@ -855,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-3KKTKVII.js").then((m) => ({
+  () => import("./PreferencesModal-D2SEVH3N.js").then((m) => ({
     default: m.PreferencesModal
   }))
 );

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(
@@ -505,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) {
@@ -518,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) {
@@ -535,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) {

package/dist/index.d.cts

@@ -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[];
 }
@@ -1526,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;
 
@@ -2113,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
@@ -2123,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'] },
@@ -2143,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 }
@@ -2161,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.d.ts

@@ -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[];
 }
@@ -1526,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;
 
@@ -2113,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
@@ -2123,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'] },
@@ -2143,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 }
@@ -2161,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-TKN3PNIW.js";
+} from "./chunk-B5FNONG3.js";
 
 // src/utils/ConsentGate.tsx
 import { Fragment, jsx } from "react/jsx-runtime";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-lgpd-consent",
-  "version": "0.3.7",
+  "version": "0.4.0",
   "description": "Biblioteca de consentimento LGPD, integrações nativas e sistema extensível para React.",
   "keywords": [
     "lgpd",
@@ -102,42 +102,42 @@
     "@eslint/compat": "1.3.2",
     "@mui/icons-material": "7.3.2",
     "@mui/material": "7.3.2",
-    "@storybook/addon-a11y": "9.1.5",
-    "@storybook/addon-docs": "9.1.5",
-    "@storybook/addon-vitest": "9.1.5",
-    "@storybook/react-vite": "9.1.5",
+    "@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": "29.5.12",
+    "@types/jest": "30.0.0",
     "@types/js-cookie": "3.0.6",
-    "@types/node": "24.3.1",
-    "@types/react": "19.1.12",
+    "@types/node": "24.5.2",
+    "@types/react": "19.1.13",
     "@types/react-dom": "19.1.9",
-    "@typescript-eslint/eslint-plugin": "8.43.0",
-    "@typescript-eslint/parser": "8.43.0",
+    "@typescript-eslint/eslint-plugin": "8.44.0",
+    "@typescript-eslint/parser": "8.44.0",
     "cross-env": "10.0.0",
-    "eslint": "8.57.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.5",
-    "globals": "^15.15.0",
-    "jest": "29.7.0",
-    "jest-environment-jsdom": "29.7.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.5",
-    "ts-jest": "29.4.1",
+    "storybook": "9.1.7",
+    "ts-jest": "29.4.4",
     "ts-node": "10.9.2",
     "tsup": "8.5.0",
-    "typedoc": "0.28.12",
+    "typedoc": "0.28.13",
     "typescript": "5.9.2",
-    "typescript-eslint": "8.43.0"
+    "typescript-eslint": "8.44.0"
   }
 }