# Popover

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.

## No React Native

Não porta. O painel ancorado ao gatilho é um problem de tela estreita antes de ser um problem 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.

## Importação

```tsx
import { Popover } from '@rivocode/ui'
```

## Exemplos

### Painel

```tsx
import { Button, Popover, PopoverClose, PopoverContent, PopoverDescription, PopoverTitle, PopoverTrigger } from '@rivocode/ui'

export function Panel() {
  return (
    <div className="min-h-60">
      <Popover defaultOpen>
        <PopoverTrigger render={<Button variant="outline" />}>Período</PopoverTrigger>
        <PopoverContent>
          <PopoverTitle>Período do relatório</PopoverTitle>
          <PopoverDescription>O intervalo vale para o total e para a lista de notas.</PopoverDescription>
          <div className="mt-4 flex justify-end">
            <PopoverClose render={<Button variant="secondary" size="sm" />}>Aplicar</PopoverClose>
          </div>
        </PopoverContent>
      </Popover>
    </div>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Desde | O que faz |
| --- | --- | --- | --- | --- |
| `actionsRef` | `RefObject<PopoverRootActions \| null>` |  | 0.4.0 | A ref to imperative actions. |
| `defaultOpen` | `boolean` |  | 0.4.0 | Whether the popover is initially open. |
| `defaultTriggerId` | `string \| null` |  | 0.4.0 | ID of the trigger that the popover is associated with. |
| `handle` | `PopoverHandle<Payload>` |  | 0.4.0 | A handle to associate the popover with a trigger. |
| `modal` | `"trap-focus" \| boolean` |  | 0.4.0 | Determines if the popover enters a modal state when open. |
| `onOpenChange` | `((open: boolean, eventDetails: PopoverRootChangeEventDetails) => void)` |  | 0.4.0 | Event handler called when the popover is opened or closed. |
| `onOpenChangeComplete` | `((open: boolean) => void)` |  | 0.4.0 | Event handler called after any animations complete when the popover is opened or closed. |
| `open` | `boolean` |  | 0.4.0 | Whether the popover is currently open. |
| `triggerId` | `string \| null` |  | 0.4.0 | ID of the trigger that the popover is associated with. |

## Partes

O componente se monta com as peças abaixo. Todas vêm de `@rivocode/ui`.

### PopoverClose

Fecha 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 | Obrigatória | Desde | O que faz |
| --- | --- | --- | --- | --- |
| `nativeButton` | `boolean` |  | 0.4.0 | Whether the component renders a native `<button>` element when replacing it via the `render` prop. |
| `render` | `ComponentRenderFn<HTMLProps, PopoverCloseState> \| ReactElement<unknown, string \| JSXElementConstructor<any>>` |  | 0.4.0 | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

### PopoverContent

O 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.

| Prop | Tipo | Obrigatória | Desde | O que faz |
| --- | --- | --- | --- | --- |
| `align` | `Align` |  | 0.4.0 | Alinhamento no eixo do lado escolhido. |
| `finalFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => void \| boolean \| HTMLElement \| null)` |  | 0.4.0 | Determines the element to focus when the popover is closed. |
| `initialFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((openType: InteractionType) => void \| boolean \| HTMLElement \| null)` |  | 0.4.0 | Determines the element to focus when the popover is opened. |
| `render` | `ComponentRenderFn<HTMLProps, PopoverPopupState> \| ReactElement<unknown, string \| JSXElementConstructor<any>>` |  | 0.4.0 | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |
| `side` | `Side` |  | 0.4.0 | Lado preferido do gatilho. |
| `sideOffset` | `number \| OffsetFunction` |  | 0.4.0 | Distancia entre o gatilho e o painel, em pixels. |

### PopoverDescription

O texto do painel, ligado a ele por `aria-describedby`.

| Prop | Tipo | Obrigatória | Desde | O que faz |
| --- | --- | --- | --- | --- |
| `render` | `ComponentRenderFn<HTMLProps, PopoverDescriptionState> \| ReactElement<unknown, string \| JSXElementConstructor<any>>` |  | 0.4.0 | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

### PopoverTitle

O 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 | Obrigatória | Desde | O que faz |
| --- | --- | --- | --- | --- |
| `render` | `ComponentRenderFn<HTMLProps, PopoverTitleState> \| ReactElement<unknown, string \| JSXElementConstructor<any>>` |  | 0.4.0 | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

### PopoverTrigger

O 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 | Obrigatória | Desde | O que faz |
| --- | --- | --- | --- | --- |
| `closeDelay` | `number` |  | 0.4.0 | How long to wait before closing the popover that was opened on hover. |
| `delay` | `number` |  | 0.4.0 | How long to wait before the popover may be opened on hover. |
| `handle` | `PopoverHandle<unknown>` |  | 0.4.0 | A handle to associate the trigger with a popover. |
| `nativeButton` | `boolean` |  | 0.4.0 | Whether the component renders a native `<button>` element when replacing it via the `render` prop. |
| `openOnHover` | `boolean` |  | 0.4.0 | Whether the popover should also open when the trigger is hovered. |
| `payload` | `unknown` |  | 0.4.0 | A payload to pass to the popover when it is opened. |
| `render` | `ComponentRenderFn<HTMLProps, PopoverTriggerState> \| ReactElement<unknown, string \| JSXElementConstructor<any>>` |  | 0.4.0 | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

## Ver também

- [AlertDialog](/componentes/alert-dialog.md)
- [ContextMenu](/componentes/context-menu.md)
- [Dialog](/componentes/dialog.md)
- [Popconfirm](/componentes/popconfirm.md)
- [PreviewCard](/componentes/preview-card.md)
- [Sheet](/componentes/sheet.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)