SaveBar
Controlada, com os quatro estados
Você tem mudanças não salvas
No formulário, com o FormSaveBar
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 aActionBarfala de uma seleção numa lista, e aSaveBarfala 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. ASaveBardiz "Salvo às 14:32" no lugar onde a pessoa estava olhando e sai; oToastpassa 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
| Prop | Tipo | Padrão |
|---|---|---|
classNamesClasse por parte: `bar` (o painel), `status` (a frase), `actions`, `discard` e `save`. | Partial<Record<"actions" | "bar" | "discard" | "save" | "status", string>> | sem padrão |
errorA 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. | string | sem padrão |
finalFocusPara onde o foco vai quando a barra sai com ele dentro, depois do "Descartar" ou do "Salvo". | RefObject<HTMLElement | null> | sem padrão |
labelsOs textos da barra. | Partial<SaveBarLabels> | sem padrão |
onDiscardLiga o "Descartar mudanças". | (() => void) | sem padrão |
onSaveChamado pelo "Salvar mudanças" e pelo "Tentar de novo". | (() => void) | sem padrão |
openHa mudanca que ainda nao foi salva. | boolean | false |
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" |
savedAtA hora que o "Salvo às" mostra. | Date | sem padrão |
statusOnde o salvamento esta. | SaveStatus | "idle" |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.