# Somente leitura, desabilitado e sem permissão

Três estados que parecem o mesmo e não são: o que se lê e não se muda, o que
ainda não se pode usar, e o que esta pessoa não alcança. Cada um tem a sua cara
e o seu texto, e nunca se troca um pelo outro.

## O problema

O CNPJ que veio da Receita aparece desabilitado, em cinza claro: ninguém
consegue ler, copiar nem selecionar, e o leitor de tela pula o campo. O botão
"Fechar o mês" fica desabilitado sem dizer por quê, e a pessoa clica dez vezes.
E a conta sem permissão abre a tela inteira, clica em "Excluir", e só então
recebe uma página 403, depois de ter preenchido o formulário.

## Quando usar

| Estado | Quando | A cara | Foco |
|---|---|---|---|
| Somente leitura | o valor existe, importa, e não se edita aqui: veio de outro sistema, está travado por regra, ou a pessoa só pode ver | o texto legível a 4,5:1, a borda tracejada sobre `surface-raised` | **focável**, selecionável e copiável |
| Desabilitado | o controle existe e ainda não pode ser usado, por uma condição da tela que a pessoa pode mudar | `fg-disabled`, `border-disabled`, `surface-raised` | **fora** da ordem do Tab |
| Sem permissão | o perfil desta pessoa não alcança a ação ou a área | a ação some, ou fica com o motivo e quem libera | depende do nível, abaixo |

## Quando não usar

- **Nunca desabilitado no lugar de somente leitura.** Valor desabilitado não se
  lê (o contraste do `fg-disabled` é de propósito baixo, e a WCAG o isenta), não
  se copia e não se alcança pelo teclado. Dado que a pessoa precisa ler é
  `readOnly`.
- **Nunca somente leitura no lugar de desabilitado.** Campo `readOnly` parece
  quase vivo, e a pessoa tenta digitar; se ele não se edita por uma condição
  que ela pode mudar, diga a condição.
- **Nunca desabilitado sem o motivo à vista.** Botão cinza calado é o defeito
  mais comum deste padrão. O motivo vai em texto perto dele, e não num
  `Tooltip` sobre o botão desabilitado: desabilitado não recebe foco, e a dica
  nunca chega a quem usa teclado ou toque.
- **Nunca o botão de enviar desabilitado até o formulário ficar válido**: ele
  não diz o que falta. Habilitado, o clique mostra ([erros.md](https://ds.rivocode.com.br/padroes/erros.md)).
- **Nunca só a página 403.** Permissão se resolve no nível em que ela existe:
  a seção, o botão, o campo.

## As peças

- `Input`, `Textarea`, `Select`, `Checkbox`, `Switch` e `RadioGroup` com
  `readOnly`: o valor legível, focável e travado.
- `DescriptionList`: o somente leitura de uma tela inteira, quando nada ali se
  edita. Formulário inteiro em `readOnly` é tabela de fatos com borda.
- `disabled` nas mesmas peças e no `Button`, e no `Field` e no `Fieldset` para o
  grupo todo.
- `Alert` com `tone="info"` ou `tone="warning"` perto do controle: o motivo do
  desabilitado, e o "quem libera" da permissão.
- `Result` com a ilustração `Forbidden`: a página 403, quando a área inteira
  está fora do alcance.
- `Badge`: o perfil da pessoa ("Atendimento"), quando ele explica o que falta.

## Comportamento

### Somente leitura

- Continua na ordem do Tab, recebe foco, deixa selecionar e copiar.
- Mostra o valor inteiro: nada de cortar com reticência o que não se pode
  abrir para ler.
- Diz de onde veio, quando isso explica o travamento: "Vem do cadastro na
  Receita" na descrição do campo.
- O formulário que mistura editáveis e travados mantém os dois com a mesma
  largura e o mesmo alinhamento: o travado não é um parágrafo solto no meio.

### Desabilitado

- A condição que libera fica à vista, perto do controle, em texto: "O mês fecha
  quando as 12 vendas no cartão forem conciliadas."
- Quando a condição se cumpre, o controle se habilita sozinho, sem recarregar.
- Desabilite o mínimo: o botão, e não a seção inteira; a seção, e não a
  página. O que ainda se pode fazer continua vivo.
- `loading` desabilita sozinho durante a espera; isso não é este estado.

### Sem permissão

Do maior para o menor nível, cada um com a sua resposta:

| Nível | A resposta |
|---|---|
| A área inteira | a página 403 com `Result`: quem libera, o pedido de acesso, e a saída para entrar com outra conta |
| Uma seção da tela | a seção aparece com um `Alert` no lugar do conteúdo ("Os valores de faturamento são vistos pelo perfil Financeiro. Peça a Marina Costa."), e o resto da tela segue |
| Uma ação | some, quando a pessoa nunca vai poder fazê-la e não precisa saber que existe; fica desabilitada com o motivo, quando saber que existe ajuda ("Só administradores excluem a conta") |
| Um campo | `readOnly`, com o motivo na descrição: a pessoa vê o valor, e não muda |

- **Decida a permissão antes de desenhar**, e não no clique: a tela já nasce
  sabendo o que a pessoa alcança. Descobrir no clique, depois de preencher, é
  o 403 que joga trabalho fora.
- **O servidor continua conferindo.** Esconder o botão é desenho, e não
  segurança.

## Texto

- Somente leitura diz a origem quando ela explica: "Vem do cadastro na
  Receita", "Definido pelo plano da empresa".
- Desabilitado diz a condição, no futuro: "Disponível quando o extrato da
  operadora bater", e não "Indisponível".
- Sem permissão diz quem libera, pelo nome ou pelo papel, e nunca culpa:
  "Quem libera esta área é quem administra a conta da empresa", e não "Acesso
  negado".

## Acessibilidade

- Somente leitura leva `readOnly` (e, fora de campo nativo, `aria-readonly`):
  o leitor de tela diz "somente leitura" e lê o valor.
- O texto do somente leitura passa nos 4,5:1 contra o fundo: é texto, e é para
  ser lido. O desabilitado é isento do contraste pela WCAG 1.4.3, e é por isso
  que ele não pode carregar informação.
- O motivo do desabilitado se liga ao controle por `aria-describedby` quando
  ele está perto; o `FormField` já faz para a `description` do campo.
- A ação que some por permissão some também do teclado e do leitor: não deixe
  um botão invisível na ordem do Tab.

## No celular e no nativo

No `@rivocode/ui-native` o desabilitado é `opacity-50` na camada inteira, uma
decisão da casa. O `Input` nativo com `editable={false}` se anuncia como
desabilitado, e por isso não serve de somente leitura: o valor que se lê e não
se muda vai num `Text` com `selectable`, ou numa `DescriptionList`, que o leitor
de tela lê inteiro. O `Tooltip` não existe no nativo, e é mais um motivo para o
porquê do desabilitado morar em texto ao lado. No celular a seção sem permissão cabe numa
linha com o `Alert`, e o 403 de área é o `Result` em tela cheia.

## Os blocos que o aplicam

- [Fechamento do caixa](https://ds.rivocode.com.br/blocos#fechamento-do-caixa)
- [Sem permissão (403)](https://ds.rivocode.com.br/blocos#sem-permissao)
