Popover
Painel
import { Popover } from '@rivocode/ui'Quando usar
Painel ancorado de conteúdo livre. A peça entre o Tooltip, que só mostra texto
curto, e o Dialog, que rouba a tela inteira.
Compõe com PopoverTrigger, PopoverContent, PopoverTitle,
PopoverDescription e PopoverClose.
side, align e sideOffset ficam no PopoverContent: quem escreve a tela
pensa neles junto com o conteúdo.
Quando não usar
Dica curta de um botão só de ícone é Tooltip: só texto, sem nada clicável.
Prévia que abre ao pousar num link é PreviewCard, que não pede clique. O
Popover abre no clique e pode levar ação dentro.
Lista de ações é Menu, que traz a navegação por seta e a semântica de menu.
Confirmação colada no botão é Popconfirm. E tarefa que precisa da tela
inteira é Dialog; no celular, o painel grande vai em Sheet.
No React Native
Não porta. O painel ancorado ao gatilho é um problema de tela estreita antes de ser um problema de toque: ele nasce debaixo do dedo que o abriu e não tem para onde fugir. No React Native o equivalente é o Sheet, que sobe de baixo e não disputa espaço com nada.
API
| Prop | Tipo | Padrão |
|---|---|---|
actionsRef0.4.0Uma ref para as ações imperativas. | RefObject<PopoverRootActions | null> | sem padrão |
defaultOpen0.4.0Se o popover começa aberto. | boolean | false |
defaultTriggerId0.4.0ID do gatilho ao qual o popover está associado. | string | null | sem padrão |
handle0.4.0Um elo para associar o popover a um gatilho. | PopoverHandle<Payload> | sem padrão |
modal0.4.0Se o popover aberto fica em estado modal. | "trap-focus" | boolean | false |
onOpenChange0.4.0Chamado quando o popover abre ou fecha. | ((open: boolean, eventDetails: PopoverRootChangeEventDetails) => void) | sem padrão |
onOpenChangeComplete0.4.0Chamado depois que as animações terminam, quando o popover abre ou fecha. | ((open: boolean) => void) | sem padrão |
open0.4.0Se o popover está aberto agora. | boolean | sem padrão |
triggerId0.4.0ID do gatilho ao qual o popover está associado. | string | null | sem padrão |
Partes
Popover se monta com estas peças. Todas vivem nesta página, porque separar cada uma num endereço obrigaria a abrir seis abas para montar uma tela.
PopoverClose
/popover-close.mdFecha o painel de dentro dele, sem você guardar estado.
O painel já fecha com Esc e com clique fora; este serve para o botão que conclui (o Aplicar de um filtro, o Entendi de uma explicação) fechar junto com o que ele faz.
| Prop | Tipo | Padrão |
|---|---|---|
nativeButton0.4.0Se a peça renderiza um `<button>` nativo quando é trocada pela prop `render`. | boolean | true |
render0.4.0Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, PopoverCloseState> | ReactElement<unknown, string | JSXElementConstructor<any>> | sem padrão |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.
PopoverContent
/popover-content.mdO painel, em portal no contêiner do RivoProvider.
side, align e sideOffset moram aqui de propósito: quem escreve a tela
decide o lado junto com o conteúdo, e não na raiz, longe do que vai dentro. O
painel vira sozinho quando não cabe do lado pedido.
São as mesmas três props, com o mesmo significado e a mesma folga padrão de
6px, no MenuContent, no SelectContent, no ComboboxContent e no
TooltipContent: o que flutua nesta biblioteca também se posiciona igual.
Ancorar em outro elemento
anchor troca o gatilho por outro ponto de apoio: um elemento, uma ref, um
retângulo virtual ou uma função que devolve um deles. É o caminho do detalhe que
abre colado num item que não é botão de abrir painel, como a tarja do
EventCalendar:
<Popover open={open} onOpenChange={setOpen}>
<PopoverContent anchor={tarja} finalFocus={() => tarja ?? true}>
<PopoverTitle>Consulta das 9h</PopoverTitle>
</PopoverContent>
</Popover>
Sem PopoverTrigger, o Popover é controlado, e o finalFocus diz para onde
o foco volta ao fechar: sem ele, cai no body.
| Prop | Tipo |
|---|---|
align0.4.0Alinhamento no eixo do lado escolhido. | Align |
anchorOnde o painel se ancora, no lugar do gatilho: um elemento, uma ref para ele, um retangulo virtual ou uma funcao que devolve um deles. | ElementRefObject<Element | null>VirtualElement(() => Element | VirtualElement | null)null |
finalFocus0.4.0O elemento que recebe o foco quando o popover fecha. | booleanRefObject<HTMLElement | null>((closeType: InteractionType) => void | boolean | HTMLElement | null) |
initialFocus0.4.0O elemento que recebe o foco quando o popover abre. | booleanRefObject<HTMLElement | null>((openType: InteractionType) => void | boolean | HTMLElement | null) |
render0.4.0Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, PopoverPopupState> | ReactElement<unknown, string | JSXElementConstructor<any>> |
side0.4.0Lado preferido do gatilho. | Side |
sideOffset0.4.0Distancia entre o gatilho e o painel, em pixels. | number | OffsetFunction |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.
PopoverDescription
/popover-description.mdO texto do painel, ligado a ele por aria-describedby.
| Prop | Tipo |
|---|---|
render0.4.0Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, PopoverDescriptionState> | ReactElement<unknown, string | JSXElementConstructor<any>> |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.
PopoverTitle
/popover-title.mdO título do painel, ligado a ele por aria-labelledby.
Sem ele o leitor de tela abre um painel sem nome, e quem navega por teclado descobre onde está lendo o primeiro parágrafo.
| Prop | Tipo |
|---|---|
render0.4.0Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, PopoverTitleState> | ReactElement<unknown, string | JSXElementConstructor<any>> |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.
PopoverTrigger
/popover-trigger.mdO que abre o painel, e a âncora dele.
A posição é medida a partir daqui, então o gatilho é o elemento visível ao lado
do qual o painel deve aparecer, e não um invólucro maior que o empurraria para
longe. Com openOnHover, abre na passagem do mouse; use com parcimônia, porque
painel que abre sozinho atravessa o caminho de quem só estava passando.
Ele não tem pele própria (o uso comum é render={<Button />}, e duas fontes de
estilo brigariam), mas tem o anel de foco do teclado. Foco não é pele: quando o
gatilho é escrito à mão, o anel daqui é o único que existe.
| Prop | Tipo | Padrão |
|---|---|---|
closeDelay0.4.0Quanto esperar antes de fechar o popover aberto pelo passar do ponteiro. | number | 0 |
delay0.4.0Quanto esperar antes de o popover poder abrir pelo passar do ponteiro. | number | 300 |
handle0.4.0Um elo para associar o gatilho a um popover. | PopoverHandle<unknown> | sem padrão |
nativeButton0.4.0Se a peça renderiza um `<button>` nativo quando é trocada pela prop `render`. | boolean | true |
openOnHover0.4.0Se o popover abre também quando o ponteiro passa sobre o gatilho. | boolean | false |
payload0.4.0Um dado a entregar ao popover quando ele abre. | unknown | sem padrão |
render0.4.0Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, PopoverTriggerState> | ReactElement<unknown, string | JSXElementConstructor<any>> | sem padrão |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.