Introduction

O componente Popover é um elemento sobreposto interativo que exibe detalhes adicionais, ações ou formulários contextuais em um cartão flutuante posicionado em relação a um elemento de ancoragem (gatilho).

Construído especificamente para nossa arquitetura de renderização estática Zero-JS e para o modelo de hidratação condicional, o Popover usa vinculações eficientes e amigáveis ao page builder. Permanece totalmente estático no HTML até ser hidratado como uma ilha interativa de Preact para tratar alternâncias e a tecla Escape com fluidez.

Usage

Estes exemplos ilustram como os autores de conteúdo configuram e vinculam blocos popover.

1. Popover informativo básico

Um popover limpo, somente texto, ideal para explicar termos, oferecer definições ou mostrar mensagens de ajuda leves sem poluir o layout.

{
  "type": "popover",
  "triggerText": "Learn More",
  "title": "Data Residency",
  "description": "Your profile data is stored securely in compliant Frankfurt (EU) server nodes."
}

2. Popover avançado com conteúdo de corpo e ações de rodapé

Um popover de onboarding contendo seções distintas: um cabeçalho informativo, texto de corpo e botões de ação personalizados aninhados no slot de rodapé.

{
  "type": "popover",
  "triggerText": "Setup Account",
  "title": "Configure API Integrations",
  "description": "Connect with external tools seamlessly.",
  "body": "Your subscription allows up to 5 concurrent server channels. Ensure your client secret credentials are copied before proceeding.",
  "footer": "Connect Keys",
  "showArrow": true
}

3. Popover com gatilho SVG personalizado e blocos filhos aninhados

Para painéis de dashboard mais complexos, os popover podem incorporar gatilhos SVG personalizados (usando markup bruto dentro de triggerIcon) e renderizar listas de componentes filhos (como Badges, Text ou botões adicionais) dentro do cartão flutuante.

{
  "type": "popover",
  "triggerText": "System Status",
  "triggerIcon": "<circle cx=\"12\" cy=\"12\" r=\"10\" /><line x1=\"12\" y1=\"16\" x2=\"12\" y2=\"12\" /><line x1=\"12\" y1=\"8\" x2=\"12.01\" y2=\"8\" />",
  "triggerAriaLabel": "System Operations Status Info",
  "title": "System Heartbeat",
  "description": "Operational health checks",
  "showArrow": true,
  "closable": true,
  "children": [
    {
      "blockType": "badge",
      "text": "API: OK",
      "colorPalette": "green"
    },
    {
      "blockType": "badge",
      "text": "DB: OK",
      "colorPalette": "green"
    }
  ]
}

Props

Architecture Notes

• Alinhamento inteligente de limites do viewport: A ilha interativa de Preact rastreia o espaço de tela dinamicamente. Se o popover abre perto de uma borda, inverte a direção automaticamente (ex. de baixo para cima) e desloca no seu eixo para evitar cortes.
• Delegação unificada de eventos: Abrir, fechar, clique-externo e tecla Escape são delegados a partir de um listener central no elemento raiz, minimizando vinculações no cliente.
• Overlays semânticos: Os popover compilam em layouts nativos e acessíveis com role="dialog", aria-haspopup="dialog" e aria-expanded="true|false", garantindo compatibilidade total com leitores de tela.