Pular para o conteúdo

Padrões de UX / Ação e resposta

Salvar

Explícito ou automático, um botão sempre habilitado, a barra que aparece com a mudança e o aviso de saída.

/padroes/salvar.mdo mesmo arquivo que a skill entrega ao agente

A tela decide uma forma de salvar e a mantém: ou a pessoa salva com um botão que está sempre ali, ou a tela salva sozinha e diz que salvou. Misturar as duas na mesma área é o que faz alguém perder trabalho.

O problema

A pessoa muda três campos, clica em outra aba do menu e perde tudo, porque nada disse que havia mudança por salvar. Ou o contrário: a tela salva sozinha, não diz, e a pessoa procura um botão que não existe. O botão de salvar desabilitado até "algo mudar" esconde o que falta, e o salvar que fica no fim de uma página longa some da vista.

Quando usar

Toda tela que edita algo que já existe: configurações, perfil, o registro aberto, o modelo de e-mail, o documento. A escolha entre as duas formas é a primeira decisão:

Forma Quando O que a tela mostra
Explícito a mudança tem efeito que a pessoa precisa decidir junto (preço, permissão, dado fiscal), ou vários campos só fazem sentido salvos juntos o botão "Salvar mudanças", sempre habilitado, e a barra de salvar quando há mudança
Automático cada campo vale sozinho e voltar é barato (preferência, rascunho, anotação, documento de texto) o estado ao lado do título: "Salvando…", "Salvo às 14:32", "Não foi possível salvar"

Quando não usar

  • Nada de salvar automático em dado com efeito externo: o preço que o cliente vê, a nota que vai para a prefeitura, a permissão de outra pessoa. Ali o salvar é uma decisão, e a decisão tem botão.
  • Nada de dois jeitos na mesma área: um Switch que salva na hora ao lado de campos que esperam o botão faz a pessoa adivinhar qual é qual. Se a página mistura, separe por seção, e diga em cada uma.
  • Nada de aviso de saída na forma automática: não há o que perder.
  • Criar algo novo não é este padrão: o cadastro termina num envio, com o Result ou o aviso, e não numa barra de salvar.

As peças

  • SaveBar: a barra de salvar, que aparece quando há mudança e diz isso, com "Salvar mudanças" e "Descartar mudanças". Gruda no pé da área e fica à vista enquanto a pessoa rola.
  • useUnsavedChanges: o aviso de saída, que pergunta antes de a pessoa sair da tela com mudança por salvar, no fechar da aba e na troca de rota.
  • Button com loading: o salvar em espera.
  • Alert: a falha do salvar, dentro da barra, sem apagar nada.
  • useToast: o "Configurações salvas" depois do sucesso.
  • Badge ou Text com tone="muted": o "Salvo às 14:32" do automático.

Comportamento

Explícito

  • Um botão só, sempre habilitado. Desabilitado não diz o que falta, e a pessoa clica num botão que não responde. Habilitado, o clique sem mudança não faz nada de errado; o clique com erro mostra o erro no campo.
  • A barra aparece quando há mudança. O isDirty do formulário liga a SaveBar, com a frase "Você tem mudanças não salvas", o descartar e o salvar. Ela gruda no pé da área, para o salvar não ficar no fim de uma página longa.
  • Descartar volta ao que estava salvo, e não ao formulário vazio: o reset recebe os valores salvos.
  • Salvar com sucesso zera a mudança: o reset(valoresSalvos) no sucesso faz o isDirty voltar a falso, e a barra sai.
  • A falha fica na barra, com um Alert que diz quem falhou, e o botão vira "Tentar de novo". O que a pessoa mudou continua nos campos.
  • Sair com mudança pergunta antes. O useUnsavedChanges recebe o isDirty e cuida do aviso enquanto ele for verdadeiro. No fechar ou recarregar da aba, quem pergunta é o próprio navegador, com o texto dele; na troca de rota dentro do app, a pergunta é um AlertDialog com "Continuar editando" e "Sair sem salvar".

Com o Form de @rivocode/ui/form, o FormSaveBar faz a barra inteira a partir do formState, e o useUnsavedChanges recebe o mesmo isDirty:

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>
const dirty = form.formState.isDirty
const guard = useUnsavedChanges(dirty, { prompt: 'dialog', blocker: useBlocker(dirty) })

<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 prompt: 'dialog' faz o confirmLeave acender blocked em vez de abrir o window.confirm, e o blocker recebe o useBlocker do router: o do React Router (useBlocker(dirty), lido pelo state) ou o do TanStack Router (useBlocker({ shouldBlockFn: () => dirty, withResolver: true }), lido pelo status). A biblioteca não importa router nenhum; proceed e reset vão para quem segurou a saída.

Automático

  • Salva depois da pausa, e não a cada tecla: useDebouncedCallback com algo entre 500 ms e 1 s, e sempre com { flushOnUnmount: true }. Sem ele, o desmonte cancela o que está pendente, e as últimas letras de quem fecha a tela logo depois de digitar nunca saem. Um flush() no useEffect da tela não substitui: a limpeza do hook roda antes, e não sobra nada.

    const save = useDebouncedCallback((draft: Draft) => api.save(draft), 800, {
      flushOnUnmount: true,
    })
    
  • Diz o estado num lugar só e fixo, ao lado do título: "Salvando…", "Salvo às 14:32". A mudança de texto é discreta e não pisca.

  • A falha não some. "Não foi possível salvar. Tentando de novo…", e depois de algumas tentativas, "Sem conexão. O que você escreveu está guardado neste aparelho" com o tentar agora. Falha calada no salvar automático é perda de trabalho que só aparece amanhã.

  • Desfazer é do campo, pelo Ctrl+Z do editor ou pelo histórico de versões, e não por um aviso a cada salvamento.

Texto

  • O botão diz o que salva: "Salvar mudanças", "Salvar modelo". Nunca só "Salvar" numa tela com mais de uma área, nem "OK".
  • O descartar diz o que perde: "Descartar mudanças".
  • O aviso de saída nomeia o que fica para trás: "Sair sem salvar as mudanças?", com "Continuar editando" de escape e "Sair sem salvar" no botão que perde.
  • O sucesso diz o efeito: "Configurações salvas. Os próximos recibos já saem com estes dados."
  • O automático diz a hora: "Salvo às 14:32", e não "Salvo" sozinho, que não muda de um salvamento para o outro.

Acessibilidade

  • A barra que aparece se anuncia uma vez, em região viva educada, e não leva o foco: a pessoa estava num campo, e continua nele.
  • O "Salvando…" e o "Salvo às 14:32" do automático moram numa região viva educada (role="status"), lida quando muda.
  • A barra grudada não pode cobrir o campo em foco: reserve a altura dela no pé da área enquanto está aberta (WCAG 2.4.11).
  • O aviso de saída é AlertDialog, que começa com o foco no escape.

No celular e no nativo

No celular a barra de salvar gruda acima da área segura de baixo, com os dois botões ocupando a largura toda, e o salvar embaixo, onde o polegar está. No React Native a troca de rota é do router do app: o aviso de saída escuta o voltar do aparelho e o gesto de voltar, além do botão da tela. O formulário nativo entra por outro caminho: native.md.

Os blocos que o aplicam

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