Estados de carregamento: Especificação do comportamento do usuário

Exige estados exclusivos pendente, sucesso, erro e vazio para telas assíncronas, proíbe um spinner ilimitado, anuncia a conclusão e preserva a entrada do usuário quando uma requisição falha.

Status do pacote: contexto de referência pronto para revisão humana. O contrato e os cenários de teste estão completos, mas não se afirma que uma implementação adotante os tenha passado.

Decisão

Uma tela assíncrona ocupa exatamente um dos estados pendente, sucesso, erro ou vazio. Pendente é limitado no tempo: após timeout_ms a tela deve entrar em erro com opção de nova tentativa, nunca um spinner infinito. Sucesso pode mostrar dados desatualizados durante a revalidação em segundo plano, com uma indicação visível de desatualização e sem spinner bloqueador empilhado. A conclusão de um carregamento iniciado pelo usuário é anunciada uma vez. Filtros digitados e rascunhos devem sobreviver ao erro. As transições vivem em state-table.yaml.

Escopo

• Telas que buscam ou modificam dados e então exibem uma região de resultado.
• Timeout, stale-while-revalidate, vazio versus erro, anúncios.
• Preservação da entrada em progresso durante recarregamentos falhos.
• Foco: esta região não rouba o foco a menos que um envio de formulário esteja em andamento.

Fora deste bloco

• Códigos de validação a nível de campo e foco no primeiro inválido.
• Texto de confirmação destrutiva.
• Cancelamento de token de streaming.

Contrato

• A região de resultado expõe um único status exclusivo dentre {pending, success, error, empty}.
• Pendente após timeout_ms sem um payload de sucesso torna-se error com request_timeout e um controle de nova tentativa habilitado.
• Vazio é legal somente quando a requisição teve sucesso e o conjunto de resultados é zero; falha 5xx ou de rede é error.
• Stale-while-revalidate mantém status: success com stale: true e não deve cobrir a região com um spinner bloqueador.
• Uma busca iniciada pelo usuário que atinja sucesso ou erro é anunciada uma vez em uma região live polida; os ticks de revalidação são silenciosos.
• Strings de filtro e rascunho digitadas pelo usuário sobrevivem ao erro; elas só são limpas via um controle explícito de reset.

Implementação

Modele o status como uma máquina de estados, não booleanos sobrepostos. Após o timeout, cancele a busca para que um corpo tardio não possa alterar erro para sucesso sem nova tentativa. Mantenha a visualização de sucesso anterior enquanto revalida. Monte a região live uma vez.

Tratamento de falhas

Nova tentativa move para pendente e desabilita tentativas duplicadas até estabilizar ou timeout. Uma revalidação falha não deve tornar-se vazia. Se a idade do stale exceder max_stale_ms, mostre erro em vez de uma visualização com aparência atual.

Verificação

Teste unitariamente o status exclusivo a partir da tabela de estados. Capture timeout, vazio versus erro, sobreposição stale, contagem de anúncios e preservação da entrada. Meça a duração do spinner em relação a timeout_ms. Execute os cenários empacotados.

Os exemplos executáveis neste pacote são fixtures e contratos de aceitação. Execute python tools/validate.py a partir da raiz da coleção para verificar a estrutura do pacote e metadados; então implemente e execute os cenários no repositório alvo.

Suposições para adoção

• Nomes e valores numéricos em example.yaml são um perfil de adoção, não padrões universais.
• A equipe adotante deve mapear atores, classes de dados, vocabulário de erros e propriedade para seu sistema.

Referências

• wcag22-status-messages