Popover

Quando usarWhen to use

Use Popover quandoUse Popover when

O conteúdo contextual precisa de ações, links, um campo simples ou explicação mais rica que Tooltip, sem bloquear o restante da página. Contextual content needs actions, links, a simple field, or richer guidance than a Tooltip without blocking the rest of the page.

Não use Popover quandoDo not use Popover when

O conteúdo é somente um label curto (use Tooltip), exige decisão bloqueante ou fluxo longo (use Modal), ou representa uma lista de comandos (use Menu). Content is only a short label (use Tooltip), requires a blocking decision or long flow (use Modal), or represents a command list (use Menu).

AnatomiaAnatomy

Trigger — Button que controla abertura e aria-expanded.Trigger — Button controlling open state and aria-expanded.
Panel — superfície elevada com role="dialog".Panel — elevated surface with role="dialog".
Header — title opcional e close absoluto.Header — optional title and absolutely positioned close control.
Body — Content Text e Content Slot independentes.Body — independent Content Text and Content Slot.
Actions — até dois Buttons substituíveis e ocultáveis separadamente.Actions — up to two independently replaceable and hideable Buttons.
Arrow — Shape fechada que aponta para o trigger.Arrow — closed Shape pointing to the trigger.

Exemplo interativoInteractive example

<div class="ds-popover ds-popover--bottom">
  <button class="ds-button ds-button--outline ds-popover__trigger"
          type="button">Ver detalhes</button>
  <div class="ds-popover__panel"
       role="dialog"
       aria-labelledby="popover-title"
       hidden>
    <div class="ds-popover__header">
      <h3 class="ds-popover__title" id="popover-title">Título</h3>
    </div>
    <button class="ds-popover__close"
            type="button"
            aria-label="Fechar popover">...</button>
    <div class="ds-popover__body">
      <p>Conteúdo contextual.</p>
    </div>
    <div class="ds-popover__actions">
      <button class="ds-button ds-button--toned ds-button--sm">Cancelar</button>
      <button class="ds-button ds-button--brand ds-button--sm">Confirmar</button>
    </div>
  </div>
</div>

Content Slot adicionalAdditional Content Slot

O slot é opcional e adicional: não substitui Content Text nem Actions. Use anatomias públicas completas dos componentes inseridos. The slot is optional and additive: it does not replace Content Text or Actions. Use the complete public anatomy of inserted components.

PlacementsPlacements

Modifier	Posição do panelPanel position
`ds-popover--bottom`	Abaixo do triggerBelow the trigger
`ds-popover--top`	Acima do triggerAbove the trigger
`ds-popover--left`	À esquerda do triggerTo the trigger's left
`ds-popover--right`	À direita do triggerTo the trigger's right

Runtime públicoPublic runtime

O módulo ds-tis/popover é obrigatório para sincronizar ARIA, foco, Escape, click externo e lifecycle. O Popover é não modal e não prende o foco. The ds-tis/popover module is required to synchronize ARIA, focus, Escape, outside click, and lifecycle. Popover is non-modal and does not trap focus.

Eventos públicos: ds-popover-open e ds-popover-close. Public events: ds-popover-open and ds-popover-close.

import {
  initPopovers,
  destroyPopovers,
  openPopover,
  closePopover
} from 'ds-tis/popover';

initPopovers();
// destroyPopovers(root) ao desmontar / on unmount

Mapeamento de tokensToken mapping

PartePart	Component tokens
Panel	`component.popover.panel.{bg,border-color,border-width,gap,max-width,padding-x,padding-y,radius,shadow}.default`
Title / Body	`component.popover.title.color.default`, `component.popover.body.{color,gap,padding-bottom}.default`
Close	`component.popover.close.{size,icon-size,padding,color}.default`, `component.popover.close.icon.stroke-width.default`
Content Slot	`component.popover.content-slot.gap.default`
Actions	`component.popover.actions.{gap,padding-top}.default`
Arrow	`component.popover.arrow.{base,fill}.default`

Acessibilidade e tecladoAccessibility and keyboard

EntradaInput	ComportamentoBehavior
Enter / Space	O Button trigger abre ou fecha pelo comportamento nativo de click.The Button trigger opens or closes through native click behavior.
Escape	Fecha o Popover e retorna foco ao trigger.Closes the Popover and returns focus to the trigger.
Tab	Segue a ordem natural; não há focus trap.Follows natural order; there is no focus trap.
`role="dialog"`	Use `aria-labelledby` para title visível ou `aria-label` quando não houver header.Use `aria-labelledby` for a visible title or `aria-label` when there is no header.