@react-lgpd-consent/mui 0.5.0 → 0.6.1

package/dist/index.d.cts

@@ -9,70 +9,299 @@ import { SnackbarProps } from '@mui/material/Snackbar';
 import { FabProps } from '@mui/material/Fab';
 import { DialogProps } from '@mui/material/Dialog';
 
+/**
+ * Propriedades para o componente Branding.
+ *
+ * @remarks
+ * Define como o branding da biblioteca ("fornecido por LÉdipO.eti.br")
+ * será exibido em diferentes contextos (banner ou modal).
+ *
+ * @category Components
+ * @public
+ * @since 1.0.0
+ *
+ * @example
+ * ```tsx
+ * <Branding variant="banner" />
+ * <Branding variant="modal" hidden={true} />
+ * ```
+ */
 interface BrandingProps {
+    /**
+     * Variante de exibição do branding.
+     *
+     * @remarks
+     * - `banner`: Estilo otimizado para o CookieBanner (menor, alinhado à direita)
+     * - `modal`: Estilo otimizado para o PreferencesModal (com padding lateral)
+     *
+     * Cada variante aplica estilos específicos de tamanho, alinhamento e espaçamento.
+     */
     variant: 'banner' | 'modal';
+    /**
+     * Se `true`, oculta completamente o componente.
+     *
+     * @remarks
+     * Útil para controlar a visibilidade do branding dinamicamente sem
+     * remover o componente da árvore React.
+     *
+     * @defaultValue false
+     */
     hidden?: boolean;
 }
 /**
- * Componente de branding - memoizado para evitar re-renders desnecessários.
- * Props são estáveis (variant, hidden) e hooks são otimizados.
+ * Componente de branding que exibe crédito "fornecido por LÉdipO.eti.br".
+ *
+ * @component
+ * @category Components
+ * @public
+ * @since 1.0.0
+ *
+ * @remarks
+ * Este componente exibe uma assinatura discreta da biblioteca em banners e modais.
+ * É open-source e gratuito - o branding é uma forma de apoiar o projeto.
+ *
+ * ### Características
+ * - **Memoizado**: Evita re-renders desnecessários (props são estáveis)
+ * - **Design tokens**: Respeita cores customizadas do contexto
+ * - **Responsivo**: Adapta-se ao tema light/dark automaticamente
+ * - **SSR-safe**: Compatível com Server-Side Rendering
+ * - **Acessibilidade**: Link com `rel="noopener noreferrer"` para segurança
+ *
+ * ### Estilos por Variante
+ * - **Banner**: Menor (0.65rem), alinhado à direita, margem superior
+ * - **Modal**: Menor (0.65rem), alinhado à direita, padding lateral e inferior
+ *
+ * ### Visibilidade
+ * Pode ser ocultado via:
+ * - Prop `hidden={true}` (controle direto)
+ * - Prop `hideBranding={true}` no ConsentProvider (afeta todos os componentes)
+ *
+ * @param props - Propriedades do componente (tipado via BrandingProps)
+ * @returns Elemento JSX do branding ou null se oculto
+ *
+ * @example Uso no banner
+ * ```tsx
+ * <Branding variant="banner" />
+ * ```
+ *
+ * @example Uso no modal
+ * ```tsx
+ * <Branding variant="modal" />
+ * ```
+ *
+ * @example Oculto dinamicamente
+ * ```tsx
+ * const [showBranding, setShowBranding] = useState(true)
+ * <Branding variant="banner" hidden={!showBranding} />
+ * ```
+ *
+ * @example Ocultar via Provider
+ * ```tsx
+ * <ConsentProvider
+ *   categories={{ enabledCategories: ['analytics'] }}
+ *   hideBranding={true}
+ * >
+ *   <App />
+ * </ConsentProvider>
+ * ```
+ *
+ * @see {@link BrandingProps} - Interface de propriedades
+ * @see {@link CookieBanner} - Usa este componente internamente
+ * @see {@link PreferencesModal} - Usa este componente internamente
  */
 declare const Branding: React.NamedExoticComponent<Readonly<BrandingProps>>;
 
 /**
- * Props do ConsentProvider com suporte a componentes MUI.
- * Estende as props do core com valores padrão para componentes UI.
+ * Propriedades do ConsentProvider com suporte a componentes Material-UI integrados.
+ *
+ * @remarks
+ * Estende as props do `ConsentProviderCore` com valores padrão para componentes UI.
+ * Este Provider é o ponto de entrada principal para uso da biblioteca com Material-UI,
+ * oferecendo uma experiência "batteries included" (tudo pronto para uso).
  *
- * @category Types
+ * ### Diferenças do Core
+ * - ✅ Injeção automática de `PreferencesModal`, `CookieBanner` e `FloatingPreferencesButton`
+ * - ✅ Suporte a tema Material-UI via `ThemeProvider`
+ * - ✅ Props dedicadas para desabilitar componentes padrão
+ * - ✅ Não requer configuração manual de componentes UI
+ *
+ * ### Quando Usar Este Provider
+ * - Você está usando Material-UI no seu projeto
+ * - Quer começar rápido com UI pronta
+ * - Prefere defaults sensatos com possibilidade de override
+ *
+ * ### Quando Usar o Core
+ * - Você quer controle total sobre a UI
+ * - Está usando outra biblioteca de UI (Chakra, Ant Design, etc.)
+ * - Prefere implementação headless
+ *
+ * @category Components
  * @public
  * @since 0.5.0
+ *
+ * @example Uso básico com defaults
+ * ```tsx
+ * import { ConsentProvider } from '@react-lgpd-consent/mui'
+ *
+ * <ConsentProvider categories={{ enabledCategories: ['analytics'] }}>
+ *   <App />
+ * </ConsentProvider>
+ * ```
+ *
+ * @example Com tema customizado
+ * ```tsx
+ * import { createTheme } from '@mui/material/styles'
+ * import { ConsentProvider } from '@react-lgpd-consent/mui'
+ *
+ * const theme = createTheme({
+ *   palette: {
+ *     primary: { main: '#1976d2' }
+ *   }
+ * })
+ *
+ * <ConsentProvider
+ *   theme={theme}
+ *   categories={{ enabledCategories: ['analytics'] }}
+ * >
+ *   <App />
+ * </ConsentProvider>
+ * ```
+ *
+ * @example Desabilitando componentes padrão
+ * ```tsx
+ * <ConsentProvider
+ *   categories={{ enabledCategories: ['analytics'] }}
+ *   disableDefaultModal={true}
+ *   disableDefaultBanner={true}
+ *   disableDefaultFloatingButton={true}
+ * >
+ *   <App />
+ * </ConsentProvider>
+ * ```
  */
 interface ConsentProviderProps extends ConsentProviderProps$1 {
     /**
      * Se `true`, desabilita a injeção automática do PreferencesModal.
-     * Use isso se quiser passar seu próprio modal via `PreferencesModalComponent`.
      *
-     * @default false
+     * @remarks
+     * Use isso quando quiser passar seu próprio modal via `PreferencesModalComponent`
+     * ou quando quiser implementação totalmente headless.
+     *
+     * Quando `false` (padrão), o modal padrão do MUI é renderizado automaticamente
+     * quando o usuário clica em "Preferências" ou "Gerenciar".
+     *
+     * @defaultValue false
      * @since 0.5.0
+     *
+     * @example
+     * ```tsx
+     * function MyModal() {
+     *   const { closePreferences } = useConsent()
+     *   return <div>Meu modal customizado</div>
+     * }
+     *
+     * <ConsentProvider
+     *   disableDefaultModal={true}
+     *   PreferencesModalComponent={MyModal}
+     * >
+     *   <App />
+     * </ConsentProvider>
+     * ```
      */
     disableDefaultModal?: boolean;
     /**
-     * Se `true`, desabilita a injeção automática do CookieBanner padrão.
-     * Útil quando se deseja uma implementação própria, mantendo outras integrações.
+     * Se `true`, desabilita a injeção automática do CookieBanner.
+     *
+     * @remarks
+     * Útil quando você quer uma implementação própria de banner,
+     * mantendo outras integrações (modal, botão flutuante).
      *
-     * @default false
+     * Quando `false` (padrão), o banner padrão do MUI é renderizado
+     * automaticamente quando o usuário ainda não consentiu.
+     *
+     * @defaultValue false
      * @since 0.5.0
+     *
+     * @example
+     * ```tsx
+     * function MyBanner() {
+     *   const { acceptAll, rejectAll } = useConsent()
+     *   return <div>Meu banner customizado</div>
+     * }
+     *
+     * <ConsentProvider
+     *   disableDefaultBanner={true}
+     *   CookieBannerComponent={MyBanner}
+     * >
+     *   <App />
+     * </ConsentProvider>
+     * ```
      */
     disableDefaultBanner?: boolean;
     /**
      * Se `true`, desabilita a injeção automática do FloatingPreferencesButton.
-     * Normalmente não é necessário — `disableFloatingPreferencesButton` já oculta o botão.
      *
-     * @default false
+     * @remarks
+     * Útil quando você quer controlar completamente como usuários reacessam
+     * suas preferências (ex: link no footer, menu de configurações).
+     *
+     * **Nota**: `disableFloatingPreferencesButton` do core também oculta o botão,
+     * mas esta prop impede completamente a renderização do componente.
+     *
+     * @defaultValue false
      * @since 0.5.0
+     *
+     * @example
+     * ```tsx
+     * <ConsentProvider
+     *   disableDefaultFloatingButton={true}
+     *   categories={{ enabledCategories: ['analytics'] }}
+     * >
+     *   <App />
+     * </ConsentProvider>
+     * ```
      */
     disableDefaultFloatingButton?: boolean;
     /**
-     * Tema Material-UI a ser aplicado ao redor dos componentes padrões.
+     * Tema Material-UI a ser aplicado ao redor dos componentes padrão.
      *
      * @remarks
-     * O tema é aplicado apenas nesta camada de apresentação. O core permanece agnóstico.
+     * O tema é aplicado apenas nesta camada de apresentação via `ThemeProvider`.
+     * O core permanece agnóstico de UI.
+     *
+     * Se você já tem um `ThemeProvider` no seu app, os componentes
+     * herdarão automaticamente. Esta prop é opcional e útil quando você quer
+     * um tema específico apenas para os componentes de consentimento.
+     *
+     * @defaultValue undefined (herda tema do contexto pai)
+     * @since 0.5.0
      *
      * @example
      * ```tsx
-     * const theme = createTheme({ palette: { primary: { main: '#1976d2' } } })
-     * <ConsentProvider theme={theme} />
-     * ```
+     * import { createTheme } from '@mui/material/styles'
      *
-     * @since 0.5.0
+     * const consentTheme = createTheme({
+     *   palette: {
+     *     primary: { main: '#2e7d32' },
+     *     background: { paper: '#fafafa' }
+     *   },
+     *   typography: {
+     *     fontFamily: 'Inter, sans-serif'
+     *   }
+     * })
+     *
+     * <ConsentProvider
+     *   theme={consentTheme}
+     *   categories={{ enabledCategories: ['analytics'] }}
+     * >
+     *   <App />
+     * </ConsentProvider>
+     * ```
      */
     theme?: Theme;
 }
 /**
- * Provider de consentimento com componentes Material-UI integrados.
- *
- * Este componente é um wrapper sobre o `ConsentProvider` do core que automaticamente
- * fornece um `PreferencesModal` padrão, tornando o setup mais simples.
+ * Provider de consentimento com componentes Material-UI integrados ("batteries included").
  *
  * @component
  * @category Components
@@ -80,32 +309,97 @@ interface ConsentProviderProps extends ConsentProviderProps$1 {
  * @since 0.5.0
  *
  * @remarks
- * **Diferenças do Core:**
- * - ✅ Automaticamente renderiza `PreferencesModal` quando o usuário clica em "Preferências"
- * - ✅ Não requer configuração de `PreferencesModalComponent` (mas permite override)
- * - ✅ Ideal para uso rápido com Material-UI
+ * Este componente é um wrapper sobre o `ConsentProvider` do core que automaticamente
+ * injeta `PreferencesModal`, `CookieBanner` e `FloatingPreferencesButton` com estilos MUI,
+ * tornando o setup extremamente simples e rápido.
  *
- * **Quando usar o Core diretamente:**
- * - ❌ Se você quiser controle total sobre qual modal renderizar
- * - ❌ Se você estiver usando uma biblioteca de UI diferente
- * - ❌ Se você quiser implementação headless
+ * ### Características Principais
+ * - ✅ **Injeção Automática**: Renderiza modal, banner e botão flutuante sem configuração
+ * - ✅ **Tema Material-UI**: Aceita `theme` prop para customização de cores e tipografia
+ * - ✅ **Override Flexível**: Permite substituir componentes padrão via props `*Component`
+ * - ✅ **Desabilitar Seletivo**: Props `disable*` para controle granular de UI
+ * - ✅ **SSR-Safe**: Compatível com NextJS e outros frameworks SSR
+ * - ✅ **Tree-shakeable**: Apenas o que você usa é incluído no bundle
  *
- * @example
- * **Uso Básico (Modal automático):**
+ * ### Diferenças do Core Provider
+ * | Recurso | MUI Provider | Core Provider |
+ * |---------|--------------|---------------|
+ * | Modal padrão | ✅ Automático | ❌ Manual |
+ * | Banner padrão | ✅ Automático | ❌ Manual |
+ * | Botão flutuante | ✅ Automático | ❌ Manual |
+ * | Suporte a tema MUI | ✅ Sim | ❌ Não |
+ * | Tamanho bundle | ~104KB | ~86KB |
+ * | Headless | Via `disable*` | ✅ Nativo |
+ *
+ * ### Quando Usar Este Provider
+ * - ✅ Você está usando Material-UI no projeto
+ * - ✅ Quer começar rápido sem configurar UI
+ * - ✅ Prefere defaults sensatos com possibilidade de override
+ * - ✅ Precisa de acessibilidade pronta (ARIA labels, keyboard nav)
+ *
+ * ### Quando Usar o Core Provider
+ * - ❌ Você quer controle total sobre a UI
+ * - ❌ Está usando outra biblioteca (Chakra, Ant Design, Tailwind)
+ * - ❌ Precisa de bundle mínimo (~18KB a menos)
+ * - ❌ Quer implementação 100% headless
+ *
+ * ### Estrutura de Renderização
+ * ```
+ * ConsentProviderCore
+ *   └─ ThemeProvider (se theme fornecido)
+ *      ├─ children (sua aplicação)
+ *      ├─ CookieBanner (se não desabilitado e sem consentimento)
+ *      ├─ PreferencesModal (se não desabilitado e preferências abertas)
+ *      └─ FloatingPreferencesButton (se não desabilitado)
+ * ```
+ *
+ * @param props - Propriedades do provider (estende ConsentProviderCoreProps)
+ * @returns Elemento React contendo o provider de contexto e componentes UI integrados
+ *
+ * @throws {Error} Se `categories.enabledCategories` não for fornecido (validação do core)
+ *
+ * @example Uso Básico (Modal + Banner + Botão Automáticos)
  * ```tsx
  * import { ConsentProvider } from '@react-lgpd-consent/mui'
  *
  * function App() {
  *   return (
- *     <ConsentProvider categories={{ enabledCategories: ['analytics'] }}>
+ *     <ConsentProvider
+ *       categories={{
+ *         enabledCategories: ['analytics', 'marketing']
+ *       }}
+ *     >
  *       <YourApp />
  *     </ConsentProvider>
  *   )
  * }
  * ```
  *
- * @example
- * **Modal customizado:**
+ * @example Com Tema Customizado MUI
+ * ```tsx
+ * import { createTheme } from '@mui/material/styles'
+ * import { ConsentProvider } from '@react-lgpd-consent/mui'
+ *
+ * const theme = createTheme({
+ *   palette: {
+ *     primary: { main: '#2e7d32' },
+ *     background: { paper: '#fafafa' }
+ *   }
+ * })
+ *
+ * function App() {
+ *   return (
+ *     <ConsentProvider
+ *       theme={theme}
+ *       categories={{ enabledCategories: ['analytics'] }}
+ *     >
+ *       <YourApp />
+ *     </ConsentProvider>
+ *   )
+ * }
+ * ```
+ *
+ * @example Override de Componentes Padrão
  * ```tsx
  * import { ConsentProvider, PreferencesModal } from '@react-lgpd-consent/mui'
  *
@@ -116,6 +410,7 @@ interface ConsentProviderProps extends ConsentProviderProps$1 {
  *       PreferencesModalComponent={(props) => (
  *         <PreferencesModal {...props} hideBranding={true} />
  *       )}
+ *       CookieBannerComponent={() => <div>Meu banner customizado</div>}
  *     >
  *       <YourApp />
  *     </ConsentProvider>
@@ -123,28 +418,55 @@ interface ConsentProviderProps extends ConsentProviderProps$1 {
  * }
  * ```
  *
- * @example
- * **Desabilitar modal padrão (headless):**
+ * @example Modo Headless (Desabilitando UI Padrão)
  * ```tsx
  * import { ConsentProvider } from '@react-lgpd-consent/mui'
+ * import { useConsent } from '@react-lgpd-consent/core'
+ *
+ * function CustomUI() {
+ *   const { acceptAll, rejectAll } = useConsent()
+ *   return <div>Minha UI totalmente customizada</div>
+ * }
  *
  * function App() {
  *   return (
  *     <ConsentProvider
  *       categories={{ enabledCategories: ['analytics'] }}
  *       disableDefaultModal={true}
+ *       disableDefaultBanner={true}
+ *       disableDefaultFloatingButton={true}
  *     >
+ *       <CustomUI />
  *       <YourApp />
  *     </ConsentProvider>
  *   )
  * }
  * ```
  *
- * @param props - Props do provider incluindo categorias, textos, callbacks, etc.
- * @returns Provider React com contexto de consentimento e UI integrada
+ * @example Com Callbacks de Eventos
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <ConsentProvider
+ *       categories={{ enabledCategories: ['analytics', 'marketing'] }}
+ *       onConsentChange={(newState) => {
+ *         console.log('Novo estado:', newState)
+ *         // Enviar evento para analytics
+ *       }}
+ *       onPreferencesOpen={() => console.log('Modal aberto')}
+ *       onPreferencesClose={() => console.log('Modal fechado')}
+ *     >
+ *       <YourApp />
+ *     </ConsentProvider>
+ *   )
+ * }
+ * ```
  *
  * @see {@link ConsentProviderCore} Para a versão headless sem UI
  * @see {@link PreferencesModal} Para o componente de modal usado por padrão
+ * @see {@link CookieBanner} Para o componente de banner usado por padrão
+ * @see {@link FloatingPreferencesButton} Para o botão flutuante usado por padrão
+ * @see {@link https://mui.com/material-ui/customization/theming/ | MUI Theming Guide} Para customização de tema
  */
 declare function ConsentProvider({ disableDefaultModal, disableDefaultBanner, disableDefaultFloatingButton, PreferencesModalComponent, CookieBannerComponent, FloatingPreferencesButtonComponent, theme, hideBranding, cookieBannerProps, preferencesModalProps, floatingPreferencesButtonProps, children, ...coreProps }: ConsentProviderProps): react_jsx_runtime.JSX.Element;
 declare namespace ConsentProvider {
@@ -382,45 +704,268 @@ interface CookieBannerProps {
 declare function CookieBanner({ policyLinkUrl, termsLinkUrl, debug, blocking, hideBranding, SnackbarProps, PaperProps, }: Readonly<CookieBannerProps>): react_jsx_runtime.JSX.Element | null;
 
 /**
- * Props para o componente FloatingPreferencesButton.
+ * Propriedades para customizar o comportamento e aparência do FloatingPreferencesButton.
+ *
+ * @remarks
+ * Interface que permite controle completo sobre o botão flutuante de preferências LGPD.
+ * O botão aparece após o consentimento inicial para permitir que usuários revisitem
+ * suas escolhas a qualquer momento.
+ *
+ * ### Posicionamento
+ * Suporta 4 posições fixas na tela:
+ * - `bottom-left`: Canto inferior esquerdo
+ * - `bottom-right`: Canto inferior direito (padrão)
+ * - `top-left`: Canto superior esquerdo
+ * - `top-right`: Canto superior direito
  *
- * Permite configurar posição, ícone, tooltip, e comportamento de exibição do botão flutuante
- * para abrir o modal de preferências de cookies LGPD.
+ * ### Customização Visual
+ * - **Ícone**: Pode ser substituído por qualquer `ReactNode`
+ * - **Tooltip**: Texto exibido ao hover (padrão vem de `useConsentTexts`)
+ * - **Cores**: Respeita design tokens ou tema MUI
+ * - **Offset**: Distância da borda em pixels
  *
- * Todos os campos são opcionais e possuem valores padrão.
+ * ### Comportamento
+ * - **Auto-hide**: Opcional via `hideWhenConsented` (padrão: `false`)
+ * - **Z-index**: 1200 (acima de conteúdo normal, abaixo de modais MUI)
+ * - **Transições**: Suaves via tema MUI
+ *
+ * @category Components
+ * @public
+ * @since 0.3.0
+ *
+ * @example Configuração básica
+ * ```tsx
+ * <FloatingPreferencesButton
+ *   position="bottom-left"
+ *   offset={16}
+ * />
+ * ```
+ *
+ * @example Customização avançada
+ * ```tsx
+ * import SettingsIcon from '@mui/icons-material/Settings'
+ *
+ * <FloatingPreferencesButton
+ *   position="top-right"
+ *   offset={32}
+ *   icon={<SettingsIcon />}
+ *   tooltip="Configurações de Privacidade"
+ *   hideWhenConsented={true}
+ *   FabProps={{
+ *     size: 'large',
+ *     color: 'secondary',
+ *     sx: { boxShadow: 3 }
+ *   }}
+ * />
+ * ```
  */
 interface FloatingPreferencesButtonProps {
-    /** Posição do botão flutuante. Padrão: 'bottom-right' */
+    /**
+     * Posição do botão flutuante na tela.
+     *
+     * @remarks
+     * Define o canto da viewport onde o botão será fixado.
+     * Usa `position: fixed` e responde a scroll da página.
+     *
+     * @defaultValue 'bottom-right'
+     */
     position?: 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right';
-    /** Offset da borda em pixels. Padrão: 24 */
+    /**
+     * Offset (distância) da borda em pixels.
+     *
+     * @remarks
+     * Aplicado tanto horizontal quanto verticalmente dependendo da posição.
+     * Exemplo: `offset={24}` em `bottom-right` = 24px da direita e 24px do fundo.
+     *
+     * @defaultValue 24
+     */
     offset?: number;
-    /** Ícone customizado. Padrão: CookieOutlined */
+    /**
+     * Ícone customizado para o botão.
+     *
+     * @remarks
+     * Pode ser qualquer ReactNode: ícone do MUI, SVG, imagem, texto, etc.
+     * Se omitido, usa `<CookieOutlined />` do Material-UI Icons.
+     *
+     * @defaultValue `<CookieOutlined />`
+     *
+     * @example
+     * ```tsx
+     * import SettingsIcon from '@mui/icons-material/Settings'
+     * <FloatingPreferencesButton icon={<SettingsIcon />} />
+     * ```
+     */
     icon?: React.ReactNode;
-    /** Tooltip customizado exibido ao passar o mouse */
+    /**
+     * Tooltip customizado exibido ao passar o mouse.
+     *
+     * @remarks
+     * Se omitido, usa o valor de `texts.preferencesButton` do contexto,
+     * com fallback para "Gerenciar Preferências de Cookies".
+     *
+     * @defaultValue undefined (usa texto do contexto)
+     *
+     * @example
+     * ```tsx
+     * <FloatingPreferencesButton tooltip="Configurações de Privacidade" />
+     * ```
+     */
     tooltip?: string;
-    /** Props adicionais para o Fab do MUI */
+    /**
+     * Props adicionais para o componente Fab do Material-UI.
+     *
+     * @remarks
+     * Permite customização completa do botão: tamanho, cor, elevação, sx, etc.
+     * Props passadas aqui sobrescrevem os defaults internos.
+     *
+     * @defaultValue undefined
+     *
+     * @example
+     * ```tsx
+     * <FloatingPreferencesButton
+     *   FabProps={{
+     *     size: 'large',
+     *     color: 'secondary',
+     *     variant: 'extended',
+     *     sx: { borderRadius: 2 }
+     *   }}
+     * />
+     * ```
+     */
     FabProps?: Partial<FabProps>;
-    /** Se deve esconder quando consentimento já foi dado. Padrão: false */
+    /**
+     * Se deve esconder o botão quando consentimento já foi dado.
+     *
+     * @remarks
+     * Útil para reduzir poluição visual após decisão inicial.
+     * Quando `true`, botão só aparece se `consented === false`.
+     *
+     * **Importante**: Mesmo escondido, usuário pode reabrir preferências
+     * via outras formas (ex: link no footer, menu de configurações).
+     *
+     * @defaultValue false
+     */
     hideWhenConsented?: boolean;
 }
 /**
+ * Componente interno do botão flutuante de preferências.
+ * @internal
+ * @category Components
+ * @param {FloatingPreferencesButtonProps} props - Propriedades do componente.
+ * @returns {JSX.Element | null} Elemento JSX do botão ou null se oculto.
+ * @remarks Memoiza estilos de posição para performance. Usa design tokens defensivamente.
+ */
+declare function FloatingPreferencesButtonComponent({ position, offset, icon, tooltip, FabProps, hideWhenConsented, }: Readonly<FloatingPreferencesButtonProps>): react_jsx_runtime.JSX.Element | null;
+/**
+ * Botão flutuante (FAB) para reabrir o modal de preferências de consentimento LGPD.
+ *
  * @component
  * @category Components
+ * @public
  * @since 0.3.0
- * Botão flutuante para abrir o modal de preferências de cookies.
  *
  * @remarks
- * Este componente é renderizado automaticamente pelo `ConsentProvider` após o consentimento inicial.
- * Ele permite ao usuário acessar rapidamente as configurações de consentimento LGPD a qualquer momento.
- * Você pode substituí-lo passando seu próprio componente para a prop `FloatingPreferencesButtonComponent`
- * no `ConsentProvider`.
+ * Este componente fornece acesso rápido e sempre visível às preferências de consentimento,
+ * permitindo que usuários revisem e alterem suas escolhas a qualquer momento.
+ *
+ * ### Renderização Automática
+ * O botão é renderizado automaticamente pelo `ConsentProvider` após o consentimento inicial,
+ * a menos que desabilitado via `disableFloatingPreferencesButton={true}`.
+ *
+ * ### Funcionalidades
+ * - **Posição fixa**: Permanece visível durante scroll
+ * - **Z-index 1200**: Fica acima do conteúdo normal, abaixo de modais
+ * - **Tooltip acessível**: ARIA label e tooltip ao hover
+ * - **Responsivo**: Funciona em mobile e desktop
+ * - **Transições suaves**: Animação de cor ao hover via tema MUI
+ * - **Design tokens**: Respeita cores customizadas do contexto
+ *
+ * ### Customização
+ * Você pode:
+ * - Alterar posição e offset
+ * - Trocar o ícone padrão (cookie)
+ * - Modificar tooltip
+ * - Ocultar quando já consentido
+ * - Passar props customizadas para o Fab do MUI
+ *
+ * ### Substituição Completa
+ * Para controle total, passe seu próprio componente:
+ *
+ * ```tsx
+ * function MyCustomButton() {
+ *   const { openPreferences } = useConsent()
+ *   return <button onClick={openPreferences}>Preferências</button>
+ * }
+ *
+ * <ConsentProvider
+ *   FloatingPreferencesButtonComponent={MyCustomButton}
+ * >
+ *   <App />
+ * </ConsentProvider>
+ * ```
+ *
+ * @param props - Propriedades para customizar o botão (tipado via FloatingPreferencesButtonProps)
+ * @returns Elemento JSX do botão flutuante ou null se oculto
+ *
+ * @throws {Error} Se usado fora do ConsentProvider (contexto não disponível)
+ *
+ * @example Uso básico (renderizado automaticamente)
+ * ```tsx
+ * // ConsentProvider já renderiza FloatingPreferencesButton automaticamente
+ * <ConsentProvider categories={{ enabledCategories: ['analytics'] }}>
+ *   <App />
+ * </ConsentProvider>
+ * ```
+ *
+ * @example Customização via props no Provider
+ * ```tsx
+ * <ConsentProvider
+ *   categories={{ enabledCategories: ['analytics'] }}
+ *   floatingPreferencesButtonProps={{
+ *     position: 'bottom-left',
+ *     offset: 16,
+ *     hideWhenConsented: true
+ *   }}
+ * >
+ *   <App />
+ * </ConsentProvider>
+ * ```
+ *
+ * @example Uso manual com ícone customizado
+ * ```tsx
+ * import SettingsIcon from '@mui/icons-material/Settings'
  *
- * Componente memoizado para otimizar performance - só re-renderiza quando props mudam.
+ * function App() {
+ *   return (
+ *     <FloatingPreferencesButton
+ *       position="top-right"
+ *       icon={<SettingsIcon />}
+ *       tooltip="Configurações de Privacidade"
+ *       FabProps={{
+ *         size: 'large',
+ *         color: 'secondary'
+ *       }}
+ *     />
+ *   )
+ * }
+ * ```
  *
- * @param {Readonly<FloatingPreferencesButtonProps>} props As propriedades para customizar o botão.
- * @returns {JSX.Element | null} O componente do botão flutuante ou `null` se não for necessário exibi-lo.
+ * @example Desabilitar completamente
+ * ```tsx
+ * <ConsentProvider
+ *   categories={{ enabledCategories: ['analytics'] }}
+ *   disableFloatingPreferencesButton={true}
+ * >
+ *   <App />
+ * </ConsentProvider>
+ * ```
+ *
+ * @see {@link ConsentProvider} - Provider que renderiza este componente automaticamente
+ * @see {@link useConsent} - Hook para acessar função openPreferences
+ * @see {@link FloatingPreferencesButtonProps} - Interface completa de propriedades
+ * @see {@link PreferencesModal} - Modal aberto ao clicar no botão
  */
-declare const FloatingPreferencesButton: React.NamedExoticComponent<Readonly<FloatingPreferencesButtonProps>>;
+declare const FloatingPreferencesButton: React.MemoExoticComponent<typeof FloatingPreferencesButtonComponent>;
 
 declare global {
     /**
@@ -431,38 +976,236 @@ declare global {
     var __LGPD_USED_INTEGRATIONS__: string[] | undefined;
 }
 /**
- * @interface PreferencesModalProps
- * Propriedades para customizar o componente `PreferencesModal`.
+ * Propriedades para customizar o comportamento e aparência do componente PreferencesModal.
+ *
+ * @remarks
+ * Esta interface permite controle total sobre o modal de preferências de consentimento LGPD.
+ * O modal pode ser usado de duas formas:
+ * - **Automático**: Renderizado pelo ConsentProvider quando usuário clica em "Preferências"
+ * - **Manual**: Controlado externamente via props `isModalOpen`, `preferences`, etc.
+ *
+ * ### Integração com Material-UI
+ * - Suporte completo a theming via `ThemeProvider`
+ * - Props diretas para Dialog do MUI via `DialogProps`
+ * - Compatibilidade com design tokens customizados
+ *
+ * @category Components
+ * @public
+ * @since 0.1.0
+ *
+ * @example Uso automático (renderizado pelo Provider)
+ * ```tsx
+ * <ConsentProvider
+ *   categories={{ enabledCategories: ['analytics'] }}
+ *   preferencesModalProps={{ hideBranding: true }}
+ * >
+ *   <App />
+ * </ConsentProvider>
+ * ```
+ *
+ * @example Uso manual com controle externo
+ * ```tsx
+ * function CustomPreferencesModal() {
+ *   const [open, setOpen] = useState(false)
+ *   const { preferences, setPreferences } = useConsent()
+ *
+ *   return (
+ *     <PreferencesModal
+ *       isModalOpen={open}
+ *       preferences={preferences}
+ *       setPreferences={setPreferences}
+ *       closePreferences={() => setOpen(false)}
+ *       DialogProps={{ maxWidth: 'md' }}
+ *     />
+ *   )
+ * }
+ * ```
  */
 interface PreferencesModalProps {
-    /** Propriedades opcionais para customizar o componente `Dialog` do Material-UI. */
+    /**
+     * Propriedades opcionais para customizar o componente `Dialog` do Material-UI.
+     *
+     * @remarks
+     * Permite customização avançada do comportamento do modal: posição, transição,
+     * largura máxima, e outros atributos do Dialog do MUI.
+     *
+     * @defaultValue undefined
+     *
+     * @example
+     * ```tsx
+     * <PreferencesModal
+     *   DialogProps={{
+     *     maxWidth: 'md',
+     *     fullWidth: true,
+     *     TransitionComponent: Slide
+     *   }}
+     * />
+     * ```
+     */
     DialogProps?: Partial<DialogProps>;
-    /** Se `true`, oculta a marca "fornecido por LÉdipO.eti.br" no modal. Padrão: `false`. */
+    /**
+     * Se `true`, oculta a marca "fornecido por LÉdipO.eti.br" no modal.
+     *
+     * @remarks
+     * A biblioteca é open-source e gratuita. O branding é uma forma de apoiar
+     * o projeto, mas pode ser removido se necessário para sua marca.
+     *
+     * @defaultValue false
+     */
     hideBranding?: boolean;
-    /** Estado de abertura do modal passado pelo Provider. Quando fornecido via PreferencesModalComponent, substitui o valor do hook useConsent. */
+    /**
+     * Estado de abertura do modal passado pelo Provider.
+     *
+     * @remarks
+     * Quando fornecido via `PreferencesModalComponent` no ConsentProvider,
+     * substitui o valor do hook `useConsent`. Permite controle externo do estado.
+     *
+     * @defaultValue undefined (usa valor do contexto)
+     */
     isModalOpen?: boolean;
-    /** Preferências de consentimento passadas pelo Provider. Quando fornecido via PreferencesModalComponent. */
+    /**
+     * Preferências de consentimento passadas pelo Provider.
+     *
+     * @remarks
+     * Quando fornecido via `PreferencesModalComponent`, permite sincronização
+     * externa do estado de preferências. Se omitido, usa o contexto interno.
+     *
+     * @defaultValue undefined (usa valor do contexto)
+     */
     preferences?: ConsentPreferences;
-    /** Função para atualizar preferências passada pelo Provider. Quando fornecido via PreferencesModalComponent. */
+    /**
+     * Função para atualizar preferências passada pelo Provider.
+     *
+     * @remarks
+     * Permite override da função de atualização de preferências.
+     * Útil para integração com gerenciadores de estado externos.
+     *
+     * @param preferences - Novas preferências de consentimento a serem aplicadas
+     * @defaultValue undefined (usa função do contexto)
+     */
     setPreferences?: (preferences: ConsentPreferences) => void;
-    /** Função para fechar o modal passada pelo Provider. Quando fornecido via PreferencesModalComponent. */
+    /**
+     * Função para fechar o modal passada pelo Provider.
+     *
+     * @remarks
+     * Callback invocado quando usuário cancela ou após salvar preferências.
+     * Se omitido, usa a função do contexto.
+     *
+     * @defaultValue undefined (usa função do contexto)
+     */
     closePreferences?: () => void;
 }
 /**
- * O `PreferencesModal` é o componente de UI que permite ao usuário ajustar suas preferências de consentimento.
+ * Modal de preferências de consentimento LGPD que permite ao usuário ajustar suas escolhas.
+ *
  * @component
  * @category Components
+ * @public
  * @since 0.1.0
+ *
  * @remarks
- * Este modal é renderizado automaticamente pelo `ConsentProvider` quando o usuário clica para gerenciar as preferências.
- * Você pode substituí-lo passando seu próprio componente para a prop `PreferencesModalComponent`
- * no `ConsentProvider` para ter controle total sobre a aparência e o comportamento do modal.
- * @param {Readonly<PreferencesModalProps>} props As propriedades para customizar o modal.
- * @returns {JSX.Element} O componente do modal de preferências.
- * @example
+ * O `PreferencesModal` é o componente de UI que apresenta uma interface detalhada
+ * para o usuário gerenciar suas preferências de consentimento categoria por categoria.
+ *
+ * ### Funcionalidades Principais
+ * - **Toggles por categoria**: Switch para cada categoria não-essencial configurada
+ * - **Categoria necessária bloqueada**: Sempre marcada e desabilitada (required by LGPD)
+ * - **Detalhes de cookies**: Accordion expansível mostrando cookies por categoria
+ * - **Mudanças temporárias**: Edições salvas localmente até confirmar com botão "Salvar"
+ * - **Sincronização automática**: Recarrega estado ao abrir o modal
+ * - **Acessibilidade**: ARIA labels, keyboard navigation, screen reader support
+ *
+ * ### Renderização Automática
+ * Este modal é renderizado automaticamente pelo `ConsentProvider` quando o usuário
+ * clica para gerenciar preferências. Não é necessário renderizá-lo manualmente,
+ * a menos que deseje controle total sobre o comportamento.
+ *
+ * ### Customização
+ * Você pode substituir este componente passando seu próprio para a prop
+ * `PreferencesModalComponent` no `ConsentProvider`:
+ *
+ * ```tsx
+ * function MyCustomModal() {
+ *   const { preferences, setPreferences, closePreferences } = useConsent()
+ *   return <div>Meu modal customizado</div>
+ * }
+ *
+ * <ConsentProvider
+ *   PreferencesModalComponent={MyCustomModal}
+ *   categories={{ enabledCategories: ['analytics'] }}
+ * >
+ *   <App />
+ * </ConsentProvider>
+ * ```
+ *
+ * ### Informações de Cookies
+ * O modal exibe automaticamente:
+ * - **Nome do cookie**: Identificador único
+ * - **Finalidade**: Para que serve (Analytics, Marketing, etc.)
+ * - **Duração**: Tempo de vida (sessão, 1 ano, etc.)
+ * - **Fornecedor**: Quem criou/gerencia (Google, Facebook, próprio site)
+ *
+ * Estas informações vêm das integrações ativas (via `getCookiesInfoForCategory`)
+ * e das categorias configuradas no Provider.
+ *
+ * @param props - Propriedades para customizar o modal (tipado via PreferencesModalProps)
+ * @returns Elemento JSX do modal de preferências ou null se não deve ser exibido
+ *
+ * @throws {Error} Se usado fora do ConsentProvider (contexto não disponível)
+ *
+ * @example Uso básico (renderizado automaticamente)
  * ```tsx
- * <PreferencesModal DialogProps={{ maxWidth: 'md' }} hideBranding={true} />
+ * // ConsentProvider já renderiza PreferencesModal automaticamente
+ * function App() {
+ *   return (
+ *     <ConsentProvider categories={{ enabledCategories: ['analytics'] }}>
+ *       <YourApp />
+ *     </ConsentProvider>
+ *   )
+ * }
+ * ```
+ *
+ * @example Customização via props
+ * ```tsx
+ * <ConsentProvider
+ *   categories={{ enabledCategories: ['analytics', 'marketing'] }}
+ *   preferencesModalProps={{
+ *     hideBranding: true,
+ *     DialogProps: {
+ *       maxWidth: 'md',
+ *       fullWidth: true
+ *     }
+ *   }}
+ * >
+ *   <App />
+ * </ConsentProvider>
  * ```
+ *
+ * @example Controle manual completo
+ * ```tsx
+ * function CustomApp() {
+ *   const [open, setOpen] = useState(false)
+ *   const { preferences, setPreferences } = useConsent()
+ *
+ *   return (
+ *     <>
+ *       <button onClick={() => setOpen(true)}>Abrir Preferências</button>
+ *       <PreferencesModal
+ *         isModalOpen={open}
+ *         preferences={preferences}
+ *         setPreferences={setPreferences}
+ *         closePreferences={() => setOpen(false)}
+ *         DialogProps={{ maxWidth: 'lg' }}
+ *       />
+ *     </>
+ *   )
+ * }
+ * ```
+ *
+ * @see {@link ConsentProvider} - Provider que renderiza este componente automaticamente
+ * @see {@link useConsent} - Hook para acessar funções de consentimento
+ * @see {@link PreferencesModalProps} - Interface completa de propriedades
+ * @see {@link getCookiesInfoForCategory} - Função que retorna informações de cookies
  */
 declare function PreferencesModal({ DialogProps, hideBranding, isModalOpen: isModalOpenProp, preferences: preferencesProp, setPreferences: setPreferencesProp, closePreferences: closePreferencesProp, }: Readonly<PreferencesModalProps>): react_jsx_runtime.JSX.Element;