react-lgpd-consent 0.3.2 → 0.3.4

package/README.md

@@ -4,42 +4,35 @@
 
   <div>
     <a href="https://www.npmjs.com/package/react-lgpd-consent"><img src="https://img.shields.io/npm/v/react-lgpd-consent?style=for-the-badge&logo=npm&color=cb3837&logoColor=white" alt="NPM Version"></a>
-     <a href="https://www.npmjs.com/package/react-lgpd-consent"><img src="https://img.shields.io/npm/dm/react-lgpd-consent?style=for-the-badge&logo=npm&color=ff6b35&logoColor=white" alt="Downloads"></a>
-     <a href="https://github.com/lucianoedipo/react-lgpd-consent/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/react-lgpd-consent?style=for-the-badge&color=green&logoColor=white" alt="License"></a>
+    <a href="https://www.npmjs.com/package/react-lgpd-consent"><img src="https://img.shields.io/npm/dm/react-lgpd-consent?style=for-the-badge&logo=npm&color=ff6b35&logoColor=white" alt="Downloads"></a>
+    <a href="https://github.com/lucianoedipo/react-lgpd-consent/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/react-lgpd-consent?style=for-the-badge&color=green&logoColor=white" alt="License"></a>
+  <a href="https://lucianoedipo.github.io/react-lgpd-consent/storybook/"><img src="https://img.shields.io/badge/Storybook-Playground-ff4785?style=for-the-badge&logo=storybook&logoColor=white" alt="Storybook"></a>
   </div>
-  
+
   <div>
     <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-Ready-3178c6?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript Ready"></a>
     <a href="https://reactjs.org/"><img src="https://img.shields.io/badge/React-18+-61dafb?style=for-the-badge&logo=react&logoColor=white" alt="React 18+"></a>
     <a href="https://nextjs.org/"><img src="https://img.shields.io/badge/Next.js-Compatible-000000?style=for-the-badge&logo=next.js&logoColor=white" alt="Next.js Compatible"></a>
   </div>
 
-  <br>
+  <br />
 
   <p>
     <a href="#-instalação"><strong>Instalação</strong></a> •
     <a href="#-uso-básico"><strong>Uso Básico</strong></a> •
-    <a href="#-documentação-completa"><strong>Documentação</strong></a> •
+  <a href="./QUICKSTART.md"><strong>📚 Guia de Início Rápido</strong></a> •
+  <a href="#-documentação-completa"><strong>Documentação</strong></a> •
+  <a href="./README.en.md">🇺🇸 🇬🇧 English</a> •
     <a href="#-como-contribuir"><strong>Contribuir</strong></a>
   </p>
-</div>
-
----
-
-## 🎯 Por que usar `react-lgpd-consent`?
-
-Esta biblioteca oferece uma solução robusta e flexível para gerenciar o consentimento de cookies em aplicações React, com foco total na **Lei Geral de Proteção de Dados (LGPD)** do Brasil.
 
-### Principais Funcionalidades
+  <!-- Quickstart callout (mantido) -->
+  <p align="center">
+    <a href="./QUICKSTART.md"><img src="https://img.shields.io/badge/Quickstart-Iniciar%20R%C3%A1pido-blue?style=for-the-badge&logo=book" alt="Quickstart"></a>
+  </p>
 
-| Funcionalidade                   | Descrição                                                                                             |
-| -------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| 🇧🇷 **Foco na LGPD**              | Implementação baseada nas diretrizes da ANPD, com textos e categorias alinhados à lei brasileira.     |
-| 🎨 **UI Automática e Customizável** | Componentes de UI (Banner e Modal) prontos para uso, baseados em Material-UI, e totalmente substituíveis. |
-| ⚙️ **Configuração Consciente**     | A prop `categories` força a declaração explícita dos cookies utilizados, seguindo o princípio da minimização. |
-| 🧠 **Guia para Desenvolvedores**   | Sistema que exibe avisos e sugestões no console (em ambiente de dev) para garantir a correta implementação. |
-| 🚀 **Integrações Nativas**         | Carregamento automático de scripts como Google Analytics e GTM, condicionado ao consentimento do usuário. |
-| 🔒 **Auditoria e Transparência**   | O cookie de consentimento armazena metadados como data, origem e versão para fins de auditoria.     |
+  <p align="center"><strong>Comece por aqui:</strong> siga o <a href="./QUICKSTART.md">Guia de Início Rápido (QUICKSTART.md)</a> para um tutorial passo-a-passo, exemplos TypeScript, tabela de props e integração com MUI — recomendado para usuários novos.</p>
+</div>
 
 ---
 
@@ -49,98 +42,47 @@ Esta biblioteca oferece uma solução robusta e flexível para gerenciar o conse
 npm install react-lgpd-consent @mui/material @emotion/react @emotion/styled js-cookie
 ```
 
-**Dependências Peer:**
-
-A biblioteca requer `react`, `react-dom`, `@mui/material` e `js-cookie` como dependências peer.
+**Dependências peer:** `react`, `react-dom`, `@mui/material` e `js-cookie`.
 
 ---
 
 ## 📖 Uso Básico
 
-Envolva sua aplicação com o `ConsentProvider` e configure as categorias de cookies que você utiliza.
+Envolva sua aplicação com o `ConsentProvider` (exemplo mínimo):
 
 ```tsx
-// Em seu arquivo principal (ex: App.tsx)
-import { ConsentProvider } from 'react-lgpd-consent';
+import { ConsentProvider } from 'react-lgpd-consent'
 
-function App() {
+export default function App() {
   return (
-    <ConsentProvider
-      categories={{
-        // É obrigatório especificar as categorias que seu site usa.
-        // A categoria 'necessary' é sempre incluída.
-        enabledCategories: ['analytics', 'marketing'],
-      }}
-    >
-      {/* O banner e o botão de preferências aparecerão automaticamente */}
-      <SuaAplicacao />
+    <ConsentProvider categories={{ enabledCategories: ['analytics'] }}>
+      <YourApp />
     </ConsentProvider>
-  );
+  )
 }
 ```
 
-### Exemplo com Integração e Textos Customizados
-
-```tsx
-import {
-  ConsentProvider,
-  ConsentScriptLoader,
-  createGoogleAnalyticsIntegration,
-} from 'react-lgpd-consent';
-
-// 1. Crie as integrações que você precisa
-const integrations = [
-  createGoogleAnalyticsIntegration({
-    measurementId: 'G-XXXXXXXXXX', // Substitua pelo seu ID
-  }),
-];
-
-function App() {
-  return (
-    <ConsentProvider
-      categories={{ enabledCategories: ['analytics'] }}
-      texts={{
-        bannerMessage: 'Nós usamos cookies para analisar o tráfego e melhorar a sua experiência.',
-        acceptAll: 'Aceitar',
-        declineAll: 'Recusar',
-        // Para conformidade com a ANPD, preencha os campos abaixo
-        controllerInfo: 'Controlado por: Sua Empresa LTDA (CNPJ: XX.XXX.XXX/XXXX-XX)',
-        contactInfo: 'Contato do DPO: dpo@suaempresa.com',
-      }}
-      onConsentGiven={(state) => {
-        console.log('O usuário deu o primeiro consentimento!', state.preferences);
-      }}
-    >
-      {/* 2. Adicione o loader de scripts para carregá-los após o consentimento */}
-      <ConsentScriptLoader integrations={integrations} />
-
-      <SuaAplicacao />
-    </ConsentProvider>
-  );
-}
-```
-
----
-
 ## 📚 Documentação Completa
 
 Para mais detalhes sobre customização, hooks e funcionalidades, consulte os seguintes guias:
 
+### 📋 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.
 - **[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.
 
+### 🎨 Documentação Interativa (GitHub Pages)
+- **[📖 Storybook - Playground Interativo](https://lucianoedipo.github.io/react-lgpd-consent/storybook/)**: Explore e teste todos os componentes em tempo real com controles interativos.
+- **[⚙️ TypeDoc - Referência de API](https://lucianoedipo.github.io/react-lgpd-consent/docs/)**: Documentação completa da API gerada automaticamente.
+- **[🏠 Portal de Documentação](https://lucianoedipo.github.io/react-lgpd-consent/)**: Página inicial com navegação entre todas as documentações.
 ---
 
 ## 🤝 Como Contribuir
-
-Contribuições são muito bem-vindas! Este é um projeto open-source para a comunidade brasileira.
-
-1.  **Reporte Bugs ou Sugira Melhorias**: Abra uma [Issue no GitHub](https://github.com/lucianoedipo/react-lgpd-consent/issues).
-2.  **Envie um Pull Request**: Siga as instruções no nosso [Guia de Desenvolvimento (`DEVELOPMENT.md`)](./DEVELOPMENT.md).
+1. Abra uma [Issue](https://github.com/lucianoedipo/react-lgpd-consent/issues) para bugs ou melhorias.
+2. Siga o Guia de Desenvolvimento em `DEVELOPMENT.md` para enviar um PR.
 
 ---
-
 ## 📄 Licença
 
-Este projeto está licenciado sob a **MIT License**. Veja o arquivo [LICENSE](./LICENSE) para mais detalhes.
+MIT — veja o arquivo `LICENSE`.

package/dist/{PreferencesModal-7RSEEVUK.js → PreferencesModal-XYBFROAB.js}

@@ -1,6 +1,6 @@
 import {
   PreferencesModal
-} from "./chunk-JUZQJHQW.js";
+} from "./chunk-7D2F6JFW.js";
 export {
   PreferencesModal
 };

package/dist/{chunk-JUZQJHQW.js → chunk-7D2F6JFW.js}

@@ -737,6 +737,7 @@ var linkStyles = {
 };
 function Branding({ variant, hidden = false }) {
   const texts = useConsentTexts();
+  const designTokens = useDesignTokens();
   if (hidden) return null;
   return /* @__PURE__ */ jsxs(
     Typography,
@@ -744,7 +745,7 @@ function Branding({ variant, hidden = false }) {
       variant: "caption",
       sx: (theme) => ({
         ...brandingStyles[variant],
-        color: theme.palette.text.secondary
+        color: designTokens?.colors?.text ?? theme.palette.text.secondary
       }),
       children: [
         texts.brandingPoweredBy || "fornecido por",
@@ -757,7 +758,7 @@ function Branding({ variant, hidden = false }) {
             rel: "noopener noreferrer",
             sx: (theme) => ({
               ...linkStyles,
-              color: theme.palette.primary.main
+              color: designTokens?.colors?.primary ?? theme.palette.primary.main
             }),
             children: "L\xC9dipO.eti.br"
           }
@@ -864,6 +865,13 @@ function CookieBanner({
     width: designTokens?.layout?.width?.desktop ?? "100%",
     p: 2
   };
+  let backdropColor = "rgba(0, 0, 0, 0.4)";
+  const backdropToken = designTokens?.layout?.backdrop;
+  if (backdropToken === false) {
+    backdropColor = "transparent";
+  } else if (typeof backdropToken === "string") {
+    backdropColor = backdropToken;
+  }
   if (blocking) {
     return /* @__PURE__ */ jsxs2(Fragment, { children: [
       /* @__PURE__ */ jsx5(
@@ -875,7 +883,7 @@ function CookieBanner({
             left: 0,
             right: 0,
             bottom: 0,
-            backgroundColor: designTokens?.layout?.backdrop ? "rgba(0, 0, 0, 0.5)" : "transparent",
+            backgroundColor: backdropColor,
             zIndex: 1299
           }
         }
@@ -932,6 +940,7 @@ function FloatingPreferencesButton({
   const { openPreferences, consented } = useConsent();
   const texts = useConsentTexts();
   const safeTheme = useThemeWithFallbacks();
+  const designTokens = useDesignTokens();
   logger.componentRender("FloatingPreferencesButton", {
     position,
     offset,
@@ -971,9 +980,9 @@ function FloatingPreferencesButton({
       onClick: openPreferences,
       sx: {
         ...getPosition(),
-        backgroundColor: safeTheme.palette.primary.main,
+        backgroundColor: designTokens?.colors?.primary ?? safeTheme.palette.primary.main,
         "&:hover": {
-          backgroundColor: safeTheme.palette.primary.dark
+          backgroundColor: designTokens?.colors?.primary ? designTokens?.colors?.primary : safeTheme.palette.primary.dark
         },
         transition: `all ${safeTheme.transitions.duration.short}ms`
       },
@@ -987,7 +996,7 @@ function FloatingPreferencesButton({
 // src/context/ConsentContext.tsx
 import { jsx as jsx7, jsxs as jsxs3 } from "react/jsx-runtime";
 var PreferencesModal = React5.lazy(
-  () => import("./PreferencesModal-7RSEEVUK.js").then((m) => ({
+  () => import("./PreferencesModal-XYBFROAB.js").then((m) => ({
     default: m.PreferencesModal
   }))
 );
@@ -1121,6 +1130,8 @@ function ConsentProvider({
   FloatingPreferencesButtonComponent,
   floatingPreferencesButtonProps = {},
   disableFloatingPreferencesButton = false,
+  blocking = false,
+  blockingStrategy = "auto",
   hideBranding = false,
   onConsentGiven,
   onPreferencesSaved,
@@ -1211,6 +1222,12 @@ function ConsentProvider({
     _registerGlobalOpenPreferences(api.openPreferences);
     return () => _unregisterGlobalOpenPreferences();
   }, [api.openPreferences]);
+  const providerBackdropColor = React5.useMemo(() => {
+    const backdrop = designTokens?.layout?.backdrop;
+    if (backdrop === false) return "transparent";
+    if (typeof backdrop === "string") return backdrop;
+    return "rgba(0, 0, 0, 0.4)";
+  }, [designTokens]);
   return /* @__PURE__ */ jsx7(SafeThemeProvider, { theme: appliedTheme, children: /* @__PURE__ */ jsx7(StateCtx.Provider, { value: state, children: /* @__PURE__ */ jsx7(ActionsCtx.Provider, { value: api, children: /* @__PURE__ */ jsx7(TextsCtx.Provider, { value: texts, children: /* @__PURE__ */ jsx7(HydrationCtx.Provider, { value: isHydrated, children: /* @__PURE__ */ jsx7(DesignProvider, { tokens: designTokens, children: /* @__PURE__ */ jsxs3(
     CategoriesProvider,
     {
@@ -1229,6 +1246,22 @@ function ConsentProvider({
             ...preferencesModalProps
           }
         ) : /* @__PURE__ */ jsx7(PreferencesModal, { hideBranding }) }),
+        blocking && isHydrated && !state.consented && blockingStrategy === "provider" && /* @__PURE__ */ jsx7(
+          "div",
+          {
+            style: {
+              position: "fixed",
+              top: 0,
+              left: 0,
+              right: 0,
+              bottom: 0,
+              backgroundColor: providerBackdropColor,
+              zIndex: 1299
+            },
+            "data-testid": "lgpd-provider-overlay",
+            "aria-hidden": true
+          }
+        ),
         !state.consented && isHydrated && (CookieBannerComponent ? /* @__PURE__ */ jsx7(
           CookieBannerComponent,
           {
@@ -1237,9 +1270,17 @@ function ConsentProvider({
             rejectAll: api.rejectAll,
             openPreferences: api.openPreferences,
             texts,
+            blocking,
+            ...cookieBannerProps
+          }
+        ) : /* @__PURE__ */ jsx7(
+          CookieBanner,
+          {
+            blocking,
+            hideBranding,
             ...cookieBannerProps
           }
-        ) : /* @__PURE__ */ jsx7(CookieBanner, {})),
+        )),
         state.consented && !disableFloatingPreferencesButton && (FloatingPreferencesButtonComponent ? /* @__PURE__ */ jsx7(
           FloatingPreferencesButtonComponent,
           {
@@ -1247,7 +1288,10 @@ function ConsentProvider({
             consented: api.consented,
             ...floatingPreferencesButtonProps
           }
-        ) : /* @__PURE__ */ jsx7(FloatingPreferencesButton, {}))
+        ) : (
+          // Encaminha `floatingPreferencesButtonProps` para o componente padrão
+          /* @__PURE__ */ jsx7(FloatingPreferencesButton, { ...floatingPreferencesButtonProps })
+        ))
       ]
     }
   ) }) }) }) }) }) });
@@ -1323,6 +1367,7 @@ function PreferencesModal2({
 }) {
   const { preferences, setPreferences, closePreferences, isModalOpen } = useConsent();
   const texts = useConsentTexts();
+  const designTokens = useDesignTokens();
   const { toggleableCategories } = useCategories();
   const [tempPreferences, setTempPreferences] = useState2(() => {
     const initialPrefs = { necessary: true };
@@ -1349,9 +1394,23 @@ function PreferencesModal2({
     closePreferences();
   };
   return /* @__PURE__ */ jsxs4(Dialog, { "aria-labelledby": "cookie-pref-title", open, onClose: handleCancel, ...DialogProps2, children: [
-    /* @__PURE__ */ jsx8(DialogTitle, { id: "cookie-pref-title", children: texts.modalTitle }),
-    /* @__PURE__ */ jsxs4(DialogContent, { dividers: true, children: [
-      /* @__PURE__ */ jsx8(Typography3, { variant: "body2", sx: { mb: 2 }, children: texts.modalIntro }),
+    /* @__PURE__ */ jsx8(
+      DialogTitle,
+      {
+        id: "cookie-pref-title",
+        sx: { fontSize: designTokens?.typography?.fontSize?.modal ?? void 0 },
+        children: texts.modalTitle
+      }
+    ),
+    /* @__PURE__ */ jsxs4(DialogContent, { dividers: true, sx: { p: designTokens?.spacing?.padding?.modal ?? void 0 }, children: [
+      /* @__PURE__ */ jsx8(
+        Typography3,
+        {
+          variant: "body2",
+          sx: { mb: 2, fontSize: designTokens?.typography?.fontSize?.modal ?? void 0 },
+          children: texts.modalIntro
+        }
+      ),
       /* @__PURE__ */ jsxs4(FormGroup, { children: [
         toggleableCategories.map((category) => /* @__PURE__ */ jsx8(
           FormControlLabel,

package/dist/index.cjs

@@ -761,6 +761,7 @@ var init_DesignContext = __esm({
 // src/components/Branding.tsx
 function Branding({ variant, hidden = false }) {
   const texts = useConsentTexts();
+  const designTokens = useDesignTokens();
   if (hidden) return null;
   return /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)(
     import_Typography.default,
@@ -768,7 +769,7 @@ function Branding({ variant, hidden = false }) {
       variant: "caption",
       sx: (theme) => ({
         ...brandingStyles[variant],
-        color: theme.palette.text.secondary
+        color: designTokens?.colors?.text ?? theme.palette.text.secondary
       }),
       children: [
         texts.brandingPoweredBy || "fornecido por",
@@ -781,7 +782,7 @@ function Branding({ variant, hidden = false }) {
             rel: "noopener noreferrer",
             sx: (theme) => ({
               ...linkStyles,
-              color: theme.palette.primary.main
+              color: designTokens?.colors?.primary ?? theme.palette.primary.main
             }),
             children: "L\xC9dipO.eti.br"
           }
@@ -795,6 +796,7 @@ var init_Branding = __esm({
   "src/components/Branding.tsx"() {
     "use strict";
     init_useConsent();
+    init_DesignContext();
     import_Link = __toESM(require("@mui/material/Link"), 1);
     import_Typography = __toESM(require("@mui/material/Typography"), 1);
     import_jsx_runtime4 = require("react/jsx-runtime");
@@ -923,6 +925,13 @@ function CookieBanner({
     width: designTokens?.layout?.width?.desktop ?? "100%",
     p: 2
   };
+  let backdropColor = "rgba(0, 0, 0, 0.4)";
+  const backdropToken = designTokens?.layout?.backdrop;
+  if (backdropToken === false) {
+    backdropColor = "transparent";
+  } else if (typeof backdropToken === "string") {
+    backdropColor = backdropToken;
+  }
   if (blocking) {
     return /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)(import_jsx_runtime5.Fragment, { children: [
       /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(
@@ -934,7 +943,7 @@ function CookieBanner({
             left: 0,
             right: 0,
             bottom: 0,
-            backgroundColor: designTokens?.layout?.backdrop ? "rgba(0, 0, 0, 0.5)" : "transparent",
+            backgroundColor: backdropColor,
             zIndex: 1299
           }
         }
@@ -1004,6 +1013,7 @@ function FloatingPreferencesButton({
   const { openPreferences, consented } = useConsent();
   const texts = useConsentTexts();
   const safeTheme = useThemeWithFallbacks();
+  const designTokens = useDesignTokens();
   logger.componentRender("FloatingPreferencesButton", {
     position,
     offset,
@@ -1043,9 +1053,9 @@ function FloatingPreferencesButton({
       onClick: openPreferences,
       sx: {
         ...getPosition(),
-        backgroundColor: safeTheme.palette.primary.main,
+        backgroundColor: designTokens?.colors?.primary ?? safeTheme.palette.primary.main,
         "&:hover": {
-          backgroundColor: safeTheme.palette.primary.dark
+          backgroundColor: designTokens?.colors?.primary ? designTokens?.colors?.primary : safeTheme.palette.primary.dark
         },
         transition: `all ${safeTheme.transitions.duration.short}ms`
       },
@@ -1063,6 +1073,7 @@ var init_FloatingPreferencesButton = __esm({
     import_Fab = __toESM(require("@mui/material/Fab"), 1);
     import_Tooltip = __toESM(require("@mui/material/Tooltip"), 1);
     import_styles3 = require("@mui/material/styles");
+    init_DesignContext();
     init_useConsent();
     init_logger();
     import_jsx_runtime6 = require("react/jsx-runtime");
@@ -1159,6 +1170,8 @@ function ConsentProvider({
   FloatingPreferencesButtonComponent,
   floatingPreferencesButtonProps = {},
   disableFloatingPreferencesButton = false,
+  blocking = false,
+  blockingStrategy = "auto",
   hideBranding = false,
   onConsentGiven,
   onPreferencesSaved,
@@ -1249,6 +1262,12 @@ function ConsentProvider({
     _registerGlobalOpenPreferences(api.openPreferences);
     return () => _unregisterGlobalOpenPreferences();
   }, [api.openPreferences]);
+  const providerBackdropColor = React5.useMemo(() => {
+    const backdrop = designTokens?.layout?.backdrop;
+    if (backdrop === false) return "transparent";
+    if (typeof backdrop === "string") return backdrop;
+    return "rgba(0, 0, 0, 0.4)";
+  }, [designTokens]);
   return /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(SafeThemeProvider, { theme: appliedTheme, children: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(StateCtx.Provider, { value: state, children: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(ActionsCtx.Provider, { value: api, children: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(TextsCtx.Provider, { value: texts, children: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(HydrationCtx.Provider, { value: isHydrated, children: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(DesignProvider, { tokens: designTokens, children: /* @__PURE__ */ (0, import_jsx_runtime7.jsxs)(
     CategoriesProvider,
     {
@@ -1267,6 +1286,22 @@ function ConsentProvider({
             ...preferencesModalProps
           }
         ) : /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(PreferencesModal, { hideBranding }) }),
+        blocking && isHydrated && !state.consented && blockingStrategy === "provider" && /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(
+          "div",
+          {
+            style: {
+              position: "fixed",
+              top: 0,
+              left: 0,
+              right: 0,
+              bottom: 0,
+              backgroundColor: providerBackdropColor,
+              zIndex: 1299
+            },
+            "data-testid": "lgpd-provider-overlay",
+            "aria-hidden": true
+          }
+        ),
         !state.consented && isHydrated && (CookieBannerComponent ? /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(
           CookieBannerComponent,
           {
@@ -1275,9 +1310,17 @@ function ConsentProvider({
             rejectAll: api.rejectAll,
             openPreferences: api.openPreferences,
             texts,
+            blocking,
+            ...cookieBannerProps
+          }
+        ) : /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(
+          CookieBanner,
+          {
+            blocking,
+            hideBranding,
             ...cookieBannerProps
           }
-        ) : /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(CookieBanner, {})),
+        )),
         state.consented && !disableFloatingPreferencesButton && (FloatingPreferencesButtonComponent ? /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(
           FloatingPreferencesButtonComponent,
           {
@@ -1285,7 +1328,10 @@ function ConsentProvider({
             consented: api.consented,
             ...floatingPreferencesButtonProps
           }
-        ) : /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(FloatingPreferencesButton, {}))
+        ) : (
+          // Encaminha `floatingPreferencesButtonProps` para o componente padrão
+          /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(FloatingPreferencesButton, { ...floatingPreferencesButtonProps })
+        ))
       ]
     }
   ) }) }) }) }) }) });
@@ -1437,6 +1483,7 @@ function PreferencesModal2({
 }) {
   const { preferences, setPreferences, closePreferences, isModalOpen } = useConsent();
   const texts = useConsentTexts();
+  const designTokens = useDesignTokens();
   const { toggleableCategories } = useCategories();
   const [tempPreferences, setTempPreferences] = (0, import_react2.useState)(() => {
     const initialPrefs = { necessary: true };
@@ -1463,9 +1510,23 @@ function PreferencesModal2({
     closePreferences();
   };
   return /* @__PURE__ */ (0, import_jsx_runtime8.jsxs)(import_Dialog.default, { "aria-labelledby": "cookie-pref-title", open, onClose: handleCancel, ...DialogProps2, children: [
-    /* @__PURE__ */ (0, import_jsx_runtime8.jsx)(import_DialogTitle.default, { id: "cookie-pref-title", children: texts.modalTitle }),
-    /* @__PURE__ */ (0, import_jsx_runtime8.jsxs)(import_DialogContent.default, { dividers: true, children: [
-      /* @__PURE__ */ (0, import_jsx_runtime8.jsx)(import_Typography3.default, { variant: "body2", sx: { mb: 2 }, children: texts.modalIntro }),
+    /* @__PURE__ */ (0, import_jsx_runtime8.jsx)(
+      import_DialogTitle.default,
+      {
+        id: "cookie-pref-title",
+        sx: { fontSize: designTokens?.typography?.fontSize?.modal ?? void 0 },
+        children: texts.modalTitle
+      }
+    ),
+    /* @__PURE__ */ (0, import_jsx_runtime8.jsxs)(import_DialogContent.default, { dividers: true, sx: { p: designTokens?.spacing?.padding?.modal ?? void 0 }, children: [
+      /* @__PURE__ */ (0, import_jsx_runtime8.jsx)(
+        import_Typography3.default,
+        {
+          variant: "body2",
+          sx: { mb: 2, fontSize: designTokens?.typography?.fontSize?.modal ?? void 0 },
+          children: texts.modalIntro
+        }
+      ),
       /* @__PURE__ */ (0, import_jsx_runtime8.jsxs)(import_FormGroup.default, { children: [
         toggleableCategories.map((category) => /* @__PURE__ */ (0, import_jsx_runtime8.jsx)(
           import_FormControlLabel.default,
@@ -1510,6 +1571,7 @@ var init_PreferencesModal = __esm({
     import_react2 = require("react");
     init_CategoriesContext();
     init_useConsent();
+    init_DesignContext();
     init_Branding();
     import_jsx_runtime8 = require("react/jsx-runtime");
   }

package/dist/index.d.cts

@@ -567,7 +567,7 @@ interface DesignTokens {
             mobile?: string;
             desktop?: string;
         };
-        backdrop?: boolean;
+        backdrop?: boolean | string;
     };
 }
 /**
@@ -713,6 +713,22 @@ interface ConsentProviderProps {
      * - `true`: Banner bloqueia interação até decisão (compliance rigorosa)
      */
     blocking?: boolean;
+    /**
+     * Estratégia de bloqueio quando `blocking` estiver habilitado.
+     * - 'auto' (padrão):
+     *   - Se usar o banner padrão da lib, o bloqueio visual/funcional fica a cargo do próprio banner.
+     *   - Se usar `CookieBannerComponent` custom, o Provider NÃO cria overlay; o bloqueio fica a cargo do componente custom (compatibilidade atual).
+     * - 'provider': o Provider cria um overlay de bloqueio por cima da aplicação (e abaixo do banner),
+     *   garantindo que cliques sejam bloqueados, independentemente do banner custom implementar ou não esse comportamento.
+     * - 'component': nenhum overlay do Provider; espera-se que o banner (padrão ou custom) trate o bloqueio.
+     *
+     * Observações:
+     * - Visual do overlay do Provider controlado por `designTokens.layout.backdrop`:
+     *   - `false`: overlay transparente (bloqueia cliques sem escurecer — útil quando o app já possui um dark-filter visual próprio).
+     *   - `string` (ex.: 'rgba(0,0,0,0.4)'): overlay com escurecimento gerenciado pela lib.
+     * - A11y: recomenda-se que o banner use semântica de diálogo (role="dialog", aria-modal="true") e trap de foco.
+     */
+    blockingStrategy?: 'auto' | 'provider' | 'component';
     /** Oculta o branding "fornecido por LÉdipO.eti.br" dos componentes. */
     hideBranding?: boolean;
     /**
@@ -776,6 +792,12 @@ interface CustomCookieBannerProps {
     rejectAll: () => void;
     openPreferences: () => void;
     texts: ConsentTexts;
+    /**
+     * Indica se o modo bloqueante está ativo no contexto.
+     * Esta prop é apenas informativa para banners customizados ajustarem sua UI.
+     * O bloqueio funcional pode ser garantido pelo Provider quando `blockingStrategy='provider'`.
+     */
+    blocking?: boolean;
 }
 /**
  * Props esperadas por um componente customizado de PreferencesModal.
@@ -883,7 +905,7 @@ interface ConsentContextValue {
  * </ConsentProvider>
  * ```
  */
-declare function ConsentProvider({ initialState, categories, texts: textsProp, theme, designTokens, PreferencesModalComponent, preferencesModalProps, CookieBannerComponent, cookieBannerProps, FloatingPreferencesButtonComponent, floatingPreferencesButtonProps, disableFloatingPreferencesButton, hideBranding, onConsentGiven, onPreferencesSaved, cookie: cookieOpts, disableDeveloperGuidance, children, }: Readonly<ConsentProviderProps>): react_jsx_runtime.JSX.Element;
+declare function ConsentProvider({ initialState, categories, texts: textsProp, theme, designTokens, PreferencesModalComponent, preferencesModalProps, CookieBannerComponent, cookieBannerProps, FloatingPreferencesButtonComponent, floatingPreferencesButtonProps, disableFloatingPreferencesButton, blocking, blockingStrategy, hideBranding, onConsentGiven, onPreferencesSaved, cookie: cookieOpts, disableDeveloperGuidance, children, }: Readonly<ConsentProviderProps>): react_jsx_runtime.JSX.Element;
 declare const defaultTexts: ConsentTexts;
 
 /**
@@ -916,7 +938,7 @@ declare const defaultTexts: ConsentTexts;
  * - **`setPreferences(preferences)`**: Define múltiplas categorias de uma vez
  * - **`openPreferences()`**: Abre o modal de preferências
  * - **`closePreferences()`**: Fecha o modal de preferências
- * - **`resetConsent()`**: Limpa todo consentimento (volta ao estado inicial)
+ * - **`resetConsent()`**: Limpa all  consentimento (volta ao estado inicial)
  *
  * ### Performance e SSR
  * - O hook é otimizado com `useMemo` interno para evitar re-renders desnecessários
@@ -1972,7 +1994,7 @@ interface CookieBannerProps {
  * <ConsentProvider CookieBannerComponent={CustomBanner}>
  * ```
  *
- * @param props - Propriedades para customizar comportamento e aparência do banner
+ * @param props - Propriedades para customizar comportamento e aparência do banner (tipado via CookieBannerProps)
  * @returns Banner de consentimento ou `null` se não deve ser exibido
  *
  * @example Uso básico (renderizado automaticamente pelo ConsentProvider)