Componentes React: semânticos, compostos, focados em marcação
Uma tela deve ser legível quanto ao que a compõe, por uma pessoa e por um leitor de tela. Aplique estas regras ao escrever ou alterar componentes React, em qualquer projeto.
- Elementos dizem o que são. Use
main,header,footer,nav,section,search,ul/li,button,time,form. Umdivouspané apenas para uma caixa que existe para layout ou rolagem.O que cada escolha proporciona:// Não assim: toda caixa é um div, então um leitor de tela ouve uma longa sequência de texto, e // o "botão" não pode ser alcançado com Tab nem pressionado com Enter. <div className="page"> <div className="top"> <span className="updated">10:42</span> <div className="search"><input placeholder="Pesquisar" /></div> </div> <div className="group"> <div className="group-name">Fruta</div> <div className="items"> <div className="item" onClick={add}>Maçãs</div> </div> </div> </div> // Assim: cada elemento diz o que é, então pontos de referência, listas e botões vêm de graça. <main> <header> <time dateTime="10:42">10:42</time> <search><input type="search" aria-label="Pesquisar produtos" /></search> </header> <section aria-labelledby="fruta"> <h2 id="fruta">Fruta</h2> <ul> <li><button type="button" onClick={add}>Maçãs</button></li> </ul> </section> </main>maineheaderpermitem que um leitor de tela salte entre partes da página;sectioncom seuh2nomeia a região;ul/lidiz "lista, 5 itens";buttoné acessível por Tab e pressionado com Enter e Espaço sem código extra;timeesearchdizem o que seu conteúdo é. Mantenha umdivonde nada é significado, como a caixa que rola uma lista lateralmente. - Uma tela é uma composição de partes nomeadas. O JSX de uma tela se lê como um esboço da tela nas próprias palavras do produto: um componente nomeado para cada parte que uma pessoa apontaria. Cada parte é um componente pequeno que possui seu elemento semântico e suas classes, portanto a tela em si não tem tags HTML brutas nem strings de classe. Ler a tela mostra o que há nela; abrir uma parte mostra sua aparência.
Vale a pena nomear uma parte quando uma pessoa a chamaria de algo ("o cabeçalho", "uma linha de produtos", "o botão voltar"). Um wrapper que existe apenas para espaçamento fica dentro da parte que precisa dele, não na tela.// Não assim: a tela é uma árvore de tags e classes, e o que cada caixa é precisa ser deduzido. <div className="flex h-screen flex-col gap-5 pt-7"> <div className="flex items-center gap-3 px-8"> <span className="text-gray-500">Loja</span> <span className="font-semibold">{storeName}</span> </div> <div className="min-h-0 flex-1 overflow-y-auto"> {categories.map((c) => ( <div key={c.name} className="flex flex-col gap-3"> <div className="text-2xl font-semibold">{c.name}</div> <div className="flex gap-6 overflow-x-auto">{/* cartões de produto */}</div> </div> ))} </div> <button className="absolute bottom-2 left-8 rounded-full" onClick={onBack}>←</button> </div> // Assim: a tela são suas partes, nomeadas pelo que são. <CatalogLayout heading="Produtos"> <CatalogHeader> <ShopName /> <StoreName name={storeName} /> </CatalogHeader> <CategoryList categories={categories} onAdd={add} /> <BackButton label="Voltar para a loja" onBack={onBack} /> </CatalogLayout> // Cada parte possui seu próprio elemento e classes, uma vez. function CatalogHeader({ children }: { children: ReactNode }) { return <header className="flex items-center gap-3 px-8">{children}</header>; } - Nomes que um aluno do segundo ano adivinharia. Use a palavra simples para a coisa:
Layout,Header,Row,Card,List,Panel,Button,Margin. Sem metáforas e sem jargão técnico (Frame,Rail,Strip,Gutter,Chrome,Shell), a menos que os próprios usuários do produto usem essa palavra. Teste: alguém que nunca viu o código pode dizer o que<ProductRow>desenha.// Não assim: metáfora e jargão que um novato precisa decodificar. <PageFrame><TopRail /><ProductStrip gutter={GUTTER} /></PageFrame> // Assim: a palavra simples para cada coisa. <PageLayout><PageHeader /><ProductRow margin={LEFT_MARGIN} /></PageLayout> - Marcação primeiro. O corpo de um componente é seu JSX. Mais do que algumas linhas de estado, efeitos ou derivação antes do
returnvão para um hook nomeado pelo que modela (useProductSearch), que retorna fatos e ações.// Não assim: quarenta linhas de estado e efeitos antes de alguém ver o que é desenhado. function CatalogScreen({ onAdd }: Props) { const [products, setProducts] = useState<Product[] | null>(null); const [query, setQuery] = useState(""); const [adding, setAdding] = useState<string | null>(null); useEffect(() => { /* buscar os produtos, proteger contra desmontagem */ }, []); const categories = useMemo(() => /* filtrar, depois agrupar */, [products, query]); const add = (p: Product) => { /* definir adding, chamar onAdd, capturar */ }; // ... mais trinta linhas ... return <CatalogLayout>...</CatalogLayout>; } // Assim: um hook nomeado pelo que modela, depois o JSX. function CatalogScreen({ onAdd }: Props) { const search = useProductSearch({ onAdd }); return ( <CatalogLayout> <CategoryList categories={search.categories} onAdd={search.add} /> </CatalogLayout> ); } - Um estado com tag para visões exclusivas. Quando uma tela mostra exatamente uma de várias coisas, uma função pura ou um hook retorna uma união discriminada que carrega os dados de cada estado, e a tela é um
switchexaustivo sobre ele. Sem ternários aninhados e sem cadeia de retornos antecipados.Com// Não assim: uma cadeia de condições, onde a ordem é a lógica e um caso é fácil de perder. if (!loaded) return <Spinner />; if ("error" in loaded) return <Notice title="Não foi possível carregar o pedido" />; if (order.cancelled) return <Notice title="Cancelado" />; return order.items.length === 0 ? <EmptyBasket /> : order.paid ? <Receipt /> : <Checkout />; // Assim: uma função decide e retorna os dados que cada caso precisa. type OrderView = | { kind: "loading" } | { kind: "failed"; error: string } | { kind: "cancelled" } | { kind: "empty" } | { kind: "checkout"; order: Order } | { kind: "paid"; order: Order; receipt: Receipt }; const view = useOrderView(id); switch (view.kind) { case "loading": return <Spinner />; case "failed": return <Notice title="Não foi possível carregar o pedido" detail={view.error} />; case "cancelled": return <Notice title="Cancelado" />; case "empty": return <EmptyBasket />; case "checkout": return <Checkout order={view.order} />; case "paid": return <ReceiptPage order={view.order} receipt={view.receipt} />; }kindexaustivo, TypeScript falha na compilação quando um novo caso é adicionado e não é desenhado. - A lógica de negócio vive fora do React. Qualquer coisa que decide, verifica, filtra, ordena ou calcula é uma função pura em um módulo simples que não importa React, para que possa ser reutilizada e testada unitariamente sem renderização. Um hook ou componente a chama; não a contém. Onde esse código vai, como estratificá-lo e como retirá-lo de um componente está na habilidade business-logic.
// productSearch.ts: sem import React, então executa e é testado por conta própria. export function productsMatching(products: readonly Product[], query: string) { const words = query.toLowerCase().split(/\s+/).filter(Boolean); return products.filter((p) => words.every((w) => p.name.toLowerCase().includes(w))); } // O hook apenas o chama. const shown = productsMatching(products, query); - Filhos reportam, pais decidem. Props são eventos com fatos (
onAdd(product)), nunca um setter do pai.// Não assim: o filho recebe os setters do pai e decide o que adicionar significa. <ProductCard product={p} setBasket={setBasket} setError={setError} /> // Assim: o filho reporta o que aconteceu, com os fatos; o pai decide. <ProductCard product={p} onAdd={() => { add(p); }} /> - Marcaçao repetida vira um componente na segunda vez que é escrita.
// Não assim: o mesmo fundo de página e padding escritos em quatro telas. <div className="relative flex h-screen w-screen flex-col bg-gray-50 p-8">...</div> // Assim: escrito uma vez, na segunda vez que foi necessário. <PageLayout>...</PageLayout> - Hooks são enxutos e derivam, não armazenam. Um hook mantém apenas o estado que não pode ser computado: o que o usuário fez e o que chegou de fora. Todo o resto é derivado durante a renderização a partir desse estado, pelas funções puras da regra 6. Sem estado que espelha uma prop ou outro estado, e sem efeito que apenas define estado a partir de outro estado. Um efeito é para sincronizar com algo fora do React (uma requisição, um timer, uma assinatura, o DOM) e se limpa. Um hook modela uma coisa.
// Armazene apenas o que o usuário fez e o que chegou de fora. const [query, setQuery] = useState(""); const { products } = useProducts(); // buscado; seu efeito se limpa // Derive o resto a cada renderização, com funções puras de um módulo simples. const shown = productsMatching(products, query); const empty = shown.length === 0; // Não assim: uma cópia que se desvia, definida por um efeito que renderiza duas vezes. // const [shown, setShown] = useState(products); // useEffect(() => { setShown(productsMatching(products, query)); }, [products, query]); - Uma divisão não deve alterar o que é desenhado. Grave a marcação renderizada antes e depois e compare; uma suíte de testes bem-sucedida não mostra um wrapper movido.
# Grave a marcação renderizada de cada tela antes da alteração, faça a alteração, grave novamente e compare.
node record-markup.mjs antes/ # seu próprio script Playwright: abre cada estado da tela, salva document.body como HTML
node record-markup.mjs depois/
diff -r antes/ depois/ # apenas os elementos que você pretendia alterar devem diferir
Remova o que muda de execução para execução (ids, horários, códigos gerados) antes de comparar, para que uma diferença real se destaque.
Não divida por dividir: uma tela ainda deve ser legível como um todo, e um componente sem regras não precisa de hook.