Pular para o conteúdo
Sobreposição

Popconfirm

/componentes/popconfirm.mdmarkdown cru, para quem lê com agent em vez de olho

Excluir uma linha

Com a chamada em curso

Sem perigo

Importar
import { Popconfirm } from '@rivocode/ui'

Quando usar

A confirmação que nasce colada no botão que a disparou: excluir uma linha sem escurecer a tela inteira.

O caso é o botão de lixeira dentro de uma lista. A pergunta aparece a poucos pixels da linha que ela ameaça, então o painel não precisa repetir o contexto que a tela toda já mostra: quem lê "Excluir o pedido 4813?" ao lado do pedido 4813 não perdeu de vista de onde veio, e a lista continua atrás, legível.

Monta-se com uma peça só: trigger é o elemento que abre e a âncora do painel, title é a pergunta, description é o que se perde, e onConfirm é a ação. side, align e sideOffset são os mesmos dos outros painéis flutuantes da casa. Numa coluna de ações encostada na borda direita, align="end" evita que o painel empurre a largura.

Os textos moram em labels, e labels.confirm é obrigatório: é o verbo com o objeto do botão que executa, "Excluir pedido", "Cancelar nota". Não há padrão porque a peça não sabe a ação, e "Confirmar" não diz o que se confirma. cancel é o do botão que sai: "Cancelar" por padrão, e "Voltar" quando o confirm já começa com "Cancelar" - o par nunca repete a palavra com dois sentidos. Melhor ainda é escrever o estado que fica, "Manter nota". busy é o que o leitor de tela ouve quando a espera começa e blocked o aviso de quem tenta sair durante ela.

<Popconfirm
  trigger={<Button variant="ghost">Cancelar nota</Button>}
  title="Cancelar a nota 4813?"
  labels={{ confirm: 'Cancelar nota', cancel: 'Manter nota' }}
  onConfirm={cancelInvoice}
/>

Sair sem fazer nada é fácil de propósito

Esc, o botão de cancelar e o clique fora fecham o painel, e os três chamam onCancel. O AlertDialog fecha só no Esc e no botão, e não no clique fora; a razão de o painel aceitar os três é que aqui o gesto distraído leva ao resultado seguro: fechar não apaga nada. O que exige intenção é o contrário: executar, que só acontece no botão vermelho, com o verbo escrito nele. Prender a pessoa num painel de 20rem para ela ler dois botões cobra atenção onde não há risco, e é assim que se treina alguém a clicar em "Confirmar" sem ler.

O foco fica preso enquanto o painel está aberto, e começa no botão de cancelar. A página continua rolando: o painel acompanha a âncora, e travar a rolagem de uma tela inteira por causa de uma pergunta de duas linhas é o peso do modal voltando pela janela.

Quando a confirmação apaga a própria linha que a abriu, o gatilho desaparece com ela e o foco não tem para onde voltar. É o que finalFocus resolve: aponte o cabeçalho da tabela, ou o que sobrar na tela.

A rede demora, e o botão tem que dizer isso

onConfirm pode devolver uma promessa. Enquanto ela não termina, o painel fica aberto, o botão entra em espera e se anuncia ocupado, o cancelar trava, e nem Esc nem o clique fora fecham: um clique vira uma chamada, e não duas linhas apagadas. Se a promessa rejeitar, tudo volta ao estado anterior com o texto ainda na tela e uma frase de erro dentro do painel, acima dos botões, anunciada ao leitor de tela: "Não foi possível concluir. Tente de novo." por padrão, ou o labels.error. A pessoa decide se tenta de novo, e o próximo clique em confirmar apaga a frase.

error é a frase vinda de fora, a mensagem do servidor quando ela serve a pessoa ("A nota já foi transmitida e não pode mais ser cancelada."). Ela vence o labels.error e sai também sem promessa, para quem guarda o erro num useMutation.

Para quem já guarda esse estado fora da peça (numa store, num useMutation), existe loading, que soma com a espera da promessa.

No celular ela vira folha de baixo

Abaixo de 640px o painel ancorado não é ancorável: 20rem pendurados num botão de lixeira encostado na borda de uma tela de 390px viram um painel torto, sem lugar para onde fugir. Nessa largura a peça troca a casca por uma folha de baixo, com os botões na largura toda e na altura de toque, a mesma decisão que o Dialog e o CalendarPanel já tomam. O conteúdo e as ações são os mesmos; o que muda é a casca.

As partes

classNames veste title, description, error, footer, confirm e cancel, e o className veste o painel, seja ele o flutuante ou a folha. Sem esses nomes só resta [&_button] na sua tela, que amarra o seu layout à árvore interna da peça.

tone escolhe entre os dois desenhos: danger, o padrão, traz o ícone de aviso e o botão vermelho de executar; neutral serve ao que se desfaz (o arquivar, o remover da seleção) porque gastar o vermelho no reversível o apaga onde ele importa.

Quando não usar

Para o que é irreversível e de escopo largo, use AlertDialog. A linha entre os dois é a largura do estrago: uma linha de tabela, um anexo, um item de lista (coisas que a pessoa vê de onde clicou e que valem uma frase) pedem este painel; cancelar uma nota fiscal na prefeitura, apagar uma conta, descartar um formulário inteiro pedem o modal, que escurece o resto, não fecha no clique fora e obriga a leitura antes de qualquer saída.

O segundo teste é o tamanho do texto: se a confirmação precisa de mais de duas linhas, de uma lista do que será perdido ou de um campo para digitar o nome do que se apaga, ela não cabe num painel ancorado e nunca coube. É AlertDialog.

E se não há pergunta nenhuma a fazer, não use nenhum dos dois: uma ação que se desfaz sozinha pede o Toast com "Desfazer", que não custa um clique a mais em cada vez que a pessoa acerta.

No React Native

Vira AlertDialog. Painel ancorado não é idioma de toque: uma pergunta de 20rem presa a um botão de lixeira encostado na borda direita a 390px sai da tela ou tapa a linha que se vai apagar. O próprio web já reconhece isso: abaixo de 640px o Popconfirm deixa de ser painel e vira folha de baixo, que é exatamente o que o nativo tem.

Uma diferença de contrato, e ela é deliberada: no web dispensar CANCELA (Esc, clique fora e o botão, os três chamam onCancel), porque ali o gesto distraído leva ao resultado seguro. O AlertDialog nativo não fecha ao tocar fora, como o do web também não. Então a saída no celular é o botão de cancelar, escrito e visível: sem Escape não há saída invisível, e é a mesma regra que o Editable segue. O onCancel tem o mesmo nome, e aqui quem o chama é o botão de cancelar e o voltar do Android.

A ação em curso porta com os mesmos nomes: quem devolve promessa em onConfirm ganha o mesmo botão em espera e a mesma trava contra o segundo toque, e o modal só fecha quando ela resolve. O tone também: danger é o padrão, e neutral pinta o botão primário para o que se desfaz. Os textos moram no mesmo labels, com as mesmas chaves e as mesmas regras: confirm obrigatório, cancel que vira "Voltar" quando a ação já se chama cancelar, busy, blocked e error, a frase que fica dentro do modal quando a promessa rejeita. O error de fora, a mensagem do servidor, também tem o mesmo nome.

API

PropTipoPadrão
labelsobrigatória

Os textos do painel.

Partial<PopconfirmLabels> & { confirm: string; }sem padrão
onConfirmobrigatória

A acao.

() => void | Promise<unknown>sem padrão
titleobrigatória

A pergunta, curta e com o alvo dentro: "Excluir o pedido 4813?".

stringsem padrão
triggerobrigatória

O botao que abre a confirmacao.

ReactElement<unknown, string | JSXElementConstructor<any>>sem padrão
align

Alinhamento no eixo do lado escolhido.

Alignsem padrão
classNames

Classe por parte: `title`, `description`, `error` (a frase da falha), `footer`, `confirm`, `cancel`.

Partial<Record<"cancel" | "confirm" | "description" | "error" | "footer" | "title", string>>sem padrão
defaultOpen

Estado inicial de quem nao controla a abertura.

booleanfalse
description

O que a pessoa perde ao confirmar, ou o que acontece depois.

ReactNodesem padrão
error

A frase de erro dentro do painel, vinda de fora: a mensagem do servidor quando ela serve a pessoa.

stringsem padrão
finalFocus

Para onde o foco volta ao fechar.

RefObject<HTMLElement | null>sem padrão
loading

Estado de espera vindo de fora, para quem ja tem a chamada em uma store.

booleanfalse
onCancel

Chamado em toda saida sem confirmar: botao, Esc, clique fora, arrasto.

(() => void)sem padrão
onOpenChange

Avisa toda abertura e todo fechamento, controlado ou nao.

((open: boolean) => void)sem padrão
open

Deixa a abertura por conta de quem usa.

booleansem padrão
side

Lado preferido do gatilho.

Sidesem padrão
sideOffset

Distancia entre o gatilho e o painel, em pixels.

number | OffsetFunctionsem padrão
titleAs

Em que nivel a pergunta sai.

"h2""h3""h4""h2"
tone

`danger` pinta o botao de vermelho e traz o icone de aviso; `neutral` serve para o que se desfaz, como arquivar.

"danger" | "neutral""danger"

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.