Pular para o conteúdo
Guia de execução · menu Design

React: os cinco padrões de componente e o lugar de cada estado

Padrões de componentes React são as cinco formas que resolvem a maioria das telas: componente com props, composição por children, estado local, lista com key e campo controlado. Gerenciar estado em React é decidir onde mora cada dado: no componente, calculado na renderização, num store compartilhado, no cache do servidor ou na URL. Quem encomenda telas a um agente de IA recebe React em quantidade e precisa saber revisar o que chega; revisar em 2026 exige saber o que mudou. O React estável é o 19.3, de 9 de setembro de 2026; o React Compiler chegou à versão 1.0 estável e memoiza sozinho o que antes se escrevia à mão; o Next.js 16 tornou o Turbopack padrão e renomeou o middleware; e um release de segurança em julho de 2026 corrigiu nove vulnerabilidades, duas delas em Server Actions. Aqui está o que a revisão precisa: os cinco padrões de componente com o sinal de reprovação de cada um, a pergunta de trinta segundos sobre onde mora cada estado, o critério oficial para dispensar um useEffect, dado de servidor em camada de cache, formulário sem redesenho a cada tecla, filtro e busca na URL, e a versão mínima que o time deve cobrar de qualquer entrega. A mesma matéria está em aula de vídeo e podcast logo abaixo.

Guia do menu Design do portal, construído sobre pesquisa de fontes primárias verificada em 18/08/2026 (documentação e blog oficiais do React e do Next.js, registros do npm, State of React 2025) e sobre os capítulos de React do curso Frontends com Vibecoding, de Alexandre Caramaschi. Ele compõe o menu com os guias de ícones, ilustrações, animação e geração de imagens, de menus, abas e paginação, de diagramas e de Tailwind e CSS moderno.

A aula, em vídeo e em podcast

O conteúdo deste guia virou uma aula gerada no NotebookLM a partir do dossiê de pesquisa, servida nos arquivos originais, sem recompressão. O vídeo apresenta o panorama em minutos; o podcast aprofunda a conversa para ouvir no deslocamento. Cada player traz download, compartilhamento e a transcrição completa para ler ou copiar.

Aula em vídeo: React em 2026Panorama do guia: componentes, estado e dados · 10 min
Podcast: React em 2026A conversa aprofundada sobre as mesmas decisões · 33 min

Arquivos originais: vídeo em MP4 · podcast em M4A · legenda do vídeo · transcrição do vídeo · transcrição do podcast

O React de 2026, em quatro fatos

O curso que origina este guia abre com um diagnóstico que segue válido: "o agente escreve muito bem o React, o Tailwind e o CSS de dois anos atrás. Ele acerta a estrutura, erra a atualidade, e nada no processo avisa." O antídoto é datar o terreno. Quatro fatos definem o React de agosto de 2026, todos da fonte oficial:

PeçaVersão estável em 18/08/2026Registro
React19.2 (patch 19.2.7, junho de 2026)react.dev/versions
React Compiler1.0 (7 de outubro de 2025)blog oficial do React
Next.js16.3 (3 de agosto de 2026)blog oficial do Next.js
TanStack Query5.101.4 (21 de julho de 2026; v6 inexiste)registro npm
TanStack Table9.1.2 (v9 estável em 4 de agosto de 2026)registro npm e releases do GitHub
react-hook-form7.85.0 (8 de agosto de 2026; v8 em beta)registro npm
nuqs2.9.6 (17 de agosto de 2026)registro npm
Zustand5.0.15 (13 de agosto de 2026)registro npm
Jotai2.20.2 (14 de julho de 2026; v3 em alpha)registro npm
Vitest4.1.10 (v5 em release candidate)registro npm e blog do Vitest
Playwright1.62.1registro npm

Versões conferidas no registro npm e nas fontes oficiais em 18 de agosto de 2026. Número de versão envelhece rápido: ao cobrar atualização, reconfira na fonte antes de citar.

Os cinco padrões de componente e o sinal de reprovação de cada um

O curso reduz a maioria das telas a cinco padrões, e o princípio que os organiza segue na documentação oficial: cada peça de estado tem um componente dono; a doc chama isso de "single source of truth" e manda subir o estado compartilhado ao pai comum em vez de duplicá-lo. Revisar vira reconhecer o padrão e procurar o sinal que o reprova:

1. Componente com props

Função tipada que devolve JSX; a prop decide a classe aplicada. Reprove quando a lista de props passou de meia dúzia e cresce a cada tela.

2. Composição por children

Invólucro genérico que cuida só de enquadramento, borda, fundo e espaçamento. É o padrão mais reutilizável do React justamente porque o invólucro dispensa saber qualquer coisa sobre o que carrega. Reprove quando o invólucro recebe props do que ele carrega.

3. Estado local com useState

Regra de ouro: atualize a partir do valor anterior, na forma (v) => v + 1, para que duas atualizações próximas deixem de se atropelar. Reprove quando o DOM é alterado na mão em vez de reconciliado.

4. Lista com map e key

A key vem do identificador do dado. A doc oficial avisa que índice como key "frequentemente leva a bugs sutis e confusos" e que key gerada na hora, como Math.random(), recria todo o DOM a cada render e perde o que o usuário digitou. Reprove quando a key é índice ou aleatória, ou o caso de lista vazia ficou sem tratamento.

5. Campo controlado

O value vem do estado e o onChange atualiza; o erro reflete na borda vermelha e no aria-invalid ao mesmo tempo. Reprove quando o erro aparece só em cor, ou só depois do envio.

O fluxo de leitura para revisar um componente devolvido, na ordem do curso: identificar o padrão; conferir se ele cabe na situação; procurar o critério no código; procurar o sinal de reprovação; e então aprovar, ou devolver com o motivo em uma frase.

A armadilha das classes montadas. O Tailwind só gera as classes que consegue ver como strings completas no código-fonte. Por isso bg-${cor}-500 ou 'text-' + tom produzem classe nenhuma no arquivo final. A solução é o mapa estático de variantes: um objeto com as strings inteiras (variantes[variante]), que o Tailwind enxerga e o revisor confere de relance. O guia de Tailwind e CSS moderno aprofunda esse lado.

Quando o widget escapa dos cinco padrões

Combobox com filtro, seletor de data e tabela navegável pelo teclado costumam ficar de fora do que um catálogo pronto de componentes entrega, e é nesse degrau que o agente improvisa uma div com onClick. O React Aria Components, mantido pela Adobe, cabe aí como dependência direta do projeto, sem intermediário: ele já traz o padrão ARIA completo do widget (papel, gerenciamento de foco, navegação por teclado, anúncio para leitor de tela) em lugar de deixar cada um desses itens para reimplementação manual. Quem chega à biblioteca por baixo de um catálogo de componentes usa esse comportamento sem enxergá-lo; instalá-la direto é o caminho para a peça que o catálogo deixou fora da lista.

A cadência de publicação ajuda a datar a entrega: a biblioteca manteve release mensal ao longo de 2026, com seleção múltipla no ComboBox na 1.16, linhas expansíveis de Table na 1.17 e o PreviewTrigger na 1.20. A pergunta que a revisão faz é curta: este widget customizado herda comportamento de uma biblioteca de acessibilidade, ou alguém escreveu o controle de foco e as teclas de seta na mão, linha a linha.

React Compiler: a memoização saiu das suas mãos

O React Compiler 1.0, estável desde 7 de outubro de 2025, é uma ferramenta de build que otimiza a aplicação por memoização automática, sem exigir reescrita. A documentação delimita o foco: melhorar a performance de atualização, pulando re-renders em cascata e cálculos caros. Ele acelera re-render; o primeiro carregamento e a rede ficam fora do escopo dele.

A recomendação oficial muda o que a revisão cobra: para código novo, confiar na memoização do compilador e reservar useMemo e useCallback para quando for preciso controle preciso; em código existente, manter a memoização já escrita ou testar com cuidado antes de remover. A doc em momento algum proíbe os dois hooks: eles viram válvula de escape. Na prática de encomenda: um componente novo coberto de useMemo em tudo que é linha é sinal de agente escrevendo o React de dois anos atrás; pergunte se o projeto já ativou o compilador antes de aceitar. Projetos novos de Expo (SDK 54 em diante) já nascem com ele ligado, e create-next-app e create-vite oferecem templates com o compilador; projeto existente precisa adotá-lo de propósito.

Confira quais componentes o compilador conseguiu otimizar. A orientação atual do React é instalar eslint-plugin-react-hooks@latest e habilitar as regras recomendadas para o compilador, como o preset recommended-latest. O compilador pode pular componentes que violam as regras do React e continuar otimizando os demais; ativá-lo no build não garante que cada componente foi memoizado. O lint expõe os diagnósticos no editor. Confira também a indicação de memoização no React DevTools, conforme a instalação oficial do React Compiler.

Onde mora cada estado: a pergunta de trinta segundos

Antes de criar qualquer estado, responda uma coisa: onde mora a verdade deste dado. O curso trata a confusão entre os tipos como a causa raiz da maioria dos bugs de estado (o sintoma clássico é uma tela mostrando um saldo e a outra mostrando outro), e errar a classificação transforma a correção: ela deixa de ser ajuste de tela e vira reescrita da camada de dados. Os cinco lugares:

Ilustração abstrata de cartões retangulares em rosa, azul-marinho e branco flutuando sobre fundo claro, conectados por linhas douradas luminosas com nós de luz, evocando componentes de interface trocando dados
Componentes trocando dados: cada cartão com um dono para o seu estado. Imagem gerada por IA.

A documentação oficial do React, na página Choosing the State Structure (consulta em 2 de outubro de 2026), resume a estrutura em cinco princípios: agrupar o estado que muda junto, evitar contradições, evitar estado redundante, evitar duplicação e evitar aninhamento profundo. Em página de campanha, o primeiro estado é o do formulário da landing page, que é local; o status do pedido que chega pelo aviso do checkout é dado de servidor, como mostra o artigo o checkout conhece a compra, a automação conhece o cliente.

Fluxograma de decisão: onde mora este estado Cinco perguntas em sequencia levam a local, derivado, compartilhado, servidor ou URL, cada um com sua ferramenta. Onde mora a verdade deste dado? Pertence a um componente só? Dá para calcular de outros valores? Atravessa telas sem vir do servidor? Pertence ao backend? Filtro, aba, ordenação ou página? Local useState ou useReducer Derivado calcule na renderização, não guarde Compartilhado de cliente Context; Zustand ou Jotai se frequente De servidor Cache com dono Na URL nuqs, o endereço da tela sim sim sim sim sim não não não não
A pergunta de trinta segundos: cada resposta "sim" aponta o lugar do estado e a ferramenta certa, antes de qualquer useState.
Tipo de estadoExemploFerramentaEvite
LocalAba de um cartão, campo abertouseState ou useReducerBiblioteca global
DerivadoTotal, lista filtradaCalcular na renderização; com o Compiler ativo, nem useMemoGuardar em useState
Compartilhado, baixa frequênciaTema, sessão, modal globalContext com useReducerStore pesado
Compartilhado, alta frequênciaCarrinho, estado de funcionalidadeZustand, com seletores e useShallowContext, que re-renderiza em cascata
Compartilhado, granularFormulário ou editor complexoJotai, por átomosUm store monolítico
Filtro, aba, paginação, busca?busca=...&pagina=2nuqs, estado na URLuseState que some no recarregamento
De servidorLista de produtos, perfilTanStack Query no cliente; cache do framework no servidorCache remontado à mão no componente
Fonte externaTamanho da janela, store própriouseSyncExternalStoreuseEffect improvisado

Quadro do curso Frontends com Vibecoding, atualizado com as recomendações das documentações oficiais em agosto de 2026.

Os números de adoção confirmam a tabela. O State of React 2025 mediu uso e retenção de cada biblioteca:

BibliotecaUsoRetenção
TanStack Query68%97%
Zustand50%94%
Jotai18%92%
Redux75% (ainda lidera o uso)34% (a retenção caiu)
Redux Toolkit54%57%

O comentário editorial da própria pesquisa resume: o Zustand "está ganhando terreno rápido" e, por liderar também em satisfação, "deve ser considerado o líder da categoria". Na semana de 9 a 15 de agosto de 2026, a API de downloads do npm registrou os downloads semanais:

A régua do curso descreve o ecossistema que o mercado de fato usa.

Estado compartilhado: o custo de re-render de cada ferramenta

A diferença entre as três ferramentas é quem redesenha quando o valor muda. Com Context e useReducer, todo consumidor re-renderiza quando o value do Provider muda, mesmo lendo uma fatia que permaneceu igual: bom para valor estável e raro, caro em alta frequência. Com Zustand, cada componente assina só a fatia que usa via seletor, sem Provider e sem cascata; a documentação da v5 avisa que seletor devolvendo referência nova a cada chamada pode causar loop infinito (o erro estampa "Maximum update depth exceeded") e prescreve o useShallow para devolver referência estável. Com Jotai, átomos primitivos se compõem e a doc garante o grão fino: átomos observados re-renderizam apenas as partes pequenas da aplicação que precisavam da atualização: o caso do formulário complexo e do editor.

Custo de re-render: Context, Zustand e Jotai Comparacao de quais componentes repintam quando o valor muda: com Context todos os consumidores repintam em cascata; com Zustand so quem assina a fatia; com Jotai so quem le o atomo alterado. Context Provider no topo todos os consumidores repintam, em cascata Zustand store fora da árvore só quem assina a fatia repinta seletor que monta objeto pede useShallow Jotai átomo alterado átomo quieto só quem lê o átomo alterado repinta componente que re-renderiza componente quieto assinatura da fatia ou do átomo
Quando o valor muda, o Context repinta todos os consumidores em cascata; o Zustand repinta só quem assina a fatia (com useShallow para referência estável); o Jotai repinta só quem lê o átomo alterado.

Três saídas antes de migrar do Context, na ordem do curso: quebrar um Context grande em vários pequenos por frequência de mudança; estabilizar o value com useMemo; e, se a alta frequência persistir, trocar por store com seletores.

Para atualização que disputa com a digitação, as primitivas de concorrência: useTransition marca a atualização como baixa prioridade e expõe o sinal de pendência; useDeferredValue deixa o valor digitado chegar na hora e adia a versão derivada; e useSyncExternalStore é o hook oficial para conectar o React a uma fonte externa; você raramente o escreve direto, e saber que ele existe explica por que o Zustand funciona com segurança no render concorrente.

Um caso à parte vem do capítulo de tabelas do curso: dado que muda várias vezes por segundo fica fora do ciclo de renderização: os dados quentes vivem no motor e a tela repinta apenas o que mudou. O teste que expõe o defeito leva um minuto: abra o painel de componentes do React e observe se o componente pai redesenha a cada atualização. Se redesenhar, o dado está no lugar errado.

Existe uma linha a mais nessa decisão, e ela atende justamente a alta frequência: os sinais reativos. O @preact/signals-react propaga a mudança com granularidade fina, atualizando o ponto da tela que lê o sinal sem levar a árvore acima dele junto no re-render, o que serve a cotação em tempo real, cronômetro e cursor de edição colaborativa. A ressalva entra colada: a convivência com o React Compiler precisa ser verificada dentro do projeto antes de adotar os dois ao mesmo tempo, porque ambos mexem no mesmo lugar, a decisão de quando o componente repinta. Adotar a dupla sem essa verificação é assumir um risco que ninguém mediu.

Quando o useEffect sobra: o critério oficial

A página "You Might Not Need an Effect" da documentação define Effects como válvula de escape do paradigma: eles existem para sincronizar o componente com um sistema externo: um widget de fora do React, a rede, o DOM do navegador. E entrega a regra na primeira dobra: sem sistema externo envolvido, você deveria dispensar o Effect. Dois abusos ganham nome próprio na doc:

Transformar dados para renderizar

Effect que lê estado, calcula e grava outro estado reinicia o processo de render do zero. A doc manda transformar os dados no topo do componente, durante o próprio render.

Tratar evento do usuário

Quando o Effect roda, você já perdeu a informação de qual interação aconteceu (qual botão foi clicado). A lógica de interação pertence ao event handler correspondente.

O critério em uma frase

Na formulação da doc: lógica causada por uma interação específica vai no event handler; lógica causada por o usuário ver o componente na tela vai no Effect.

Critério oficial: quando o useEffect sobra Sem sistema externo, dispense o Effect: dado no render, evento no handler; com sistema externo, use Effect, com o desvio useEffectEvent. Há um sistema externo envolvido? Dispense o Effect a regra da primeira dobra da doc Transformar dado calcule no topo do componente, no render Evento do usuário a lógica vai no event handler useEffect: sincronizar widget fora do React, rede, DOM do navegador Desvio: useEffectEvent (19.2) valor lido ali não re-dispara o Effect; fica fora do array de dependências não sim parte "de evento" Na revisão: todo useEffect novo nomeia o sistema externo que o justifica.
O critério oficial da doc: sem sistema externo o Effect sobra; com sistema externo ele sincroniza, e o useEffectEvent isola a parte de evento.

O 19.2 completou o quadro com o useEffectEvent: ele separa a parte "de evento" da lógica de um Effect, para que valores lidos ali dentro deixem de re-disparar o Effect inteiro; Effect Events ficam fora do array de dependências, por regra da doc. Na mesma leva, o <Activity> esconde e restaura a interface e o estado interno dos filhos: ao esconder, o React guarda o estado, destrói os Effects e oculta com display: none; ao voltar, restaura o estado e recria os Effects. Quem revisa precisa saber que painel escondido por Activity mantém o formulário preenchido ao alternar, comportamento desejado e surpreendente para quem esperava desmontagem.

Na revisão: todo useEffect novo responde à pergunta do sistema externo. Sem resposta, devolva com o critério da doc no comentário. As exceções legítimas existem (sincronizar um widget, assinar um evento do navegador), e a própria documentação prefere biblioteca de dados a fetch manual em Effect para buscar dados.

Dado de servidor: cache com dono

Buscar dado de servidor juntando estado de componente com efeitos colaterais reimplementa, à mão e mal, uma camada de cache: sem revalidação, sem deduplicação e sem estado de obsolescência. A comparação é nossa; a motivação oficial do TanStack Query descreve o mesmo cenário: sem uma solução holística, os desenvolvedores acabam "cobbling together component-based state and side-effects" para prover dado assíncrono, e as bibliotecas tradicionais de estado de cliente "are not so great at working with async or server state". A biblioteca entrega "fetching, caching, synchronizing and updating server state" com useQuery para leitura (data, isPending, isError, refetch), useMutation para escrita e invalidação por chave. A linha estável segue a v5 (5.101.4, de 21 de julho de 2026), e uma v6 inexiste no npm: entrega que cite "TanStack Query 6" está citando algo que ainda foi publicado em lugar nenhum.

Cada dado tem um dono só. O erro que todo iniciante comete é copiar o dado do servidor para dentro de um Zustand ou de um useState e manter duas cópias do mesmo número. Deixe o dado do servidor no cache da biblioteca e guarde no estado local só o que é da tela, como filtro aberto e aba selecionada. O erro de estreia da própria ferramenta: usar a mesma queryKey para consultas diferentes, o que faz uma tela mostrar o dado da outra sem aviso.

Para os estados assíncronos de envio, o React 19 trouxe três hooks, cada um com a letra miúda que derruba código de agente.

useActionState

Unifica envio, pendência e erro. Um erro lançado cancela as ações enfileiradas e aciona o Error Boundary mais próximo.

useFormStatus

Vem do pacote react-dom e só funciona chamado de um componente renderizado dentro do <form>. A doc é explícita: ele reporta o form pai, e chamá-lo no mesmo componente que renderiza o form devolve nada (o erro clássico em código gerado).

useOptimistic

Mostra o valor temporário enquanto a Action corre e reverte sozinho na falha, no padrão do curtir que pinta na hora. Use em curtir, marcar e arrastar, e mantenha pagamento fora disso.

Resposta de modelo que chega token a token

O useOptimistic cobre o valor que a interface consegue adiantar. Resposta de modelo de linguagem pede o movimento complementar da mesma família: o valor final leva segundos para existir e chega em pedaços, então a tela renderiza de forma incremental. O servidor abre um fluxo, por Server-Sent Events ou pelo corpo de um fetch lido em stream, e a interface pinta o texto parcial conforme ele chega, em vez de segurar um indicador de carregamento até a última palavra.

Duas exigências ao revisar uma tela que faz streaming. O texto parcial mora num contêiner com aria-live="polite", para que o leitor de tela acompanhe o que vai aparecendo sem cortar a fala a cada token. E o estado final entra num commit único, quando o fluxo fecha: guardar cada pedaço como estado novo transforma cada token em um render, e a conta aparece na primeira resposta longa.

A API use() lê uma Promise direto no componente e, ao contrário dos hooks, pode aparecer em condicionais e loops. O tratamento de erro é estrutural: Promise pendente aciona o fallback do <Suspense>; Promise rejeitada aciona o Error Boundary mais próximo; a doc avisa que use dentro de try-catch simplesmente falha. E o Error Boundary continua sendo a única razão sancionada para escrever classe em 2026: "There is currently no way to write an Error Boundary as a function component", diz a referência oficial, que aponta o pacote react-error-boundary para quem prefere dispensar a classe própria.

Formulários: teclar sem redesenhar o formulário inteiro

O FAQ oficial do react-hook-form explica o mecanismo: a biblioteca se apoia em formulário não controlado (o register captura uma ref, em vez de value e onChange), e essa abordagem reduz os re-renders causados pela digitação. A régua de adoção do curso segue de pé: num campo único de busca, um useState resolve com menos código; a biblioteca se justifica a partir de três campos, ou quando o formulário engasgar no celular. A versão estável é a 7.85.0, de 8 de agosto de 2026; a v8 existe só em beta; entrega baseada nela é aposta, e aposta se declara.

O modo de validação é decisão de re-render, com aviso na fonte. A doc do useForm lista os modos e carimba o onChange: validação a cada tecla, múltiplos re-renders e "impacto significativo de performance". O onTouched valida no primeiro blur e depois a cada mudança: o comportamento que o usuário espera, sem o custo.

const { register, handleSubmit, formState: { errors, isSubmitting } } =
  useForm<Cadastro>({ resolver: zodResolver(cadastroSchema), mode: "onTouched" });

A API que a revisão reconhece de relance: register liga o <input> ao formulário; handleSubmit valida antes de chamar o envio; formState expõe errors, isSubmitting e isValid. Campo que precise ser controlado entra via Controller, que isola o re-render ao próprio campo.

Filtro, aba e busca moram na URL

O quinto lugar de estado é o endereço da tela, e a ferramenta é o nuqs (2.9.6, de 17 de agosto de 2026; o pacote publica quase toda semana). A doc o apresenta como substituto direto: quem gerencia estado de interface com React.useState pode trocar por useQueryState para sincronizá-lo com a URL. Parâmetro de busca nasce string; para número, parseAsInteger converte "with parseInt (base 10)", e o valor default fica interno ao React: ele só vai para a URL se for setado explicitamente. Desde a versão 2 o uso exige envolver a aplicação no NuqsAdapter do framework (a doc lista adapters para Next.js, SPA com Vite, Remix, React Router v6, v7 e v8 e TanStack Router), e esquecê-lo na raiz é o erro de estreia: o valor nunca chega ao endereço.

O ganho de negócio que o curso destaca continua o argumento decisivo: o cliente manda o link do filtro para um colega, e o suporte reproduz a tela exata de uma reclamação. O guia de menus, abas e paginação retoma a mesma régua do lado da navegação. E para projeto fora do Next.js, os roteadores atuais são o React Router, na major 8 ("a user-obsessed, standards-focused, multi-strategy router", na definição do site oficial), e o TanStack Router, focado em type-safety: "the route tree is the application contract".

Next.js 16: a fronteira, o cache e a versão mínima

O Next.js 16, de 21 de outubro de 2025, mexeu no chão que o agente pisa em quatro pontos.

Turbopack virou o padrão

O Turbopack ficou estável e virou o bundler padrão de projetos novos.

middleware.ts virou proxy.ts

O middleware.ts foi renomeado para proxy.ts, rodando em Node.js. A forma antiga segue aceita no Edge runtime, já deprecada e com remoção anunciada.

Acesso assíncrono obrigatório

params, cookies() e headers() passaram a exigir acesso assíncrono.

Cache Components

O cache implícito do App Router deu lugar aos Cache Components com a diretiva use cache, habilitada desde o 16.0 e ainda opt-in via cacheComponents: true.

O 16.3, de 3 de agosto de 2026, somou até 90% menos memória no dev server e a suíte opt-in Instant Navigations, de cinco ferramentas, incluindo o helper de teste instant() para Playwright.

Sinal de entrega datada: código que o agente devolver com middleware.ts novo, params síncrono ou experimental.ppr é código do Next de 2024.

Ilustração abstrata em duas camadas: blocos geométricos azul-marinho na parte inferior e painéis translúcidos claros na superior, separados por uma linha luminosa rosa que pacotes de luz rosa e dourados atravessam, evocando a fronteira entre servidor e navegador
A fronteira entre servidor e navegador: só cruza o que é serializável. Imagem gerada por IA.

Sobre a fronteira, a doc oficial diz exatamente onde a diretiva vai: "use client" declara um ponto de entrada para renderização no cliente, no topo do arquivo, antes de qualquer import; ela dispensa repetição em todo arquivo de Client Component; entra só nos arquivos que servem de fronteira, e as props que a cruzam precisam ser serializáveis. O erro clássico que o curso descreve continua: escrever a diretiva em todo arquivo para calar o editor manda o componente inteiro para o navegador e joga fora o principal ganho do framework. Do outro lado, "use server" marca as Server Functions; para chamá-las do cliente, elas vivem em arquivo dedicado com a diretiva no topo.

Fronteira servidor-navegador do Next.js Server Components no alto, o arquivo com use client como ponto de entrada e props serializaveis cruzando a linha da fronteira. Servidor: Server Components (padrão) Layout (Server) Página (Server) Fronteira props que cruzam precisam ser serializáveis props serializáveis "use client" ponto de entrada, topo do arquivo Import: vira Client Component Import: sem repetir a diretiva Navegador Diretiva só nos arquivos de fronteira: em todo arquivo, o componente inteiro vai ao navegador.
A fronteira do Next.js 16: Server Components por padrão no alto, o arquivo com "use client" como ponto de entrada e só props serializáveis cruzando a linha.

Segurança virou critério de aceite. O July 2026 Security Release do Next.js, de 20 de julho de 2026, corrigiu nove CVEs, entre eles CVE-2026-64641 (negação de serviço via Server Actions, severidade alta), CVE-2026-64642 (bypass de proxy/middleware com Turbopack e um único locale, alta) e CVE-2026-64649 (SSRF em Server Actions em servidores custom, alta), com correções nas versões 16.2.11 e 15.5.21. Duas consequências práticas: o time cobra do agente versão mínima 16.2.11 (ou 15.5.21 na linha antiga) em qualquer entrega, e as recomendações da doc para Server Functions entram na revisão: autenticar e autorizar antes de operação sensível, ler autenticação de cookies ou headers em vez de aceitar token como parâmetro, e retornar só o que a interface precisa, porque o valor de retorno é serializado e enviado ao cliente.

Tela de dados: a escada e o v9 que mudou a conta

A escada do curso para lista longa segue válida: tabela nativa até alguns milhares de linhas; virtualização (TanStack Table para a lógica, TanStack Virtual 3.14.9 para desenhar só o visível) até a casa das cem mil; fatias pelo servidor quando a medição condenar o degrau de baixo; e desenhar como imagem só aceitando o preço de reconstruir a acessibilidade à mão. Sobe-se um degrau por vez, com medição.

Escada de quatro degraus para tela de dados Quatro degraus em ordem: tabela nativa, virtualizacao com TanStack Table v9 e Virtual, fatias pelo servidor e desenhar como imagem; sobe-se um degrau por vez, com medicao. Suba só com medição 1 Tabela nativa até alguns milhares de linhas 2 Virtualização TanStack Table v9 + TanStack Virtual até a casa das cem mil parte de 5kb, features declaradas 3 Fatias pelo servidor quando a medição condenar o degrau de baixo 4 Desenhar como imagem só aceitando o preço: acessibilidade reconstruída à mão sobe-se um degrau por vez, com medição
A escada para lista longa: tabela nativa até alguns milhares de linhas, virtualização com TanStack Table v9 e Virtual até a casa das cem mil, fatias pelo servidor quando a medição condenar o degrau de baixo, e imagem só aceitando reconstruir a acessibilidade à mão.

O degrau dois mudou de conta em 4 de agosto de 2026, quando o TanStack Table v9 saiu estável.

O modelo invertido

O guia de migração oficial inverte o modelo: cada tabela declara explicitamente as features que usa, via tableFeatures(), e o pacote parte de "5kb of bundled JS": tabela que só ordena deixa de embarcar o código de filtro e paginação.

O atalho que anula o ganho

O mesmo guia avisa: o modo de compatibilidade useLegacyTable inclui todas as features e "resulting in a larger bundle size than you even got with Table V8".

O passo de ouro na revisão

Registrar só os recursos que a tela usa e rodar o analisador de pacote antes e depois; ganho de peso sem medição é conversa.

Efeitos colaterais da virtualização

Os dois valem também aqui: o Ctrl+F do navegador deixa de encontrar o que ainda foi desenhado (ofereça busca própria) e a navegação por teclado precisa ser reconstruída.

Testes: comportamento, papel e navegador de verdade

A régua segue a da Testing Library, que a doc formula sem rodeio: o teste deve se parecer com o jeito que o usuário interage com a tela, e o getByRole, que consulta a árvore de acessibilidade, "should be your top preference for just about everything". A frase seguinte da doc é o bônus da revisão: se o papel deixa o elemento inalcançável, "it's possible your UI is inaccessible": o teste que falha em achar o botão pelo papel está denunciando a tela, além do código.

O ferramental de 2026 encorpou em três frentes.

Vitest 4

Lançado em 22 de outubro de 2025, removeu o selo experimental do Browser Mode e ganhou teste de regressão visual: componente rodando em navegador de verdade, com pacotes de renderização para React entre outros. A estável é a 4.1.10, com a v5 em release candidate.

Playwright

Aposentou os pacotes experimentais de component testing: o guia atual monta uma galeria de "stories" servida pelo próprio dev server, com a fixture mount() no @playwright/test comum (1.62.1): cliques reais, layout real, regressão visual possível.

Next.js 16.3 com Instant Navigations

Quem o usa ainda ganha o helper instant() para afirmar o que deve aparecer instantaneamente numa navegação.

A rede sob controle no teste de componente

Consultar pelo papel resolve metade do problema; a outra metade é o dado que o componente busca. Um componente montado sobre TanStack Query só se comporta como em produção quando a resposta da rede é controlável no teste, e trocar o fetch por uma função falsa amarra o teste ao detalhe de implementação que a própria régua da Testing Library manda evitar. O MSW (Mock Service Worker) intercepta a requisição na camada de service worker: o componente dispara a chamada de sempre, e o teste decide o que volta, com atraso, com erro ou com a lista inteira. Aí o ciclo fecha, porque o mesmo getByRole passa a afirmar os três estados que o usuário vê, carregando, falhou e chegou, sobre uma rede que o teste governa.

Como cancelar uma operação sem perder o texto recebido

Separe o pedido em andamento do resultado que já chegou e descarte respostas de pedidos antigos. Na escola Horizonte, um cenário hipotético, a agência revê um briefing enquanto o texto aparece em partes. Cancelar deve parar o trabalho local e conservar a parte útil para leitura. A oficina mostra o mecanismo inteiro: um AbortController (objeto nativo que carrega um sinal de cancelamento) por pedido, um número de série que identifica qual pedido ainda vale e uma mensagem distinta para cada fase.

Cenário da oficina

O botão de cancelar tem efeito quando chega à operação que está esperando. Trocar apenas o rótulo da tela deixa o processamento continuar; uma resposta atrasada ainda pode sobrescrever o pedido seguinte. O identificador da operação protege a tela dessa troca. O caso abaixo reproduz a reclamação que chegou ao suporte da agência: o texto do briefing anterior aparecia por cima do novo depois de a pessoa trocar o assunto e clicar de novo.

Quem
Marina, redatora da agência que atende a escola Horizonte, gera três briefings por tarde no painel de campanhas.
Tarefa
Pedir o briefing da campanha de matrículas, ler os primeiros trechos, perceber que o assunto estava errado, cancelar e pedir de novo com o assunto certo.
Falha vista
O botão mudava para "Cancelado", mas segundos depois o texto do pedido antigo continuava chegando e apagava o rascunho que ela já estava lendo. Em dois relatos, a resposta do assunto errado apareceu depois do começo da resposta certa.
Resultado esperado
Cancelar para a chegada de texto em menos de um segundo, o trecho já recebido continua na tela para leitura, e nenhum pedido antigo escreve na caixa depois de um pedido novo começar.
Mapa da oficina. Linha do tempo de dois pedidos: o primeiro é cancelado, sua resposta atrasada é descartada pelo número de série e o segundo conclui com o texto preservado.
Linha do tempo de pedidos com cancelamento por AbortController e descarte por número de série Três faixas horizontais: a tela, a operação 1 e a operação 2, sobre um eixo de tempo. Passo 1: a pessoa inicia e nasce a operação 1 com série 1 e um AbortController. Passo 2: dois trechos chegam e a tela mostra o texto parcial. Passo 3: a pessoa cancela; abort é chamado na operação 1 e a operação 2 nasce com série 2. Passo 4: um trecho atrasado da operação 1 tenta escrever na tela e é descartado porque a série 1 é diferente da ativa. Passo 5: a operação 2 conclui e a tela mostra o estado concluído com o texto preservado. Tela Op. 1 Op. 2 tempo Iniciar série 1 new AbortController() t1 t2 parcial: 2 trechos Cancelar abort() sinal abortado série 2 ativo = série 2 t3 1 ≠ 2: descartado t1 t4 concluída

  1. A pessoa inicia. Nasce a operação 1 com número de série 1 e um AbortController próprio; a referência "ativo" aponta para ela.
  2. Dois trechos chegam. Cada um passa pela checagem "ainda sou o ativo?" antes de entrar na tela, que mostra o texto parcial.
  3. A pessoa cancela e pede de novo. O código chama abort() na operação 1 e cria a operação 2 com série 2; "ativo" passa a apontar para a 2.
  4. Um trecho atrasado da operação 1 chega. A comparação de série falha (1 é diferente de 2) e o trecho é descartado sem tocar a tela.
  5. A operação 2 recebe seus trechos e conclui. A tela anuncia "concluída" uma única vez; o texto fica para leitura.

Sem JavaScript, o quadro aparece completo; a lista numerada descreve cada passo.

O desenho separa dois mecanismos que costumam ser confundidos. O AbortController interrompe a espera: quem está dentro de await recebe a rejeição e para de trabalhar. O número de série protege a tela: mesmo que a fonte ignore o cancelamento e continue enviando, nenhum trecho com série antiga chega ao estado. Os dois juntos cobrem o caso em que a rede demora e o caso em que o provedor responde depois de abortado.

Demonstrar

Observe três pontos na caixa abaixo. O número da operação no texto de estado muda a cada pedido novo, e esse é o número de série do mapa. A contagem de trechos para de subir no instante do cancelamento, enquanto o texto recebido continua visível. O botão Cancelar fica ativo apenas enquanto existe uma operação pendente, e o botão Repetir só depois do primeiro pedido.

Abra a aba Console das DevTools antes de começar. A demonstração usa um transporte local, sem rede; por isso a aba Rede fica vazia, e isso faz parte do exercício. Em um projeto real, cada pedido apareceria ali, e o cancelado mostraria o estado "(canceled)" na coluna de status.

Dados de exercício: os quatro trechos do briefing local
OrdemTrechoChega após
1Briefing hipotético com o assunto digitado650 ms
2Objetivo: revisar a clareza do formulário1,3 s
3Verificação pelo teclado (ponto da falha simulada)1,95 s
4Entrega: registrar o resultado local2,6 s

Demonstração local em JavaScript nativo. Os quatro trechos são predefinidos. Não há React em execução nesta caixa, API, modelo de IA ou envio de dados. A espera curta existe para você conseguir observar e cancelar cada etapa.

Briefing hipotético da escola Horizonte

Estado inicial. Preencha o assunto e inicie a simulação.

Nenhuma operação em andamento.

O texto de exemplo aparecerá aqui.

Execute a interrupção e a falha

  1. Inicie a simulação e cancele depois de aparecer o primeiro trecho. O texto permanece, e a contagem para de aumentar.
  2. Repita o mesmo pedido. Ele começa do zero com um novo número de série; repetir não anexa o conteúdo antigo nem recupera um trecho que ficou pendente.
  3. Ative a falha e inicie outra simulação. Depois de dois trechos, a mensagem explica a interrupção e mantém a parte recebida.
  4. Desative a falha e use Iniciar simulação para enviar a nova configuração. Repetir o mesmo pedido conserva a configuração anterior, inclusive a falha.
  5. Restaure o exemplo enquanto ele espera. Uma conclusão atrasada não deve repintar a caixa depois da restauração, porque a restauração esvazia a referência ativa antes de abortar.

Os estados inicial, enviando, recebendo, concluído, cancelado e erro têm significados diferentes, e a caixa de estado troca a frase inteira a cada transição. O texto parcial não comprova conclusão. Numa resposta longa real, atualize a apresentação em lotes e anuncie mudanças úteis de estado, em vez de enviar cada token ao leitor de tela.

Investigar as falhas

As cinco linhas abaixo saíram de revisões de código em painéis de campanha e portais de curso. Cada uma tem um teste reproduzível no navegador. Comece pelo sintoma que a pessoa descreve e só depois procure a causa no código; a ordem inversa costuma levar a refatorações sem efeito.

Falhas que esta oficina reproduz
SintomaCausa provávelComo confirmarCorreção
Texto do pedido antigo aparece por cima do novoA tela aceita qualquer resposta que chega; o pedido anterior continuou vivo sem AbortController ou a fonte ignora o sinal.Inicie, troque o assunto, inicie de novo em menos de um segundo. Na aba Rede, veja se o primeiro pedido segue como "pending" até terminar.Um AbortController por pedido, abort() antes de criar o próximo e comparação de série antes de cada setState.
Cancelar muda o rótulo, mas os trechos continuam chegandoO clique só altera estado visual; o sinal nunca é passado ao fetch ou à espera.Coloque um ponto de parada em "abort()" nas DevTools. Se ele nunca dispara, o botão está desconectado do controlador.Guardar o controlador em uma ref e chamar abort() no clique; passar o mesmo signal ao fetch.
Depois de uma falha, os botões ficam todos desabilitadosO bloco finally só libera a tela no caminho de sucesso, ou o erro é lançado antes de marcar pendente como falso.Ative a falha simulada e veja se "Iniciar" volta a ficar ativo após a mensagem de erro.Liberar os controles no finally, protegido pela comparação de série.
Aviso de "atualização em componente desmontado" ou texto que surge em outra telaO componente saiu da tela e a promessa pendente ainda chamou setState.Inicie e navegue para outra rota antes do fim. Em StrictMode, monte e desmonte duas vezes e conte os pedidos na aba Rede.Função de limpeza do Effect que aborta o ativo e zera a ref.
Leitor de tela narra cada trecho e a pessoa perde o estadoA região de texto recebido tem aria-live, ou o status repete a frase inteira a cada token.Com NVDA ou VoiceOver, inicie a simulação e conte quantas falas ocorrem antes de "concluída".aria-live só no parágrafo de status; a caixa de texto usa aria-busy e recebe o resultado em lotes.

Código de referência

O código abaixo reproduz em React o contrato que a demonstração implementa em JavaScript nativo: transporte com sinal, gancho com série e referência ativa, componente que só descreve a tela. Os três arquivos se importam na ordem em que aparecem. Em um projeto com o App Router do Next.js, acrescente "use client"; na primeira linha do componente.

// esperar-cancelavel.js
// Espera que respeita um AbortSignal e um transporte local de ensino.
// Em produção, troque localResponse por fetch(url, { signal }) e leia
// o corpo com response.body.getReader() para receber em partes.

export function esperar(ms, signal) {
  return new Promise((resolve, reject) => {
    if (signal.aborted) return reject(signal.reason);
    const aoAbortar = () => {
      clearTimeout(cronometro);
      signal.removeEventListener("abort", aoAbortar);
      reject(signal.reason); // DOMException "AbortError" por padrão
    };
    const cronometro = setTimeout(() => {
      signal.removeEventListener("abort", aoAbortar);
      resolve();
    }, ms);
    signal.addEventListener("abort", aoAbortar, { once: true });
  });
}

// Gerador assíncrono: entrega um trecho por vez e para no abort.
export async function* respostaLocal(assunto, falhar, signal) {
  const trechos = [
    `Briefing hipotético: ${assunto}.\n`,
    "Objetivo: revisar a clareza do formulário da campanha.\n",
    "Verificação: preencher pelo teclado e corrigir um campo inválido.\n",
    "Entrega: registrar o resultado local e o próximo ajuste."
  ];
  for (let i = 0; i < trechos.length; i += 1) {
    await esperar(650, signal);
    if (falhar && i === 2) throw new Error("Falha didática após dois trechos.");
    yield trechos[i];
  }
}
// useOperacaoCancelavel.js
// Um pedido ativo por vez, identificado por serial. Resposta de serial
// antigo é descartada antes de tocar o estado; o texto parcial fica.
import { useEffect, useRef, useState } from "react";

const INICIAL = { fase: "inicial", texto: "", recebidos: 0, serial: 0, erro: "" };

export function useOperacaoCancelavel(fonte) {
  const [vista, setVista] = useState(INICIAL);
  const ativo = useRef(null);   // { serial, controlador }
  const serial = useRef(0);
  const ultimoPedido = useRef(null);

  // Limpeza do Effect: sair da tela aborta o que estiver esperando.
  useEffect(() => () => { ativo.current?.controlador.abort(); ativo.current = null; }, []);

  async function executar(pedido) {
    ativo.current?.controlador.abort();           // cancela o anterior
    const tarefa = { serial: ++serial.current, controlador: new AbortController() };
    ativo.current = tarefa;
    ultimoPedido.current = pedido;
    setVista({ ...INICIAL, fase: "enviando", serial: tarefa.serial });
    try {
      for await (const trecho of fonte(pedido, tarefa.controlador.signal)) {
        if (ativo.current !== tarefa) return;      // serial antigo: descarta
        setVista((v) => ({ ...v, fase: "recebendo", texto: v.texto + trecho, recebidos: v.recebidos + 1 }));
      }
      if (ativo.current === tarefa) setVista((v) => ({ ...v, fase: "concluido" }));
    } catch (erro) {
      if (ativo.current !== tarefa) return;
      const cancelado = tarefa.controlador.signal.aborted;
      setVista((v) => ({ ...v, fase: cancelado ? "cancelado" : "falhou", erro: cancelado ? "" : String(erro.message || erro) }));
    } finally {
      if (ativo.current === tarefa) ativo.current = null;
    }
  }

  const cancelar = () => ativo.current?.controlador.abort();
  const repetir = () => { if (!ativo.current && ultimoPedido.current) executar(ultimoPedido.current); };
  const restaurar = () => {
    const anterior = ativo.current; ativo.current = null; // some antes de abortar
    anterior?.controlador.abort();
    ultimoPedido.current = null;
    setVista(INICIAL);
  };
  const pendente = vista.fase === "enviando" || vista.fase === "recebendo";
  return { vista, pendente, executar, cancelar, repetir, restaurar };
}
// OperacaoCancelavel.jsx  (no App Router do Next.js, comece com "use client";)
import { useState } from "react";
import { respostaLocal } from "./esperar-cancelavel";
import { useOperacaoCancelavel } from "./useOperacaoCancelavel";

const MENSAGENS = {
  inicial: "Estado inicial. Preencha o assunto e inicie a simulação.",
  enviando: "Enviando na simulação local.",
  recebendo: "Recebendo texto local. Você pode cancelar.",
  concluido: "Concluída localmente. Nenhum dado foi enviado.",
  cancelado: "Cancelada. O texto parcial foi preservado.",
  falhou: "A operação falhou. O texto parcial foi preservado."
};

export default function OperacaoCancelavel() {
  const [assunto, setAssunto] = useState("Campanha da escola Horizonte");
  const [falhar, setFalhar] = useState(false);
  const op = useOperacaoCancelavel((pedido, signal) => respostaLocal(pedido.assunto, pedido.falhar, signal));

  function enviar(evento) {
    evento.preventDefault();
    if (op.pendente || !assunto.trim()) return;
    op.executar({ assunto: assunto.trim(), falhar });
  }
  const rotulo = op.vista.serial ? `Operação ${op.vista.serial}: ` : "";
  const detalhe = op.vista.fase === "falhou" ? ` ${op.vista.erro}` : "";

  return (
    <section aria-label="Operação local cancelável">
      <form onSubmit={enviar}>
        <label>Assunto do briefing
          <input required maxLength={120} value={assunto} readOnly={op.pendente}
            onChange={(e) => setAssunto(e.target.value)} />
        </label>
        <label><input type="checkbox" checked={falhar} disabled={op.pendente}
          onChange={(e) => setFalhar(e.target.checked)} /> Simular falha após dois trechos</label>
        <button disabled={op.pendente}>Iniciar simulação</button>
        <button type="button" disabled={!op.pendente} onClick={op.cancelar}>Cancelar operação</button>
        <button type="button" disabled={op.pendente || op.vista.serial === 0} onClick={op.repetir}>Repetir o mesmo pedido</button>
        <button type="button" onClick={op.restaurar}>Restaurar exemplo</button>
      </form>
      {/* Uma mensagem por fase; o leitor de tela recebe só a mudança de estado. */}
      <p role="status">{rotulo}{MENSAGENS[op.vista.fase]}{detalhe}</p>
      <p>{op.vista.recebidos} de 4 trechos recebidos.</p>
      <pre role="region" aria-label="Texto recebido" aria-busy={op.pendente}>{op.vista.texto || "O texto de exemplo aparecerá aqui."}</pre>
    </section>
  );
}

A função de limpeza do Effect cancela a operação quando o componente sai da tela. Cada pedido recebe seu próprio objeto; antes de aplicar uma resposta, o código verifica se ele ainda é o ativo. Isso também protege o caso em que a fonte ignora o cancelamento. O método "restaurar" esvazia a referência antes de chamar abort(), e por isso a rejeição da espera encontra um ativo diferente e sai sem escrever.

Ao conectar uma API real, passe o signal ao fetch e propague a interrupção no servidor quando o provedor permitir. Autenticação, autorização, limite de uso e prazo pertencem ao servidor. Cancelar a espera não desfaz uma escrita já confirmada, e repetir uma geração pode consumir uma nova chamada cobrada.

Critérios de aceite

Levar para o projeto. Em React ou Next.js, o gancho acima entra como está; em Astro ou HTML puro, o mesmo contrato cabe em uma classe com os métodos executar, cancelar e restaurar, que é o que a demonstração desta página faz. Em produção, meça três coisas: a proporção de pedidos cancelados (acima de um quinto indica que o assunto é mal explicado antes do envio), o tempo entre o clique em cancelar e a última escrita na tela, e a quantidade de pedidos com série antiga descartados, que deve ser maior que zero sem nunca aparecer para a pessoa.

Referências verificadas em 6 de outubro de 2026: MDN: AbortSignal e cancelamento, MDN: AbortController, React: ciclo de vida e limpeza de Effects e W3C: mensagens de estado e excesso de anúncios.

Como reordenar tarefas sem trocar seus rascunhos

Mantenha o identificador da tarefa quando sua posição muda e guarde o texto necessário para desfazer a exclusão. A agência da escola Horizonte, ainda no exemplo hipotético, reorganiza a campanha enquanto edita os títulos. O rascunho precisa acompanhar a tarefa, mesmo quando ela muda de lugar. A oficina trata a lista como três camadas que precisam concordar: a ordem no estado, os nós no documento (cada um preso a um id por chave estável) e o movimento que apenas ilustra a diferença entre a posição antiga e a nova.

Cenário da oficina

Uma lista pode deslizar com suavidade e estar errada: o campo parece pertencer a outro item, ou a restauração recupera o título antigo. Primeiro confira identidade, ordem do documento e foco. Depois anime a diferença entre a posição anterior e a nova. O caso abaixo vem do painel de produção de uma campanha de matrículas, onde a ordem das tarefas muda várias vezes por dia.

Quem
Caio, coordenador de conteúdo da agência, organiza as tarefas da campanha de matrículas da escola Horizonte num quadro com três cartões editáveis: briefing, formulário e material.
Tarefa
Reescrever o título do cartão briefing, descê-lo para a segunda posição, excluir o cartão material por engano e recuperá-lo com o texto que tinha.
Falha vista
Depois de descer o cartão, o texto reescrito ficou no primeiro cartão, agora chamado formulário. Ao desfazer a exclusão, o cartão material voltou com o título de fábrica, sem a edição da tarde. No celular, o foco pulou para o topo da página a cada movimento.
Resultado esperado
O texto editado acompanha o cartão briefing para a segunda posição; desfazer devolve o cartão material com o texto editado, na posição em que estava; o foco permanece no controle da tarefa movida.
Mapa da oficina. Estado com ids, nós no documento presos por chave estável e, à direita, o caminho errado com chave por índice; abaixo, a medida FLIP e a remoção com desfazer.
Lista com chave estável: estado, nós no documento, FLIP, remoção e desfazer, ao lado do erro de chave por índice Três colunas. À esquerda, o estado como lista de ids: briefing, formulario, material. No centro, os nós do documento, um por id. À direita, o caminho errado com chave por índice. Passo 1: cada id aponta para seu nó. Passo 2: a pessoa digita um rascunho no campo do nó briefing. Passo 3: briefing desce para a segunda posição; o mesmo nó se move com o rascunho e o FLIP mede a diferença de topo para animar; no caminho errado, o nó da posição 1 continua no lugar com o rascunho e recebe o título formulário. Passo 4: material é removido do estado e do documento, mas o objeto com id e posição fica guardado. Passo 5: desfazer insere o item de volta na posição 3 e o foco vai para o campo desse nó. Estado (ids) Nós no documento Errado: chave = índice briefing formulario material key=id nó briefing nó formulário nó material nó da posição 1 nó da posição 2 rascunho digitado rascunho digitado briefing desce nó briefing + rascunho delta = antes − depois FLIP: anima delta até 0 formulário + rascunho o texto ficou no índice 0 e mudou de dono removido = { id, posição 3 } nó sai, Map guarda splice(3, 0, item) foco no campo de material

  1. O estado é uma lista de ids. Cada id aponta para um nó do documento pela chave estável; o caminho errado, à direita, numera os nós pela posição.
  2. A pessoa digita um rascunho no campo do nó briefing. Nas duas colunas o texto está no primeiro nó.
  3. briefing desce para a segunda posição. Com chave estável, o mesmo nó se move levando o rascunho, e o FLIP mede a diferença de topo para animar. Com chave por índice, o nó fica parado, recebe o título formulário e o rascunho muda de dono.
  4. material é removido do estado e sai do documento, mas o objeto com id e posição fica guardado em "removido", junto com o texto editado.
  5. Desfazer insere o item de volta na posição 3, o nó reaparece com o rascunho e o foco vai para o campo desse nó, e assim o leitor de tela anuncia a tarefa restaurada.

Sem JavaScript, o quadro aparece completo; a lista numerada descreve cada passo.

A sigla FLIP vem de First, Last, Invert, Play (medir antes, deixar o navegador aplicar a nova ordem, deslocar o elemento de volta e animar até zero). Ela aparece no mapa como uma caixa de cálculo porque é um cálculo: a diferença entre o topo medido antes da troca e o topo depois dela. O deslocamento inicial é aplicado com transform, e por isso a ordem real do documento já está correta no primeiro quadro da animação.

Demonstrar

Observe a linha "Ordem atual no documento" abaixo da lista. Ela imprime os ids na ordem em que os nós estão no documento, e é a prova de que a reordenação aconteceu antes da animação terminar. Observe também para onde o foco vai depois de cada ação: o botão clicado continua focado após mover; o botão Desfazer recebe foco após excluir; o campo da tarefa restaurada recebe foco após desfazer.

Para inspecionar, abra a aba Elements das DevTools, selecione o ul da lista e acompanhe os li trocando de lugar: o atributo data-item-id continua colado a cada nó. Depois ative "Rendering" e "Paint flashing" para ver que só os itens deslocados são repintados.

Dados de exercício: as três tarefas da campanha
Id estávelTítulo inicialPosição inicial
briefingRevisar proposta da escola1
formularioConferir formulário da campanha2
materialPreparar material da aula3

Demonstração local em JavaScript nativo. Os mesmos elementos do documento mudam de posição; não há React, arraste obrigatório ou servidor nesta caixa. Os dados ficam apenas nesta página. Uma recarga restaura os títulos iniciais.

Tarefas hipotéticas da campanha
  • Identificador estável: briefing
  • Identificador estável: formulario
  • Identificador estável: material

Edite uma tarefa e mude sua posição.

Ordem inicial no documento: briefing, formulario, material.

Confira identidade, foco e recuperação

  1. Troque o título de briefing por uma tarefa sua. Use Descer e confira se o texto acompanha o identificador briefing.
  2. Faça o caminho pelo teclado. O controle da tarefa movida mantém o foco; ao alcançar uma borda, o foco volta ao campo daquela tarefa.
  3. Exclua a tarefa editada e use Desfazer última exclusão. O rascunho volta, e o campo restaurado recebe foco.
  4. Ative a recusa e tente excluir outra tarefa. A mensagem explica o resultado; ordem e rascunho permanecem iguais.
  5. Ative a preferência de menos movimento do sistema ou do portal. Repita a reordenação: o mesmo resultado aparece sem o deslocamento animado.

A demonstração guarda só a última exclusão, sem prazo oculto para desfazer. Excluir de novo substitui essa possibilidade; os demais rascunhos continuam preservados. Para uma aplicação que precisa de histórico maior, defina a quantidade de operações e a persistência antes de prometer recuperação.

Investigar as falhas

As falhas abaixo têm um traço em comum: a animação esconde o problema por alguns segundos. Desligue o movimento (preferência do sistema ou interruptor do portal) antes de investigar; com a lista parada, o defeito de identidade aparece no primeiro clique.

Falhas que esta oficina reproduz
SintomaCausa provávelComo confirmarCorreção
O texto digitado fica na posição antiga e muda de tarefaChave por índice (key={i}) ou campo não controlado: React reaproveita o nó da posição e só troca o título.Digite num campo, mova a tarefa e compare o data-item-id do li que contém o texto na aba Elements.key={item.id} com id vindo do dado; título no estado da lista, nunca só no DOM.
Desfazer restaura o título de fábricaA exclusão guardou apenas o id e a restauração relê o item de uma lista inicial.Edite, exclua, desfaça. Se o texto voltou ao original, o objeto guardado não carregava o rascunho.Guardar o item completo e a posição no momento da exclusão.
Foco pula para o topo da página após moverO botão clicado foi destruído e recriado, ou o foco é restaurado pelo índice de antes da troca.Use Tab até "Descer", pressione Enter e veja onde o anel de foco aparece; com leitor de tela, ouça o que é anunciado.Guardar o id que deve receber foco e aplicá-lo em useLayoutEffect, buscando o nó pelo id.
Item fica deslocado quando a animação é interrompidaDuas animações ao mesmo tempo no mesmo nó, ou transform fixado por estilo em linha ao cancelar.Clique em Descer e Subir em sequência rápida; inspecione o style do li no fim.Cancelar as animações pendentes antes de medir; usar element.animate sem estilo em linha residual.
Com menos movimento ativado, os itens continuam deslizandoA preferência é lida uma vez na montagem e não escuta "change", ou só a preferência do sistema é considerada.Com a página aberta, ative "Reduzir movimento" no sistema e mova um item.Escutar o evento change da matchMedia e o atributo do portal; cancelar animações na mudança.
A lista vazia prende a pessoa sem saídaO botão Desfazer está dentro da lista removida ou fica desabilitado quando não há itens.Exclua as três tarefas e tente recuperar uma sem recarregar.Desfazer e Restaurar fora da lista, sempre alcançáveis pelo teclado; parágrafo de estado vazio com instrução.

Código de referência

O gancho useFlip isola a medição e a animação; o componente cuida só de estado, foco e desfazer. A terceira peça mostra a mesma reordenação com a View Transitions API (recurso do navegador que fotografa o antes e o depois de uma mudança no DOM e anima a diferença), útil em Astro ou HTML puro. No App Router do Next.js, acrescente "use client"; na primeira linha dos dois primeiros arquivos.

// useFlip.js
// FLIP com a Web Animations API: First (mede antes), Last (React pinta a
// nova ordem), Invert (desloca de volta), Play (anima até zero).
// Cada animação é cancelada ao desmontar ou quando a preferência muda.
import { useEffect, useLayoutEffect, useRef } from "react";

export function useFlip(dependencia, { duracao = 180 } = {}) {
  const nos = useRef(new Map());          // id -> elemento
  const posicoes = useRef(new Map());     // id -> top medido no ciclo anterior
  const animacoes = useRef(new Set());
  const reduzido = useRef(false);

  // Registrador de ref: use em <li ref={registrar(item.id)}>.
  const registrar = (id) => (no) => { if (no) nos.current.set(id, no); else nos.current.delete(id); };
  const cancelarTudo = () => { animacoes.current.forEach((a) => a.cancel()); animacoes.current.clear(); };

  useEffect(() => {
    const consulta = matchMedia("(prefers-reduced-motion: reduce)");
    const ler = () => { reduzido.current = consulta.matches || document.documentElement.dataset.llxMotion === "reduce"; cancelarTudo(); };
    ler();
    consulta.addEventListener("change", ler);
    return () => { consulta.removeEventListener("change", ler); cancelarTudo(); };
  }, []);

  // Roda depois que o DOM foi reordenado e antes de o navegador pintar.
  useLayoutEffect(() => {
    cancelarTudo();
    const atuais = new Map();
    nos.current.forEach((no, id) => {
      const topo = no.getBoundingClientRect().top;
      const anterior = posicoes.current.get(id);
      atuais.set(id, topo);
      const delta = anterior === undefined ? 0 : anterior - topo;
      if (!reduzido.current && delta && typeof no.animate === "function") {
        const animacao = no.animate(
          [{ transform: `translateY(${delta}px)` }, { transform: "translateY(0)" }],
          { duration: duracao, easing: "ease-out" }
        );
        animacoes.current.add(animacao);
        animacao.onfinish = animacao.oncancel = () => animacoes.current.delete(animacao);
      }
    });
    posicoes.current = atuais;
  }, [dependencia, duracao]);

  return { registrar, nos };
}
// ListaComIdentidade.jsx  (no App Router do Next.js, comece com "use client";)
import { useLayoutEffect, useRef, useState } from "react";
import { useFlip } from "./useFlip";

const INICIAIS = [
  { id: "briefing", titulo: "Revisar proposta da escola" },
  { id: "formulario", titulo: "Conferir formulário da campanha" },
  { id: "material", titulo: "Preparar material da aula" }
];

export default function ListaComIdentidade() {
  const [itens, setItens] = useState(INICIAIS);
  const [removido, setRemovido] = useState(null);   // { item, posicao }
  const [aviso, setAviso] = useState("Edite uma tarefa e mude sua posição.");
  const { registrar, nos } = useFlip(itens);
  const focoId = useRef(null);                       // id que recebe foco após pintar
  const botaoDesfazer = useRef(null);

  // Foco preso ao id, nunca ao índice: o mesmo nó recebe o foco após mover.
  useLayoutEffect(() => {
    if (focoId.current === "desfazer") botaoDesfazer.current?.focus();
    else if (focoId.current) nos.current.get(focoId.current)?.querySelector("input")?.focus({ preventScroll: true });
    focoId.current = null;
  }, [itens, nos]);

  function mover(id, direcao) {
    const proximo = [...itens];
    const i = proximo.findIndex((it) => it.id === id);
    const destino = i + direcao;
    if (destino < 0 || destino >= proximo.length) return;
    [proximo[i], proximo[destino]] = [proximo[destino], proximo[i]];
    focoId.current = id;
    setItens(proximo);
    setAviso(`${id} movido para a posição ${destino + 1}.`);
  }
  function remover(id) {
    const i = itens.findIndex((it) => it.id === id);
    setRemovido({ item: itens[i], posicao: i });      // guarda o rascunho junto
    const restantes = itens.filter((it) => it.id !== id);
    focoId.current = "desfazer";
    setItens(restantes);
    setAviso(`${id} removido. Desfazer recupera o texto.`);
  }
  function desfazer() {
    if (!removido) return;
    const proximo = [...itens];
    proximo.splice(Math.min(removido.posicao, proximo.length), 0, removido.item);
    focoId.current = removido.item.id;
    setItens(proximo); setRemovido(null);
    setAviso(`${removido.item.id} restaurado com o rascunho.`);
  }
  const editar = (id, titulo) => setItens((atual) => atual.map((it) => (it.id === id ? { ...it, titulo } : it)));

  return (
    <section aria-label="Lista com identidade">
      <button ref={botaoDesfazer} disabled={!removido} onClick={desfazer}>Desfazer última exclusão</button>
      <p role="status">{aviso}</p>
      {!itens.length && <p>Lista vazia. Desfaça a última exclusão.</p>}
      <ul>
        {itens.map((item, i) => (
          <li key={item.id} ref={registrar(item.id)}>
            <label>Tarefa {item.id}
              <input value={item.titulo} maxLength={100} onChange={(e) => editar(item.id, e.target.value)} />
            </label>
            <button disabled={i === 0} onClick={() => mover(item.id, -1)} aria-label={`Subir ${item.id}`}>Subir</button>
            <button disabled={i === itens.length - 1} onClick={() => mover(item.id, 1)} aria-label={`Descer ${item.id}`}>Descer</button>
            <button onClick={() => remover(item.id)} aria-label={`Excluir ${item.id}`}>Excluir</button>
          </li>
        ))}
      </ul>
    </section>
  );
}
// reordenar-com-view-transitions.js
// Alternativa ao FLIP manual: a View Transitions API tira a foto "antes",
// aplica a mudança de DOM e anima cada elemento nomeado até a posição "depois".
// Funciona em HTML puro, Astro ou dentro de flushSync no React.

export function reordenarAnimado(lista, novaOrdem, { reduzido = false } = {}) {
  const nos = new Map([...lista.children].map((no) => [no.dataset.itemId, no]));
  const aplicar = () => { for (const id of novaOrdem) lista.append(nos.get(id)); };

  // Sem suporte ou com menos movimento pedido: só reordena.
  if (reduzido || typeof document.startViewTransition !== "function") { aplicar(); return Promise.resolve(); }

  // Cada item precisa de um view-transition-name único e estável (o id).
  nos.forEach((no, id) => { no.style.viewTransitionName = `item-${id}`; });
  const transicao = document.startViewTransition(aplicar);
  return transicao.finished.finally(() => {
    nos.forEach((no) => { no.style.viewTransitionName = ""; });
  });
}

/* CSS mínimo que acompanha (um arquivo .css do projeto):
::view-transition-group(*) { animation-duration: 180ms; animation-timing-function: ease-out; }
@media (prefers-reduced-motion: reduce) {
  ::view-transition-group(*), ::view-transition-old(*), ::view-transition-new(*) { animation: none; }
}
*/

// Em React 19, envolva o setState em flushSync dentro do callback para que a
// foto "depois" seja tirada com o DOM já atualizado:
//   document.startViewTransition(() => flushSync(() => setItens(proximo)));

O exemplo React respeita a preferência de movimento do sistema e cancela animações ao desmontar. Se a aplicação também oferecer uma preferência própria, combine as duas, como faz a demonstração desta página. A animação serve para mostrar a mudança; a ordem real dos elementos já está correta antes dela terminar.

Em uma exclusão remota, a confirmação pode chegar depois. useOptimistic permite mostrar um estado provisório, mas a aplicação ainda precisa explicar a falha e preservar informação para recuperar o item. Aqui a recusa é local e explícita; nenhum timer representa confirmação de servidor. Ocultar com Activity, desmontar e excluir são decisões diferentes. Para a campanha da escola, registre qual delas cada comando realiza e teste o rascunho depois de voltar.

Critérios de aceite

Levar para o projeto. Em React ou Next.js, copie o gancho e o componente e troque os dados iniciais pelos da sua API, mantendo o id do banco como chave. Em Astro ou HTML puro, use a função com View Transitions e dê a cada item um view-transition-name derivado do id. Em produção, meça a taxa de "desfazer" após exclusão (acima de um décimo das exclusões indica botão mal posicionado) e registre, em teste automatizado, que o elemento com o texto editado mantém o mesmo id depois de uma reordenação.

Referências verificadas em 6 de outubro de 2026: React: preservar e reiniciar estado, React: atualização otimista e recuperação, React: ocultar uma interface preservando estado com Activity, MDN: Element.animate (Web Animations API) e MDN: View Transition API.

Animação em React que acompanha a rolagem e se desfaz ao sair

Numa animação vinculada à rolagem, o chamado scrub (a animação avança conforme a pessoa rola), o movimento anda para a frente quando a página desce e volta quando a página sobe. Quem comanda o ritmo é o gesto da pessoa, sem relógio interno disparando a sequência. Por isso ela funciona bem para revelar blocos, criar profundidade e contar uma sequência. A oficina percorre o mecanismo completo: o ouvinte de rolagem que mede o alvo, o laço que interpola a posição com atraso, a parada quando o elemento chega, a versão parada para quem pediu menos movimento e a limpeza que desfaz tudo ao desmontar.

Cenário da oficina

O ajuste que mais muda a sensação é o atraso de suavização, o tempo que o elemento leva para alcançar a rolagem. Os guias gratuitos do Annnimate, estúdio Good Fella, recomendam de 0,5 a 1 s para revelação e profundidade e de 1,5 a 2 s para atmosfera, como fundos distantes. Acima de 2 s, o movimento parece desligado do gesto. O caso abaixo junta o ajuste de atraso ao defeito que mais aparece em revisão: a animação que sobrevive à desmontagem do componente.

Quem
Lia, desenvolvedora da página de vendas do curso de marketing da escola Horizonte, feita em Next.js com três blocos de depoimentos que sobem e aparecem conforme a rolagem.
Tarefa
Deixar a revelação presa ao gesto com chegada macia, garantir que a página fique parada para quem pediu menos movimento e provar que navegar entre a página de vendas e o checkout dez vezes deixa um único ouvinte de rolagem vivo.
Falha vista
Com o atraso em 3 s, os depoimentos ainda subiam quando a pessoa já tinha parado de rolar. Depois de ir e voltar do checkout algumas vezes, o celular esquentava e a rolagem engasgava: cada visita deixava um ouvinte e um laço de animação presos à página antiga, e o StrictMode mostrava a animação em dobro já no ambiente local.
Resultado esperado
Atraso entre 0,5 e 1 s; versão parada com movimento reduzido; contador de ouvintes em 1 depois de qualquer quantidade de idas e voltas; laço de animação parado quando o bloco sai da tela.
Mapa da oficina. Do gesto de rolagem ao transform, passando pelo laço com atraso, a parada ao chegar, o atalho para movimento reduzido e a limpeza correta ao lado do ouvinte órfão.
Pipeline da animação presa à rolagem: ouvinte, medição, laço com atraso, parada, movimento reduzido e limpeza na desmontagem Quatro linhas de caixas ligadas por setas. Passo 1: o gesto de rolagem dispara o ouvinte passivo, que chama medir e calcula o alvo em pixels. Passo 2: iniciar laço só roda se o componente está montado e visível, segundo o IntersectionObserver. Passo 3: a cada quadro, a posição atual avança uma fração exponencial da distância até o alvo, com constante de tempo igual ao atraso dividido por três, e o resultado vai para transform translateX. Passo 4: quando a distância cai abaixo de meio pixel o laço para e fica em espera; com movimento reduzido, a posição atual recebe o alvo direto, sem laço. Passo 5: desmontar remove o ouvinte, desconecta os três observadores e cancela o quadro pendente; o contador de ouvintes fica em um. Passo 6: no caminho errado, sem limpeza, o ouvinte fica preso à faixa e o contador sobe a dois e três a cada remontagem. gesto: rolagem scroll, passive medir(): alvoX linha fina no alvo iniciarLaco() só se montado e visível (IntersectionObserver) requestAnimationFrame(passo) um laço por vez: quadro guarda o id atualX += (alvoX − atualX) · (1 − e^(−dt/τ)) τ = atraso / 3: chega a 95 % no tempo escolhido transform: translateX sem layout, sem will-change |alvo − atual| < 0,5 px laço para: "em espera" movimento reduzido atualX = alvoX, sem laço desmontar() removeEventListener disconnect ×3, cancelAF ouvintes: 1 sem limpeza ouvinte órfão preso StrictMode: em dobro ouvintes: 2, 3…

  1. O gesto de rolagem dispara o ouvinte passivo da faixa. Ele chama medir(), que converte a posição da rolagem em um alvo em pixels e move a linha fina.
  2. iniciarLaco() pede um requestAnimationFrame somente se o componente está montado, visível na tela (IntersectionObserver) e sem laço em andamento.
  3. A cada quadro, passo() avança a posição atual por uma fração exponencial da distância, com constante de tempo igual ao atraso dividido por três, e escreve o resultado em transform.
  4. Quando a distância fica abaixo de meio pixel, o laço para e o painel mostra "em espera". Com movimento reduzido, a posição atual recebe o alvo direto e o laço nem começa.
  5. desmontar() remove o ouvinte, desconecta os observadores de visibilidade, tamanho e preferência e cancela o quadro pendente. O contador de ouvintes fica em 1 após remontar.
  6. No caminho errado, a função de limpeza não existe: o ouvinte fica preso à faixa, o StrictMode duplica a animação e o contador sobe a 2 e 3 a cada remontagem.

Sem JavaScript, o quadro aparece completo; a lista numerada descreve cada passo.

Por que a animação precisa ser desfeita quando o componente sai

Um componente React nasce quando aparece na tela e é desmontado quando sai dela. Se a animação criada ali não for desfeita, sobram ouvintes órfãos (funções que continuam esperando a rolagem) e cálculos que ninguém vê. Isso é vazamento de memória: a página fica mais pesada a cada visita àquela tela e o celular sente primeiro.

O React 19 deixa o problema visível. No StrictMode, o modo de desenvolvimento que roda verificações extras, cada efeito é montado, desmontado e montado de novo de propósito. Sem limpeza, a mesma animação passa a existir em dobro, com dois gatilhos disputando o mesmo elemento. O defeito que só apareceria semanas depois em produção aparece logo no primeiro teste local.

O GSAP, biblioteca de animação gratuita com todos os plugins desde a versão 3.13, resolve isso no React com o useGSAP, gancho do pacote @gsap/react. Tudo o que for criado dentro dele é desfeito sozinho quando o componente desmonta. Dentro do gancho, gsap.matchMedia() com (prefers-reduced-motion: no-preference) registra o movimento só para quem não pediu menos movimento ao sistema.

Um último cuidado vale para o CSS. A propriedade will-change, que pede ao navegador uma camada própria para o elemento, só compensa em quem se move o tempo todo. Segundo os mesmos guias, cem elementos com ela bastam para derrubar um celular. Um bloco que só se revela uma vez dispensa a dica.

Demonstrar

Observe três medidores abaixo da faixa. "Distância entre rolagem e quadrado" é o valor absoluto de alvo menos atual, o mesmo da caixa de chegada do mapa; ela sobe durante o gesto e cai a zero depois que você para. "Ouvintes de rolagem ativos" conta quantas funções estão presas à faixa, e é o número que prova a limpeza. "Laço de animação" mostra se o requestAnimationFrame está rodando, em espera, parado ou parado fora da tela.

Para ver o laço parar fora da tela, role a página inteira até a oficina sumir e volte: o medidor muda para "parado fora da tela" e retorna a "em espera". Na aba Performance das DevTools, grave cinco segundos rolando a faixa com 0,5 s e repita com 3 s: a quantidade de quadros com trabalho é maior no segundo caso, porque o quadrado demora mais para chegar.

Dados de exercício: os cinco atrasos da faixa
AtrasoConstante de tempo (atraso ÷ 3)Leitura
0 ssem interpolaçãocola no gesto, como scrub ligado com valor verdadeiro
0,5 s0,17 srevelação e profundidade: acompanha com leveza
1 s0,33 srevelação e profundidade: chegada mais macia
2 s0,67 satmosfera: fundos e camadas distantes
3 s1 smovimento desligado do gesto, só para provar o limite

Demonstração local em JavaScript nativo, sem GSAP. Role a faixa abaixo com a roda do mouse, o dedo ou as setas do teclado depois de focá-la. O quadrado acompanha a rolagem; a linha fina marca onde ele deveria estar sem atraso.

Atraso de suavização

Faixa indicada para revelação e profundidade (0,5 a 1 s): acompanha o gesto com leveza.

Posição do quadrado na pista
  1. Trecho 1 de 6: início da faixa
  2. Trecho 2 de 6: role mais um pouco
  3. Trecho 3 de 6: compare a linha e o quadrado
  4. Trecho 4 de 6: pare e veja a distância cair
  5. Trecho 5 de 6: troque o atraso e repita
  6. Trecho 6 de 6: fim da faixa
Distância entre rolagem e quadrado
0 px
Ouvintes de rolagem ativos
0
Laço de animação
sem JavaScript

Escolha um atraso e role a faixa.

Como ler a oficina

  1. Com 0 s, a distância fica perto de zero o tempo todo. Com 0,5 e 1 s, ela sobe durante o gesto e cai logo depois que você para.
  2. Com 3 s, o quadrado ainda está chegando quando você já parou de rolar. É a sensação de movimento desligado do gesto que os guias apontam.
  3. Use Desmontar e montar de novo. O contador vai a 0 e volta a 1: o ouvinte antigo saiu antes de o novo entrar.
  4. Marque a simulação sem limpeza e repita. O contador sobe para 2, depois 3: é o efeito em dobro do StrictMode. Desmarcar remove os ouvintes esquecidos. A demonstração limita a simulação a quatro ouvintes esquecidos para a página continuar leve.

O laço de animação, a função que redesenha o quadrado a cada quadro da tela, só roda enquanto o quadrado ainda não alcançou a rolagem e para quando a oficina sai da tela. A animação mexe apenas em transform, a propriedade que o navegador move sem recalcular o layout da página. Ela dispensa will-change, porque o quadrado fica parado na maior parte do tempo.

Investigar as falhas

Os sintomas abaixo aparecem em páginas de vendas e portais de curso com revelação na rolagem. Três deles só se manifestam depois de várias navegações, por isso a tabela indica como provocar a repetição sem esperar o relato de quem usa.

Falhas que esta oficina reproduz
SintomaCausa provávelComo confirmarCorreção
A página engasga mais a cada ida e volta entre rotasOuvinte de rolagem e laço de animação criados no efeito sem função de limpeza.Em Performance das DevTools, use o painel de ouvintes do elemento (aba Event Listeners) após dez navegações; ou use a simulação sem limpeza desta página e veja o contador subir.Devolver a função de limpeza no useEffect, ou criar tudo dentro de useGSAP, que reverte sozinho.
Animação em dobro no ambiente local, normal em produçãoStrictMode monta, desmonta e remonta; sem limpeza, dois ScrollTriggers disputam o mesmo elemento.Com StrictMode ligado, imprima no console o total de ScrollTrigger.getAll() após a montagem.A mesma limpeza da linha anterior; o StrictMode é o teste, e a produção também está vazando.
O elemento chega depois que a pessoa já parou de rolarAtraso de suavização acima de 2 s em elemento de conteúdo.Selecione 3 s na faixa, role e pare: a distância continua acima de zero por mais de um segundo.scrub entre 0,5 e 1 para revelação; valores maiores só em fundos e camadas distantes.
Com menos movimento ativado, os blocos continuam subindoA animação foi registrada fora de gsap.matchMedia, ou o CSS de partida (opacity 0) vale para todos.Ative "Reduzir movimento" no sistema e recarregue; os blocos devem estar visíveis e parados no lugar.Registrar dentro de matchMedia com no-preference e deixar o estado de partida só nessa media query.
Blocos invisíveis para sempre em quem usa leitor de tela ou JavaScript bloqueadoO CSS parte de opacity 0 e só o JavaScript revela.Desligue JavaScript nas DevTools e recarregue; percorra a página com o leitor de tela e procure os depoimentos.Estado de partida aplicado por classe que o JavaScript adiciona, ou dentro de @supports e da media query de movimento.
Rolagem pesada no celular mesmo com poucos elementos animadoswill-change em dezenas de elementos, ou animação de top, left ou height em vez de transform.Em Rendering das DevTools, ative "Layer borders" e conte as camadas; em Performance, procure "Layout" nos quadros durante a rolagem.Animar só transform e opacity; will-change apenas em quem se move continuamente.

Código de referência

O primeiro arquivo é a versão com GSAP: o useGSAP desfaz tudo ao desmontar e o matchMedia cuida do movimento reduzido. O segundo reproduz, como gancho React sem biblioteca, o mecanismo da demonstração desta página, com a função de limpeza que espelha cada coisa criada. O terceiro é o CSS da versão parada e de uma revelação dirigida pela rolagem sem JavaScript, com animation-timeline: view() onde houver suporte. Instale gsap e @gsap/react para o primeiro.

"use client";
// RevelacaoNaRolagem.jsx
// Revelação presa à rolagem com GSAP + ScrollTrigger. O useGSAP desfaz tudo
// o que foi criado no escopo quando o componente desmonta, inclusive no
// ciclo duplo do StrictMode. gsap.matchMedia registra a animação só para
// quem não pediu menos movimento; os demais recebem a versão parada.
import { useRef } from "react";
import gsap from "gsap";
import { ScrollTrigger } from "gsap/ScrollTrigger";
import { useGSAP } from "@gsap/react";

gsap.registerPlugin(ScrollTrigger, useGSAP);

export default function RevelacaoNaRolagem({ children, atraso = 0.5 }) {
  const raiz = useRef(null);

  useGSAP(() => {
    const mm = gsap.matchMedia();
    mm.add("(prefers-reduced-motion: no-preference)", () => {
      // Os cartões sobem e aparecem conforme a pessoa rola; scrub entre
      // 0,5 e 1 s mantém o movimento preso ao gesto com chegada macia.
      gsap.from(".cartao", {
        y: 48,
        opacity: 0,
        stagger: 0.1,
        scrollTrigger: {
          trigger: raiz.current,
          start: "top 80%",
          end: "bottom 60%",
          scrub: Math.min(1, Math.max(0.5, atraso))
        }
      });
    });
    // Nada a devolver: o useGSAP reverte os tweens e o ScrollTrigger sozinho.
  }, { scope: raiz, dependencies: [atraso] });

  return <section ref={raiz}>{children}</section>;
}
// useRolagemSuave.js
// O mecanismo da demonstração desta página em forma de gancho, sem GSAP:
// ouvinte de rolagem mede o alvo, um laço de requestAnimationFrame
// interpola a posição com atraso e tudo é removido na função de limpeza.
import { useEffect, useRef } from "react";

export function useRolagemSuave({ faixa, alvo, atraso = 0.5 }) {
  const quadro = useRef(0);
  const estado = useRef({ alvoX: 0, atualX: 0, ultimo: 0 });

  useEffect(() => {
    const f = faixa.current, el = alvo.current;
    if (!f || !el) return;
    const consulta = matchMedia("(prefers-reduced-motion: reduce)");
    const reduz = () => consulta.matches || document.documentElement.dataset.llxMotion === "reduce";
    let visivel = true;
    const s = estado.current;

    const medir = () => {
      const curso = f.scrollHeight - f.clientHeight;
      const progresso = curso > 0 ? f.scrollTop / curso : 0;
      s.alvoX = progresso * (f.clientWidth - el.offsetWidth);
    };
    const passo = (agora) => {
      quadro.current = 0;
      const dt = s.ultimo ? Math.min(0.1, (agora - s.ultimo) / 1000) : 1 / 60;
      s.ultimo = agora;
      const efetivo = reduz() ? 0 : atraso;
      // Interpolação exponencial: ~95 % do caminho no tempo escolhido (tau = atraso/3).
      s.atualX = efetivo === 0 ? s.alvoX : s.atualX + (s.alvoX - s.atualX) * (1 - Math.exp(-dt / (efetivo / 3)));
      if (Math.abs(s.alvoX - s.atualX) < 0.5) { s.atualX = s.alvoX; s.ultimo = 0; }
      el.style.transform = `translateX(${s.atualX.toFixed(2)}px)`;
      if (s.ultimo && visivel) quadro.current = requestAnimationFrame(passo); // continua só se falta caminho
    };
    const iniciar = () => { if (!quadro.current && visivel) quadro.current = requestAnimationFrame(passo); };
    const aoRolar = () => { medir(); iniciar(); };

    f.addEventListener("scroll", aoRolar, { passive: true });
    const io = new IntersectionObserver(([e]) => { visivel = e.isIntersecting; if (visivel) iniciar(); else { cancelAnimationFrame(quadro.current); quadro.current = 0; } });
    io.observe(f);
    const ro = new ResizeObserver(() => { medir(); iniciar(); });
    ro.observe(f);
    consulta.addEventListener("change", iniciar);
    medir(); s.atualX = s.alvoX; passo(performance.now());

    // Limpeza: espelho exato do que foi criado acima. Sem ela, o StrictMode
    // deixa dois ouvintes e dois laços presos à mesma faixa.
    return () => {
      f.removeEventListener("scroll", aoRolar);
      io.disconnect();
      ro.disconnect();
      consulta.removeEventListener("change", iniciar);
      cancelAnimationFrame(quadro.current);
      quadro.current = 0;
    };
  }, [faixa, alvo, atraso]);
}
/* revelacao.css
 * Versão parada e versão só em CSS da revelação presa à rolagem.
 * 1) Quem pediu menos movimento vê o conteúdo já no lugar, sem deslizar.
 * 2) Onde há suporte a animation-timeline (Chrome e Edge, 2024 em diante),
 *    a revelação roda sem JavaScript e sem laço: o navegador liga a
 *    animação ao progresso do elemento na janela (view()).
 */

/* Estado de partida só vale quando movimento é permitido. */
@media (prefers-reduced-motion: no-preference) {
  .cartao {
    opacity: 0;
    transform: translateY(48px);
    will-change: auto; /* sem camada própria: o cartão se move uma vez */
  }
}

/* Revelação dirigida pela rolagem, sem JavaScript, onde houver suporte. */
@supports (animation-timeline: view()) {
  @media (prefers-reduced-motion: no-preference) {
    .cartao {
      animation: revelar linear both;
      animation-timeline: view();
      animation-range: entry 0% entry 60%; /* do primeiro pixel até 60 % da entrada */
    }
  }
}
@keyframes revelar {
  from { opacity: 0; transform: translateY(48px); }
  to { opacity: 1; transform: none; }
}

/* Versão parada: preferência do sistema ou interruptor do portal. */
@media (prefers-reduced-motion: reduce) {
  .cartao { opacity: 1; transform: none; animation: none; }
}
html[data-llx-motion="reduce"] .cartao { opacity: 1; transform: none; animation: none; }

A função de limpeza do segundo arquivo é um espelho do que o efeito criou: um removeEventListener para cada addEventListener, um disconnect para cada observador, um cancelAnimationFrame para o quadro pendente. Essa simetria é o critério de revisão mais rápido para efeitos com rolagem. Se a lista de coisas criadas e a lista de coisas desfeitas têm tamanhos diferentes, há vazamento.

Critérios de aceite

Levar para o projeto. Em React ou Next.js, prefira o componente com useGSAP quando a página já usa GSAP e o gancho nativo quando o peso do pacote importa; os dois exigem "use client" no App Router. Em Astro ou HTML puro, comece pelo CSS com animation-timeline e acrescente JavaScript só onde falta suporte. Em produção, meça o INP (Interaction to Next Paint, a métrica de resposta a interações dos Core Web Vitals) nas páginas com revelação e compare com páginas sem ela, e registre a memória da aba após vinte navegações no fluxo de vendas: uma curva que só sobe denuncia o ouvinte órfão.

Referências verificadas em 6 de outubro de 2026: Annnimate: Ease Visualizer, Stagger Playground, ScrollTrigger Builder e guias, GSAP: useGSAP e limpeza no React, GSAP: gsap.matchMedia(), React: StrictMode e efeitos montados duas vezes e MDN: animation-timeline e animações dirigidas pela rolagem.

Portal denso: a interface que mostra tudo sem assustar

Um portal com centenas de páginas, dezenas de menus e milhares de links tem um problema que nenhum componente isolado resolve: a pessoa que chega com pouca prática precisa saber onde está, o que pode fazer e quanto falta, antes de ler qualquer parágrafo. O estudo da Nielsen Norman Group, publicado em 2016 com 179 participantes em seis sites, mediu o custo de esconder a navegação atrás de um ícone: no computador, as tarefas levaram ao menos 39% mais tempo, a descoberta de conteúdo caiu mais de 20% e o menu escondido foi usado em 27% dos casos, contra 48% com o menu visível, tudo medido em 2016. A recomendação que saiu dali continua válida em 2026: no computador, mostrar as opções de primeiro nível; no celular, deixar até quatro à vista e esconder o resto.

Os portais públicos que medem o que publicam apontam na mesma direção. Em 31 de janeiro de 2025 o GOV.UK trocou a grade de cartões das 16 páginas de assunto por uma lista de texto e pôs no topo de três a seis links para o conteúdo mais visto; no teste A/B, quem viu a lista achou o conteúdo mais rápido, clicou um pouco mais e buscou menos no computador, e o rótulo "Popular tasks" virou "Most viewed" porque as pessoas queriam saber o critério da sugestão. Em 8 de junho de 2026 a mesma equipe reescreveu mais de 130 páginas de orientação para cerca de 3.000 publicadores, classificou cada seção em manter, fundir ou remover, e validou a taxonomia nova de assuntos e subassuntos com teste de árvore antes de desenhar qualquer menu. O Baymard Institute, no benchmark atualizado em 13 de outubro de 2026 com mais de 17 mil elementos de 180 lojas dos Estados Unidos e da Europa, classificou a navegação de 61% dos sites no computador e 65% no celular entre medíocre e ruim; é evidência de comércio eletrônico, e a transferência para um portal de conteúdo pede teste nas tarefas daquele portal. E a Nielsen Norman Group, em 20 de março de 2026, observou nove pessoas usando chatbots de sites e concluiu que, para achar uma informação simples, o chat costuma custar mais digitação, espera e memória do que links, filtros e busca. A lição que atravessa os quatro estudos: decidir o que merece existir como página vem antes de desenhar o menu, e o caminho visível continua sendo o principal.

O que mudou de 2024 para 2026 foi a plataforma. Quatro recursos que exigiam biblioteca viraram padrão do navegador, com a interoperabilidade garantida pelo programa Interop 2026, anunciado em 12 de fevereiro de 2026 pelos times do Chrome, do Firefox e do Safari: o posicionamento por âncora em CSS (dica que se cola ao botão sem calcular coordenadas) alcançou o Firefox 147 em janeiro de 2026 e ficou disponível nos quatro motores; o atributo popover (camada que abre e fecha por cima da página, com fechamento por Esc e por clique fora) está no Chrome desde a versão 114, no Firefox desde a 125 e no Safari desde a 17; a View Transitions API (transição animada entre dois estados da mesma página) chegou ao Firefox 144; e as animações presas à rolagem em CSS, com animation-timeline, estão no Chrome desde a 115 e no Safari desde a 26, com o Firefox prevista para a versão 161. Para um portal denso isso significa menos JavaScript, menos biblioteca e menos chance de a animação quebrar o leitor de tela.

No lado das bibliotecas, duas mudanças pesam na escolha. Em julho de 2026 o shadcn/ui passou a gerar os componentes sobre o Base UI por padrão, mantendo o Radix para quem inicia com -b radix; o Base UI, feito pelos autores do Radix, do Material UI e do Floating UI, está na versão 1.9.0 de 9 de outubro de 2026 e cobre menu, diálogo, popover, abas e campos com teclado e leitor de tela resolvidos. E o GSAP, desde a versão 3.13 de 30 de abril de 2025, é gratuito com todos os plugins para uso comercial, o que tira o custo de licença da conversa sobre animação; a versão vigente é a 3.15.0.

Dez padrões que mantêm tudo à vista

Cada padrão abaixo aparece no portal de exercício logo adiante. A ordem é a de leitura de quem chega: primeiro saber onde está, depois achar, depois ler, por fim agir.

  1. Mapa da página com posição de leitura. Uma lista fixa das seções marca a que está na tela e uma barra fina mostra quanto falta. Na prática: IntersectionObserver marca a seção visível e aria-current="location" conta ao leitor de tela. O U.S. Web Design System só monta o índice quando a página tem ao menos dois títulos e o indica para páginas com três ou mais seções ou mais de três alturas de tela; página curta dispensa o mapa.
  2. Paleta de comandos. Ctrl e K abrem um campo que filtra seções e ações pelo que a pessoa digita. Quem não sabe em qual menu a ação mora escreve o que quer. A paleta é atalho de quem volta, nunca o único caminho: o GitHub anunciou a aposentadoria da sua em julho de 2025 e recuou em 16 de julho de 2025, porque ela estava no fluxo diário de muita gente, e mesmo assim a busca visível segue no topo. Na prática: <dialog> nativo com lista role="listbox", filtro que ignora acento; em React, o cmdk dentro do Dialog do shadcn/ui.
  3. Resumo antes do detalhe. Toda seção abre com três linhas que se sustentam sozinhas; o detalhe fica num <details> com a contagem de itens no título. O modo síntese esconde o detalhe de todas de uma vez e o deixa a um clique.
  4. Navegação de primeiro nível sempre visível. Abas ou links no topo, no máximo cinco no computador e quatro no celular, com o resto num painel que abre por botão com aria-expanded.
  5. Dica ancorada no lugar da dúvida. O termo técnico ganha um botão que abre a explicação colada a ele, com popover e position-anchor. Fecha com Esc, com clique fora e sem roubar o foco.
  6. Transição que explica a mudança. Trocar de aba com document.startViewTransition() faz a tela deslizar em vez de piscar; com menos movimento pedido ao sistema, a troca é imediata e o conteúdo é o mesmo.
  7. Revelação na rolagem só para o que entra. O bloco surge quando entra na área visível, com animation-timeline: view() dentro de @supports; nos navegadores sem o recurso, o IntersectionObserver acrescenta uma classe. Nada depende da animação para ser lido.
  8. Tabela longa que não despeja tudo. Cabeçalho fixo, filtro, ordenação por coluna com aria-sort, lotes de dez linhas e a frase "mostrando N de M". Acima de alguns milhares de linhas, virtualização com o TanStack Virtual.
  9. Tour guiado de poucos passos. Quatro passos no máximo, cada um apontando um controle real, com foco preso na caixa, Esc para sair e retorno do foco ao botão de origem. Em produção, o driver.js faz isso em 5 KB. O tour nunca abre sozinho na primeira visita: ajuda no ponto da tarefa, com exemplo preenchido e texto curto ao lado do campo, vale mais do que uma apresentação obrigatória.
  10. Estado vazio que diz o próximo passo. Filtro sem resultado, busca sem resposta e tabela sem linhas mostram uma frase com a ação seguinte, nunca um espaço em branco.

Oficina: o portal de exercício

Demonstração local em JavaScript nativo, sem biblioteca. O portal abaixo tem seis seções, uma tabela de 40 linhas e as ações sempre à vista. Experimente Ctrl e K com o foco dentro da oficina, clique no mapa, ligue o modo síntese, troque de aba e inicie o tour. Os medidores no fim dizem qual recurso nativo este navegador tem e o que foi substituído por JavaScript.

Esta oficina precisa de JavaScript ligado. Sem ele, o texto das seis seções e a tabela continuam legíveis abaixo, e os padrões estão explicados na lista acima.

Plano de trabalho

Em 30 segundos: o plano divide o ano em quatro etapas e cada etapa tem uma entrega que o cliente consegue conferir sozinho.

O diagnóstico ocupa as duas primeiras semanas e termina com um relatório de uma página. A implantação configura as automações e fecha com o primeiro envio real. O relacionamento acompanha respostas e devoluções mês a mês. A reconquista procura quem parou de abrir as mensagens.

Ver as quatro entregas (4 itens)
  • Relatório de diagnóstico de uma página.
  • Primeiro envio real com taxa de entrega medida.
  • Painel mensal de respostas e devoluções.
  • Lista de contatos reconquistados com a oferta usada.

Plataformas

Em 30 segundos: a agência usa três plataformas e cada uma responde por uma pergunta diferente do cliente.

A automação de e-mail e WhatsApp responde "quem recebeu e quem respondeu". A análise de tráfego responde "de onde veio quem se cadastrou". A planilha de acompanhamento responde "quanto custou cada contato". Misturar as três na mesma tela é a origem de boa parte das dúvidas no atendimento.

Ver o que cada plataforma guarda (3 itens)
  • Automação: listas, sequências, aberturas e respostas.
  • Tráfego: origem, página de entrada e conversão por canal.
  • Planilha: gasto por canal e custo por contato (CPL).

Temas

Em 30 segundos: quatro temas organizam o estudo, da estratégia da conta à aquisição com passagem para o atendimento.

Estratégia e gestão da conta definem meta e prazo. Marca e confiança sustentam a oferta. Conteúdo e busca geram a demanda. Aquisição e vendas fecham o ciclo com o atendimento. Cada tema tem uma ordem sugerida e uma entrega ao final.

Ver a ordem sugerida (4 itens)
  1. Estratégia e gestão da conta.
  2. Marca e confiança.
  3. Conteúdo e busca.
  4. Aquisição e vendas.

Segmentos

Em 30 segundos: 50 guias por ramo de negócio adaptam diagnóstico, implantação e relacionamento ao cliente da agência.

Os guias se agrupam em seis famílias, de imóveis a educação. A pessoa escolhe o ramo do cliente e recebe a sequência de mensagens, o calendário e os indicadores daquele mercado. O catálogo completo, com filtro e ordenação, está na aba ao lado.

Ver as seis famílias (6 itens)
  • Imóveis, veículos e obras.
  • Saúde e estética.
  • Serviços profissionais.
  • Varejo, moda e beleza.
  • Alimentação e presentes.
  • Educação, infoprodutos e eventos.

Recursos

Em 30 segundos: e-books, episódios, artigos e ferramentas ficam separados em estudar, produzir e consultar.

Quem quer aprofundar uma decisão abre os e-books e os episódios. Quem precisa publicar uma entrega vai aos roteiros e aos guias de execução visual. Quem quer esclarecer um termo abre o glossário. A separação por intenção reduz o menu de 11 itens para três grupos.

Ver os três grupos (3 itens)
  • Estudar: e-books, vídeo e podcast, artigos.
  • Produzir: roteiros, canais, execução visual.
  • Consultar: glossário, meu estudo, laboratórios.

Medição

Em 30 segundos: três números por mês bastam para saber se a conta vai bem, e todos têm a etapa do funil escrita ao lado.

Contatos novos por canal, taxa de resposta das sequências e custo por contato. Cada número aparece com a etapa a que pertence, porque "conversão" sem a etapa é a fonte mais comum de discussão entre agência e cliente. O relatório da aba ao lado mostra o formato.

Ver os três números (3 itens)
  • Contatos novos por canal (etapa: cadastro).
  • Taxa de resposta (etapa: relacionamento).
  • Custo por contato (etapa: aquisição).
    Setas escolhem, Enter executa, Esc fecha.
    Controles ao alcance na primeira tela
    sem JavaScript
    Troca de aba
    sem JavaScript
    Revelação na rolagem
    sem JavaScript
    Dica ancorada
    sem JavaScript

    Portal de exercício carregando.

    Como ler a oficina

    1. Role a área central e veja o mapa à esquerda acompanhar a seção em leitura. Clique em "Medição": o foco vai ao título da seção, e o Tab seguinte cai no primeiro controle dela.
    2. Com o foco dentro da oficina, pressione Ctrl e K, digite "cat" e dê Enter; depois repita com "medicao", sem acento, e veja a seção Medição aparecer. A aba Catálogo abre, e o medidor "Troca de aba" diz se a transição foi nativa ou se o navegador trocou sem animar.
    3. No catálogo, filtre por "clínicas", ordene por "Resposta" duas vezes e peça mais dez linhas. A frase "mostrando N de M" muda a cada ação e o foco pousa na primeira linha nova.
    4. Ligue o modo síntese: cada seção fica só com o resumo e a contagem do detalhe. Abra um detalhe e confira que ele continua a um clique.
    5. Inicie o tour. Use Tab para percorrer os botões da caixa, Esc para sair e confira que o foco volta ao botão "Tour de quatro passos".
    6. Peça menos movimento ao sistema ou ao portal: a troca de aba fica imediata, os blocos deixam de deslizar e o aviso aparece. O conteúdo é o mesmo.

    Critério de aceite: toda seção tem resumo legível sem abrir nada; a paleta acha qualquer seção e ação em até três letras; a tabela nunca mostra mais de dez linhas sem pedido; mapa, abas, tour e paleta funcionam só com o teclado e, ao fechar, devolvem o foco ao ponto de partida ou o levam ao destino escolhido; com menos movimento pedido, nada desliza; e a página mede, em vez de supor, qual recurso nativo o navegador tem.

    Bibliotecas e APIs vigentes em 21 de outubro de 2026

    Versão publicada no npm ou situação nos navegadores, licença e uso indicado para o portal denso.
    RecursoVersão ou suporteLicençaPara que serve no portal denso
    Popover APIChrome 114, Firefox 125, Safari 17plataformaDica, menu e painel por cima da página, com Esc e clique fora sem JavaScript.
    CSS anchor positioningChrome 125, Firefox 147, Safari 26 (Baseline em janeiro de 2026)plataformaColar a dica ao botão; position-try-fallbacks vira a caixa quando falta espaço.
    View Transitions APIChrome 111, Safari 18, Firefox 144 (mesma página); entre páginas no Interop 2026plataformaTroca de aba, filtro e ordenação com movimento que explica o que mudou.
    CSS scroll-driven animationsChrome 115, Safari 26, Firefox 161 (prevista)plataformaRevelar blocos conforme entram, sem laço de animação em JavaScript.
    Base UI1.9.0, 9 de outubro de 2026MITMenu, diálogo, popover, abas e campos sem estilo, com teclado e leitor de tela prontos; padrão do shadcn/ui desde julho de 2026.
    Radix UI1.8.1, 12 de outubro de 2026MITMesma função do Base UI para projetos que já o usam; o shadcn/ui mantém a opção.
    React Aria Components1.22.1, 9 de outubro de 2026Apache 2.0Componentes da Adobe com foco em acessibilidade e internacionalização.
    cmdk1.1.1, 14 de março de 2025MITPaleta de comandos em React; base do componente Command do shadcn/ui.
    driver.js1.10.2, 18 de outubro de 2026MITTour guiado e destaque de elemento, sem dependência, perto de 5 KB.
    Motion14.5.0, 21 de outubro de 2026MITAnimação declarativa em React, com useReducedMotion e animação de layout entre estados.
    GSAP3.15.0, 13 de abril de 2026gratuita, inclusive comercialLinhas do tempo e scrub com ScrollTrigger; useGSAP limpa ao desmontar.
    TanStack Virtual3.14.21, 16 de outubro de 2026MITListas e tabelas com milhares de linhas desenhando só o que está visível.
    React e Next.jsReact 19.3.1 (14 de outubro de 2026) e Next.js 16.4.2 (15 de outubro de 2026)MITBase do portal; o App Router usa a View Transitions API na navegação quando ligada.

    Roteiro por vibecoding: do pedido ao portal que mostra tudo

    Vibecoding é pedir a tela a um agente de código (Claude Code, Codex ou Cursor) e revisar o resultado, em vez de escrever cada componente. O roteiro abaixo foi desenhado para que a pessoa com pouca prática consiga pedir, conferir e corrigir, e para que o agente receba contrato, não adjetivo. Cada passo traz o prompt pronto.

    1. Inventário antes da tela. Liste as seções, as ações e as perguntas mais frequentes do portal numa tabela de três colunas. Prompt: Leia o repositório e liste em uma tabela todas as páginas, os menus e as ações que o usuário pode executar. Marque as cinco ações mais usadas. Não escreva código ainda.
    2. Contrato de leitura. Defina o que toda seção precisa ter: título, resumo de três linhas, detalhe fechado com contagem, próxima ação. Prompt: Crie o componente Secao com props titulo, resumo, itens e proximaAcao. O resumo aparece sempre; os itens ficam em um details com a contagem no summary. Sem biblioteca de animação.
    3. Mapa e posição de leitura. Prompt: Crie MapaDaPagina: lista fixa das seções, marca a seção visível com IntersectionObserver e aria-current="location", barra de progresso da rolagem. Clicar em um item rola até a seção e move o foco ao título. Respeite prefers-reduced-motion.
    4. Paleta de comandos. Prompt: Adicione uma paleta de comandos com cmdk dentro do Dialog do shadcn/ui, aberta por Ctrl+K e por um botão visível; não misture outra biblioteca de acessibilidade no mesmo componente. Itens: todas as seções e as cinco ações do inventário. O filtro ignora acentos ("medicao" acha "Medição"). Setas, Enter e Esc funcionam; ao fechar sem escolher, o foco volta ao botão; ao escolher, o foco vai ao destino.
    5. Dica ancorada. Prompt: Transforme cada termo técnico da lista em um botão com popover nativo e anchor positioning em CSS (position-anchor, position-area, position-try-fallbacks). Sem suporte a âncora, posicione por JavaScript. Nunca use title como única explicação.
    6. Transição e revelação. Prompt: Troque de aba dentro de document.startViewTransition quando existir e quando o usuário não pedir menos movimento. Revele os blocos na rolagem com animation-timeline: view() dentro de @supports e IntersectionObserver como alternativa. A versão sem animação precisa mostrar o mesmo conteúdo.
    7. Tabela longa. Prompt: Crie TabelaLonga com cabeçalho fixo, filtro por texto, ordenação por coluna com aria-sort, lotes de dez linhas, frase "mostrando N de M" em role="status" e foco na primeira linha nova. Acima de 2.000 linhas, use @tanstack/react-virtual e mantenha aria-rowcount na tabela e aria-rowindex em cada linha desenhada.
    8. Tour de quatro passos. Prompt: Adicione um tour com driver.js de até quatro passos apontando o botão da paleta, o mapa, o modo síntese e a aba do catálogo, em um componente "use client" carregado por import dinâmico. Esc encerra, o foco volta ao botão de início e o tour não abre sozinho na primeira visita.
    9. Revisão medida. Rode npx impeccable detect --json na página publicada em 1.280 e 390 pixels, o axe no navegador e um teste de teclado do início ao fim. Prompt: Leia o JSON do detector e corrija só os achados de contraste, tamanho de texto e foco. Liste o que é escolha de estilo e não mude.
    10. Prova de aceite. Peça ao agente o teste que repete o critério de aceite desta oficina em Playwright, com @axe-core/playwright para a acessibilidade e page.emulateMedia({ reducedMotion: "reduce" }) para a versão sem movimento: resumo visível sem clique, paleta em três letras com e sem acento, tabela em dez linhas, teclado do começo ao fim e o mesmo conteúdo com menos movimento. Para desempenho, peça o INP (tempo de resposta à interação) medido com a biblioteca web-vitals e rotulado como laboratório; o percentil 75 de campo só existe depois de publicar, no relatório de usuários reais.

    Dois cuidados valem para qualquer agente. Peça um passo por vez e confira no navegador antes do próximo, porque o agente que recebe os dez passos de uma vez tende a entregar os três primeiros bem e improvisar o resto. E escreva os prompts com o nome do componente, o atributo ARIA e o comportamento no teclado, porque "deixe intuitivo" não é contrato e o agente preenche o vazio com o que viu mais vezes na internet.

    Abrir o exemplo React: PortalDenso.jsx

    Instale cmdk, motion e driver.js e salve como PortalDenso.jsx. O componente reúne a paleta, o mapa com posição de leitura e a troca de aba com a View Transitions API; o tour e a tabela seguem o mesmo contrato da oficina.

    "use client";
    import { useEffect, useRef, useState, startTransition } from "react";
    import { Command } from "cmdk";
    import { useReducedMotion } from "motion/react";
    import { driver } from "driver.js";
    import "driver.js/dist/driver.css";
    
    const SECOES = [
      { id: "plano", titulo: "Plano de trabalho" },
      { id: "plataformas", titulo: "Plataformas" },
      { id: "temas", titulo: "Temas" },
      { id: "medicao", titulo: "Medição" }
    ];
    
    function trocarComTransicao(atualizar, menosMovimento) {
      if (!menosMovimento && typeof document.startViewTransition === "function") {
        document.startViewTransition(() => startTransition(atualizar));
      } else {
        atualizar();
      }
    }
    
    export default function PortalDenso({ children }) {
      const menosMovimento = useReducedMotion();
      const [aba, setAba] = useState("visao");
      const [paletaAberta, setPaletaAberta] = useState(false);
      const [secaoAtual, setSecaoAtual] = useState(SECOES[0].id);
      const palco = useRef(null);
      const botaoPaleta = useRef(null);
    
      useEffect(() => {
        const vigia = new IntersectionObserver((entradas) => {
          const visivel = entradas.filter((e) => e.isIntersecting).sort((a, b) => b.intersectionRatio - a.intersectionRatio)[0];
          if (visivel) setSecaoAtual(visivel.target.id);
        }, { root: palco.current, threshold: [0.25, 0.5, 0.75] });
        palco.current?.querySelectorAll("[data-secao]").forEach((s) => vigia.observe(s));
        return () => vigia.disconnect();
      }, []);
    
      useEffect(() => {
        const atalho = (e) => {
          if ((e.ctrlKey || e.metaKey) && e.key.toLowerCase() === "k") { e.preventDefault(); setPaletaAberta(true); }
        };
        document.addEventListener("keydown", atalho);
        return () => document.removeEventListener("keydown", atalho);
      }, []);
    
      function irPara(id) {
        setPaletaAberta(false);
        const alvo = document.getElementById(id);
        alvo?.scrollIntoView({ behavior: menosMovimento ? "auto" : "smooth", block: "start" });
        alvo?.querySelector("h2, h3")?.focus();
      }
    
      function iniciarTour() {
        driver({
          showProgress: true,
          steps: [
            { element: "#botao-paleta", popover: { title: "1 de 4: uma busca para tudo", description: "Ctrl e K abrem a paleta." } },
            { element: "#mapa", popover: { title: "2 de 4: onde você está", description: "A seção em leitura fica marcada." } },
            { element: "#abas", popover: { title: "3 de 4: catálogo", description: "A tabela abre em lotes de dez." } },
            { element: "#secao-medicao", popover: { title: "4 de 4: números com etapa", description: "Cada número diz a etapa do funil." } }
          ],
          onDestroyed: () => botaoPaleta.current?.focus()
        }).drive();
      }
    
      return (
        <div className="portal">
          <div role="toolbar" aria-label="Ações do portal">
            <button id="botao-paleta" ref={botaoPaleta} type="button" onClick={() => setPaletaAberta(true)}>Buscar seção ou ação (Ctrl K)</button>
            <button type="button" onClick={iniciarTour}>Tour de quatro passos</button>
          </div>
          <nav id="mapa" aria-label="Mapa da página">
            <ol>{SECOES.map((s) => (
              <li key={s.id}><a href={`#${s.id}`} aria-current={s.id === secaoAtual ? "location" : undefined} onClick={(e) => { e.preventDefault(); irPara(s.id); }}>{s.titulo}</a></li>
            ))}</ol>
          </nav>
          <div id="abas" role="tablist">
            {["visao", "catalogo"].map((id) => (
              <button key={id} role="tab" aria-selected={aba === id} onClick={() => trocarComTransicao(() => setAba(id), menosMovimento)}>{id === "visao" ? "Visão geral" : "Catálogo"}</button>
            ))}
          </div>
          <div ref={palco} className="palco">{children(aba)}</div>
          <Command.Dialog open={paletaAberta} onOpenChange={(aberta) => { setPaletaAberta(aberta); if (!aberta) botaoPaleta.current?.focus(); }} label="Paleta de comandos">
            <Command.Input placeholder="Digite uma seção ou uma ação" />
            <Command.List>
              <Command.Empty>Nada encontrado. Tente outra palavra.</Command.Empty>
              <Command.Group heading="Seções">
                {SECOES.map((s) => <Command.Item key={s.id} onSelect={() => irPara(s.id)}>Ir para: {s.titulo}</Command.Item>)}
              </Command.Group>
              <Command.Group heading="Ações">
                <Command.Item onSelect={() => { setPaletaAberta(false); trocarComTransicao(() => setAba("catalogo"), menosMovimento); }}>Abrir o catálogo</Command.Item>
                <Command.Item onSelect={() => { setPaletaAberta(false); iniciarTour(); }}>Iniciar o tour</Command.Item>
              </Command.Group>
            </Command.List>
          </Command.Dialog>
        </div>
      );
    }

    Referências lidas em 21 de outubro de 2026: Nielsen Norman Group: Hamburger Menus and Hidden Navigation Hurt UX Metrics (26 de junho de 2016), GOV.UK: páginas de assunto em lista e links mais vistos (31 de janeiro de 2025), GOV.UK: nova orientação de conteúdo e publicação, mais de 130 páginas reestruturadas (8 de junho de 2026), Baymard Institute: benchmark de navegação de 180 lojas (atualizado em 13 de outubro de 2026), Nielsen Norman Group: chatbots de sites contra busca e navegação (20 de março de 2026), GitHub: pausa na aposentadoria da paleta de comandos (16 de julho de 2025), U.S. Web Design System: in-page navigation, web.dev: Interop 2026 (12 de fevereiro de 2026), web.dev: novidades da plataforma em janeiro de 2026, anchor positioning em Baseline, Can I use: animation-timeline, Can I use: Popover API, Chrome for Developers: View Transition API, shadcn/ui: Base UI como padrão (julho de 2026), Base UI, GSAP 3.13: gratuito com todos os plugins (30 de abril de 2025), Motion para React, driver.js, cmdk, TanStack Virtual e React Aria Components. As versões da tabela foram lidas no registro do npm na mesma data. A pesquisa de partida foi feita pelo geo-orchestrator em 21 de outubro de 2026, com 13 tarefas em cinco provedores (Grok 4.7 e Perplexity na busca, GPT-5.5 e Gemini na redação, Claude Sonnet e Claude Fable na revisão), e cada fato citado aqui foi relido na página de origem antes de entrar no texto.

    Como revisar o que o agente devolve: a checklist de 2026

    Infográfico ilustrado em estilo de mapa antigo resumindo o guia: padrões de componente com sinais de reprovação, o mapa dos cinco lugares do estado (local, derivado, compartilhado, servidor e URL), a tabela de ferramenta por tipo de estado, o piso de versão React 19.2 e Next.js 16.2.11 e a regra do useEffect só para sistemas externos
    Resumo visual do guia, gerado por IA no NotebookLM. A grafia de alguns rótulos escorrega, um vício conhecido da geração de imagem; os números estão certos e o texto do guia prevalece.

    O que este guia deixa de fora, e por quê

    O guia cobre a revisão e a encomenda; ficam fora, por serem pré-requisito ou especialidade: a sintaxe do JSX em si; o mecanismo interno de reconciliação e o funcionamento do compilador por dentro; o bootstrap de um projeto novo; hooks customizados; a tipagem avançada de TypeScript com React; e a mecânica completa de Server Actions além das recomendações de segurança citadas. Quando o trabalho esbarrar num desses temas, a fonte é a documentação oficial de cada projeto: react.dev, nextjs.org e as docs de cada biblioteca da tabela de versões.

    Guias para postar

    Dois guias prontos para o LinkedIn e o Instagram

    Cada cartão abaixo foi desenhado para sair como imagem: escolha o formato, abra a tela de print, capture a área do cartão e publique com a legenda que o botão copia. O conteúdo resume o método desta página, então o post leva o leitor de volta para cá.

    Design · React e estadoLeadlovers 2026

    Os cinco lugares onde um dado pode morar

    Antes de criar qualquer estado, decida de quem é a verdade daquele dado.
    1. Local fica no próprio componente. Aba aberta e campo em foco vivem ali, e só ali.
    2. Derivado ninguém guarda. Total e lista filtrada saem do cálculo na hora de desenhar a tela.
    3. Compartilhado de cliente atravessa telas. Tema, sessão e carrinho pedem uma loja própria.
    4. Dado de servidor mora no cache. Copiar para dentro da tela cria dois números diferentes.
    5. Filtro e busca moram no endereço. O link reproduz a tela exata que o cliente reclamou.
    brasilgeo.ai/leadlovers2026Guia 1 de 2
    Legenda sugerida para LinkedIn e Instagram
    Duas telas mostrando saldos diferentes quase sempre têm a mesma origem: o mesmo dado guardado em dois lugares.
    
    O guia de React do portal resolve isso com uma pergunta de trinta segundos, feita antes de criar qualquer estado: onde mora a verdade deste dado. São cinco respostas possíveis. O que pertence a um componente só fica local. O que dá para calcular ninguém guarda. O que atravessa telas vai para uma loja de cliente. O que vem do servidor fica no cache, com dono. E filtro, aba e busca moram no endereço da tela.
    
    Errar a classificação sai caro: a correção deixa de ser ajuste de tela e vira reescrita da camada de dados.
    
    Comente qual dos cinco lugares mais confunde o seu time.
    
    Guia completo: brasilgeo.ai/leadlovers2026/design/react/
    
    #Leadlovers #React #Frontend #DesignDeProduto
    Design · React e estadoLeadlovers 2026

    Sinais de que a entrega usa o React de 2024

    Confira antes de aceitar a tela que um agente de IA devolveu.
    • Versão inventada denuncia na hora. React 20 e TanStack Query v6 existem em lugar nenhum; o React 19.3 é real, de 9 de setembro de 2026.
    • Arquivo middleware.ts com o nome antigo mostra que o código ignorou o Next.js 16.
    • Memoização escrita à mão em tudo pede explicação. Pergunte se o projeto ativou o React Compiler.
    • Todo useEffect nomeia o sistema externo que o justifica. Sem esse nome, ele volta para quem escreveu.
    • Peça o teste que acha o botão pelo papel. Ele prova o comportamento e denuncia tela inacessível.
    brasilgeo.ai/leadlovers2026Guia 2 de 2
    Legenda sugerida para LinkedIn e Instagram
    O agente escreve muito bem o React de dois anos atrás: acerta a estrutura, erra a atualidade, e nada no processo avisa.
    
    O guia de React do portal transforma esse risco em uma revisão curta. Comece pela data da entrega. O React 19.3 foi lançado em 9 de setembro de 2026 e está confirmado na página oficial de versões. O quadro de agosto abaixo é histórico; confira a versão e os avisos de segurança do projeto antes de cobrar uma atualização. Depois olhe o resto: arquivo middleware.ts com o nome antigo, memoização escrita à mão em todo componente novo, useEffect sem sistema externo nomeado e teste que procura o botão pelo texto em vez do papel.
    
    Cinco conferências resolvem boa parte do retrabalho que chegaria semanas depois.
    
    Comente qual desses sinais mais aparece nas entregas que você recebe.
    
    Guia completo: brasilgeo.ai/leadlovers2026/design/react/
    
    #Leadlovers #React #NextJS #RevisaoDeCodigo

    Perguntas frequentes

    Quais são os padrões de componentes React mais usados?

    Cinco padrões resolvem a maioria das telas: componente com props, composição por children, estado local com useState, lista com map e key, e campo controlado. Cada um tem um sinal de reprovação: lista de props que cresce a cada tela, invólucro que conhece o que carrega, DOM alterado na mão, key de índice ou aleatória e erro mostrado só em cor. Na revisão, identifique o padrão primeiro e depois procure o sinal.

    Como fazer o gerenciamento de estado em React?

    Decida onde mora a verdade de cada dado antes de escrever código. Estado de um componente só fica em useState; valor calculável se calcula na renderização; estado compartilhado de cliente vai para Context ou, em alta frequência, Zustand ou Jotai; dado do servidor fica no cache do TanStack Query; filtro e aba moram na URL. A documentação do React acrescenta cinco princípios: agrupar o que muda junto e evitar contradição, redundância, duplicação e aninhamento profundo.

    O que mudou no React 19.3?

    Lançado em 9 de setembro de 2026, segundo o blog oficial do React, o 19.3 tornou estável o componente ViewTransition, que anima elementos ao entrar, sair ou mudar de lugar com a View Transition API do navegador. Trouxe também Fragment Refs, a função browser() para tirar da renderização no servidor o componente que depende de recurso do navegador, suporte a Trusted Types e Context renderizado direto em Server Components. Rode os testes do projeto antes de atualizar.

    O que o React Compiler muda na revisão de código?

    O React Compiler 1.0, estável desde 7 de outubro de 2025, memoiza sozinho o que antes se escrevia à mão. Para código novo, a recomendação oficial é confiar no compilador e reservar useMemo e useCallback para quando for preciso controle preciso. Componente novo coberto de useMemo em tudo que é linha é sinal de agente escrevendo o React de dois anos atrás: pergunte se o projeto já ativou o compilador.

    Quando um useEffect se justifica?

    Quando existe um sistema externo para sincronizar: um widget de fora do React, a rede ou o DOM do navegador. A página You Might Not Need an Effect, da documentação oficial, entrega a régua: sem sistema externo envolvido, dispense o Effect. Derivar estado de outro estado acontece durante o próprio render, e lógica de interação pertence ao event handler correspondente.

    Onde deve morar o dado que vem do servidor?

    No cache de uma biblioteca como o TanStack Query, com useQuery para leitura, useMutation para escrita e invalidação por chave. Copiar o dado do servidor para um useState ou um Zustand cria duas cópias do mesmo número, e uma tela passa a mostrar um saldo diferente da outra. O estado local guarda só o que é da tela, como filtro aberto e aba selecionada.

    Quando trocar o Context por Zustand ou Jotai?

    Depois de esgotar as três saídas do curso: quebrar um Context grande em vários pequenos por frequência de mudança, estabilizar o value com useMemo e, se a alta frequência persistir, migrar para store com seletores. Com Context, todo consumidor re-renderiza quando o value do Provider muda; com Zustand, cada componente assina só a fatia que usa; com Jotai, átomos re-renderizam apenas as partes pequenas que precisavam da atualização.

    Qual versão mínima do Next.js cobrar em qualquer entrega?

    A 16.2.11, ou a 15.5.21 na linha antiga: são as versões com as correções do July 2026 Security Release, que fechou nove CVEs, entre eles negação de serviço e SSRF em Server Actions. No Next.js 16 o middleware.ts foi renomeado para proxy.ts; entrega com middleware.ts novo, params síncrono ou experimental.ppr é código do Next de 2024.

    Por que a key de uma lista deve vir do identificador do dado?

    A documentação oficial do React avisa que índice como key frequentemente leva a bugs sutis e confusos, e que key gerada na hora, como Math.random(), recria todo o DOM a cada render e perde o que o usuário digitou. A key vem do identificador do próprio dado, e a revisão reprova lista com key de índice ou aleatória, ou com o caso de lista vazia sem tratamento.

    Por onde começar

    Assista à aula e abra o último componente React que o time recebeu de um agente com três perguntas deste guia: qual dos cinco padrões ele é, e qual o sinal de reprovação daquele padrão; onde mora a verdade de cada estado, com a tabela de ferramentas ao lado; e que versão de React e de Next.js a entrega assume; o piso de segurança é 16.2.11. O que falhar vira o backlog da semana. O menu Design continua nos guias de ícones e imagens, navegação, diagramas e Tailwind, e o vocabulário das aulas mora no glossário.

    Instruções deste guia para agentes de IA (Markdown e JSON)

    Regras, decisões, números, erros comuns, código e checklist destilados da página para Claude, Codex e outros agentes. Arquivos: agentes.md · agentes.json · índice dos guias

    # React: instruções para agentes de IA
    
    - Página: Padrões de componentes React e gerenciamento de estado (https://brasilgeo.ai/leadlovers2026/design/react/)
    - Revisado em: 2026-11-16
    - JSON com o mesmo conteúdo: https://brasilgeo.ai/leadlovers2026/design/react/agentes.json
    - Índice dos guias de Design para agentes: https://brasilgeo.ai/leadlovers2026/design/llms.txt
    - Esquema: design-guia-para-agentes/v1
    
    Decide como escrever e revisar React em 2026: cinco padrões de componente com sinal de reprovação, o lugar de cada tipo de estado (local, derivado, cliente, servidor, URL), o critério oficial para dispensar useEffect, formulários sem re-render por tecla e a versão mínima de Next.js por segurança. Resultado: componente atual, sem estado duplicado e sem memoização ou efeito desnecessários.
    
    ## Quando consultar
    
    - Escrever ou revisar componente, tela, formulário ou lista em React ou Next.js.
    - Decidir onde guardar um dado: useState, Context, Zustand, Jotai, TanStack Query ou URL.
    - Adicionar useEffect, useMemo ou useCallback.
    - Buscar dado de servidor, enviar formulário ou mostrar resposta em streaming.
    - Montar filtro, aba ou busca que o usuário compartilha por link.
    - Criar tabela longa, lista reordenável ou animação ligada à rolagem.
    - Conferir versões e segurança de uma entrega de outro agente.
    
    ## Regras
    
    - **REA-01** (obrigatória). Antes de criar estado, classifique o dado (local, derivado, cliente compartilhado, servidor ou URL) e use a ferramenta daquele lugar. Por quê: Errar a classe vira reescrita da camada de dados. Sintoma: duas telas com saldos diferentes.
    - **REA-02** (obrigatória). Calcule dado derivado (total, lista filtrada) no render. Nunca o guarde em useState. Por quê: Duas fontes de verdade divergem na primeira alteração.
    - **REA-03** (obrigatória). Todo useEffect nomeia o sistema externo que sincroniza (widget fora do React, rede, DOM do navegador). Sem sistema externo, remova o Effect. Por quê: Critério oficial de 'You Might Not Need an Effect'.
    - **REA-04** (obrigatória). Lógica causada por interação vai no event handler. Só a causada por o componente aparecer na tela vai no Effect. Por quê: No Effect já se perdeu qual interação ocorreu.
    - **REA-05** (obrigatória). Todo Effect que cria listener, observer, timer, frame ou AbortController devolve limpeza que desfaz cada item criado. Por quê: O StrictMode monta, desmonta e remonta. Sem limpeza a animação roda em dobro e a memória sobe.
    - **REA-06** (obrigatória). Dado de servidor fica no cache do TanStack Query (cliente) ou do framework (servidor), com invalidação explícita. Nunca copie para useState ou Zustand. Por quê: A cópia cria dois números do mesmo dado.
    - **REA-07** (obrigatória). Dê a cada consulta uma queryKey própria, com os parâmetros dentro. Por quê: Mesma queryKey em consultas diferentes mostra o dado de uma tela na outra.
    - **REA-08** (obrigatória). Em lista, key vem do id do dado. Nunca índice nem Math.random(). Trate a lista vazia. Por quê: Índice 'leva a bugs sutis'. Key aleatória recria o DOM e perde o que o usuário digitou.
    - **REA-09** (obrigatória). Revise cada componente pelo padrão e reprove pelo sinal: props com mais de meia dúzia e crescendo; children com invólucro que recebe props do que carrega; DOM alterado à mão em vez de useState; key de índice ou aleatória, ou lista vazia sem tratamento; erro só em cor ou só após o envio. Por quê: Os cinco padrões (props, children, useState, lista com key, campo controlado) cobrem a maioria das telas.
    - **REA-10** (obrigatória). Campo controlado mostra o erro em texto, na borda e com aria-invalid, sem esperar o envio. Por quê: Erro só em cor reprova o padrão.
    - **REA-11** (recomendada). Em código novo, deixe a memoização ao React Compiler 1.0 e reserve useMemo e useCallback para controle preciso. Pergunte se o projeto ativou o compilador antes de aceitar memoização manual em tudo. Por quê: Recomendação oficial. Em código existente, mantenha ou teste antes de remover.
    - **REA-12** (obrigatória). Filtro, aba, ordenação, página e busca moram na URL com nuqs. Envolva a raiz no NuqsAdapter do framework. Por quê: O link reproduz a tela. Sem o adapter o valor nunca chega ao endereço.
    - **REA-13** (recomendada). Cliente compartilhado de alta frequência vai para Zustand (seletores) ou Jotai (granular). Context só para valor estável. Seletor Zustand que monta objeto exige useShallow. Por quê: Context re-renderiza todo consumidor. Seletor com referência nova gera 'Maximum update depth exceeded'.
    - **REA-14** (recomendada). Formulário com 3 campos ou mais, ou lento no celular, usa react-hook-form com mode "onTouched". Campo único usa useState. Por quê: register usa ref (não controlado). O modo onChange valida a cada tecla, com 'impacto significativo de performance'.
    - **REA-15** (obrigatória). Chame useFormStatus em componente filho dentro do <form>, nunca no que renderiza o form. Use useOptimistic só para curtir, marcar e arrastar, nunca para pagamento. Por quê: useFormStatus reporta o form pai. useOptimistic reverte sozinho na falha.
    - **REA-16** (obrigatória). Escreva "use client" só nos arquivos de fronteira, no topo. Props que cruzam a fronteira são serializáveis. Por quê: A diretiva em todo arquivo manda o componente inteiro ao navegador.
    - **REA-17** (obrigatória). Exija Next.js 16.2.11 ou mais novo (15.5.21 na linha 15). Server Function autentica e autoriza antes de operação sensível, lê credencial de cookie ou header e devolve só o que a tela usa. Por quê: O July 2026 Security Release corrigiu 9 CVEs, incluindo DoS e SSRF em Server Actions.
    - **REA-18** (obrigatória). No Next.js 16, use proxy.ts (não middleware.ts novo), await em params, cookies() e headers(), e Cache Components com "use cache". Evite experimental.ppr. Por quê: A forma antiga é Next de 2024.
    - **REA-19** (obrigatória). Lista longa sobe a escada um degrau por vez, com medição: tabela nativa, virtualização, fatias pelo servidor, imagem. Com TanStack Table v9, declare só as features usadas em tableFeatures() e recuse useLegacyTable. Por quê: useLegacyTable inclui tudo e pesa mais que a v8. Virtualização quebra Ctrl+F e teclado.
    - **REA-20** (recomendada). Teste com getByRole e simule a rede com MSW para afirmar carregando, falhou e chegou. Por quê: Se o papel não acha o elemento, a tela pode ser inacessível.
    - **REA-21** (obrigatória). Operação cancelável: um AbortController por pedido, guardado como pedido ativo. Compare com o ativo antes de cada setState e passe o signal ao fetch. Por quê: O controller interrompe a espera. A comparação protege a tela se a fonte ignorar o abort.
    - **REA-22** (obrigatória). Animação ligada à rolagem usa só transform e opacity, atraso de 0,5 a 1 s para conteúdo e versão parada sob prefers-reduced-motion. will-change só no que se move sempre. Por quê: Acima de 2 s parece desligada do gesto. 100 elementos com will-change derrubam um celular.
    - **REA-23** (obrigatória). Widget complexo (combobox, seletor de data, tabela navegável) vem de biblioteca de acessibilidade (React Aria Components, Base UI, Radix), nunca de div com onClick. Por quê: Elas trazem papel ARIA, foco e teclado prontos.
    - **REA-24** (obrigatória). Cite só versões que existem: React 19.x, Next 16.x, TanStack Query v5. Por quê: React 20 e TanStack Query v6 não existem.
    
    ## Decisões rápidas
    
    | Situação | Escolha | Evite |
    | --- | --- | --- |
    | Dado de um componente só (aba aberta, campo aberto) | useState ou useReducer | Biblioteca global |
    | Dado calculável de outros (total, lista filtrada) | Calcular no render | Guardar em useState |
    | Cliente compartilhado, baixa frequência (tema, sessão, modal) | Context com useReducer | Store pesado |
    | Cliente compartilhado, alta frequência (carrinho) | Zustand com seletores e useShallow | Context, que re-renderiza em cascata |
    | Formulário ou editor complexo com grão fino | Jotai, por átomos | Store monolítico |
    | Filtro, aba, ordenação, página ou busca | URL com nuqs | useState que some ao recarregar |
    | Dado do backend (produtos, perfil) | TanStack Query no cliente ou cache do framework no servidor | Cópia em useState ou Zustand |
    | Fonte externa (tamanho da janela, store próprio) | useSyncExternalStore | useEffect improvisado |
    | Atualização que disputa com a digitação | useTransition (pendência) ou useDeferredValue (versão derivada adiada) |  |
    | Context grande com cascata | 1) dividir por frequência, 2) estabilizar value com useMemo, 3) store com seletores |  |
    | Dado que muda várias vezes por segundo | Fora do ciclo de render (motor próprio) ou sinais reativos, verificando a convivência com o Compiler | setState a cada mensagem |
    
    ## Números de referência
    
    | Valor | Para quê | Fonte |
    | --- | --- | --- |
    | React 19.3, 9/9/2026 (19.3.1 em 14/10/2026) | Versão estável a assumir. Traz ViewTransition estável, Fragment Refs e Context em Server Components | blog do React |
    | React Compiler 1.0, 7/10/2025 | Memoização automática em build | blog do React |
    | Next.js 16 (21/10/2025); 16.4.2 em 15/10/2026 | Turbopack padrão, proxy.ts, Cache Components | blog do Next.js |
    | Next.js 16.2.11 ou 15.5.21 | Piso de segurança (9 CVEs, release de 20/7/2026) | July 2026 Security Release |
    | TanStack Query 5.101.4; react-hook-form 7.85.0; nuqs 2.9.6; Zustand 5.0.15; Jotai 2.20.2 | Versões estáveis de 18/8/2026. Reconfira antes de citar | registro npm |
    | TanStack Table 9.1.2 (v9 estável em 4/8/2026); TanStack Virtual 3.14.21 | Tabela com features declaradas e virtualização | registro npm |
    | TanStack Query 68% de uso e 97% de retenção; Zustand 50% e 94%; Jotai 18% e 92% | Adoção das opções de estado | State of React 2025 |
    | 0,5 a 1 s (conteúdo); 1,5 a 2 s (fundo) | Atraso de scrub na rolagem | guias Annnimate |
    | Acima de 2.000 linhas | Passa a virtualizar com @tanstack/react-virtual (aria-rowcount e aria-rowindex) | prompt de tabela longa |
    
    ## Erros comuns e a correção
    
    - Erro: useEffect que lê estado, calcula e grava outro estado. Corrija: Calcule no topo do componente, durante o render.
    - Erro: Dado de servidor copiado para useState ou Zustand. Corrija: Mantenha no cache do TanStack Query.
    - Erro: useMemo e useCallback em todo componente novo. Corrija: Confie no React Compiler.
    - Erro: bg-${cor}-500 ou 'text-' + tom (o Tailwind só gera classes que vê inteiras) Corrija: Mapa estático de variantes com as strings completas.
    - Erro: useFormStatus no componente que renderiza o form. Corrija: Mova para um botão filho dentro do <form>.
    - Erro: middleware.ts novo, params síncrono, experimental.ppr. Corrija: proxy.ts, await params, Cache Components.
    - Erro: Estado de streaming gravado a cada token. Corrija: Parcial em contêiner aria-live="polite" e estado final em um commit único.
    - Erro: use() dentro de try-catch. Corrija: Suspense trata a pendente e o Error Boundary a rejeitada. Para Error Boundary use react-error-boundary.
    
    ## Padrões de código
    
    ### Estado na URL com nuqs
    
    Filtro, busca e página que o link deve reproduzir.
    
    ```tsx
    "use client";
    import { useQueryState, parseAsInteger } from "nuqs";
    
    // Exige <NuqsAdapter> na raiz do app.
    export function Filtros() {
      const [busca, setBusca] = useQueryState("busca", { defaultValue: "" });
      const [pagina, setPagina] = useQueryState("pagina", parseAsInteger.withDefault(1));
      return (
        <>
          <input value={busca} onChange={(e) => { setBusca(e.target.value); setPagina(1); }} />
          <button onClick={() => setPagina((p) => p + 1)}>Página {pagina}</button>
        </>
      );
    }
    ```
    
    ### Operação cancelável
    
    Streaming ou requisição que o usuário cancela e repete.
    
    ```tsx
    import { useEffect, useRef, useState } from "react";
    
    type Tarefa = { controlador: AbortController };
    
    export function useOperacao(fonte: (signal: AbortSignal) => AsyncIterable<string>) {
      const [texto, setTexto] = useState("");
      const ativo = useRef<Tarefa | null>(null);
      // Sair da tela aborta o pedido pendente.
      useEffect(() => () => { ativo.current?.controlador.abort(); ativo.current = null; }, []);
    
      async function executar() {
        ativo.current?.controlador.abort();
        const tarefa = { controlador: new AbortController() };
        ativo.current = tarefa; // a identidade do objeto faz o papel do serial
        setTexto("");
        try {
          for await (const t of fonte(tarefa.controlador.signal)) {
            if (ativo.current !== tarefa) return; // pedido antigo: descarta
            setTexto((x) => x + t);
          }
        } catch { /* cancelado ou falhou: o texto parcial fica */ }
        finally { if (ativo.current === tarefa) ativo.current = null; }
      }
      return { texto, executar, cancelar: () => ativo.current?.controlador.abort() };
    }
    ```
    
    ## Checklist antes de entregar
    
    - [ ] A entrega assume React 19.2 ou 19.3 e Next.js 16.2.11 ou mais novo, sem React 20 nem TanStack Query v6.
    - [ ] Cada componente cabe num dos cinco padrões e não tem o sinal de reprovação dele.
    - [ ] Cada estado tem lugar declarado: local, derivado, cliente, servidor ou URL.
    - [ ] Nenhum dado derivado está em useState e nenhum dado de servidor está duplicado em store local.
    - [ ] Todo useEffect nomeia o sistema externo e devolve limpeza do que criou.
    - [ ] Sem useMemo e useCallback em massa: o Compiler está ativo ou há motivo escrito.
    - [ ] Listas usam key de id e tratam o caso vazio.
    - [ ] Filtro, aba e busca estão na URL, com NuqsAdapter na raiz.
    - [ ] "use client" só nas fronteiras, Server Functions autenticam, e existe proxy.ts em vez de middleware.ts novo.
    - [ ] Formulário de 3 campos ou mais usa mode onTouched, com erros em texto e aria-invalid.
    - [ ] Testes localizam por getByRole e a rede é simulada com MSW.
    - [ ] Animação respeita prefers-reduced-motion e o conteúdo aparece sem JavaScript.
    
    ## Ferramentas citadas
    
    - **React Compiler 1.0**: Memoização automática em build.
    - **TanStack Query 5**: Cache de dado de servidor.
    - **nuqs 2**: Estado na URL.
    - **react-hook-form 7**: Formulário não controlado.
    - **React Aria Components, Base UI, Radix**: Widgets acessíveis prontos.
    - **Zustand 5 e Jotai 2**: Estado de cliente de alta frequência.
    
    ## Onde aprofundar na página
    
    - [Cinco padrões e sinal de reprovação](https://brasilgeo.ai/leadlovers2026/design/react/#padroes)
    - [React Compiler](https://brasilgeo.ai/leadlovers2026/design/react/#compilador)
    - [Onde mora cada estado](https://brasilgeo.ai/leadlovers2026/design/react/#estado)
    - [Quando o useEffect sobra](https://brasilgeo.ai/leadlovers2026/design/react/#effect)
    - [Dado de servidor e hooks de formulário do React 19](https://brasilgeo.ai/leadlovers2026/design/react/#servidor)
    - [Estado na URL](https://brasilgeo.ai/leadlovers2026/design/react/#url)
    - [Next.js 16 e segurança](https://brasilgeo.ai/leadlovers2026/design/react/#next)
    - [Tela de dados e TanStack Table v9](https://brasilgeo.ai/leadlovers2026/design/react/#tabelas)
    - [Testes e MSW](https://brasilgeo.ai/leadlovers2026/design/react/#testes-msw)
    
    ## Guias relacionados
    
    - [TypeScript](https://brasilgeo.ai/leadlovers2026/design/typescript/): Tipagem de props, hooks e formulários em TSX. Instruções: https://brasilgeo.ai/leadlovers2026/design/typescript/agentes.md
    - [Tailwind e tokens](https://brasilgeo.ai/leadlovers2026/design/tailwind/): Classes montadas, mapa de variantes e tokens. Instruções: https://brasilgeo.ai/leadlovers2026/design/tailwind/agentes.md
    - [Navegação](https://brasilgeo.ai/leadlovers2026/design/navegacao/): Abas, paginação e paleta de comandos. Instruções: https://brasilgeo.ai/leadlovers2026/design/navegacao/agentes.md
    - [Dashboards](https://brasilgeo.ai/leadlovers2026/design/dashboards/): Telas de dados com números, tabelas e estados. Instruções: https://brasilgeo.ai/leadlovers2026/design/dashboards/agentes.md
    - [frontend-2027](https://brasilgeo.ai/leadlovers2026/design/frontend2027/): Stack moderna e decisões de estado em projeto novo. Instruções: https://brasilgeo.ai/leadlovers2026/design/frontend2027/agentes.md
    
    ## Fontes primárias
    
    - [React: versões](https://react.dev/versions)
    - [React: You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect)
    - [React: Choosing the State Structure](https://react.dev/learn/choosing-the-state-structure)
    
    Dados desta página para agentes de IA
    # Padrões de componentes React e gerenciamento de estado
    
    - Endereço: https://brasilgeo.ai/leadlovers2026/design/react/
    - Objetivo: Padrões de componentes React e estado em 2026: cinco padrões, onde mora cada estado, React 19.3, portal denso para leigos e o que revisar no código da IA.
    - Tipo: portal-leadlovers-design
    - Atualizada em: 2026-11-16
    - Publicada em: 2026-08-18
    - Idioma: pt-BR
    - Indexável: sim
    
    ## Seções
    1. [A aula, em vídeo e em podcast](https://brasilgeo.ai/leadlovers2026/design/react/#aula-title)
    2. [O React de 2026, em quatro fatos](https://brasilgeo.ai/leadlovers2026/design/react/#panorama-title)
    3. [Os cinco padrões de componente e o sinal de reprovação de cada um](https://brasilgeo.ai/leadlovers2026/design/react/#padroes-title)
    4. [React Compiler: a memoização saiu das suas mãos](https://brasilgeo.ai/leadlovers2026/design/react/#compilador-title)
    5. [Onde mora cada estado: a pergunta de trinta segundos](https://brasilgeo.ai/leadlovers2026/design/react/#estado-title)
    6. [Estado compartilhado: o custo de re-render de cada ferramenta](https://brasilgeo.ai/leadlovers2026/design/react/#compartilhado-title)
    7. [Quando o useEffect sobra: o critério oficial](https://brasilgeo.ai/leadlovers2026/design/react/#effect-title)
    8. [Dado de servidor: cache com dono](https://brasilgeo.ai/leadlovers2026/design/react/#servidor-title)
    9. [Formulários: teclar sem redesenhar o formulário inteiro](https://brasilgeo.ai/leadlovers2026/design/react/#formularios-title)
    10. [Filtro, aba e busca moram na URL](https://brasilgeo.ai/leadlovers2026/design/react/#url-title)
    11. [Next.js 16: a fronteira, o cache e a versão mínima](https://brasilgeo.ai/leadlovers2026/design/react/#next-title)
    12. [Tela de dados: a escada e o v9 que mudou a conta](https://brasilgeo.ai/leadlovers2026/design/react/#tabelas-title)
    13. [Testes: comportamento, papel e navegador de verdade](https://brasilgeo.ai/leadlovers2026/design/react/#testes-title)
    14. [Como cancelar uma operação sem perder o texto recebido](https://brasilgeo.ai/leadlovers2026/design/react/#oficina-operacao-title)
    15. [Como reordenar tarefas sem trocar seus rascunhos](https://brasilgeo.ai/leadlovers2026/design/react/#oficina-lista-title)
    16. [Animação em React que acompanha a rolagem e se desfaz ao sair](https://brasilgeo.ai/leadlovers2026/design/react/#oficina-scrub-title)
    17. [Portal denso: a interface que mostra tudo sem assustar](https://brasilgeo.ai/leadlovers2026/design/react/#oficina-portal-denso-title)
    18. [Como revisar o que o agente devolve: a checklist de 2026](https://brasilgeo.ai/leadlovers2026/design/react/#revisao-title)
    19. [O que este guia deixa de fora, e por quê](https://brasilgeo.ai/leadlovers2026/design/react/#lacunas-title)
    20. [Dois guias prontos para o LinkedIn e o Instagram](https://brasilgeo.ai/leadlovers2026/design/react/#llg-guias-title)
    
    ## Links principais
    - [Início do portal](https://brasilgeo.ai/leadlovers2026/)
    - [Design](https://brasilgeo.ai/leadlovers2026/design/)
    - [menus, abas e paginação](https://brasilgeo.ai/leadlovers2026/design/navegacao/)
    - [diagramas](https://brasilgeo.ai/leadlovers2026/design/diagramas/)
    - [Tailwind e CSS moderno](https://brasilgeo.ai/leadlovers2026/design/tailwind/)
    - [vídeo em MP4](https://brasilgeo.ai/podcast/episodios/leadlovers2026-design-react/aula-react.mp4)
    - [podcast em M4A](https://brasilgeo.ai/podcast/episodios/leadlovers2026-design-react/podcast-react.m4a)
    - [legenda do vídeo](https://brasilgeo.ai/media/leadlovers2026/design-react/aula-react.pt.vtt)
    - [transcrição do vídeo](https://brasilgeo.ai/media/leadlovers2026/design-react/aula-react-transcricao.txt)
    - [transcrição do podcast](https://brasilgeo.ai/media/leadlovers2026/design-react/podcast-react-transcricao.txt)
    - [API](https://brasilgeo.ai/leadlovers2026/glossario/)
    - [instalação oficial do React Compiler](https://react.dev/learn/react-compiler/installation) (externo)
    - [Server Component](https://react.dev/reference/rsc/server-components) (externo)
    - [Choosing the State Structure](https://react.dev/learn/choosing-the-state-structure) (externo)
    - [MDN: AbortSignal e cancelamento](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) (externo)
    - [MDN: AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) (externo)
    - [React: ciclo de vida e limpeza de Effects](https://react.dev/reference/react/useEffect) (externo)
    
    ## Para agentes
    - JSON com os mesmos dados no elemento script#pagina-para-agentes (esquema pagina-brasilgeo-para-agentes/v1).
    - JSON-LD da página no <head>: Article, VideoObject, AudioObject, BreadcrumbList, FAQPage.
    - Índice do site para agentes: https://brasilgeo.ai/llms.txt
    - Listas resumidas para caber em 12 KB (sem subtítulos); a página completa está no endereço acima.