Pular para o conteúdo
Formulário

SaveBar

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

Controlada, com os quatro estados

No formulário, com o FormSaveBar

É o nome que o cliente lê na cobrança.

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

Quando usar

A barra de salvar do formulário: entra quando há mudança que ainda não foi salva, diz em que pé está o salvamento e oferece "Descartar mudanças" e "Salvar mudanças". Configurações da conta, cadastro do cliente, dados da empresa, a ficha do produto.

const [status, setStatus] = useState<SaveStatus>('idle')
const [savedAt, setSavedAt] = useState<Date>()

<SaveBar
  open={dirty}
  status={status}
  savedAt={savedAt}
  onSave={save}
  onDiscard={() => setName(saved)}
/>

A barra não guarda o formulário. open diz que há mudança pendente, status diz onde está o salvamento, e onDiscard é quem volta os campos ao salvo.

No formulário, o FormSaveBar

Com o Form de @rivocode/ui/form, o FormSaveBar lê o formState do react-hook-form e liga tudo sozinho:

async function save(values: Settings) {
  try {
    await api.saveSettings(values)
    form.reset(values)
  } catch {
    form.setError('root.server', { message: 'O servidor não respondeu' })
  }
}

<Form form={form} onSubmit={save}>
  <FormField name="tradeName" label="Nome fantasia">
    {(field) => <Input {...field} />}
  </FormField>
  <FormSaveBar />
</Form>

Ele entra com isDirty, espera com isSubmitting, mostra a hora do salvo quando o envio dá certo e o formulário volta a ficar limpo, e cai no erro quando há um erro em root. O "Descartar mudanças" chama form.reset().

Duas regras saem disso. Depois de salvar, form.reset(values): é o que faz dos valores salvos o novo ponto de partida, e sem isso o formulário continua "sujo" e a barra não sai. A falha do servidor vai em setError('root.server'), e não num throw: o handleSubmit do react-hook-form propaga o erro, e ele chega ao console como promessa rejeitada sem ninguém ver.

O atalho mora no subcaminho /form porque é lá que o react-hook-form é peer. Valeu a peça porque a ligação à mão tem três armadilhas que todo formulário repete: esquecer o reset depois do salvo, deixar o "Descartar" clicável durante o envio e não ter onde mostrar a falha.

Os quatro estados

status O que a barra diz Os botões
idle com open "Você tem mudanças não salvas" "Descartar mudanças" e "Salvar mudanças"
saving "Salvando…" o salvar em espera, recusando o segundo clique; o descartar desligado
saved "Salvo às 14:32" nenhum; a barra sai sozinha quatro segundos depois
error "Não foi possível salvar. O que você mudou continua aqui." o salvar vira "Tentar de novo"

Com error, a barra mostra e anuncia a frase do servidor no lugar do "Não foi possível salvar", enquanto status é error. No FormSaveBar, passe a mensagem que o onSubmit pôs em root:

<FormSaveBar error={form.formState.errors.root?.serverError?.message} />

Sem error, ou com ela vazia, vale o texto padrão, que diz também que o que a pessoa mudou continua ali; escreva a frase do servidor com isso em mente.

No erro a barra fica, mesmo com open falso, e o que a pessoa escreveu não é tocado: o "Tentar de novo" chama o mesmo onSave. Mudança nova depois do salvo traz a barra de volta pedindo para salvar.

O "Salvar mudanças" fica sempre habilitado enquanto há mudança, e não só quando o formulário é válido: botão desligado não diz o que falta, e o envio com erro mostra cada campo que falta. Sem onSave, ele é type="submit" e envia o <form> em volta, que é o caso do Form.

Onde ela fica

position="sticky", o padrão, gruda no pé da área que a contém: ponha a barra como último filho do formulário. Ela ocupa lugar embaixo dele enquanto está aberta, então o último campo nunca fica escondido atrás dela.

position="fixed" gruda no pé da janela. A distância da borda é a mesma do ToastViewport, --rc-toast-bottom (1rem sem ela) mais a área do gesto do celular, então a tela que tem uma barra de navegação embaixo declara a altura dela uma vez e a barra de salvar sobe junto com os avisos:

@media (max-width: 767px) {
  :root {
    --rc-toast-bottom: calc(4.5rem + 0.5rem);
  }
}

Nos dois casos ela empilha em --rc-z-sticky, abaixo de menu, diálogo e aviso.

Leitor de tela e foco

A barra é anunciada numa região viva educada que existe antes da primeira mudança: ouve-se "Você tem mudanças não salvas" quando ela entra, "Salvando…", "Salvo às 14:32" ou o erro quando o estado muda, e "Mudanças descartadas" depois do descartar.

Ela não rouba o foco: quem está digitando continua no campo. Quando os botões somem com o foco neles, depois do descartar ou do salvo, o foco volta para o campo de onde a pessoa veio; finalFocus manda para outro lugar.

Avisar ao sair: useUnsavedChanges

const { confirmLeave } = useUnsavedChanges(form.formState.isDirty)

Enquanto when for verdadeiro, fechar a aba, recarregar ou sair para outro site abre o aviso do próprio navegador, pelo beforeunload. O texto desse aviso é o do navegador: nenhum navegador atual mostra mensagem própria ali. No Safari do iPhone o beforeunload não dispara de forma confiável; ali o que protege é a barra estar à vista.

A navegação dentro do app não passa pelo beforeunload, e a biblioteca não conhece o seu roteador. Para ela, o confirmLeave(leave) chama leave direto quando não há mudança, e só depois da confirmação quando há.

A confirmação é o window.confirm por padrão. Com prompt: "dialog", o confirmLeave não pergunta: ele acende blocked e espera a tela responder com proceed (sai) ou reset (fica). É o que deixa a pergunta ser o AlertDialog da casa, com os textos prontos em labels (title, message, stay, leave, que trocam pela opção labels).

O bloqueio da troca de rota entra pela opção blocker, que recebe o que o useBlocker do seu router devolve: o hook lê o state do React Router ou o status do TanStack Router, acende o mesmo blocked e manda proceed e reset para o router.

React Router, com o useBlocker do modo de dados:

const dirty = form.formState.isDirty
const guard = useUnsavedChanges(dirty, { prompt: 'dialog', blocker: useBlocker(dirty) })

TanStack Router, com withResolver para o bloqueio esperar a resposta:

const dirty = form.formState.isDirty
const blocker = useBlocker({ shouldBlockFn: () => dirty, withResolver: true })
const guard = useUnsavedChanges(dirty, { prompt: 'dialog', blocker })

Nos dois, a pergunta é o mesmo AlertDialog, aberto por blocked:

<AlertDialog open={guard.blocked} onOpenChange={(open) => !open && guard.reset()}>
  <AlertDialogContent>
    <AlertDialogTitle>{guard.labels.title}</AlertDialogTitle>
    <AlertDialogDescription>{guard.labels.message}</AlertDialogDescription>
    <AlertDialogFooter>
      <Button variant="secondary" onClick={guard.reset}>{guard.labels.stay}</Button>
      <Button variant="danger" onClick={guard.proceed}>{guard.labels.leave}</Button>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>

O mesmo guard.confirmLeave(() => navigate('/clientes')) continua servindo ao "Cancelar" que a tela desenha, e abre o mesmo diálogo.

Next.js App Router não tem bloqueio de navegação. O que sai da tela é o link e o router.push, então é neles que a confirmação entra:

const router = useRouter()
const { confirmLeave } = useUnsavedChanges(form.formState.isDirty)

<Link
  href="/clientes"
  onClick={(event) => {
    event.preventDefault()
    confirmLeave(() => router.push('/clientes'))
  }}
>
  Voltar para clientes
</Link>

O voltar do navegador no App Router não passa por nenhum dos dois; ali vale o mesmo do Safari: a barra à vista.

Partes

classNames alcança cada nó pelo nome: bar (o painel), status (a frase), actions, discard e save. labels troca os textos: dirty, saving, saved (recebe a hora e devolve a frase), error, save, retry, discard, discarded e region.

Quando não usar

  • Ação em lote sobre itens selecionados é ActionBar. As duas entram pelo pé da área e somem sozinhas, mas a ActionBar fala de uma seleção numa lista, e a SaveBar fala de um formulário com mudança pendente.
  • Confirmar que salvou depois que a pessoa saiu da tela, ou salvar que acontece longe da barra, é Toast. A SaveBar diz "Salvo às 14:32" no lugar onde a pessoa estava olhando e sai; o Toast passa por cima de qualquer tela.
  • Controle que vale na hora, como Switch, TabList variant="segmented" ou a ordem de uma lista, salva sozinho, sem barra. Não misture os dois no mesmo formulário: quem vê um campo que salvou sozinho espera que o vizinho salve também.
  • Corrigir um valor só, sem sair da tela, é Editable, que salva ao sair do campo.
  • Formulário curto que fecha ao enviar, como o de um Dialog, tem o botão de enviar no rodapé dele, e não barra.

No React Native

Traduz, com os mesmos open, status, savedAt, error, onDiscard, labels e as mesmas frases nos quatro estados, que vêm do mesmo arquivo dos dois lados. A error troca a frase do erro pela do servidor, e é ela que o leitor de tela ouve.

onSave é obrigatório. No React Native não há <form> nem type="submit", então o botão não tem o que enviar sozinho. Dentro do Form de @rivocode/ui-native/form, o FormSaveBar já chama o submit do formulário, e lê o formState como no web.

Ela fica por cima, acima da área segura de baixo. Como a ActionBar, a barra é absolute no pé da tela, sem sticky nem fixed, e a altura da barra do sistema entra por bottomInset: useSafeAreaInsets().bottom, mais a da barra de abas quando a tela tem uma. Quem a monta deixa o respiro no fim da rolagem para o último campo não ficar embaixo dela. Os estados são anunciados pelo leitor de tela do sistema, e ela não toma o foco.

O useUnsavedChanges atravessa com a mesma assinatura e outro gatilho. Não há beforeunload no aparelho: o que tira a pessoa da tela é a navegação. No Expo Router, passe preventRemove: usePreventRemove. O native stack não emite beforeRemove no voltar do cabeçalho nem no voltar do Android: a tela sai antes, e ele só respeita a saída segurada de antemão. Com preventRemove, o hook segura o voltar do cabeçalho, o gesto do iOS e o voltar do Android, e o "Descartar" solta a trava e segue a navegação que a pessoa pediu. O hook chama essa função como hook, então ela é a mesma em todo render. No React Navigation 7, cujo usePreventRemove não entrega o repeat, passe também navigation (o useNavigation()), por onde a ação segurada é despachada.

No stack em JavaScript, navigation sozinho basta: o hook segura o evento beforeRemove. Sem preventRemove nem navigation, ele segura só o voltar do Android pelo BackHandler, e só quando há onLeave, que é o que fazer depois do "Descartar"; sem onLeave, o voltar segue sem perguntar, porque não haveria como sair. O confirmLeave(leave) é o mesmo do web, e no react-native-web o beforeunload vale como lá.

A pergunta é sempre o AlertDialog da casa, igual no iOS e no Android: o hook não pergunta, acende blocked e espera proceed (sai) ou reset (fica), e os textos saem prontos em labels. Vale para o preventRemove, para o beforeRemove, para o voltar do Android e para o confirmLeave(leave, stay). Não há Alert do sistema: no iOS ele sai centrado com o "Descartar" em vermelho, no Android sai no desenho do Material, com outra ordem e sem o vermelho, e nenhum dos dois é o da casa. Por isso a tela renderiza o AlertDialog abaixo, e o prompt: 'dialog' fica na assinatura só para a chamada que divide código com o web. O blocker tem a forma do web (state do React Router, status do TanStack Router) para o app que tenha um router com bloqueio; com o Expo Router e o React Navigation, quem segura é o preventRemove ou o navigation.

import { usePreventRemove } from 'expo-router'

const guard = useUnsavedChanges(dirty, { preventRemove: usePreventRemove })

<AlertDialog
  open={guard.blocked}
  onOpenChange={() => {}}
  title={guard.labels.title}
  description={guard.labels.message}
  onConfirm={guard.proceed}
  onCancel={guard.reset}
  labels={{ confirm: guard.labels.leave, cancel: guard.labels.stay }}
/>

O open segue o blocked, então o onOpenChange não precisa fazer nada: o "Descartar" chama o proceed e o "Continuar editando" e o voltar do Android chamam o reset.

As partes vestem pelo mesmo classNames do web: bar, status, actions, discard e save, e o className veste o mesmo painel de bar.

No iOS e no Android. A pergunta do useUnsavedChanges é o AlertDialog da casa nos dois. No Android ela aparece no voltar do sistema; no iOS, que não tem voltar, aparece no voltar do cabeçalho e no gesto de borda, pelo preventRemove (ou pelo beforeRemove do navigation, no stack em JavaScript), e no confirmLeave da saída que o app desenha.

API

PropTipoPadrão
classNames

Classe por parte: `bar` (o painel), `status` (a frase), `actions`, `discard` e `save`.

Partial<Record<"actions" | "bar" | "discard" | "save" | "status", string>>sem padrão
error

A mensagem do servidor, no lugar do "Nao foi possivel salvar" enquanto `status` e `error`: a barra mostra e o leitor de tela ouve esta frase.

stringsem padrão
finalFocus

Para onde o foco vai quando a barra sai com ele dentro, depois do "Descartar" ou do "Salvo".

RefObject<HTMLElement | null>sem padrão
labels

Os textos da barra.

Partial<SaveBarLabels>sem padrão
onDiscard

Liga o "Descartar mudanças".

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

Chamado pelo "Salvar mudanças" e pelo "Tentar de novo".

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

Ha mudanca que ainda nao foi salva.

booleanfalse
position

`sticky` gruda no pe da area que a contem, que e o fim do formulario; `fixed` gruda no pe da janela e le `--rc-toast-bottom`, a mesma variavel do `ToastViewport`, para subir acima da barra de baixo do celular.

"fixed" | "sticky""sticky"
savedAt

A hora que o "Salvo às" mostra.

Datesem padrão
status

Onde o salvamento esta.

SaveStatus"idle"

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.