{
  "esquema": "design-guia-para-agentes/v1",
  "guia": "react",
  "nome": "React",
  "titulo": "Padrões de componentes React e gerenciamento de estado",
  "descricao": "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.",
  "url": "https://brasilgeo.ai/leadlovers2026/design/react/",
  "arquivos": {
    "markdown": "https://brasilgeo.ai/leadlovers2026/design/react/agentes.md",
    "json": "https://brasilgeo.ai/leadlovers2026/design/react/agentes.json",
    "indice": "https://brasilgeo.ai/leadlovers2026/design/llms.txt"
  },
  "revisadoEm": "2026-11-16",
  "idioma": "pt-BR",
  "resumo": "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.",
  "quandoUsar": [
    "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": [
    {
      "id": "REA-01",
      "nivel": "obrigatória",
      "regra": "Antes de criar estado, classifique o dado (local, derivado, cliente compartilhado, servidor ou URL) e use a ferramenta daquele lugar.",
      "porque": "Errar a classe vira reescrita da camada de dados. Sintoma: duas telas com saldos diferentes."
    },
    {
      "id": "REA-02",
      "nivel": "obrigatória",
      "regra": "Calcule dado derivado (total, lista filtrada) no render. Nunca o guarde em useState.",
      "porque": "Duas fontes de verdade divergem na primeira alteração."
    },
    {
      "id": "REA-03",
      "nivel": "obrigatória",
      "regra": "Todo useEffect nomeia o sistema externo que sincroniza (widget fora do React, rede, DOM do navegador). Sem sistema externo, remova o Effect.",
      "porque": "Critério oficial de 'You Might Not Need an Effect'."
    },
    {
      "id": "REA-04",
      "nivel": "obrigatória",
      "regra": "Lógica causada por interação vai no event handler. Só a causada por o componente aparecer na tela vai no Effect.",
      "porque": "No Effect já se perdeu qual interação ocorreu."
    },
    {
      "id": "REA-05",
      "nivel": "obrigatória",
      "regra": "Todo Effect que cria listener, observer, timer, frame ou AbortController devolve limpeza que desfaz cada item criado.",
      "porque": "O StrictMode monta, desmonta e remonta. Sem limpeza a animação roda em dobro e a memória sobe."
    },
    {
      "id": "REA-06",
      "nivel": "obrigatória",
      "regra": "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.",
      "porque": "A cópia cria dois números do mesmo dado."
    },
    {
      "id": "REA-07",
      "nivel": "obrigatória",
      "regra": "Dê a cada consulta uma queryKey própria, com os parâmetros dentro.",
      "porque": "Mesma queryKey em consultas diferentes mostra o dado de uma tela na outra."
    },
    {
      "id": "REA-08",
      "nivel": "obrigatória",
      "regra": "Em lista, key vem do id do dado. Nunca índice nem Math.random(). Trate a lista vazia.",
      "porque": "Índice 'leva a bugs sutis'. Key aleatória recria o DOM e perde o que o usuário digitou."
    },
    {
      "id": "REA-09",
      "nivel": "obrigatória",
      "regra": "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.",
      "porque": "Os cinco padrões (props, children, useState, lista com key, campo controlado) cobrem a maioria das telas."
    },
    {
      "id": "REA-10",
      "nivel": "obrigatória",
      "regra": "Campo controlado mostra o erro em texto, na borda e com aria-invalid, sem esperar o envio.",
      "porque": "Erro só em cor reprova o padrão."
    },
    {
      "id": "REA-11",
      "nivel": "recomendada",
      "regra": "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.",
      "porque": "Recomendação oficial. Em código existente, mantenha ou teste antes de remover."
    },
    {
      "id": "REA-12",
      "nivel": "obrigatória",
      "regra": "Filtro, aba, ordenação, página e busca moram na URL com nuqs. Envolva a raiz no NuqsAdapter do framework.",
      "porque": "O link reproduz a tela. Sem o adapter o valor nunca chega ao endereço."
    },
    {
      "id": "REA-13",
      "nivel": "recomendada",
      "regra": "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.",
      "porque": "Context re-renderiza todo consumidor. Seletor com referência nova gera 'Maximum update depth exceeded'."
    },
    {
      "id": "REA-14",
      "nivel": "recomendada",
      "regra": "Formulário com 3 campos ou mais, ou lento no celular, usa react-hook-form com mode \"onTouched\". Campo único usa useState.",
      "porque": "register usa ref (não controlado). O modo onChange valida a cada tecla, com 'impacto significativo de performance'."
    },
    {
      "id": "REA-15",
      "nivel": "obrigatória",
      "regra": "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.",
      "porque": "useFormStatus reporta o form pai. useOptimistic reverte sozinho na falha."
    },
    {
      "id": "REA-16",
      "nivel": "obrigatória",
      "regra": "Escreva \"use client\" só nos arquivos de fronteira, no topo. Props que cruzam a fronteira são serializáveis.",
      "porque": "A diretiva em todo arquivo manda o componente inteiro ao navegador."
    },
    {
      "id": "REA-17",
      "nivel": "obrigatória",
      "regra": "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.",
      "porque": "O July 2026 Security Release corrigiu 9 CVEs, incluindo DoS e SSRF em Server Actions."
    },
    {
      "id": "REA-18",
      "nivel": "obrigatória",
      "regra": "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.",
      "porque": "A forma antiga é Next de 2024."
    },
    {
      "id": "REA-19",
      "nivel": "obrigatória",
      "regra": "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.",
      "porque": "useLegacyTable inclui tudo e pesa mais que a v8. Virtualização quebra Ctrl+F e teclado."
    },
    {
      "id": "REA-20",
      "nivel": "recomendada",
      "regra": "Teste com getByRole e simule a rede com MSW para afirmar carregando, falhou e chegou.",
      "porque": "Se o papel não acha o elemento, a tela pode ser inacessível."
    },
    {
      "id": "REA-21",
      "nivel": "obrigatória",
      "regra": "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.",
      "porque": "O controller interrompe a espera. A comparação protege a tela se a fonte ignorar o abort."
    },
    {
      "id": "REA-22",
      "nivel": "obrigatória",
      "regra": "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.",
      "porque": "Acima de 2 s parece desligada do gesto. 100 elementos com will-change derrubam um celular."
    },
    {
      "id": "REA-23",
      "nivel": "obrigatória",
      "regra": "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.",
      "porque": "Elas trazem papel ARIA, foco e teclado prontos."
    },
    {
      "id": "REA-24",
      "nivel": "obrigatória",
      "regra": "Cite só versões que existem: React 19.x, Next 16.x, TanStack Query v5.",
      "porque": "React 20 e TanStack Query v6 não existem."
    }
  ],
  "decisoes": [
    {
      "situacao": "Dado de um componente só (aba aberta, campo aberto)",
      "escolha": "useState ou useReducer",
      "evitar": "Biblioteca global"
    },
    {
      "situacao": "Dado calculável de outros (total, lista filtrada)",
      "escolha": "Calcular no render",
      "evitar": "Guardar em useState"
    },
    {
      "situacao": "Cliente compartilhado, baixa frequência (tema, sessão, modal)",
      "escolha": "Context com useReducer",
      "evitar": "Store pesado"
    },
    {
      "situacao": "Cliente compartilhado, alta frequência (carrinho)",
      "escolha": "Zustand com seletores e useShallow",
      "evitar": "Context, que re-renderiza em cascata"
    },
    {
      "situacao": "Formulário ou editor complexo com grão fino",
      "escolha": "Jotai, por átomos",
      "evitar": "Store monolítico"
    },
    {
      "situacao": "Filtro, aba, ordenação, página ou busca",
      "escolha": "URL com nuqs",
      "evitar": "useState que some ao recarregar"
    },
    {
      "situacao": "Dado do backend (produtos, perfil)",
      "escolha": "TanStack Query no cliente ou cache do framework no servidor",
      "evitar": "Cópia em useState ou Zustand"
    },
    {
      "situacao": "Fonte externa (tamanho da janela, store próprio)",
      "escolha": "useSyncExternalStore",
      "evitar": "useEffect improvisado"
    },
    {
      "situacao": "Atualização que disputa com a digitação",
      "escolha": "useTransition (pendência) ou useDeferredValue (versão derivada adiada)"
    },
    {
      "situacao": "Context grande com cascata",
      "escolha": "1) dividir por frequência, 2) estabilizar value com useMemo, 3) store com seletores"
    },
    {
      "situacao": "Dado que muda várias vezes por segundo",
      "escolha": "Fora do ciclo de render (motor próprio) ou sinais reativos, verificando a convivência com o Compiler",
      "evitar": "setState a cada mensagem"
    }
  ],
  "numeros": [
    {
      "valor": "React 19.3, 9/9/2026 (19.3.1 em 14/10/2026)",
      "uso": "Versão estável a assumir. Traz ViewTransition estável, Fragment Refs e Context em Server Components",
      "fonte": "blog do React"
    },
    {
      "valor": "React Compiler 1.0, 7/10/2025",
      "uso": "Memoização automática em build",
      "fonte": "blog do React"
    },
    {
      "valor": "Next.js 16 (21/10/2025); 16.4.2 em 15/10/2026",
      "uso": "Turbopack padrão, proxy.ts, Cache Components",
      "fonte": "blog do Next.js"
    },
    {
      "valor": "Next.js 16.2.11 ou 15.5.21",
      "uso": "Piso de segurança (9 CVEs, release de 20/7/2026)",
      "fonte": "July 2026 Security Release"
    },
    {
      "valor": "TanStack Query 5.101.4; react-hook-form 7.85.0; nuqs 2.9.6; Zustand 5.0.15; Jotai 2.20.2",
      "uso": "Versões estáveis de 18/8/2026. Reconfira antes de citar",
      "fonte": "registro npm"
    },
    {
      "valor": "TanStack Table 9.1.2 (v9 estável em 4/8/2026); TanStack Virtual 3.14.21",
      "uso": "Tabela com features declaradas e virtualização",
      "fonte": "registro npm"
    },
    {
      "valor": "TanStack Query 68% de uso e 97% de retenção; Zustand 50% e 94%; Jotai 18% e 92%",
      "uso": "Adoção das opções de estado",
      "fonte": "State of React 2025"
    },
    {
      "valor": "0,5 a 1 s (conteúdo); 1,5 a 2 s (fundo)",
      "uso": "Atraso de scrub na rolagem",
      "fonte": "guias Annnimate"
    },
    {
      "valor": "Acima de 2.000 linhas",
      "uso": "Passa a virtualizar com @tanstack/react-virtual (aria-rowcount e aria-rowindex)",
      "fonte": "prompt de tabela longa"
    }
  ],
  "evitar": [
    {
      "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."
    }
  ],
  "padroes": [
    {
      "nome": "Estado na URL com nuqs",
      "quando": "Filtro, busca e página que o link deve reproduzir",
      "linguagem": "tsx",
      "codigo": "\"use client\";\nimport { useQueryState, parseAsInteger } from \"nuqs\";\n\n// Exige <NuqsAdapter> na raiz do app.\nexport function Filtros() {\n  const [busca, setBusca] = useQueryState(\"busca\", { defaultValue: \"\" });\n  const [pagina, setPagina] = useQueryState(\"pagina\", parseAsInteger.withDefault(1));\n  return (\n    <>\n      <input value={busca} onChange={(e) => { setBusca(e.target.value); setPagina(1); }} />\n      <button onClick={() => setPagina((p) => p + 1)}>Página {pagina}</button>\n    </>\n  );\n}"
    },
    {
      "nome": "Operação cancelável",
      "quando": "Streaming ou requisição que o usuário cancela e repete",
      "linguagem": "tsx",
      "codigo": "import { useEffect, useRef, useState } from \"react\";\n\ntype Tarefa = { controlador: AbortController };\n\nexport function useOperacao(fonte: (signal: AbortSignal) => AsyncIterable<string>) {\n  const [texto, setTexto] = useState(\"\");\n  const ativo = useRef<Tarefa | null>(null);\n  // Sair da tela aborta o pedido pendente.\n  useEffect(() => () => { ativo.current?.controlador.abort(); ativo.current = null; }, []);\n\n  async function executar() {\n    ativo.current?.controlador.abort();\n    const tarefa = { controlador: new AbortController() };\n    ativo.current = tarefa; // a identidade do objeto faz o papel do serial\n    setTexto(\"\");\n    try {\n      for await (const t of fonte(tarefa.controlador.signal)) {\n        if (ativo.current !== tarefa) return; // pedido antigo: descarta\n        setTexto((x) => x + t);\n      }\n    } catch { /* cancelado ou falhou: o texto parcial fica */ }\n    finally { if (ativo.current === tarefa) ativo.current = null; }\n  }\n  return { texto, executar, cancelar: () => ativo.current?.controlador.abort() };\n}"
    }
  ],
  "checklist": [
    "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": [
    {
      "nome": "React Compiler 1.0",
      "uso": "Memoização automática em build"
    },
    {
      "nome": "TanStack Query 5",
      "uso": "Cache de dado de servidor"
    },
    {
      "nome": "nuqs 2",
      "uso": "Estado na URL"
    },
    {
      "nome": "react-hook-form 7",
      "uso": "Formulário não controlado"
    },
    {
      "nome": "React Aria Components, Base UI, Radix",
      "uso": "Widgets acessíveis prontos"
    },
    {
      "nome": "Zustand 5 e Jotai 2",
      "uso": "Estado de cliente de alta frequência"
    }
  ],
  "ondeAprofundar": [
    {
      "tema": "Cinco padrões e sinal de reprovação",
      "ancora": "#padroes",
      "url": "https://brasilgeo.ai/leadlovers2026/design/react/#padroes"
    },
    {
      "tema": "React Compiler",
      "ancora": "#compilador",
      "url": "https://brasilgeo.ai/leadlovers2026/design/react/#compilador"
    },
    {
      "tema": "Onde mora cada estado",
      "ancora": "#estado",
      "url": "https://brasilgeo.ai/leadlovers2026/design/react/#estado"
    },
    {
      "tema": "Quando o useEffect sobra",
      "ancora": "#effect",
      "url": "https://brasilgeo.ai/leadlovers2026/design/react/#effect"
    },
    {
      "tema": "Dado de servidor e hooks de formulário do React 19",
      "ancora": "#servidor",
      "url": "https://brasilgeo.ai/leadlovers2026/design/react/#servidor"
    },
    {
      "tema": "Estado na URL",
      "ancora": "#url",
      "url": "https://brasilgeo.ai/leadlovers2026/design/react/#url"
    },
    {
      "tema": "Next.js 16 e segurança",
      "ancora": "#next",
      "url": "https://brasilgeo.ai/leadlovers2026/design/react/#next"
    },
    {
      "tema": "Tela de dados e TanStack Table v9",
      "ancora": "#tabelas",
      "url": "https://brasilgeo.ai/leadlovers2026/design/react/#tabelas"
    },
    {
      "tema": "Testes e MSW",
      "ancora": "#testes-msw",
      "url": "https://brasilgeo.ai/leadlovers2026/design/react/#testes-msw"
    }
  ],
  "relacionados": [
    {
      "guia": "typescript",
      "motivo": "Tipagem de props, hooks e formulários em TSX.",
      "url": "https://brasilgeo.ai/leadlovers2026/design/typescript/",
      "instrucoes": "https://brasilgeo.ai/leadlovers2026/design/typescript/agentes.md"
    },
    {
      "guia": "tailwind",
      "motivo": "Classes montadas, mapa de variantes e tokens.",
      "url": "https://brasilgeo.ai/leadlovers2026/design/tailwind/",
      "instrucoes": "https://brasilgeo.ai/leadlovers2026/design/tailwind/agentes.md"
    },
    {
      "guia": "navegacao",
      "motivo": "Abas, paginação e paleta de comandos.",
      "url": "https://brasilgeo.ai/leadlovers2026/design/navegacao/",
      "instrucoes": "https://brasilgeo.ai/leadlovers2026/design/navegacao/agentes.md"
    },
    {
      "guia": "dashboards",
      "motivo": "Telas de dados com números, tabelas e estados.",
      "url": "https://brasilgeo.ai/leadlovers2026/design/dashboards/",
      "instrucoes": "https://brasilgeo.ai/leadlovers2026/design/dashboards/agentes.md"
    },
    {
      "guia": "frontend2027",
      "motivo": "Stack moderna e decisões de estado em projeto novo.",
      "url": "https://brasilgeo.ai/leadlovers2026/design/frontend2027/",
      "instrucoes": "https://brasilgeo.ai/leadlovers2026/design/frontend2027/agentes.md"
    }
  ],
  "fontes": [
    {
      "titulo": "React: versões",
      "url": "https://react.dev/versions"
    },
    {
      "titulo": "React: You Might Not Need an Effect",
      "url": "https://react.dev/learn/you-might-not-need-an-effect"
    },
    {
      "titulo": "React: Choosing the State Structure",
      "url": "https://react.dev/learn/choosing-the-state-structure"
    }
  ]
}
