# SaveBar

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.

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

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

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

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

```css
@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

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

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

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

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

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

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

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

## Importação

```tsx
import { SaveBar } from '@rivocode/ui'
```

## Exemplos

### Controlada, com os quatro estados

```tsx
import { Field, FieldLabel, Input, SaveBar, useUnsavedChanges, type SaveStatus } from '@rivocode/ui'
import { Form, FormField, FormSaveBar, useZodForm } from '@rivocode/ui/form'
import { useState } from 'react'
import { z } from 'zod'

const SAVED_NAME = 'Aurora Comércio de Utilidades Ltda.'

async function persist(fail: boolean) {
  await new Promise((resolve) => setTimeout(resolve, 900))
  if (fail) throw new Error('O servidor não respondeu')
}

const schema = z.object({
  tradeName: z.string().trim().min(2, 'Escreva o nome fantasia, ou repita a razão social'),
})

export function Controlled() {
  const [saved, setSaved] = useState(SAVED_NAME)
  const [name, setName] = useState(SAVED_NAME)
  const [status, setStatus] = useState<SaveStatus>('idle')
  const [savedAt, setSavedAt] = useState<Date>()
  const [failNext, setFailNext] = useState(true)
  const dirty = name !== saved

  useUnsavedChanges(dirty)

  async function save() {
    setStatus('saving')
    try {
      await persist(failNext)
      setSaved(name)
      setSavedAt(new Date())
      setStatus('saved')
    } catch {
      setFailNext(false)
      setStatus('error')
    }
  }

  return (
    <div className="flex w-full max-w-xl flex-col gap-4">
      <Field>
        <FieldLabel>Razão social</FieldLabel>
        <Input value={name} onChange={(event) => setName(event.target.value)} />
      </Field>
      <SaveBar
        open={dirty}
        status={status}
        savedAt={savedAt}
        onSave={save}
        onDiscard={() => {
          setName(saved)
          setStatus('idle')
        }}
      />
    </div>
  )
}

const schema = z.object({
  tradeName: z.string().trim().min(2, 'Escreva o nome fantasia, ou repita a razão social'),
})
```

### No formulário, com o FormSaveBar

```tsx
import { Field, FieldLabel, Input, SaveBar, useUnsavedChanges, type SaveStatus } from '@rivocode/ui'
import { Form, FormField, FormSaveBar, useZodForm } from '@rivocode/ui/form'
import { useState } from 'react'
import { z } from 'zod'

async function persist(fail: boolean) {
  await new Promise((resolve) => setTimeout(resolve, 900))
  if (fail) throw new Error('O servidor não respondeu')
}

const schema = z.object({
  tradeName: z.string().trim().min(2, 'Escreva o nome fantasia, ou repita a razão social'),
})

export function InForm() {
  const form = useZodForm(schema, { defaultValues: { tradeName: 'Aurora' } })
  useUnsavedChanges(form.formState.isDirty)

  async function save(values: z.output<typeof schema>) {
    try {
      await persist(false)
      form.reset(values)
    } catch {
      form.setError('root.server', { message: 'O servidor não respondeu. Tente de novo.' })
    }
  }

  return (
    <Form form={form} onSubmit={save} className="w-full max-w-xl">
      <FormField name="tradeName" label="Nome fantasia" description="É o nome que o cliente lê na cobrança.">
        {(field) => <Input {...field} placeholder="Ex.: Aurora" />}
      </FormField>
      <FormSaveBar />
    </Form>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `classNames` | `Partial<Record<"actions" \| "bar" \| "discard" \| "save" \| "status", string>>` |  |  | - | Classe por parte: `bar` (o painel), `status` (a frase), `actions`, `discard` e `save`. |
| `error` | `string` |  |  | - | 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. |
| `finalFocus` | `RefObject<HTMLElement \| null>` |  |  | - | Para onde o foco vai quando a barra sai com ele dentro, depois do "Descartar" ou do "Salvo". |
| `labels` | `Partial<SaveBarLabels>` |  |  | - | Os textos da barra. |
| `onDiscard` | `(() => void)` |  |  | - | Liga o "Descartar mudanças". |
| `onSave` | `(() => void)` |  |  | - | Chamado pelo "Salvar mudanças" e pelo "Tentar de novo". |
| `open` | `boolean` |  | `false` | - | Ha mudanca que ainda nao foi salva. |
| `position` | `"fixed" \| "sticky"` |  | `"sticky"` | - | `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. |
| `savedAt` | `Date` |  |  | - | A hora que o "Salvo às" mostra. |
| `status` | `SaveStatus` |  | `"idle"` | - | Onde o salvamento esta. |

Além dessas: repassa `className`, `style`, `id` e os demais atributos do elemento raiz.

## Ver também

- [AudioRecorder](/componentes/audio-recorder.md)
- [Autocomplete](/componentes/autocomplete.md)
- [Calendar](/componentes/calendar.md)
- [Checkbox](/componentes/checkbox.md)
- [CheckboxCard](/componentes/checkbox-card.md)
- [CheckboxGroup](/componentes/checkbox-group.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)
