Desarrollo de Componentes Next.js con Skeletons (nextjs-compone…

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

Flujo de trabajo especializado para crear React Server Components (RSC) y Client Components listos para producción con skeletons de Suspense, pruebas TDD de doble capa (pruebas unitarias Jest + RTL y pruebas de integración/hidratación/visuales con Playwright), traducciones con diccionarios next-intl, tokens de tema semánticos y diagnóstico en tiempo de ejecución en vivo mediante next-devtools MCP.

[!TIP] Activos y Plantillas Modulares:

• Búsqueda y Contexto de Documentación Next.js: references/nextjs-docs-lookup.md
• Arquitectura de Pruebas y Verificación: references/testing-architecture-guide.md
• Estándares de Storybook y Separación: references/storybook-reference.md
• Navegación Instantánea y Prefetching: references/instant-navigation-and-prefetching.md
• Guía de Depuración con Next DevTools: references/next-devtools-debugging.md
• Caché y Revalidación: references/caching-and-revalidation.md
• Plantillas de Código: resources/templates/ (Componente, Skeleton, Prueba Unitaria Jest, Especificación Playwright)
• Implementaciones de Referencia: examples/
• Scripts de Verificación: scripts/verify-dev.ps1 (Windows) / scripts/verify-dev.sh (Linux)

---

Reglas y Estándares Arquitectónicos

1. Contexto de Planificación y Rutas

• Lee docs/project.json para resolver package_manager, new_component_dir, style_file_dir, component_library, dictionaries_dir (por defecto: "messages") y supported_languages.
• Todas las rutas internas DEBEN usar ROUTES de @/lib/routes.
• Todos los metadatos de autor/sitio DEBEN usar SITE_CONFIG de @/lib/site-config.
• Jerarquía de ruta objetivo: <new_component_dir>/<page_or_global>/<ComponentName>/
  • Categoría: global/ para elementos compartidos de layout; <page-name>/ (ej. home/, about/, lab/) para secciones de ámbito de página.

2. Consulta de Documentación Interna de Next.js (node_modules/next/dist/docs)

• Búsqueda en Documentación Local mediante Codebase Memory MCP: Para cualquier creación de componente, consulta e inspecciona activamente la documentación local de la distribución de Next.js en node_modules/next/dist/docs/ usando las herramientas MCP de codebase-memory (search_code, search_graph, get_code_snippet) para encontrar firmas de API relevantes, directivas ('use cache', 'use client', 'use server'), componentes integrados (next/image, next/link, next/font, <Form>), hooks de navegación (useRouter, usePathname) y políticas de caché (cacheLife, cacheTag).
• Elimina Deprecaciones y Alucinaciones: Nunca te bases en suposiciones o patrones obsoletos de Next.js; la documentación local node_modules/next/dist/docs que coincide con la versión del paquete instalado es la fuente principal de verdad. Consulta references/nextjs-docs-lookup.md.

3. Servidor de Desarrollo y Protocolo Next DevTools

• Verificación del Servidor de Desarrollo y Conexión: Antes/durante el desarrollo del componente, verifica si el servidor de desarrollo de Next.js está en ejecución mediante el servidor MCP next-devtools (nextjs_index).
• Si el Servidor Está en Ejecución: Conéctate al servidor y puerto en ejecución inmediatamente; no reinicies.
• Si el Servidor NO Está en Ejecución: Inicia el servidor de desarrollo en segundo plano (pnpm dev, IsDaemon: true) y verifica la conexión mediante nextjs_index.
• Depuración en Tiempo de Ejecución: Después de implementar los componentes, consulta next-devtools (nextjs_call) para inspeccionar errores, verificar el estado de compilación y diagnosticar problemas de tiempo de ejecución inmediatamente. Consulta references/next-devtools-debugging.md.

4. Límites de RSC y Push-Down de Componentes Cliente Hoja

1. Componentes Servidor por Defecto: Mantén los componentes renderizados en el servidor (async function).
2. Empuja "use client" Hacia Abajo: Aísla los manejadores interactivos (botones, conmutadores, entradas de formulario) en pequeños componentes Cliente hoja.
3. Composición RSC: Pasa los Componentes Servidor como children o props dentro de envoltorios Cliente. Nunca importes Componentes Servidor dentro de archivos "use client".

5. Estilos, Propiedades Lógicas y Tokens de Tema

• Tokens Semánticos: Usa exclusivamente variables CSS semánticas definidas en app/globals.css (bg-background, text-foreground, border-border, text-muted-foreground). Los colores hexadecimales hardcodeados (#FAFAFA) o escalas de color crudas (bg-blue-500) están PROHIBIDOS.
• Fusión de Clases: Siempre fusiona clases usando cn(...) (clsx + tailwind-merge).
• Propiedades Lógicas (BiDi): Usa exclusivamente propiedades lógicas de Tailwind (ms-, pe-, ps-, me-, start, end). Las clases direccionales físicas (ml-, mr-, pl-, pr-, left-, right-) están PROHIBIDAS.
• Enlaces de Progreso: Usa <Link> de @vercel/react-transition-progress para la navegación principal, CTA de héroe y tarjetas interactivas; usa next/link estándar para enlaces de utilidad estáticos.
• Imágenes: Usa siempre next/image con dimensiones explícitas o fill, sizes responsivos y priority para activos LCP visibles en la pantalla.

6. Navegación Instantánea, Suspense Granular y Arquitectura de Caché

• Las Tres Palancas para Componentes Instantáneos:
  1. Empuja Hacia Abajo: Extrae operaciones asíncronas específicas de la solicitud (await params, await searchParams, cookies(), headers(), llamadas DB/API no cacheadas) en subcomponentes hoja envueltos en <Suspense>. Los padres y hermanos estáticos se elevan directamente al App Shell estático.
  2. Cache: Combina 'use cache' con cacheLife y cacheTag a nivel de función/componente. Usa patrones de Sesión Puente:
     • Patrón A (Extraer y Pasar): Extrae atributos de sesión (ej. team_id, role, tier) de cookies() externamente y pásalos como argumentos a funciones con 'use cache' para que los datos en caché se compartan entre todos los usuarios con atributos coincidentes (el costo escala con el número de equipo/atributo, no con el número de sesiones de usuario).
     • Patrón B ("use cache: private"): Para búsquedas de sesión estrictamente específicas del usuario, usa almacenamiento en caché de sesión solo del navegador con stale >= 5m que viaja con el App Shell.
  3. Estrategia de Prefetching y Cuadrículas Densas:
     • Prefetching por Defecto del App Shell (<Link> / prefetch={null}): Precarga un App Shell estático/compartido por ruta. Costo acotado ($O(\text{rutas})$), cero invocaciones al servidor por enlace. Úsalo para feeds densos, cuadrículas de tarjetas (50+ tarjetas) y navegación masiva.
     • Prefetching por Enlace (<Link prefetch={true}>): Resuelve datos de URL dinámicos (params, searchParams) antes de la navegación con 1 invocación al servidor por enlace visible. Úsalo con moderación para CTA de alta intención, acciones de héroe o elementos de listas maestro-detalle donde el parpadeo del skeleton debe eliminarse.
     • Cuadrículas de Tarjetas Densas: NUNCA uses prefetch={true} de forma generalizada en docenas de tarjetas en feeds. Mantén el <Link> por defecto o usa prefetching basado en la intención de hover/enfoque (router.prefetch()).
• Estados de Carga Granulares (Anti-Parpadeo de Página Completa): Nunca envuelvas un componente o página completa en un solo límite <Suspense> de nivel superior que muestre skeletons completos. Mantén los títulos, marcos de layout y contenido en caché visibles inmediatamente; coloca <Suspense> estrictamente alrededor de los slots de transmisión dinámica.
• Directivas de Caché Nativas de Next.js 16: Consulta references/instant-navigation-and-prefetching.md y references/caching-and-revalidation.md.

7. TanStack Query y Prefetching del Servidor

• Contrato de Caché Unificado: Define key, tag y queryOptions con staleTime explícito (ej. 30_000 ms).
• Prefetching del Servidor: Dispara el prefetch sin esperar (void queryClient.prefetchQuery(...)) llamando directamente a funciones DB internas (cero fetch relativo en el servidor). Deshidrata con <HydrationBoundary>.
• Componentes Transmitidos: Usa useSuspenseQuery dentro de <Suspense fallback={<[NombreComponente]Skeleton />}>.
• Mutaciones Optimistas: Usa useMutation con instantáneas de caché onMutate y reversiones onError; llama a Server Actions con updateTag(cache.tag).

8. División de Trabajo de Pruebas de Doble Capa (Jest vs. Playwright)

• Jest + RTL ([NombreComponente].test.tsx):
  • Bucle de retroalimentación rápida en jsdom.
  • Permutaciones de props, elementos de UI condicionales y estados vacíos/nulos.
  • Interacciones de usuario mediante @testing-library/user-event (nunca fireEvent).
  • Mocks de enrutamiento de Next.js (useRouter, usePathname, useSearchParams de next/navigation).
  • Comprobaciones de interpolación y pluralización del diccionario next-intl dentro de NextIntlClientProvider.
  • Consultas de roles accesibles (screen.getByRole) y comprobaciones automáticas de a11y (jest-axe).
• Playwright ([NombreComponente].spec.ts o especificaciones a nivel de página):
  • Ejecución en navegador real (Chromium/WebKit/Firefox).
  • Afirmaciones de Shell Instantáneo (@next/playwright): Usa el ayudante instant(page, ...) para afirmar que los shells estáticos y los App Shells precargados se renderizan inmediatamente antes de que se resuelva la transmisión dinámica del servidor.
  • Cero Incoherencias de Hidratación: Escucha los eventos de la consola del navegador (page.on('console')) para detectar y fallar pruebas en advertencias de hidratación de SSR de React.
  • Regresión Visual y BiDi: Usa expect(page).toHaveScreenshot() en todos los temas (variables OKLCH claras vs. oscuras) y direcciones de texto (dir="ltr" vs. dir="rtl").
  • Resiliencia de Red: Usa page.route() para probar respuestas de red lentas (verificando que los skeletons de Suspense coincidan con la geometría para evitar CLS) y límites de error 500.
• Estándares de Pruebas Detallados: Consulta references/testing-architecture-guide.md.

---

Fase 0: Plan de Implementación y Puerta de Aprobación

[!IMPORTANT] Planificar Antes de Ejecutar: Siempre genera y presenta un artefacto implementation_plan.md que detalle todas las creaciones de archivos planificadas, modificaciones, contratos TypeScript, adiciones al diccionario de traducción y casos de prueba TDD antes de ejecutar cualquier operación de escritura, modificar diccionarios o crear componentes en el repositorio. Espera la confirmación/aprobación del usuario antes de proceder con la ejecución.

El plan de implementación debe cubrir:

1. Arquitectura y Ruta Objetivo: Directorio objetivo completo (<new_component_dir>/<page_or_global>/<ComponentName>/) y clasificación (RSC vs. componente Cliente hoja).
2. Documentación Local de Next.js Consultada: Rutas de documentación específicas consultadas bajo node_modules/next/dist/docs/ (ej. 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 y tipos con anotaciones TSDoc estrictas en inglés.
4. Estrategia de Diccionario: Espacios de nombres y claves de traducción explícitos para añadir a messages/[locale].json en todos los supported_languages en docs/project.json (cero cadenas hardcodeadas o diccionarios mock en archivo).
5. Tokens de Tema y Estilos: Variables CSS semánticas OKLCH identificadas y clases de layout lógicas.
6. Estrategia de Pruebas y Diagnóstico:
   • Pruebas Unitarias Jest ([NombreComponente].test.tsx): Configuraciones mock (next/navigation), variaciones de props, afirmaciones de callbacks, integración con NextIntlClientProvider y consultas de roles a11y.
   • Escenarios de Integración Playwright ([NombreComponente].spec.ts): Objetivos de instantánea visual (temas claro/oscuro, layouts lógicos LTR vs. RTL), comprobaciones de limitación de red/geometría de skeleton y listeners de verificación de hidratación.
   • Diagnóstico con Next DevTools: Comprobaciones de errores de tiempo de ejecución y compilación mediante next-devtools.
7. Puerta de Verificación: Comandos de verificación exactos para ejecutar (verify-dev.ps1, pruebas unitarias específicas y especificaciones e2e de Playwright).

---

Pasos del Flujo de Trabajo

• Paso 0: Generación del Plan de Implementación y Puerta de Aprobación

  • Busca e inspecciona node_modules/next/dist/docs mediante codebase-memory MCP (search_code, search_graph) para cualquier API, directiva, hook o componente de Next.js utilizado por el componente planificado para asegurar un contexto actualizado.
  • Sintetiza los requisitos del componente, escanea docs/project.json y genera implementation_plan.md documentando las consultas de documentación y los contratos.
  • Establece request_feedback = true y user_facing = true en el artefacto.
  • Espera la revisión y aprobación explícita del usuario antes de escribir cualquier código.

• Paso 1: Verificación del Servidor de Desarrollo y Conexión a Next DevTools

  • Consulta el MCP next-devtools mediante nextjs_index para detectar instancias del servidor de desarrollo de Next.js en ejecución.
  • Si el Servidor de Desarrollo está en ejecución: Conéctate al puerto e instancia del servidor activo; continúa desarrollando sin reiniciar.
  • Si el Servidor de Desarrollo NO está en ejecución: Inicia el servidor de desarrollo en segundo plano (pnpm dev, IsDaemon: true) y verifica el descubrimiento con nextjs_index.

• Paso 2: Población del Diccionario y Definición del Contrato TypeScript

  • Lee docs/project.json para resolver dictionaries_dir (messages es el valor por defecto) y supported_languages.
  • Define el espacio de nombres y las claves de traducción del componente.
  • Puebla todos los archivos de diccionario (messages/en.json, messages/fa.json, etc.) con traducciones auténticas para cada idioma soportado antes de escribir JSX.
  • Define interfaces de props con anotaciones TSDoc estrictas en inglés (@param, @defaultValue, @returns).
  • Si hay más de un idioma soportado, el componente debe obtener primero la traducción y si falla, usar valores de respaldo.

• Paso 3: Pruebas Unitarias de Línea Base TDD ([NombreComponente].test.tsx mediante Jest + RTL)

  • Escribe [NombreComponente].test.tsx ANTES de implementar el componente.
  • Simula los hooks de next/navigation (useRouter, usePathname, useSearchParams).
  • Envuelve los componentes renderizados en NextIntlClientProvider suministrando los messages del diccionario y el locale activo.
  • Prueba atributos direccionales (dir="rtl" vs. dir="ltr"), props predeterminados, callbacks interactivos (@testing-library/user-event), fallbacks de skeleton de Suspense y roles ARIA semánticos.

• **Paso 4