Popover

Camada flutuante com conteúdo livre, aberta a partir de um gatilho.

O Popover mostra conteúdo rico perto do que o abriu: uma explicação mais longa, uma configuração pequena, um resumo. Para uma lista de ações use Dropdown; para uma dica curta ao passar o mouse, Tooltip; para fluxos maiores, Modal ou Sheet.

import { Popover } from "@rastreio-x/ui";

Padrão

O gatilho é o primeiro filho (um Button), seguido de Popover.Content e Popover.Dialog. Popover.Heading dá o título e nome acessível.

Com seta

Popover.Arrow aponta para o gatilho. Em gatilhos só com ícone, o botão precisa de aria-label.

Posições

placement em Popover.Content: top, bottom (padrão), left e right, com ajuste automático se faltar espaço (shouldFlip).

Conteúdo interativo

O Popover aceita controles, e você pode controlar a abertura com isOpen e onOpenChange.

Anatomia

Popover
├── Popover.Arrow
├── Popover.Content
├── Popover.Dialog
├── Popover.Heading
└── Popover.Trigger

Popover.Trigger: o gatilho (opcional quando o primeiro filho é um botão).
Popover.Content: a camada, posicionada e com limite de largura.
Popover.Arrow: seta opcional.
Popover.Dialog e Popover.Heading: o diálogo e o título.

Propriedades

Popover:

Popover
Prop	Tipo	Padrão	Descrição
`children`*	`React.ReactNode`	-	Conteúdo do componente.
`defaultOpen`	`boolean`	-	Abre o elemento na primeira renderização (não controlado).
`isOpen`	`boolean`	-	Controla se o elemento está aberto (controlado).
`onOpenChange`	`((isOpen: boolean) => void)`	-	Chamada quando o elemento abre ou fecha.

Popover.Content:

Popover.Content
Prop	Tipo	Padrão	Descrição
`children`*	`React.ReactNode`	-	Conteúdo do componente.
`aria-label`	`string`	-	Nome acessível, lido por leitores de tela quando não há rótulo visível.
`arrowBoundaryOffset`	`number`	`0`	Distância mínima entre a borda da seta e a borda da camada.
`arrowRef`	`RefObject<Element \| null>`	-	Referência ao elemento da seta.
`boundaryElement`	`Element`	`document.body`	Elemento que serve de limite para o posicionamento.
`className`	`ClassNameOrFunction<PopoverRenderProps>`	`'react-aria-Popover'`	Classes CSS aplicadas ao elemento.
`containerPadding`	`number`	`12`	Espaço mínimo entre a camada e a borda do contêiner.
`crossOffset`	`number`	`0`	Deslocamento adicional no eixo transversal entre a camada e o âncora.
`defaultOpen`	`boolean`	-	Abre o elemento na primeira renderização (não controlado).
`getTargetRect`	`((target: Element) => DOMRect \| null \| undefined)`	`target.getBoundingClientRect()`	Substitui o retângulo do alvo; útil para posicionar em relação a um ponto.
`isEntering`	`boolean`	-	Indica que a animação de entrada está em andamento.
`isExiting`	`boolean`	-	Indica que a animação de saída está em andamento.
`isKeyboardDismissDisabled`	`boolean`	`false`	Impede que a tecla Esc feche a camada.
`isNonModal`	`boolean`	-	Camada não modal: elementos fora dela continuam acessíveis a tecnologias assistivas.
`isOpen`	`boolean`	-	Controla se o elemento está aberto (controlado).
`maxHeight`	`number`	-	Altura máxima da camada; por padrão ocupa o espaço disponível na janela.
`offset`	`number`	`8`	Deslocamento adicional no eixo principal entre a camada e o âncora.
`onOpenChange`	`((isOpen: boolean) => void)`	-	Chamada quando o elemento abre ou fecha.
`placement`	`Placement`	`'bottom'`	Lado ou posição em que o elemento aparece.
`render`	`DOMRenderFunction<'div', PopoverRenderProps>`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`scrollRef`	`RefObject<Element \| null>`	`overlayRef`	Referência à região rolável da camada.
`shouldCloseOnInteractOutside`	`((element: Element) => boolean)`	-	Decide se uma interação fora da camada a fecha.
`shouldFlip`	`boolean`	`true`	Inverte o lado quando não há espaço suficiente.
`shouldSkipAnimation`	`boolean`	-	Mostra e esconde sem animação de entrada ou saída.
`shouldUpdatePosition`	`boolean`	`true`	Atualiza a posição automaticamente ao rolar ou redimensionar.
`style`	`StyleOrFunction<PopoverRenderProps>`	-	Estilos em linha aplicados ao elemento.
`trigger`	`string`	-	Nome do componente que abriu a camada (exposto em `data-trigger`).
`triggerRef`	`RefObject<Element \| null>`	-	Referência ao elemento a que a camada se posiciona.
`UNSTABLE_portalContainer`	`Element`	`document.body`	Elemento que recebe o portal da camada. Interface instável.

Animações

CSS
indicativo

A camada entra e sai com opacity e transform em transição curta, a partir do lado do gatilho. Com prefers-reduced-motion, a folha global da fachada reduz as transições a 0,01 ms e ela aparece direto.

Acessibilidade

O gatilho expõe aria-expanded e aria-haspopup="dialog"; a camada é um diálogo não modal nomeado pelo Popover.Heading.
Teclado: Enter ou Espaço abrem; o foco vai para dentro; Tab percorre os controles; Esc fecha e devolve o foco ao gatilho.
Dê sempre um título (visível ou aria-label no diálogo).
Não use para conteúdo essencial ou para erros: quem não abre o Popover nunca os vê.
O clique fora fecha; não dependa disso para ações destrutivas.

Boas práticas

Faça

Conteúdo curto e opcional, com título claro e no máximo uma ação.

Evite

Formulários longos, informação crítica ou menus de ações (isso é Dropdown).

Limite a largura (max-w-64 a max-w-80).
Se o conteúdo precisa ser lido por todos, mostre-o na página.
Evite Popover dentro de Popover.

Relacionados

Dropdown para listas de ações.
Tooltip para dicas curtas.
Sheet e Modal para fluxos maiores.