@react-lgpd-consent/mui 0.5.0

package/dist/index.d.cts

@@ -0,0 +1,469 @@
+import { ConsentProviderProps as ConsentProviderProps$1, ConsentPreferences } from '@react-lgpd-consent/core';
+export * from '@react-lgpd-consent/core';
+export { ConsentProvider as ConsentProviderHeadless } from '@react-lgpd-consent/core';
+import * as React from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { Theme } from '@mui/material/styles';
+import { PaperProps } from '@mui/material/Paper';
+import { SnackbarProps } from '@mui/material/Snackbar';
+import { FabProps } from '@mui/material/Fab';
+import { DialogProps } from '@mui/material/Dialog';
+
+interface BrandingProps {
+    variant: 'banner' | 'modal';
+    hidden?: boolean;
+}
+/**
+ * Componente de branding - memoizado para evitar re-renders desnecessários.
+ * Props são estáveis (variant, hidden) e hooks são otimizados.
+ */
+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.
+ *
+ * @category Types
+ * @public
+ * @since 0.5.0
+ */
+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
+     * @since 0.5.0
+     */
+    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.
+     *
+     * @default false
+     * @since 0.5.0
+     */
+    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
+     * @since 0.5.0
+     */
+    disableDefaultFloatingButton?: boolean;
+    /**
+     * Tema Material-UI a ser aplicado ao redor dos componentes padrões.
+     *
+     * @remarks
+     * O tema é aplicado apenas nesta camada de apresentação. O core permanece agnóstico.
+     *
+     * @example
+     * ```tsx
+     * const theme = createTheme({ palette: { primary: { main: '#1976d2' } } })
+     * <ConsentProvider theme={theme} />
+     * ```
+     *
+     * @since 0.5.0
+     */
+    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.
+ *
+ * @component
+ * @category Components
+ * @public
+ * @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
+ *
+ * **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
+ *
+ * @example
+ * **Uso Básico (Modal automático):**
+ * ```tsx
+ * import { ConsentProvider } from '@react-lgpd-consent/mui'
+ *
+ * function App() {
+ *   return (
+ *     <ConsentProvider categories={{ enabledCategories: ['analytics'] }}>
+ *       <YourApp />
+ *     </ConsentProvider>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * **Modal customizado:**
+ * ```tsx
+ * import { ConsentProvider, PreferencesModal } from '@react-lgpd-consent/mui'
+ *
+ * function App() {
+ *   return (
+ *     <ConsentProvider
+ *       categories={{ enabledCategories: ['analytics'] }}
+ *       PreferencesModalComponent={(props) => (
+ *         <PreferencesModal {...props} hideBranding={true} />
+ *       )}
+ *     >
+ *       <YourApp />
+ *     </ConsentProvider>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * **Desabilitar modal padrão (headless):**
+ * ```tsx
+ * import { ConsentProvider } from '@react-lgpd-consent/mui'
+ *
+ * function App() {
+ *   return (
+ *     <ConsentProvider
+ *       categories={{ enabledCategories: ['analytics'] }}
+ *       disableDefaultModal={true}
+ *     >
+ *       <YourApp />
+ *     </ConsentProvider>
+ *   )
+ * }
+ * ```
+ *
+ * @param props - Props do provider incluindo categorias, textos, callbacks, etc.
+ * @returns Provider React com contexto de consentimento e UI integrada
+ *
+ * @see {@link ConsentProviderCore} Para a versão headless sem UI
+ * @see {@link PreferencesModal} Para o componente de modal usado por padrão
+ */
+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 {
+    var displayName: string;
+}
+
+/**
+ * Propriedades para customizar o comportamento e aparência do componente CookieBanner.
+ *
+ * @remarks
+ * Esta interface permite controle completo sobre o banner de consentimento, desde
+ * o comportamento de exibição até a customização visual avançada. O banner pode
+ * operar em dois modos principais: bloqueante (modal) ou não-bloqueante (snackbar).
+ *
+ * ### Modos de Exibição
+ * - **Bloqueante** (`blocking: true`): Banner como modal sobreposto, impede interação
+ * - **Não-bloqueante** (`blocking: false`): Banner como snackbar, permite navegação
+ *
+ * ### Integração com Material-UI
+ * - Suporte completo a theming via `ThemeProvider`
+ * - Props diretas para componentes internos (`SnackbarProps`, `PaperProps`)
+ * - Compatibilidade com design tokens customizados
+ * - Responsividade automática em diferentes viewport sizes
+ *
+ * ### Debug e Desenvolvimento
+ * - Prop `debug` força exibição independente do estado de consentimento
+ * - Logging automático de interações do usuário quando ativo
+ * - Suporte a React DevTools para inspecionar props
+ *
+ * @example Configuração básica
+ * ```tsx
+ * <CookieBanner
+ *   policyLinkUrl="/privacy-policy"
+ *   blocking={false}
+ * />
+ * ```
+ *
+ * @example Configuração avançada com customização
+ * ```tsx
+ * <CookieBanner
+ *   policyLinkUrl="https://example.com/cookies"
+ *   blocking={true}
+ *   hideBranding={true}
+ *   debug={process.env.NODE_ENV === 'development'}
+ *   SnackbarProps={{
+ *     anchorOrigin: { vertical: 'top', horizontal: 'center' }
+ *   }}
+ *   PaperProps={{
+ *     elevation: 8,
+ *     sx: { borderRadius: 2 }
+ *   }}
+ * />
+ * ```
+ *
+ * @public
+ * @since 0.1.0
+ */
+interface CookieBannerProps {
+    /**
+     * URL para a política de privacidade ou cookies do site.
+     *
+     * @remarks
+     * Quando fornecida, aparece como link "Política de Privacidade" no banner.
+     * Link abre em nova aba/janela (`target="_blank"`) por segurança.
+     *
+     * @example "/privacy-policy" | "https://example.com/cookies"
+     */
+    policyLinkUrl?: string;
+    /**
+     * URL para os termos de uso do site (opcional). Quando fornecida, será considerada uma rota "segura"
+     * para não aplicar bloqueio total (overlay) mesmo em modo bloqueante.
+     */
+    termsLinkUrl?: string;
+    /**
+     * Força exibição do banner em modo de debug, independente do consentimento.
+     *
+     * @remarks
+     * Útil durante desenvolvimento para testar diferentes estados visuais.
+     * **Nunca deixe `true` em produção** - causará exibição permanente do banner.
+     *
+     * @defaultValue false
+     */
+    debug?: boolean;
+    /**
+     * Controla se o banner bloqueia interação com o restante da página.
+     *
+     * @remarks
+     * - `true`: Banner como modal/overlay, bloqueia interação até decisão
+     * - `false`: Banner como snackbar, permite navegação normal
+     *
+     * Banner bloqueante é mais eficaz para compliance, mas pode afetar UX.
+     *
+     * @defaultValue true
+     */
+    blocking?: boolean;
+    /**
+     * Oculta a marca "fornecido por LÉdipO.eti.br" no banner.
+     *
+     * @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;
+    /**
+     * Propriedades personalizadas para o componente Snackbar (modo não-bloqueante).
+     *
+     * @remarks
+     * Aplica-se apenas quando `blocking={false}`. Permite customização completa
+     * da posição, animação e comportamento do snackbar do Material-UI.
+     *
+     * @example
+     * ```tsx
+     * SnackbarProps={{
+     *   anchorOrigin: { vertical: 'top', horizontal: 'center' },
+     *   autoHideDuration: null, // Banner fica até decisão do usuário
+     *   TransitionComponent: Slide
+     * }}
+     * ```
+     */
+    SnackbarProps?: Partial<SnackbarProps>;
+    /**
+     * Propriedades personalizadas para o componente Paper que envolve o conteúdo.
+     *
+     * @remarks
+     * Permite customização avançada da aparência: elevação, bordas, cores, etc.
+     * Aplicado em ambos os modos (bloqueante e não-bloqueante).
+     *
+     * @example
+     * ```tsx
+     * PaperProps={{
+     *   elevation: 12,
+     *   sx: {
+     *     borderRadius: '16px',
+     *     border: '2px solid',
+     *     borderColor: 'primary.main'
+     *   }
+     * }}
+     * ```
+     */
+    PaperProps?: Partial<PaperProps>;
+}
+/**
+ * Banner principal de consentimento LGPD que solicita decisão do usuário sobre cookies.
+ * @component
+ * @category Components
+ * @remarks
+ * O CookieBanner é o ponto de entrada principal para interação com o sistema de consentimento.
+ * Aparece automaticamente quando o usuário ainda não tomou decisão sobre cookies,
+ * oferecendo opções claras de aceitar, rejeitar ou personalizar preferências.
+ *
+ * ### Funcionalidades Principais
+ * - **Exibição condicional**: Aparece apenas se usuário não deu consentimento
+ * - **Duas modalidades**: Bloqueante (modal) ou não-bloqueante (snackbar)
+ * - **Ações do usuário**: Aceitar tudo, rejeitar tudo, ou abrir preferências
+ * - **Link para política**: Opção de link para política de privacidade
+ * - **Branding opcional**: Marca discreta "fornecido por LÉdipO.eti.br"
+ * - **Totalmente customizável**: Via props, tokens de design ou componente próprio
+ *
+ * ### Estados de Exibição
+ * - **Não exibido**: Usuário já consentiu ou ainda hidratando (SSR)
+ * - **Snackbar**: Modo não-bloqueante, permite interação com a página
+ * - **Modal**: Modo bloqueante, impede interação até decisão
+ * - **Debug**: Sempre visível independente do estado (desenvolvimento)
+ *
+ * ### Integração com Sistema
+ * - Conecta automaticamente com `ConsentProvider`
+ * - Usa textos do `useConsentTexts()` para i18n
+ * - Aplica design tokens do `useDesignTokens()`
+ * - Registra todas as interações via sistema de logging
+ * - Suporte completo a SSR com hidratação segura
+ *
+ * ### Substituição Personalizada
+ * Para controle total, use `CookieBannerComponent` no ConsentProvider:
+ *
+ * ```tsx
+ * function CustomBanner() {
+ *   const { acceptAll, rejectAll } = useConsent();
+ *   return <div>Meu banner customizado</div>;
+ * }
+ *
+ * <ConsentProvider CookieBannerComponent={CustomBanner}>
+ * ```
+ *
+ * @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)
+ * ```typescript
+ * // ConsentProvider renderiza CookieBanner automaticamente
+ * function App() {
+ *   return (
+ *     // ConsentProvider envolve a aplicação
+ *     // CookieBanner aparece quando necessário
+ *   );
+ * }
+ * ```
+ *
+ * @example Customização via props no ConsentProvider
+ * ```typescript
+ * // Configuração com propriedades customizadas
+ * const bannerProps = {
+ *   policyLinkUrl: "/privacy",
+ *   blocking: false,
+ *   hideBranding: true
+ * };
+ *
+ * // ConsentProvider com cookieBannerProps
+ * ```
+ *
+ * @example Uso manual com customização avançada
+ * ```typescript
+ * function App() {
+ *   const bannerConfig = {
+ *     policyLinkUrl: "https://example.com/cookies",
+ *     blocking: true,
+ *     PaperProps: { elevation: 8 },
+ *     SnackbarProps: { anchorOrigin: { vertical: 'top' as const } }
+ *   };
+ *
+ *   // Renderização manual com config avançada
+ *   return null; // CookieBanner com bannerConfig
+ * }
+ * ```
+ *
+ * @see {@link ConsentProvider} - Provider que renderiza este componente automaticamente
+ * @see {@link useConsent} - Hook para acessar funções de consentimento
+ * @see {@link useConsentTexts} - Hook para textos personalizáveis
+ * @see {@link CookieBannerProps} - Interface completa de propriedades
+ *
+ * @public
+ * @since 0.1.0
+ */
+declare function CookieBanner({ policyLinkUrl, termsLinkUrl, debug, blocking, hideBranding, SnackbarProps, PaperProps, }: Readonly<CookieBannerProps>): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Props para o componente FloatingPreferencesButton.
+ *
+ * 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.
+ *
+ * Todos os campos são opcionais e possuem valores padrão.
+ */
+interface FloatingPreferencesButtonProps {
+    /** Posição do botão flutuante. Padrão: 'bottom-right' */
+    position?: 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right';
+    /** Offset da borda em pixels. Padrão: 24 */
+    offset?: number;
+    /** Ícone customizado. Padrão: CookieOutlined */
+    icon?: React.ReactNode;
+    /** Tooltip customizado exibido ao passar o mouse */
+    tooltip?: string;
+    /** Props adicionais para o Fab do MUI */
+    FabProps?: Partial<FabProps>;
+    /** Se deve esconder quando consentimento já foi dado. Padrão: false */
+    hideWhenConsented?: boolean;
+}
+/**
+ * @component
+ * @category Components
+ * @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`.
+ *
+ * Componente memoizado para otimizar performance - só re-renderiza quando props mudam.
+ *
+ * @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.
+ */
+declare const FloatingPreferencesButton: React.NamedExoticComponent<Readonly<FloatingPreferencesButtonProps>>;
+
+declare global {
+    /**
+     * @internal
+     * Variável global para rastrear integrações usadas.
+     * Usado internamente para logging e análise de performance.
+     */
+    var __LGPD_USED_INTEGRATIONS__: string[] | undefined;
+}
+/**
+ * @interface PreferencesModalProps
+ * Propriedades para customizar o componente `PreferencesModal`.
+ */
+interface PreferencesModalProps {
+    /** Propriedades opcionais para customizar o componente `Dialog` do Material-UI. */
+    DialogProps?: Partial<DialogProps>;
+    /** Se `true`, oculta a marca "fornecido por LÉdipO.eti.br" no modal. Padrão: `false`. */
+    hideBranding?: boolean;
+    /** Estado de abertura do modal passado pelo Provider. Quando fornecido via PreferencesModalComponent, substitui o valor do hook useConsent. */
+    isModalOpen?: boolean;
+    /** Preferências de consentimento passadas pelo Provider. Quando fornecido via PreferencesModalComponent. */
+    preferences?: ConsentPreferences;
+    /** Função para atualizar preferências passada pelo Provider. Quando fornecido via PreferencesModalComponent. */
+    setPreferences?: (preferences: ConsentPreferences) => void;
+    /** Função para fechar o modal passada pelo Provider. Quando fornecido via PreferencesModalComponent. */
+    closePreferences?: () => void;
+}
+/**
+ * O `PreferencesModal` é o componente de UI que permite ao usuário ajustar suas preferências de consentimento.
+ * @component
+ * @category Components
+ * @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
+ * ```tsx
+ * <PreferencesModal DialogProps={{ maxWidth: 'md' }} hideBranding={true} />
+ * ```
+ */
+declare function PreferencesModal({ DialogProps, hideBranding, isModalOpen: isModalOpenProp, preferences: preferencesProp, setPreferences: setPreferencesProp, closePreferences: closePreferencesProp, }: Readonly<PreferencesModalProps>): react_jsx_runtime.JSX.Element;
+
+export { Branding, type BrandingProps, ConsentProvider, type ConsentProviderProps, CookieBanner, type CookieBannerProps, FloatingPreferencesButton, type FloatingPreferencesButtonProps, PreferencesModal, type PreferencesModalProps };