O que Padrões de UI React faz?
Princípios Fundamentais
- Nunca mostre UI desatualizada - Spinners de carregamento apenas quando realmente carregando
- Sempre exiba erros - Os usuários precisam saber quando algo falha
- Atualizações otimistas - Faça a UI parecer instantânea
- Divulgação progressiva - Mostre o conteúdo conforme ele se torna disponível
- Degradação graciosa - Dados parciais são melhores do que nenhum dado
Padrões de Estado de Carregamento
A Regra de Ouro
Mostre o indicador de carregamento SOMENTE quando não houver dados para exibir.
// CORRETO - Mostra carregamento apenas quando não há dados
const { data, loading, error } = useGetItemsQuery();
if (error) return <ErrorState error={error} onRetry={refetch} />;
if (loading && !data) return <LoadingState />;
if (!data?.items.length) return <EmptyState />;
return <ItemList items={data.items} />;
// ERRADO - Mostra spinner mesmo quando temos dados em cache
if (loading) return <LoadingState />; // Pisca na recarga!
Árvore de Decisão de Estado de Carregamento
Há um erro?
→ Sim: Mostre estado de erro com opção de repetir
→ Não: Continue
Está carregando E não temos dados?
→ Sim: Mostre indicador de carregamento (spinner/skeleton)
→ Não: Continue
Temos dados?
→ Sim, com itens: Mostre os dados
→ Sim, mas vazio: Mostre estado vazio
→ Não: Mostre carregamento (fallback)
Skeleton vs Spinner
| Use Skeleton Quando | Use Spinner Quando |
|---|---|
| Formato de conteúdo conhecido | Formato de conteúdo desconhecido |
| Layouts de lista/cartão | Ações de modal |
| Carregamento inicial da página | Submissões de botão |
| Placeholders de conteúdo | Operações inline |
Padrões de Tratamento de Erro
A Hierarquia de Tratamento de Erro
1. Erro inline (nível de campo) → Erros de validação de formulário
2. Notificação toast → Erros recuperáveis, usuário pode repetir
3. Banner de erro → Erros de página, dados ainda parcialmente utilizáveis
4. Tela de erro completa → Irrecuperável, precisa de ação do usuário
Sempre Mostre Erros
CRÍTICO: Nunca engula erros silenciosamente.
// CORRETO - Erro sempre exibido ao usuário
const [createItem, { loading }] = useCreateItemMutation({
onCompleted: () => {
toast.success({ title: 'Item criado' });
},
onError: (error) => {
console.error('createItem falhou:', error);
toast.error({ title: 'Falha ao criar item' });
},
});
// ERRADO - Erro capturado silenciosamente, usuário não sabe
const [createItem] = useCreateItemMutation({
onError: (error) => {
console.error(error); // Usuário não vê nada!
},
});
Padrão de Componente de Estado de Erro
interface ErrorStateProps {
error: Error;
onRetry?: () => void;
title?: string;
}
const ErrorState = ({ error, onRetry, title }: ErrorStateProps) => (
<div className="error-state">
<Icon name="exclamation-circle" />
<h3>{title ?? 'Algo deu errado'}</h3>
<p>{error.message}</p>
{onRetry && (
<Button onClick={onRetry}>Tentar Novamente</Button>
)}
</div>
);
Padrões de Estado de Botão
Estado de Carregamento do Botão
<Button
onClick={handleSubmit}
isLoading={isSubmitting}
disabled={!isValid || isSubmitting}
>
Enviar
</Button>
Desabilitar Durante Operações
CRÍTICO: Sempre desabilite gatilhos durante operações assíncronas.
// CORRETO - Botão desabilitado enquanto carrega
<Button
disabled={isSubmitting}
isLoading={isSubmitting}
onClick={handleSubmit}
>
Enviar
</Button>
// ERRADO - Usuário pode tocar várias vezes
<Button onClick={handleSubmit}>
{isSubmitting ? 'Enviando...' : 'Enviar'}
</Button>
Estados Vazios
Requisitos de Estado Vazio
Toda lista/coleção DEVE ter um estado vazio:
// ERRADO - Sem estado vazio
return <FlatList data={items} />;
// CORRETO - Estado vazio explícito
return (
<FlatList
data={items}
ListEmptyComponent={<EmptyState />}
/>
);
Estados Vazios Contextuais
// Pesquisa sem resultados
<EmptyState
icon="search"
title="Nenhum resultado encontrado"
description="Tente termos de pesquisa diferentes"
/>
// Lista sem itens ainda
<EmptyState
icon="plus-circle"
title="Nenhum item ainda"
description="Crie seu primeiro item"
action={{ label: 'Criar Item', onClick: handleCreate }}
/>
Padrão de Submissão de Formulário
const MyForm = () => {
const [submit, { loading }] = useSubmitMutation({
onCompleted: handleSuccess,
onError: handleError,
});
const handleSubmit = async () => {
if (!isValid) {
toast.error({ title: 'Corrija os erros' });
return;
}
await submit({ variables: { input: values } });
};
return (
<form>
<Input
value={values.name}
onChange={handleChange('name')}
error={touched.name ? errors.name : undefined}
/>
<Button
type="submit"
onClick={handleSubmit}
disabled={!isValid || loading}
isLoading={loading}
>
Enviar
</Button>
</form>
);
};
Anti-Padrões
Estados de Carregamento
// ERRADO - Spinner quando dados existem (causa piscada)
if (loading) return <Spinner />;
// CORRETO - Mostra carregamento apenas sem dados
if (loading && !data) return <Spinner />;
Tratamento de Erro
// ERRADO - Erro engolido
try {
await mutation();
} catch (e) {
console.log(e); // Usuário não sabe!
}
// CORRETO - Erro exibido
onError: (error) => {
console.error('operação falhou:', error);
toast.error({ title: 'Operação falhou' });
}
Estados de Botão
// ERRADO - Botão não desabilitado durante submissão
<Button onClick={submit}>Enviar</Button>
// CORRETO - Desabilitado e mostra carregamento
<Button onClick={submit} disabled={loading} isLoading={loading}>
Enviar
</Button>
Checklist
Antes de finalizar qualquer componente de UI:
Estados de UI:
- Estado de erro tratado e mostrado ao usuário
- Estado de carregamento mostrado apenas quando não há dados
- Estado vazio fornecido para coleções
- Botões desabilitados durante operações assíncronas
- Botões mostram indicador de carregamento quando apropriado
Dados e Mutações:
- Mutações têm manipulador onError
- Todas as ações do usuário têm feedback (toast/visual)
Integração com Outras Skills
- graphql-schema: Use padrões de mutação com tratamento de erro adequado
- testing-patterns: Teste todos os estados de UI (carregamento, erro, vazio, sucesso)
- formik-patterns: Aplique padrões de submissão de formulários