Introduction

El componente Popover es un elemento superpuesto interactivo que muestra detalles adicionales, acciones o formularios contextuales en una tarjeta flotante posicionada en relación con un elemento de activación (ancla).

Construido específicamente pensando en nuestra arquitectura de renderizado estático Zero-JS y en el modelo de hidratación condicional, el Popover utiliza enlaces eficientes y amigables con el page builder. Permanece completamente estático en el HTML hasta que se hidrata como una isla interactiva de Preact para manejar los disparadores de alternancia y escape con fluidez.

Usage

Estos ejemplos ilustran cómo los autores de contenido configuran y enlazan bloques popover.

1. Popover informativo básico

Un popover limpio, solo texto, ideal para explicar términos, ofrecer definiciones o mostrar mensajes de ayuda ligeros sin saturar la página.

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

2. Popover avanzado con contenido de cuerpo y acciones de pie

Un popover de incorporación que contiene secciones distintas: una cabecera informativa, texto de cuerpo y botones de acción personalizados anidados en el pie.

{
  "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 con disparador SVG personalizado y bloques hijos anidados

Para paneles de dashboard más complejos, los popover pueden incrustar disparadores SVG personalizados (usando markup sin procesar dentro de triggerIcon) y renderizar listas de componentes hijos (como Badges, Text o botones adicionales) dentro de la tarjeta flotante.

{
  "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

• Alineación inteligente de límites del viewport: La isla interactiva de Preact rastrea el espacio de pantalla dinámicamente. Si el popover se abre cerca de un borde, invierte la dirección automáticamente (p. ej. de abajo hacia arriba) y se desplaza en su eje para evitar recortes.
• Delegación unificada de eventos: Abrir, cerrar, clic fuera y tecla Escape se delegan limpiamente desde un listener central en el elemento raíz. Esto minimiza los enlaces de eventos en cliente.
• Overlays semánticos: Los popover compilan en layouts nativos y accesibles con role="dialog", aria-haspopup="dialog" y aria-expanded="true|false", asegurando compatibilidad total con lectores de pantalla.