# Salvar

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`:

```tsx
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>
```

```tsx
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.

  ```tsx
  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](https://ds.rivocode.com.br/skill/reference/native.md).

## Os blocos que o aplicam

- [Configurações](https://ds.rivocode.com.br/blocos#configuracoes)
- [Modelo do e-mail de boas-vindas](https://ds.rivocode.com.br/blocos#modelo-de-e-mail)
