@react-lgpd-consent/core 0.7.2 → 0.8.0

package/CHANGELOG.md

@@ -1,36 +1,52 @@
 # Changelog - @react-lgpd-consent/core
 
-## 0.7.2
+## 0.8.0
 
-### 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
+### Minor Changes
 
-  ### 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.
+- [#142](https://github.com/lucianoedipo/react-lgpd-consent/pull/142) [`29b4464`](https://github.com/lucianoedipo/react-lgpd-consent/commit/29b4464bd0ea878a21573a0752aca3adc31743d9) Thanks [@lucianoedipo](https://github.com/lucianoedipo)! - ### Correcoes
+  - 1d15920 fix: corrigir formatacao da verificacao de multiplas versoes do React
 
   ### 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.
+  - ed5fa36 refactor: aprimorar documentacao e estrutura de validacao do ConsentProvider
+  - 709e977 refactor: melhorar validacao e sanitizacao das categorias no ConsentProvider
+  - 6ee4d03 feat: recalcular categorias no CategoriesContext ao adicionar novas entradas
+  - 6ee4d03 refactor: melhorar descoberta e validacao de cookies
+  - 6ee4d03 refactor: refinar helpers de integracao para maior clareza
+  - 6ee4d03 refactor: simplificar logica de sincronizacao de versoes no script sync-versions.mjs
+  - ef2968a refactor: trocar acessos diretos a window/document por globalThis em loaders, utils e testes
+  - 3af2fcb fix: ajustar path resolution no tsconfig para melhor import de modulos
+
+  ### Funcionalidades
+  - 6ee4d03 feat: aprimorar acessibilidade e gerenciamento de consentimento
+  - 6ee4d03 feat: estender matchers Jest com jest-axe para acessibilidade
+  - 6ee4d03 feat: revisar textos de consentimento para mais clareza
+  - 6ee4d03 feat: introduzir modos de bloqueio no ConsentProvider
+  - 6ee4d03 feat: adicionar testes para hard blocking no ConsentProvider
+  - d641639 feat: adicionar gerenciamento de eventos para categorias obrigatorias no CategoriesProvider
 
   ### 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.
+  - b04c00b feat: adicionar testes para CookieBanner, FloatingPreferencesButton e PreferencesModal
+  - b04c00b testes: validar renderizacao do CookieBanner por consentimento e modo debug
+  - b04c00b testes: verificar textos localizados no FloatingPreferencesButton via props
+  - b04c00b testes: cobrir reset temporario, scripts ativos e textos customizados no PreferencesModal
+  - testes: cobrir fluxo SSR de leitura/remoção/escrita de cookie consent
+
+  ### Ferramentas
+  - b04c00b feat: script interativo de changeset para versionamento em monorepos
+  - b04c00b refactor: coverage-check usando node imports
+  - b04c00b refactor: ajustar script do TypeDoc para compatibilidade ESM
+
+  ### Documentacao
+  - 6ee4d03 docs: atualizar README e exemplos com novos recursos
+  - d430eef docs: atualizar instrucoes para agentes com comandos essenciais
+  - d430eef docs: refletir uso de globalThis na documentacao
+  - d430eef docs: atualizar API com novas integracoes e configuracoes de testes ESM/CJS
+  - docs: quickstart com comentarios e nota sobre injecao automatica de UI MUI
+
+  ### A11y
+  - a11y: PreferencesModal com aria-describedby
+  - a11y: testes de teclado (Escape + retorno de foco)
 
 ## 0.7.1
 

package/README.md

@@ -100,13 +100,13 @@ import { ConsentProvider } from '@react-lgpd-consent/core'
 ### Presets ANPD
 
 ```tsx
-import { createAnpdCategories, ANPD_CATEGORY_PRESETS } from '@react-lgpd-consent/core'
+import { createAnpdCategoriesConfig, ANPD_CATEGORY_PRESETS } from '@react-lgpd-consent/core'
 
 // Preset BÁSICO
-const basic = createAnpdCategories({ include: ['analytics'] })
+const basic = createAnpdCategoriesConfig({ include: ['analytics'] })
 
 // Preset COMPLETO
-const full = createAnpdCategories({
+const full = createAnpdCategoriesConfig({
   include: ['analytics', 'marketing', 'functional', 'social', 'personalization']
 })
 ```

package/dist/index.cjs

@@ -64,27 +64,27 @@ var EXPANDED_DEFAULT_TEXTS = {
   categories: {
     necessary: {
       name: "Cookies Necess\xE1rios",
-      description: "Essenciais para o funcionamento b\xE1sico do site",
+      description: "Essenciais para o funcionamento b\xE1sico do site e n\xE3o podem ser desativados",
       examples: "Sess\xE3o, seguran\xE7a, prefer\xEAncias de idioma"
     },
     analytics: {
       name: "Cookies de Analytics",
-      description: "Ajudam a entender como os visitantes usam o site",
+      description: "Opcionais. Ajudam a entender como os visitantes usam o site",
       examples: "Google Analytics, contadores de p\xE1gina"
     },
     marketing: {
       name: "Cookies de Marketing",
-      description: "Usados para personalizar an\xFAncios e ofertas",
+      description: "Opcionais. Usados para personalizar an\xFAncios e ofertas",
       examples: "Facebook Pixel, Google Ads, remarketing"
     },
     functional: {
       name: "Cookies Funcionais",
-      description: "Melhoram a funcionalidade e personaliza\xE7\xE3o",
+      description: "Opcionais. Melhoram a funcionalidade e personaliza\xE7\xE3o",
       examples: "Chat, mapas, v\xEDdeos embarcados"
     },
     performance: {
       name: "Cookies de Performance",
-      description: "Coletam informa\xE7\xF5es sobre velocidade e estabilidade",
+      description: "Opcionais. Coletam informa\xE7\xF5es sobre velocidade e estabilidade",
       examples: "Monitoramento de erro, otimiza\xE7\xE3o de velocidade"
     }
   },
@@ -557,7 +557,6 @@ function buildConsentStorageKey(options) {
 var DEFAULT_COOKIE_OPTS = {
   name: "cookieConsent",
   maxAge: DEFAULT_MAX_AGE_SECONDS,
-  maxAgeDays: 365,
   sameSite: "Lax",
   secure: false,
   path: "/",
@@ -566,18 +565,23 @@ var DEFAULT_COOKIE_OPTS = {
 function resolveCookieOptions(opts) {
   const currentWindow = globalThis.window;
   const currentLocation = globalThis.location;
-  const protocols = [currentWindow?.location?.protocol, currentLocation?.protocol].filter(
-    Boolean
-  );
+  const protocols = [currentWindow?.location?.protocol, currentLocation?.protocol].filter(Boolean);
   const forceHttps = globalThis.__LGPD_FORCE_HTTPS__ === true;
   const isHttps = forceHttps || protocols.includes("https:");
-  const maxAgeSecondsFromDays = typeof opts?.maxAgeDays === "number" ? Math.max(0, opts.maxAgeDays * 24 * 60 * 60) : null;
-  const maxAgeSeconds = typeof opts?.maxAge === "number" ? Math.max(0, opts.maxAge) : maxAgeSecondsFromDays ?? DEFAULT_MAX_AGE_SECONDS;
+  const maxAgeSeconds = typeof opts?.maxAge === "number" ? Math.max(0, opts.maxAge) : typeof opts?.maxAgeDays === "number" ? Math.max(0, opts.maxAgeDays) * 24 * 60 * 60 : DEFAULT_MAX_AGE_SECONDS;
+  let secure;
+  if (typeof opts?.secure === "boolean") {
+    secure = opts.secure;
+  } else if (isHttps) {
+    secure = true;
+  } else {
+    secure = DEFAULT_COOKIE_OPTS.secure;
+  }
   return {
     name: opts?.name ?? DEFAULT_COOKIE_OPTS.name,
     maxAge: maxAgeSeconds,
     sameSite: opts?.sameSite ?? DEFAULT_COOKIE_OPTS.sameSite ?? "Lax",
-    secure: typeof opts?.secure === "boolean" ? opts.secure : isHttps ? true : DEFAULT_COOKIE_OPTS.secure,
+    secure,
     path: opts?.path ?? DEFAULT_COOKIE_OPTS.path ?? "/",
     domain: opts?.domain ?? DEFAULT_COOKIE_OPTS.domain ?? void 0
   };
@@ -696,7 +700,7 @@ function removeConsentCookie(opts) {
 }
 
 // src/utils/dataLayerEvents.ts
-var LIBRARY_VERSION = "0.7.2";
+var LIBRARY_VERSION = "0.8.0";
 function ensureDataLayer() {
   const currentWindow = globalThis.window;
   if (!currentWindow) return;
@@ -1732,14 +1736,88 @@ function runPeerDepsCheck() {
 
 // src/utils/validation.ts
 var isDev = () => typeof process !== "undefined" && process.env.NODE_ENV !== "production";
+var sanitizeCategories = (categories) => {
+  const enabled = [...new Set(categories.enabledCategories ?? [])];
+  const sanitizedEnabled = enabled.filter((c) => c !== "necessary");
+  return {
+    enabled,
+    sanitizedEnabled,
+    custom: categories.customCategories ?? []
+  };
+};
+var collectZodIssues = (z, categories, issues) => {
+  if (!z || !categories) return;
+  const CustomCategorySchema = z.object({
+    id: z.string().min(1, "customCategories[].id deve ser uma string n\xE3o vazia"),
+    name: z.string().min(1, "customCategories[].name deve ser uma string n\xE3o vazia"),
+    description: z.string().min(1, "customCategories[].description deve ser uma string n\xE3o vazia"),
+    essential: z.boolean().optional(),
+    cookies: z.array(z.string().min(1)).optional()
+  });
+  const ProjectCategoriesConfigSchema = z.object({
+    enabledCategories: z.array(z.string().min(1)).optional(),
+    customCategories: z.array(CustomCategorySchema).optional()
+  }).strict();
+  const res = ProjectCategoriesConfigSchema.safeParse(categories);
+  if (!res.success) {
+    res.error.issues.forEach(
+      (issue) => issues.push({ path: `categories.${issue.path.join(".")}`, message: issue.message })
+    );
+  }
+  const customParse = z.array(CustomCategorySchema).safeParse(categories.customCategories ?? []);
+  if (!customParse.success) {
+    customParse.error.issues.forEach(
+      (issue) => issues.push({ path: `customCategories.${issue.path.join(".")}`, message: issue.message })
+    );
+  }
+};
+var collectCategoryWarnings = (input) => {
+  const warnings = [];
+  const { enabled, sanitizedEnabled, custom } = input;
+  if (enabled.includes("necessary")) {
+    warnings.push("'necessary' \xE9 sempre inclu\xEDda automaticamente \u2014 remova de enabledCategories.");
+  }
+  const invalidEnabled = sanitizedEnabled.filter((c) => typeof c !== "string" || c.trim() === "");
+  if (invalidEnabled.length > 0) {
+    warnings.push(
+      `enabledCategories cont\xE9m valores inv\xE1lidos: ${invalidEnabled.map(String).join(", ")} \u2014 remova ou corrija os IDs de categoria`
+    );
+  }
+  const ids = /* @__PURE__ */ new Set();
+  const dupes = [];
+  ["necessary", ...sanitizedEnabled].forEach((id) => {
+    if (ids.has(id)) dupes.push(id);
+    ids.add(id);
+  });
+  custom?.forEach((c) => {
+    if (ids.has(c.id)) dupes.push(c.id);
+    ids.add(c.id);
+  });
+  if (dupes.length > 0) {
+    warnings.push(
+      `IDs de categoria duplicados detectados: ${Array.from(new Set(dupes)).join(
+        ", "
+      )} \u2014 verifique 'enabledCategories' e 'customCategories'.`
+    );
+  }
+  return warnings;
+};
+var reportValidationMessages = (warnings, errors, issues) => {
+  if (warnings.length > 0) {
+    logger.warn("Valida\xE7\xE3o do ConsentProvider:", ...warnings);
+  }
+  if (errors.length > 0 || issues.length > 0) {
+    issues.forEach((i) => errors.push(`Prop inv\xE1lida: ${i.path} \u2014 ${i.message}`));
+    logger.error("Erros de configura\xE7\xE3o do ConsentProvider:", ...errors);
+  }
+};
 function validateConsentProviderProps(props) {
   const warnings = [];
   const errors = [];
   const sanitized = {};
   if (!isDev()) {
     if (props.categories) {
-      const enabled = [...new Set(props.categories.enabledCategories ?? [])];
-      const sanitizedEnabled = enabled.filter((c) => c !== "necessary");
+      const { sanitizedEnabled } = sanitizeCategories(props.categories);
       sanitized.categories = {
         enabledCategories: sanitizedEnabled,
         customCategories: props.categories.customCategories
@@ -1754,94 +1832,27 @@ function validateConsentProviderProps(props) {
     z = void 0;
   }
   const issues = [];
-  if (z) {
-    const CustomCategorySchema = z.object({
-      id: z.string().min(1, "customCategories[].id deve ser uma string n\xE3o vazia"),
-      name: z.string().min(1, "customCategories[].name deve ser uma string n\xE3o vazia"),
-      description: z.string().min(1, "customCategories[].description deve ser uma string n\xE3o vazia"),
-      essential: z.boolean().optional(),
-      cookies: z.array(z.string().min(1)).optional()
-    });
-    const ProjectCategoriesConfigSchema = z.object({
-      enabledCategories: z.array(z.string().min(1)).optional(),
-      customCategories: z.array(CustomCategorySchema).optional()
-    }).strict();
-    const res = ProjectCategoriesConfigSchema.safeParse(props.categories);
-    if (!res.success) {
-      res.error.issues.forEach(
-        (issue) => issues.push({ path: `categories.${issue.path.join(".")}`, message: issue.message })
-      );
-    }
-  }
-  if (!props.categories) {
-    warnings.push(
-      "Prop 'categories' n\xE3o fornecida \u2014 o ConsentProvider requer configura\xE7\xE3o de categorias."
-    );
-  } else {
-    const cat = props.categories;
-    const enabled = [...new Set(cat.enabledCategories ?? [])];
-    if (enabled.includes("necessary")) {
-      warnings.push("'necessary' \xE9 sempre inclu\xEDda automaticamente \u2014 remova de enabledCategories.");
-    }
-    const sanitizedEnabled = enabled.filter((c) => c !== "necessary");
-    const invalidEnabled = sanitizedEnabled.filter((c) => typeof c !== "string" || c.trim() === "");
-    if (invalidEnabled.length > 0) {
-      warnings.push(
-        `enabledCategories cont\xE9m valores inv\xE1lidos: ${invalidEnabled.map(String).join(", ")} \u2014 remova ou corrija os IDs de categoria`
-      );
-    }
-    const custom = cat.customCategories ?? [];
-    if (z) {
-      const CustomCategorySchema = z.object({
-        id: z.string().min(1),
-        name: z.string().min(1),
-        description: z.string().min(1),
-        essential: z.boolean().optional(),
-        cookies: z.array(z.string().min(1)).optional()
-      });
-      const customParse = z.array(CustomCategorySchema).safeParse(custom);
-      if (!customParse.success) {
-        customParse.error.issues.forEach(
-          (issue) => issues.push({ path: `customCategories.${issue.path.join(".")}`, message: issue.message })
-        );
-      }
-    }
-    const ids = /* @__PURE__ */ new Set();
-    const dupes = [];
-    ["necessary", ...sanitizedEnabled].forEach((id) => {
-      if (ids.has(id)) dupes.push(id);
-      ids.add(id);
-    });
-    custom.forEach((c) => {
-      if (ids.has(c.id)) dupes.push(c.id);
-      ids.add(c.id);
-    });
-    if (dupes.length > 0) {
-      warnings.push(
-        `IDs de categoria duplicados detectados: ${Array.from(new Set(dupes)).join(
-          ", "
-        )} \u2014 verifique 'enabledCategories' e 'customCategories'.`
-      );
-    }
+  collectZodIssues(z, props.categories, issues);
+  if (props.categories) {
+    const { enabled, sanitizedEnabled, custom } = sanitizeCategories(props.categories);
+    warnings.push(...collectCategoryWarnings({ enabled, sanitizedEnabled, custom }));
     sanitized.categories = {
       enabledCategories: sanitizedEnabled,
       customCategories: custom
     };
+  } else {
+    warnings.push(
+      "Prop 'categories' n\xE3o fornecida \u2014 o ConsentProvider requer configura\xE7\xE3o de categorias."
+    );
   }
-  if (warnings.length > 0) {
-    logger.warn("Valida\xE7\xE3o do ConsentProvider:", ...warnings);
-  }
-  if (errors.length > 0 || issues.length > 0) {
-    issues.forEach((i) => errors.push(`Prop inv\xE1lida: ${i.path} \u2014 ${i.message}`));
-    logger.error("Erros de configura\xE7\xE3o do ConsentProvider:", ...errors);
-  }
+  reportValidationMessages(warnings, errors, issues);
   return { sanitized, warnings, errors };
 }
 
 // src/utils/cookieDiscovery.ts
 function discoverRuntimeCookies() {
   const currentDocument = globalThis.document;
-  if (currentDocument === void 0 || !currentDocument.cookie) return [];
+  if (!currentDocument?.cookie) return [];
   const names = Array.from(
     new Set(
       currentDocument.cookie.split(";").map((s) => s.trim()).filter(Boolean).map((s) => s.split("=")[0])
@@ -1873,7 +1884,7 @@ function isConsentJson(val) {
 }
 function detectConsentCookieName() {
   const currentDocument = globalThis.document;
-  if (currentDocument === void 0 || !currentDocument.cookie) return null;
+  if (!currentDocument?.cookie) return null;
   try {
     const pairs = currentDocument.cookie.split(";").map((s) => s.trim()).filter(Boolean);
     for (const p of pairs) {
@@ -2027,19 +2038,19 @@ function createFullConsentState(consented, preferences, source, projectConfig, i
 }
 var BASE_TEXTS = {
   // Textos básicos
-  bannerMessage: "Utilizamos cookies para melhorar sua experi\xEAncia.",
+  bannerMessage: "Usamos cookies necess\xE1rios para o funcionamento do site. Os demais cookies s\xE3o opcionais e voc\xEA pode aceitar, rejeitar ou ajustar suas prefer\xEAncias.",
   acceptAll: "Aceitar todos",
-  declineAll: "Recusar",
+  declineAll: "Rejeitar opcionais",
   preferences: "Prefer\xEAncias",
-  policyLink: "Saiba mais",
-  modalTitle: "Prefer\xEAncias de Cookies",
-  modalIntro: "Ajuste as categorias de cookies. Cookies necess\xE1rios s\xE3o sempre utilizados para funcionalidades b\xE1sicas.",
+  policyLink: "Pol\xEDtica de privacidade",
+  modalTitle: "Prefer\xEAncias de cookies",
+  modalIntro: "Cookies necess\xE1rios s\xE3o sempre ativos. As demais categorias s\xE3o opcionais e voc\xEA pode ativ\xE1-las ou desativ\xE1-las a qualquer momento.",
   save: "Salvar prefer\xEAncias",
   necessaryAlwaysOn: "Cookies necess\xE1rios (sempre ativos)",
   // Textos adicionais para UI customizada
-  preferencesButton: "Configurar Cookies",
-  preferencesTitle: "Gerenciar Prefer\xEAncias de Cookies",
-  preferencesDescription: "Escolha quais tipos de cookies voc\xEA permite que sejam utilizados.",
+  preferencesButton: "Gerenciar cookies",
+  preferencesTitle: "Gerenciar prefer\xEAncias de cookies",
+  preferencesDescription: "Escolha quais categorias opcionais voc\xEA permite. Cookies necess\xE1rios permanecem sempre ativos.",
   close: "Fechar",
   accept: "Aceitar",
   reject: "Rejeitar",
@@ -2160,6 +2171,7 @@ function ConsentProvider({
   floatingPreferencesButtonProps = {},
   disableFloatingPreferencesButton = false,
   blocking = false,
+  blockingMode = "soft",
   blockingStrategy = "auto",
   hideBranding: _hideBranding = false,
   onConsentGiven,
@@ -2437,6 +2449,7 @@ function ConsentProvider({
       hideBranding: incoming.hideBranding === void 0 ? _hideBranding : Boolean(incoming.hideBranding)
     };
   }, [cookieBannerProps, blocking, _hideBranding]);
+  const hardBlockingActive = blocking && isHydrated && !state.consented && blockingMode === "hard";
   const content = /* @__PURE__ */ jsxRuntime.jsx(StateCtx.Provider, { value: state, children: /* @__PURE__ */ jsxRuntime.jsx(ActionsCtx.Provider, { value: api, children: /* @__PURE__ */ jsxRuntime.jsx(TextsCtx.Provider, { value: texts, children: /* @__PURE__ */ jsxRuntime.jsx(HydrationCtx.Provider, { value: isHydrated, children: /* @__PURE__ */ jsxRuntime.jsx(DesignProvider, { tokens: designTokens, children: /* @__PURE__ */ jsxRuntime.jsxs(
     CategoriesProvider,
     {
@@ -2444,7 +2457,16 @@ function ConsentProvider({
       disableDeveloperGuidance,
       disableDiscoveryLog,
       children: [
-        children,
+        /* @__PURE__ */ jsxRuntime.jsx(
+          "div",
+          {
+            "data-testid": "lgpd-app-content",
+            "aria-hidden": hardBlockingActive ? true : void 0,
+            inert: hardBlockingActive,
+            style: { display: "contents" },
+            children
+          }
+        ),
         PreferencesModalComponent ? /* @__PURE__ */ jsxRuntime.jsx(
           PreferencesModalComponent,
           {

package/dist/index.d.cts

@@ -175,8 +175,7 @@ declare const GUIDANCE_PRESETS: {
  * Tipo auxiliar para variações de texto.
  *
  * Define um subconjunto opcional dos textos principais do banner e modal,
- * permitindo variações de t    es: {
-      bannerMessage: 'Utilizamos cookies para mejorar su experiencia y mostrar contenido personalizado.', (formal, casual, etc.) sem sobrescrever todos os textos.
+ * permitindo variações de tom (formal, casual, etc.) sem sobrescrever todos os textos.
  *
  * @category Types
  * @since 0.4.1
@@ -1174,6 +1173,19 @@ type BackdropConfig = boolean | string | {
  * @since 0.1.3
  * @remarks
  * **Histórico**: v0.4.1 - Expandido substancialmente com novos tokens
+ *
+ * ### Mapa de tokens (top-level)
+ * - `colors`: cores base, semânticas e por componente
+ * - `typography`: fonte, tamanhos, pesos e hierarquia
+ * - `spacing`: espaçamentos, padding/margin e radius
+ * - `layout`: posição, largura, backdrop e z-index
+ * - `effects`: sombras, transições e filtros
+ * - `accessibility`: contraste, motion e foco
+ * - `themes`: overrides para light/dark
+ *
+ * ### Overrides complementares (MUI)
+ * Mesmo com tokens, você pode ajustar detalhes via `sx` e `ThemeProvider`.
+ * Ex.: `cookieBannerProps.PaperProps.sx` e `preferencesModalProps.DialogProps.sx`.
  * @public
  *
  * @example Configuração básica
@@ -1681,6 +1693,16 @@ interface ConsentProviderProps {
      * - `true`: Banner bloqueia interação até decisão (compliance rigorosa)
      */
     blocking?: boolean;
+    /**
+     * Intensidade do bloqueio quando `blocking` estiver habilitado.
+     * - 'soft' (padrão): aplica apenas overlay visual (cliques bloqueados).
+     * - 'hard': aplica overlay + torna o conteúdo da aplicação inerte (sem foco/teclado).
+     *
+     * @remarks
+     * O modo `hard` utiliza o atributo `inert` para restringir navegação por teclado
+     * ao banner/modal, atendendo contextos regulatórios mais estritos.
+     */
+    blockingMode?: 'soft' | 'hard';
     /**
      * Estratégia de bloqueio quando `blocking` estiver habilitado.
      * - 'auto' (padrão):
@@ -1826,6 +1848,20 @@ interface ConsentProviderProps {
  * @since 0.3.1
  * @public
  * Fornece acesso ao estado de consentimento e ações necessárias para o banner.
+ *
+ * @example
+ * ```tsx
+ * function MyBanner({ acceptAll, rejectAll, openPreferences, texts }: CustomCookieBannerProps) {
+ *   return (
+ *     <div>
+ *       <p>{texts.bannerMessage}</p>
+ *       <button onClick={acceptAll}>{texts.acceptAll}</button>
+ *       <button onClick={rejectAll}>{texts.declineAll}</button>
+ *       <button onClick={openPreferences}>{texts.preferences}</button>
+ *     </div>
+ *   )
+ * }
+ * ```
  */
 interface CustomCookieBannerProps {
     consented: boolean;
@@ -1851,6 +1887,28 @@ interface CustomCookieBannerProps {
  * Fornece acesso às preferências atuais do usuário, funções para atualizar e salvar preferências,
  * fechar o modal e textos customizados da interface.
  *
+ * @example
+ * ```tsx
+ * function MyPreferencesModal({
+ *   preferences,
+ *   setPreferences,
+ *   closePreferences,
+ *   isModalOpen,
+ *   texts,
+ * }: CustomPreferencesModalProps) {
+ *   if (!isModalOpen) return null
+ *   return (
+ *     <div role="dialog" aria-label={texts.accessibility?.modalLabel}>
+ *       <h2>{texts.modalTitle}</h2>
+ *       <button onClick={() => setPreferences({ ...preferences, analytics: true })}>
+ *         {texts.acceptAll}
+ *       </button>
+ *       <button onClick={closePreferences}>{texts.close ?? 'Fechar'}</button>
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
  * @property preferences Preferências atuais de consentimento do usuário.
  * @property setPreferences Função para atualizar e salvar as preferências.
  * @property closePreferences Função para fechar o modal de preferências.
@@ -1870,6 +1928,14 @@ interface CustomPreferencesModalProps {
  * @since 0.3.1
  * @public
  * Fornece acesso às ações de abertura do modal e ao estado de consentimento.
+ *
+ * @example
+ * ```tsx
+ * function MyFloatingButton({ openPreferences, consented }: CustomFloatingPreferencesButtonProps) {
+ *   if (!consented) return null
+ *   return <button onClick={openPreferences}>Gerenciar cookies</button>
+ * }
+ * ```
  */
 interface CustomFloatingPreferencesButtonProps {
     openPreferences: () => void;
@@ -2050,6 +2116,7 @@ type ConsentEvent = ConsentInitializedEvent | ConsentUpdatedEvent;
  * @param {ProjectCategoriesConfig} props.categories - **Obrigatório**. Define as categorias de cookies que seu projeto utiliza, em conformidade com o princípio de minimização da LGPD.
  * @param {Partial<AdvancedConsentTexts>} [props.texts] - Objeto para customizar todos os textos exibidos na UI.
  * @param {boolean} [props.blocking=false] - Se `true`, exibe um overlay que impede a interação com o site até uma decisão do usuário.
+ * @param {'soft' | 'hard'} [props.blockingMode='soft'] - Intensidade do bloqueio; use `hard` para tornar o conteúdo inerte e restringir navegação por teclado.
  * @param {(state: ConsentState) => void} [props.onConsentGiven] - Callback executado na primeira vez que o usuário dá o consentimento.
  * @param {(prefs: ConsentPreferences) => void} [props.onPreferencesSaved] - Callback executado sempre que o usuário salva novas preferências.
  * @param {boolean} [props.disableDeveloperGuidance=false] - Desativa as mensagens de orientação no console em ambiente de desenvolvimento.
@@ -2083,7 +2150,7 @@ type ConsentEvent = ConsentInitializedEvent | ConsentUpdatedEvent;
  * </ConsentProvider>
  * ```
  */
-declare function ConsentProvider({ initialState, categories, texts: textsProp, language, textVariant, designTokens, PreferencesModalComponent, preferencesModalProps, CookieBannerComponent, cookieBannerProps, FloatingPreferencesButtonComponent, floatingPreferencesButtonProps, disableFloatingPreferencesButton, blocking, blockingStrategy, hideBranding: _hideBranding, onConsentGiven, onPreferencesSaved, cookie: cookieOpts, storage, onConsentVersionChange, disableDeveloperGuidance, guidanceConfig, children, disableDiscoveryLog, onConsentInit, onConsentChange, onAuditLog, }: Readonly<ConsentProviderProps>): react_jsx_runtime.JSX.Element;
+declare function ConsentProvider({ initialState, categories, texts: textsProp, language, textVariant, designTokens, PreferencesModalComponent, preferencesModalProps, CookieBannerComponent, cookieBannerProps, FloatingPreferencesButtonComponent, floatingPreferencesButtonProps, disableFloatingPreferencesButton, blocking, blockingMode, blockingStrategy, hideBranding: _hideBranding, onConsentGiven, onPreferencesSaved, cookie: cookieOpts, storage, onConsentVersionChange, disableDeveloperGuidance, guidanceConfig, children, disableDiscoveryLog, onConsentInit, onConsentChange, onAuditLog, }: Readonly<ConsentProviderProps>): react_jsx_runtime.JSX.Element;
 declare const defaultTexts: AdvancedConsentTexts;
 
 /**
@@ -3678,6 +3745,20 @@ interface RegisteredScript {
  * @returns Função de cleanup para remover o script da fila.
  */
 declare function registerScript(def: RegisteredScript): () => void;
+/**
+ * Props do ConsentScriptLoader.
+ *
+ * @category Types
+ * @since 0.2.0
+ *
+ * @example
+ * ```tsx
+ * <ConsentScriptLoader
+ *   integrations={[COMMON_INTEGRATIONS.googleTagManager({ containerId: 'GTM-XXXX' })]}
+ *   reloadOnChange
+ * />
+ * ```
+ */
 interface ConsentScriptLoaderProps {
     /** Lista de integrações de scripts para carregar baseado no consentimento */
     integrations: ScriptIntegration[];
@@ -3706,6 +3787,14 @@ interface ConsentScriptLoaderProps {
  *
  * <ConsentScriptLoader integrations={integrations} />
  * ```
+ *
+ * @example
+ * ```tsx
+ * <ConsentScriptLoader
+ *   integrations={[COMMON_INTEGRATIONS.googleTagManager({ containerId: 'GTM-XXXX' })]}
+ *   nonce="csp-nonce"
+ * />
+ * ```
  */
 declare function ConsentScriptLoader({ integrations, reloadOnChange, nonce, }: Readonly<ConsentScriptLoaderProps>): null;
 /**

package/dist/index.d.ts

@@ -175,8 +175,7 @@ declare const GUIDANCE_PRESETS: {
  * Tipo auxiliar para variações de texto.
  *
  * Define um subconjunto opcional dos textos principais do banner e modal,
- * permitindo variações de t    es: {
-      bannerMessage: 'Utilizamos cookies para mejorar su experiencia y mostrar contenido personalizado.', (formal, casual, etc.) sem sobrescrever todos os textos.
+ * permitindo variações de tom (formal, casual, etc.) sem sobrescrever todos os textos.
  *
  * @category Types
  * @since 0.4.1
@@ -1174,6 +1173,19 @@ type BackdropConfig = boolean | string | {
  * @since 0.1.3
  * @remarks
  * **Histórico**: v0.4.1 - Expandido substancialmente com novos tokens
+ *
+ * ### Mapa de tokens (top-level)
+ * - `colors`: cores base, semânticas e por componente
+ * - `typography`: fonte, tamanhos, pesos e hierarquia
+ * - `spacing`: espaçamentos, padding/margin e radius
+ * - `layout`: posição, largura, backdrop e z-index
+ * - `effects`: sombras, transições e filtros
+ * - `accessibility`: contraste, motion e foco
+ * - `themes`: overrides para light/dark
+ *
+ * ### Overrides complementares (MUI)
+ * Mesmo com tokens, você pode ajustar detalhes via `sx` e `ThemeProvider`.
+ * Ex.: `cookieBannerProps.PaperProps.sx` e `preferencesModalProps.DialogProps.sx`.
  * @public
  *
  * @example Configuração básica
@@ -1681,6 +1693,16 @@ interface ConsentProviderProps {
      * - `true`: Banner bloqueia interação até decisão (compliance rigorosa)
      */
     blocking?: boolean;
+    /**
+     * Intensidade do bloqueio quando `blocking` estiver habilitado.
+     * - 'soft' (padrão): aplica apenas overlay visual (cliques bloqueados).
+     * - 'hard': aplica overlay + torna o conteúdo da aplicação inerte (sem foco/teclado).
+     *
+     * @remarks
+     * O modo `hard` utiliza o atributo `inert` para restringir navegação por teclado
+     * ao banner/modal, atendendo contextos regulatórios mais estritos.
+     */
+    blockingMode?: 'soft' | 'hard';
     /**
      * Estratégia de bloqueio quando `blocking` estiver habilitado.
      * - 'auto' (padrão):
@@ -1826,6 +1848,20 @@ interface ConsentProviderProps {
  * @since 0.3.1
  * @public
  * Fornece acesso ao estado de consentimento e ações necessárias para o banner.
+ *
+ * @example
+ * ```tsx
+ * function MyBanner({ acceptAll, rejectAll, openPreferences, texts }: CustomCookieBannerProps) {
+ *   return (
+ *     <div>
+ *       <p>{texts.bannerMessage}</p>
+ *       <button onClick={acceptAll}>{texts.acceptAll}</button>
+ *       <button onClick={rejectAll}>{texts.declineAll}</button>
+ *       <button onClick={openPreferences}>{texts.preferences}</button>
+ *     </div>
+ *   )
+ * }
+ * ```
  */
 interface CustomCookieBannerProps {
     consented: boolean;
@@ -1851,6 +1887,28 @@ interface CustomCookieBannerProps {
  * Fornece acesso às preferências atuais do usuário, funções para atualizar e salvar preferências,
  * fechar o modal e textos customizados da interface.
  *
+ * @example
+ * ```tsx
+ * function MyPreferencesModal({
+ *   preferences,
+ *   setPreferences,
+ *   closePreferences,
+ *   isModalOpen,
+ *   texts,
+ * }: CustomPreferencesModalProps) {
+ *   if (!isModalOpen) return null
+ *   return (
+ *     <div role="dialog" aria-label={texts.accessibility?.modalLabel}>
+ *       <h2>{texts.modalTitle}</h2>
+ *       <button onClick={() => setPreferences({ ...preferences, analytics: true })}>
+ *         {texts.acceptAll}
+ *       </button>
+ *       <button onClick={closePreferences}>{texts.close ?? 'Fechar'}</button>
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
  * @property preferences Preferências atuais de consentimento do usuário.
  * @property setPreferences Função para atualizar e salvar as preferências.
  * @property closePreferences Função para fechar o modal de preferências.
@@ -1870,6 +1928,14 @@ interface CustomPreferencesModalProps {
  * @since 0.3.1
  * @public
  * Fornece acesso às ações de abertura do modal e ao estado de consentimento.
+ *
+ * @example
+ * ```tsx
+ * function MyFloatingButton({ openPreferences, consented }: CustomFloatingPreferencesButtonProps) {
+ *   if (!consented) return null
+ *   return <button onClick={openPreferences}>Gerenciar cookies</button>
+ * }
+ * ```
  */
 interface CustomFloatingPreferencesButtonProps {
     openPreferences: () => void;
@@ -2050,6 +2116,7 @@ type ConsentEvent = ConsentInitializedEvent | ConsentUpdatedEvent;
  * @param {ProjectCategoriesConfig} props.categories - **Obrigatório**. Define as categorias de cookies que seu projeto utiliza, em conformidade com o princípio de minimização da LGPD.
  * @param {Partial<AdvancedConsentTexts>} [props.texts] - Objeto para customizar todos os textos exibidos na UI.
  * @param {boolean} [props.blocking=false] - Se `true`, exibe um overlay que impede a interação com o site até uma decisão do usuário.
+ * @param {'soft' | 'hard'} [props.blockingMode='soft'] - Intensidade do bloqueio; use `hard` para tornar o conteúdo inerte e restringir navegação por teclado.
  * @param {(state: ConsentState) => void} [props.onConsentGiven] - Callback executado na primeira vez que o usuário dá o consentimento.
  * @param {(prefs: ConsentPreferences) => void} [props.onPreferencesSaved] - Callback executado sempre que o usuário salva novas preferências.
  * @param {boolean} [props.disableDeveloperGuidance=false] - Desativa as mensagens de orientação no console em ambiente de desenvolvimento.
@@ -2083,7 +2150,7 @@ type ConsentEvent = ConsentInitializedEvent | ConsentUpdatedEvent;
  * </ConsentProvider>
  * ```
  */
-declare function ConsentProvider({ initialState, categories, texts: textsProp, language, textVariant, designTokens, PreferencesModalComponent, preferencesModalProps, CookieBannerComponent, cookieBannerProps, FloatingPreferencesButtonComponent, floatingPreferencesButtonProps, disableFloatingPreferencesButton, blocking, blockingStrategy, hideBranding: _hideBranding, onConsentGiven, onPreferencesSaved, cookie: cookieOpts, storage, onConsentVersionChange, disableDeveloperGuidance, guidanceConfig, children, disableDiscoveryLog, onConsentInit, onConsentChange, onAuditLog, }: Readonly<ConsentProviderProps>): react_jsx_runtime.JSX.Element;
+declare function ConsentProvider({ initialState, categories, texts: textsProp, language, textVariant, designTokens, PreferencesModalComponent, preferencesModalProps, CookieBannerComponent, cookieBannerProps, FloatingPreferencesButtonComponent, floatingPreferencesButtonProps, disableFloatingPreferencesButton, blocking, blockingMode, blockingStrategy, hideBranding: _hideBranding, onConsentGiven, onPreferencesSaved, cookie: cookieOpts, storage, onConsentVersionChange, disableDeveloperGuidance, guidanceConfig, children, disableDiscoveryLog, onConsentInit, onConsentChange, onAuditLog, }: Readonly<ConsentProviderProps>): react_jsx_runtime.JSX.Element;
 declare const defaultTexts: AdvancedConsentTexts;
 
 /**
@@ -3678,6 +3745,20 @@ interface RegisteredScript {
  * @returns Função de cleanup para remover o script da fila.
  */
 declare function registerScript(def: RegisteredScript): () => void;
+/**
+ * Props do ConsentScriptLoader.
+ *
+ * @category Types
+ * @since 0.2.0
+ *
+ * @example
+ * ```tsx
+ * <ConsentScriptLoader
+ *   integrations={[COMMON_INTEGRATIONS.googleTagManager({ containerId: 'GTM-XXXX' })]}
+ *   reloadOnChange
+ * />
+ * ```
+ */
 interface ConsentScriptLoaderProps {
     /** Lista de integrações de scripts para carregar baseado no consentimento */
     integrations: ScriptIntegration[];
@@ -3706,6 +3787,14 @@ interface ConsentScriptLoaderProps {
  *
  * <ConsentScriptLoader integrations={integrations} />
  * ```
+ *
+ * @example
+ * ```tsx
+ * <ConsentScriptLoader
+ *   integrations={[COMMON_INTEGRATIONS.googleTagManager({ containerId: 'GTM-XXXX' })]}
+ *   nonce="csp-nonce"
+ * />
+ * ```
  */
 declare function ConsentScriptLoader({ integrations, reloadOnChange, nonce, }: Readonly<ConsentScriptLoaderProps>): null;
 /**

package/dist/index.js

@@ -40,27 +40,27 @@ var EXPANDED_DEFAULT_TEXTS = {
   categories: {
     necessary: {
       name: "Cookies Necess\xE1rios",
-      description: "Essenciais para o funcionamento b\xE1sico do site",
+      description: "Essenciais para o funcionamento b\xE1sico do site e n\xE3o podem ser desativados",
       examples: "Sess\xE3o, seguran\xE7a, prefer\xEAncias de idioma"
     },
     analytics: {
       name: "Cookies de Analytics",
-      description: "Ajudam a entender como os visitantes usam o site",
+      description: "Opcionais. Ajudam a entender como os visitantes usam o site",
       examples: "Google Analytics, contadores de p\xE1gina"
     },
     marketing: {
       name: "Cookies de Marketing",
-      description: "Usados para personalizar an\xFAncios e ofertas",
+      description: "Opcionais. Usados para personalizar an\xFAncios e ofertas",
       examples: "Facebook Pixel, Google Ads, remarketing"
     },
     functional: {
       name: "Cookies Funcionais",
-      description: "Melhoram a funcionalidade e personaliza\xE7\xE3o",
+      description: "Opcionais. Melhoram a funcionalidade e personaliza\xE7\xE3o",
       examples: "Chat, mapas, v\xEDdeos embarcados"
     },
     performance: {
       name: "Cookies de Performance",
-      description: "Coletam informa\xE7\xF5es sobre velocidade e estabilidade",
+      description: "Opcionais. Coletam informa\xE7\xF5es sobre velocidade e estabilidade",
       examples: "Monitoramento de erro, otimiza\xE7\xE3o de velocidade"
     }
   },
@@ -533,7 +533,6 @@ function buildConsentStorageKey(options) {
 var DEFAULT_COOKIE_OPTS = {
   name: "cookieConsent",
   maxAge: DEFAULT_MAX_AGE_SECONDS,
-  maxAgeDays: 365,
   sameSite: "Lax",
   secure: false,
   path: "/",
@@ -542,18 +541,23 @@ var DEFAULT_COOKIE_OPTS = {
 function resolveCookieOptions(opts) {
   const currentWindow = globalThis.window;
   const currentLocation = globalThis.location;
-  const protocols = [currentWindow?.location?.protocol, currentLocation?.protocol].filter(
-    Boolean
-  );
+  const protocols = [currentWindow?.location?.protocol, currentLocation?.protocol].filter(Boolean);
   const forceHttps = globalThis.__LGPD_FORCE_HTTPS__ === true;
   const isHttps = forceHttps || protocols.includes("https:");
-  const maxAgeSecondsFromDays = typeof opts?.maxAgeDays === "number" ? Math.max(0, opts.maxAgeDays * 24 * 60 * 60) : null;
-  const maxAgeSeconds = typeof opts?.maxAge === "number" ? Math.max(0, opts.maxAge) : maxAgeSecondsFromDays ?? DEFAULT_MAX_AGE_SECONDS;
+  const maxAgeSeconds = typeof opts?.maxAge === "number" ? Math.max(0, opts.maxAge) : typeof opts?.maxAgeDays === "number" ? Math.max(0, opts.maxAgeDays) * 24 * 60 * 60 : DEFAULT_MAX_AGE_SECONDS;
+  let secure;
+  if (typeof opts?.secure === "boolean") {
+    secure = opts.secure;
+  } else if (isHttps) {
+    secure = true;
+  } else {
+    secure = DEFAULT_COOKIE_OPTS.secure;
+  }
   return {
     name: opts?.name ?? DEFAULT_COOKIE_OPTS.name,
     maxAge: maxAgeSeconds,
     sameSite: opts?.sameSite ?? DEFAULT_COOKIE_OPTS.sameSite ?? "Lax",
-    secure: typeof opts?.secure === "boolean" ? opts.secure : isHttps ? true : DEFAULT_COOKIE_OPTS.secure,
+    secure,
     path: opts?.path ?? DEFAULT_COOKIE_OPTS.path ?? "/",
     domain: opts?.domain ?? DEFAULT_COOKIE_OPTS.domain ?? void 0
   };
@@ -672,7 +676,7 @@ function removeConsentCookie(opts) {
 }
 
 // src/utils/dataLayerEvents.ts
-var LIBRARY_VERSION = "0.7.2";
+var LIBRARY_VERSION = "0.8.0";
 function ensureDataLayer() {
   const currentWindow = globalThis.window;
   if (!currentWindow) return;
@@ -1708,14 +1712,88 @@ function runPeerDepsCheck() {
 
 // src/utils/validation.ts
 var isDev = () => typeof process !== "undefined" && process.env.NODE_ENV !== "production";
+var sanitizeCategories = (categories) => {
+  const enabled = [...new Set(categories.enabledCategories ?? [])];
+  const sanitizedEnabled = enabled.filter((c) => c !== "necessary");
+  return {
+    enabled,
+    sanitizedEnabled,
+    custom: categories.customCategories ?? []
+  };
+};
+var collectZodIssues = (z, categories, issues) => {
+  if (!z || !categories) return;
+  const CustomCategorySchema = z.object({
+    id: z.string().min(1, "customCategories[].id deve ser uma string n\xE3o vazia"),
+    name: z.string().min(1, "customCategories[].name deve ser uma string n\xE3o vazia"),
+    description: z.string().min(1, "customCategories[].description deve ser uma string n\xE3o vazia"),
+    essential: z.boolean().optional(),
+    cookies: z.array(z.string().min(1)).optional()
+  });
+  const ProjectCategoriesConfigSchema = z.object({
+    enabledCategories: z.array(z.string().min(1)).optional(),
+    customCategories: z.array(CustomCategorySchema).optional()
+  }).strict();
+  const res = ProjectCategoriesConfigSchema.safeParse(categories);
+  if (!res.success) {
+    res.error.issues.forEach(
+      (issue) => issues.push({ path: `categories.${issue.path.join(".")}`, message: issue.message })
+    );
+  }
+  const customParse = z.array(CustomCategorySchema).safeParse(categories.customCategories ?? []);
+  if (!customParse.success) {
+    customParse.error.issues.forEach(
+      (issue) => issues.push({ path: `customCategories.${issue.path.join(".")}`, message: issue.message })
+    );
+  }
+};
+var collectCategoryWarnings = (input) => {
+  const warnings = [];
+  const { enabled, sanitizedEnabled, custom } = input;
+  if (enabled.includes("necessary")) {
+    warnings.push("'necessary' \xE9 sempre inclu\xEDda automaticamente \u2014 remova de enabledCategories.");
+  }
+  const invalidEnabled = sanitizedEnabled.filter((c) => typeof c !== "string" || c.trim() === "");
+  if (invalidEnabled.length > 0) {
+    warnings.push(
+      `enabledCategories cont\xE9m valores inv\xE1lidos: ${invalidEnabled.map(String).join(", ")} \u2014 remova ou corrija os IDs de categoria`
+    );
+  }
+  const ids = /* @__PURE__ */ new Set();
+  const dupes = [];
+  ["necessary", ...sanitizedEnabled].forEach((id) => {
+    if (ids.has(id)) dupes.push(id);
+    ids.add(id);
+  });
+  custom?.forEach((c) => {
+    if (ids.has(c.id)) dupes.push(c.id);
+    ids.add(c.id);
+  });
+  if (dupes.length > 0) {
+    warnings.push(
+      `IDs de categoria duplicados detectados: ${Array.from(new Set(dupes)).join(
+        ", "
+      )} \u2014 verifique 'enabledCategories' e 'customCategories'.`
+    );
+  }
+  return warnings;
+};
+var reportValidationMessages = (warnings, errors, issues) => {
+  if (warnings.length > 0) {
+    logger.warn("Valida\xE7\xE3o do ConsentProvider:", ...warnings);
+  }
+  if (errors.length > 0 || issues.length > 0) {
+    issues.forEach((i) => errors.push(`Prop inv\xE1lida: ${i.path} \u2014 ${i.message}`));
+    logger.error("Erros de configura\xE7\xE3o do ConsentProvider:", ...errors);
+  }
+};
 function validateConsentProviderProps(props) {
   const warnings = [];
   const errors = [];
   const sanitized = {};
   if (!isDev()) {
     if (props.categories) {
-      const enabled = [...new Set(props.categories.enabledCategories ?? [])];
-      const sanitizedEnabled = enabled.filter((c) => c !== "necessary");
+      const { sanitizedEnabled } = sanitizeCategories(props.categories);
       sanitized.categories = {
         enabledCategories: sanitizedEnabled,
         customCategories: props.categories.customCategories
@@ -1730,94 +1808,27 @@ function validateConsentProviderProps(props) {
     z = void 0;
   }
   const issues = [];
-  if (z) {
-    const CustomCategorySchema = z.object({
-      id: z.string().min(1, "customCategories[].id deve ser uma string n\xE3o vazia"),
-      name: z.string().min(1, "customCategories[].name deve ser uma string n\xE3o vazia"),
-      description: z.string().min(1, "customCategories[].description deve ser uma string n\xE3o vazia"),
-      essential: z.boolean().optional(),
-      cookies: z.array(z.string().min(1)).optional()
-    });
-    const ProjectCategoriesConfigSchema = z.object({
-      enabledCategories: z.array(z.string().min(1)).optional(),
-      customCategories: z.array(CustomCategorySchema).optional()
-    }).strict();
-    const res = ProjectCategoriesConfigSchema.safeParse(props.categories);
-    if (!res.success) {
-      res.error.issues.forEach(
-        (issue) => issues.push({ path: `categories.${issue.path.join(".")}`, message: issue.message })
-      );
-    }
-  }
-  if (!props.categories) {
-    warnings.push(
-      "Prop 'categories' n\xE3o fornecida \u2014 o ConsentProvider requer configura\xE7\xE3o de categorias."
-    );
-  } else {
-    const cat = props.categories;
-    const enabled = [...new Set(cat.enabledCategories ?? [])];
-    if (enabled.includes("necessary")) {
-      warnings.push("'necessary' \xE9 sempre inclu\xEDda automaticamente \u2014 remova de enabledCategories.");
-    }
-    const sanitizedEnabled = enabled.filter((c) => c !== "necessary");
-    const invalidEnabled = sanitizedEnabled.filter((c) => typeof c !== "string" || c.trim() === "");
-    if (invalidEnabled.length > 0) {
-      warnings.push(
-        `enabledCategories cont\xE9m valores inv\xE1lidos: ${invalidEnabled.map(String).join(", ")} \u2014 remova ou corrija os IDs de categoria`
-      );
-    }
-    const custom = cat.customCategories ?? [];
-    if (z) {
-      const CustomCategorySchema = z.object({
-        id: z.string().min(1),
-        name: z.string().min(1),
-        description: z.string().min(1),
-        essential: z.boolean().optional(),
-        cookies: z.array(z.string().min(1)).optional()
-      });
-      const customParse = z.array(CustomCategorySchema).safeParse(custom);
-      if (!customParse.success) {
-        customParse.error.issues.forEach(
-          (issue) => issues.push({ path: `customCategories.${issue.path.join(".")}`, message: issue.message })
-        );
-      }
-    }
-    const ids = /* @__PURE__ */ new Set();
-    const dupes = [];
-    ["necessary", ...sanitizedEnabled].forEach((id) => {
-      if (ids.has(id)) dupes.push(id);
-      ids.add(id);
-    });
-    custom.forEach((c) => {
-      if (ids.has(c.id)) dupes.push(c.id);
-      ids.add(c.id);
-    });
-    if (dupes.length > 0) {
-      warnings.push(
-        `IDs de categoria duplicados detectados: ${Array.from(new Set(dupes)).join(
-          ", "
-        )} \u2014 verifique 'enabledCategories' e 'customCategories'.`
-      );
-    }
+  collectZodIssues(z, props.categories, issues);
+  if (props.categories) {
+    const { enabled, sanitizedEnabled, custom } = sanitizeCategories(props.categories);
+    warnings.push(...collectCategoryWarnings({ enabled, sanitizedEnabled, custom }));
     sanitized.categories = {
       enabledCategories: sanitizedEnabled,
       customCategories: custom
     };
+  } else {
+    warnings.push(
+      "Prop 'categories' n\xE3o fornecida \u2014 o ConsentProvider requer configura\xE7\xE3o de categorias."
+    );
   }
-  if (warnings.length > 0) {
-    logger.warn("Valida\xE7\xE3o do ConsentProvider:", ...warnings);
-  }
-  if (errors.length > 0 || issues.length > 0) {
-    issues.forEach((i) => errors.push(`Prop inv\xE1lida: ${i.path} \u2014 ${i.message}`));
-    logger.error("Erros de configura\xE7\xE3o do ConsentProvider:", ...errors);
-  }
+  reportValidationMessages(warnings, errors, issues);
   return { sanitized, warnings, errors };
 }
 
 // src/utils/cookieDiscovery.ts
 function discoverRuntimeCookies() {
   const currentDocument = globalThis.document;
-  if (currentDocument === void 0 || !currentDocument.cookie) return [];
+  if (!currentDocument?.cookie) return [];
   const names = Array.from(
     new Set(
       currentDocument.cookie.split(";").map((s) => s.trim()).filter(Boolean).map((s) => s.split("=")[0])
@@ -1849,7 +1860,7 @@ function isConsentJson(val) {
 }
 function detectConsentCookieName() {
   const currentDocument = globalThis.document;
-  if (currentDocument === void 0 || !currentDocument.cookie) return null;
+  if (!currentDocument?.cookie) return null;
   try {
     const pairs = currentDocument.cookie.split(";").map((s) => s.trim()).filter(Boolean);
     for (const p of pairs) {
@@ -2003,19 +2014,19 @@ function createFullConsentState(consented, preferences, source, projectConfig, i
 }
 var BASE_TEXTS = {
   // Textos básicos
-  bannerMessage: "Utilizamos cookies para melhorar sua experi\xEAncia.",
+  bannerMessage: "Usamos cookies necess\xE1rios para o funcionamento do site. Os demais cookies s\xE3o opcionais e voc\xEA pode aceitar, rejeitar ou ajustar suas prefer\xEAncias.",
   acceptAll: "Aceitar todos",
-  declineAll: "Recusar",
+  declineAll: "Rejeitar opcionais",
   preferences: "Prefer\xEAncias",
-  policyLink: "Saiba mais",
-  modalTitle: "Prefer\xEAncias de Cookies",
-  modalIntro: "Ajuste as categorias de cookies. Cookies necess\xE1rios s\xE3o sempre utilizados para funcionalidades b\xE1sicas.",
+  policyLink: "Pol\xEDtica de privacidade",
+  modalTitle: "Prefer\xEAncias de cookies",
+  modalIntro: "Cookies necess\xE1rios s\xE3o sempre ativos. As demais categorias s\xE3o opcionais e voc\xEA pode ativ\xE1-las ou desativ\xE1-las a qualquer momento.",
   save: "Salvar prefer\xEAncias",
   necessaryAlwaysOn: "Cookies necess\xE1rios (sempre ativos)",
   // Textos adicionais para UI customizada
-  preferencesButton: "Configurar Cookies",
-  preferencesTitle: "Gerenciar Prefer\xEAncias de Cookies",
-  preferencesDescription: "Escolha quais tipos de cookies voc\xEA permite que sejam utilizados.",
+  preferencesButton: "Gerenciar cookies",
+  preferencesTitle: "Gerenciar prefer\xEAncias de cookies",
+  preferencesDescription: "Escolha quais categorias opcionais voc\xEA permite. Cookies necess\xE1rios permanecem sempre ativos.",
   close: "Fechar",
   accept: "Aceitar",
   reject: "Rejeitar",
@@ -2136,6 +2147,7 @@ function ConsentProvider({
   floatingPreferencesButtonProps = {},
   disableFloatingPreferencesButton = false,
   blocking = false,
+  blockingMode = "soft",
   blockingStrategy = "auto",
   hideBranding: _hideBranding = false,
   onConsentGiven,
@@ -2413,6 +2425,7 @@ function ConsentProvider({
       hideBranding: incoming.hideBranding === void 0 ? _hideBranding : Boolean(incoming.hideBranding)
     };
   }, [cookieBannerProps, blocking, _hideBranding]);
+  const hardBlockingActive = blocking && isHydrated && !state.consented && blockingMode === "hard";
   const content = /* @__PURE__ */ jsx(StateCtx.Provider, { value: state, children: /* @__PURE__ */ jsx(ActionsCtx.Provider, { value: api, children: /* @__PURE__ */ jsx(TextsCtx.Provider, { value: texts, children: /* @__PURE__ */ jsx(HydrationCtx.Provider, { value: isHydrated, children: /* @__PURE__ */ jsx(DesignProvider, { tokens: designTokens, children: /* @__PURE__ */ jsxs(
     CategoriesProvider,
     {
@@ -2420,7 +2433,16 @@ function ConsentProvider({
       disableDeveloperGuidance,
       disableDiscoveryLog,
       children: [
-        children,
+        /* @__PURE__ */ jsx(
+          "div",
+          {
+            "data-testid": "lgpd-app-content",
+            "aria-hidden": hardBlockingActive ? true : void 0,
+            inert: hardBlockingActive,
+            style: { display: "contents" },
+            children
+          }
+        ),
         PreferencesModalComponent ? /* @__PURE__ */ jsx(
           PreferencesModalComponent,
           {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-lgpd-consent/core",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "Núcleo da biblioteca de consentimento LGPD para React - Estado, hooks e utilitários sem dependências de UI",
   "keywords": [
     "lgpd",