BIGboss248/nextjs-wordpress

Desenvolvimento de Componentes & Skeletons Next.js (nextjs-component-dev)

Fluxo de trabalho especializado para a criação de React Server Components (RSC) e Client Components prontos para produção, com skeletons de Suspense, testes de dupla camada TDD (testes unitários Jest + RTL e verificações de integração/hidratação/visuais Playwright), traduções baseadas em dicionários next-intl, tokens de tema semânticos e diagnóstico de tempo de execução ao vivo via MCP next-devtools.

[!TIP] Ativos e Modelos Modulares:

• Pesquisa e Contexto da Documentação do Next.js: references/nextjs-docs-lookup.md
• Arquitetura e Verificação de Testes: references/testing-architecture-guide.md
• Padrões e Separação do Storybook: references/storybook-reference.md
• Navegação e Pré-busca Instantâneas: references/instant-navigation-and-prefetching.md
• Guia de Depuração Next DevTools: references/next-devtools-debugging.md
• Cache e Revalidação: references/caching-and-revalidation.md
• Modelos de Código: resources/templates/ (Componente, Skeleton, Teste Unitário Jest, Especificação Playwright)
• Implementações de Referência: examples/
• Scripts de Verificação: scripts/verify-dev.ps1 (Windows) / scripts/verify-dev.sh (Linux)

---

Regras e Padrões Arquiteturais

1. Contexto de Planejamento e Caminhos

• Leia docs/project.json para resolver package_manager, new_component_dir, style_file_dir, component_library, dictionaries_dir (padrão: "messages") e supported_languages.
• Todas as rotas internas DEVEM usar ROUTES de @/lib/routes.
• Todos os metadados de autor/site DEVEM usar SITE_CONFIG de @/lib/site-config.
• Hierarquia de caminho alvo: <new_component_dir>/<page_or_global>/<ComponentName>/
  • Categoria: global/ para elementos de layout compartilhado; <page-name>/ (ex: home/, about/, lab/) para seções de escopo de página.

2. Consulta à Documentação Interna do Next.js (node_modules/next/dist/docs)

• Pesquisar Documentos Locais via MCP Codebase Memory: Para qualquer criação de componente, consulte e inspecione ativamente os documentos locais de distribuição do Next.js em node_modules/next/dist/docs/ usando as ferramentas MCP codebase-memory (search_code, search_graph, get_code_snippet) para assinaturas de API relevantes, diretivas ('use cache', 'use client', 'use server'), componentes integrados (next/image, next/link, next/font, <Form>), hooks de navegação (useRouter, usePathname) e políticas de cache (cacheLife, cacheTag).
• Eliminar Depreciações e Alucinações: Nunca confie em suposições ou padrões desatualizados do Next.js; os documentos locais node_modules/next/dist/docs que correspondem à versão do pacote instalado são a fonte primária da verdade. Consulte references/nextjs-docs-lookup.md.

3. Servidor de Desenvolvimento e Protocolo Next DevTools

• Verificação e Sintonização do Servidor de Desenvolvimento: Antes/durante o desenvolvimento do componente, verifique se o servidor de desenvolvimento Next.js está em execução via servidor MCP next-devtools (nextjs_index).
• Se o Servidor Estiver em Execução: Sintonize imediatamente no servidor e porta em execução; não reinicie.
• Se o Servidor Não Estiver em Execução: Inicie o servidor de desenvolvimento em segundo plano (pnpm dev, IsDaemon: true) e verifique a conexão via nextjs_index.
• Depuração em Tempo de Execução: Após implementar componentes, consulte next-devtools (nextjs_call) para inspecionar erros, verificar o status da compilação e diagnosticar problemas de tempo de execução imediatamente. Consulte references/next-devtools-debugging.md.

4. Limites RSC e Client Componentes Folha

1. Componentes de Servidor por Padrão: Mantenha os componentes renderizados no servidor (função async).
2. Empurre "use client" para Baixo: Isole manipuladores interativos (botões, alternadores, entradas de formulário) em pequenos Componentes Cliente folha.
3. Composição RSC: Passe Componentes de Servidor como children ou props para wrappers Cliente. Nunca importe Componentes de Servidor dentro de arquivos "use client".

5. Estilização, Propriedades Lógicas e Tokens de Tema

• Tokens Semânticos: Use exclusivamente variáveis CSS semânticas definidas em app/globals.css (bg-background, text-foreground, border-border, text-muted-foreground). Cores hexadecimais codificadas (#FAFAFA) ou escalas de cores brutas (bg-blue-500) são PROIBIDAS.
• Mesclagem de Classes: Sempre mescle classes usando cn(...) (clsx + tailwind-merge).
• Propriedades Lógicas (BiDi): Use exclusivamente propriedades lógicas do Tailwind (ms-, pe-, ps-, me-, start, end). Classes direcionais físicas (ml-, mr-, pl-, pr-, left-, right-) são PROIBIDAS.
• Links de Progresso: Use <Link> de @vercel/react-transition-progress para navegação principal, CTAs de herói e cartões interativos; use next/link padrão para links de utilidade estáticos.
• Imagens: Sempre use next/image com dimensões explícitas ou fill, sizes responsivos e priority para ativos LCP acima da dobra.

6. Navegação Instantânea, Suspense Granular e Arquitetura de Cache

• As Três Alavancas para Componentes Instantâneos:
  1. Empurre para Baixo: Extraia operações assíncronas específicas de requisição (await params, await searchParams, cookies(), headers(), chamadas DB/API não armazenadas em cache) em sub-componentes folha envolvidos em <Suspense>. Pais e irmãos estáticos são elevados diretamente para o App Shell estático.
  2. Cache: Combine 'use cache' com cacheLife e cacheTag no nível de função/componente. Use padrões de Pontes de Sessão:
     • Padrão A (Extrair e Passar): Extraia atributos de sessão (ex: team_id, role, tier) de cookies() externamente e passe como argumentos para funções 'use cache' para que dados em cache sejam compartilhados entre todos os usuários com atributos correspondentes (o custo escala com a contagem de equipe/atributo, não com a contagem de sessão de usuário).
     • Padrão B ("use cache: private"): Para consultas de sessão estritamente específicas do usuário, use cache de sessão apenas no navegador com stale >= 5m que viaja com o App Shell.
  3. Estratégia de Pré-busca e Grades Densas:
     • Pré-busca Padrão do App Shell (<Link> / prefetch={null}): Pré-busca um App Shell estático/compartilhado por rota. Custo limitado ($O(\text{rotas})$), zero invocações de servidor por link. Use para feeds densos, grades de cartões (50+ cartões) e navegação em massa.
     • Pré-busca por Link (<Link prefetch={true}>): Resolve dados de URL dinâmicos (params, searchParams) antes da navegação com 1 invocação de servidor por link visível. Use com moderação para CTAs primários de alta intenção, ações de herói ou itens de lista mestre-detalhe onde o flash do skeleton deve ser eliminado.
     • Grades de Cartões Densas: NUNCA use prefetch={true} genérico em dezenas de cartões em feeds. Mantenha o <Link> padrão ou use pré-busca por intenção de hover/foco (router.prefetch()).
• Estados de Carregamento Granulares (Anti-Flash de Página Inteira): Nunca envolva um componente ou página inteira em um único limite <Suspense> de nível superior que exiba skeletons completos. Mantenha títulos, quadros de layout e conteúdo em cache visíveis imediatamente; coloque <Suspense> estritamente em torno de slots de streaming dinâmicos.
• Diretivas de Cache Nativas do Next.js 16: Consulte references/instant-navigation-and-prefetching.md e references/caching-and-revalidation.md.

7. TanStack Query e Pré-busca no Servidor

• Contrato de Cache Unificado: Defina key, tag e queryOptions com staleTime explícito (ex: 30_000 ms).
• Pré-busca no Servidor: Acione a pré-busca não aguardada (void queryClient.prefetchQuery(...)) chamando funções DB internas diretamente (zero requisição relativa no servidor). Desidrate com <HydrationBoundary>.
• Componentes Streamed: Use useSuspenseQuery dentro de <Suspense fallback={<[NomeDoComponente]Skeleton />}>.
• Mutações Otimistas: Use useMutation com snapshots de cache onMutate e rollbacks onError; chame Server Actions com updateTag(cache.tag).

8. Divisão de Trabalho de Testes de Dupla Camada (Jest vs. Playwright)

• Jest + RTL ([NomeDoComponente].test.tsx):
  • Ciclo de feedback rápido em jsdom.
  • Permutações de props, elementos de UI condicionais e estados vazios/nulos.
  • Interações de usuário via @testing-library/user-event (nunca fireEvent).
  • Mocks de roteamento Next.js (useRouter, usePathname, useSearchParams de next/navigation).
  • Verificações de interpolação e pluralização de dicionário next-intl dentro de NextIntlClientProvider.
  • Consultas de funções acessíveis (screen.getByRole) e verificações de acessibilidade automatizadas (jest-axe).
• Playwright ([NomeDoComponente].spec.ts ou especificações de nível de página):
  • Execução em navegador real (Chromium/WebKit/Firefox).
  • Asserções de Shell Instantâneo (@next/playwright): Use o helper instant(page, ...) para afirmar que shells estáticos e App Shells pré-buscados são renderizados imediatamente antes da resolução do streaming dinâmico do servidor.
  • Zero Incompatibilidade de Hidratação: Ouça eventos do console do navegador (page.on('console')) para detectar e falhar testes em avisos de hidratação SSR do React.
  • Regressão Visual e BiDi: Use expect(page).toHaveScreenshot() em temas (claro vs. escuro variáveis OKLCH) e direções de texto (dir="ltr" vs. dir="rtl").
  • Resiliência de Rede: Use page.route() para testar respostas de rede lentas (verificando se os skeletons de Suspense correspondem à geometria para evitar CLS) e limites de erro 500.
• Padrões de Teste Detalhados: Consulte references/testing-architecture-guide.md.

---

Fase 0: Plano de Implementação e Portão de Aprovação

[!IMPORTANT] Planeje Antes de Executar: Sempre gere e apresente um artefato implementation_plan.md detalhando todas as criações de arquivos planejadas, modificações, contratos TypeScript, adições de dicionário de tradução e casos de teste TDD antes de executar qualquer operação de escrita, modificar dicionários ou criar componentes no repositório. Aguarde a confirmação/aprovação do usuário antes de prosseguir com a execução.

O plano de implementação deve cobrir:

1. Arquitetura e Caminho Alvo: Diretório alvo completo (<new_component_dir>/<page_or_global>/<ComponentName>/) e classificação (RSC vs. componente cliente folha).
2. Documentos Locais do Next.js Consultados: Caminhos de documentos específicos verificados em node_modules/next/dist/docs/ (ex: 04-api-reference/04-components/image.md, 03-directives/use-cache.md, 04-api-reference/02-functions/use-router.md).
3. Contratos TypeScript: Interfaces de props e tipos com anotações TSDoc estritas em inglês.
4. Estratégia de Dicionário: Namespaces e chaves de tradução explícitas para adicionar a messages/[locale].json em todos os supported_languages em docs/project.json (zero strings codificadas ou dicionários mock em arquivo).
5. Tokens de Tema e Estilização: Variáveis CSS OKLCH semânticas identificadas e classes de layout lógicas.
6. Estratégia de Testes e Diagnóstico:
   • Testes Unitários Jest ([NomeDoComponente].test.tsx): Configurações de mock (next/navigation), variações de props, asserções de callback, integração com NextIntlClientProvider e consultas de função de acessibilidade.
   • Cenários de Integração Playwright ([NomeDoComponente].spec.ts): Alvos de snapshot visual (tokens de tema claro/escuro, layouts lógicos LTR vs. RTL), verificações de geometria de skeleton com throttling de rede e ouvintes de verificação de hidratação.
   • Diagnóstico Next DevTools: Verificações de erro em tempo de execução e compilação via next-devtools.
7. Portão de Verificação: Comandos de verificação exatos para executar (verify-dev.ps1, testes unitários direcionados e especificações e2e Playwright).

---

Etapas do Fluxo de Trabalho

• Etapa 0: Geração do Plano de Implementação e Portão de Aprovação

  • Pesquise e inspecione node_modules/next/dist/docs via MCP codebase-memory (search_code, search_graph) para quaisquer APIs, diretivas, hooks ou componentes do Next.js utilizados pelo componente planejado para garantir contexto atualizado.
  • Sintetize os requisitos do componente, escaneie docs/project.json e gere implementation_plan.md documentando os documentos consultados e contratos.
  • Defina request_feedback = true e user_facing = true no artefato.
  • Aguarde a revisão e aprovação explícita do usuário antes de escrever qualquer código.

• Etapa 1: Verificação do Servidor de Desenvolvimento e Conexão Next DevTools

  • Consulte o MCP next-devtools via nextjs_index para detectar instâncias do servidor de desenvolvimento Next.js em execução.
  • Se o Servidor de Desenvolvimento estiver em execução: Sintonize na porta e instância do servidor ativo; continue desenvolvendo sem reiniciar.
  • Se o Servidor de Desenvolvimento NÃO estiver em execução: Inicie o servidor de desenvolvimento em segundo plano (pnpm dev, IsDaemon: true) e verifique a descoberta com nextjs_index.

• Etapa 2: População do Dicionário e Definição do Contrato TypeScript

  • Leia docs/project.json para resolver dictionaries_dir (messages é o padrão) e supported_languages.
  • Defina o namespace de tradução e as chaves do componente.
  • Popule todos os arquivos de dicionário (messages/en.json, messages/fa.json, etc.) com traduções autênticas para cada idioma suportado antes de escrever JSX.
  • Defina interfaces de props com anotações TSDoc estritas em inglês (@param, @defaultValue, @returns).
  • Se houver mais de um idioma suportado, o componente deve buscar a tradução primeiro e, se falhar, usar fallbacks.

• Etapa 3: Testes Unitários de Linha de Base TDD ([NomeDoComponente].test.tsx via Jest + RTL)

  • Escreva [NomeDoComponente].test.tsx ANTES de implementar o componente.
  • Moke hooks de next/navigation (useRouter, usePathname, useSearchParams).
  • Envolva os componentes renderizados em NextIntlClientProvider fornecendo o dicionário messages e locale ativo.
  • Teste atributos direcionais (dir="rtl" vs. dir="ltr"), props padrão, callbacks interativos (@testing-library/user-event), fallbacks de skeleton de Suspense e funções ARIA semânticas.

• **Etapa 4

…

[truncado para tradução]