Adaptador Visual de Componentes shadcn

# shadcn Component Visual Adapter ## Objective Refactor the existing `${component_name}` component located at `${component_file_path}` to match the visual design, structure, and behavior of the reference component available at: > ${install_command:bunx --bun shadcn@latest add accordion} ${reference_url:} ← opcional; dejar en blanco si no existe página de documentación NO reemplazar la lógica de negocio, la interfaz de props existente ni los patrones de obtención de datos. Conservarlos. Adaptar solo la capa visual: estructura de marcado, nombres de clases, animaciones y atributos de accesibilidad. ## Paso 1 - Analizar el Componente Existente Antes de escribir cualquier código: 1. Leer el código fuente completo de `${component_file_path}`. 2. Mapear: - Todas las props y sus tipos (interfaces de TypeScript o PropTypes). - Variables de estado internas (`useState`, `useReducer`, slices de Zustand, etc.). - Proveedores de contexto o hooks personalizados consumidos. - Componentes hijos renderizados y dónde se encuentran. - Manejadores de eventos y callbacks expuestos al componente padre. 3. Listar cada import - marcar cualquier conflicto que pueda tener o que pueda ser reemplazado por el primitivo de shadcn. Generar una tabla de auditoría breve antes de tocar cualquier código: | Elemento | Valor actual | Acción | |----------|--------------|--------| | Props | ... | mantener / renombrar / eliminar | | Estado | ... | mantener / migrar | | Contexto/Hooks | ... | mantener / reemplazar | | Sub-componentes | ... | mantener / reemplazar | | Dependencias | ... | mantener / instalar / eliminar | ## Paso 2 - Resolución de Dependencias Ejecutar el comando de instalación directamente: ${install_command} Después de que el comando se complete, los archivos generados aparecerán en ${components_dir:components/ui}/. Continuar al Paso 3 usando esos archivos. ## Paso 3 - Revisar el Componente de Referencia SI ${reference_url} se proporciona → obtenerlo y extraer la especificación visual como antes. SI ${reference_url} está en blanco → leer los archivos descargados por el comando CLI en el Paso 2 y extraer la misma información directamente del código fuente: - Esquema de variantes de cva - Atributos data-state / data-disabled - Clases de animación/transición - Roles y props ARIA - Patrones de uso de cn() ## Paso 4 - Refactorizar el Componente Aplicar la estructura visual del Paso 3 al componente existente del Paso 1. ### Reglas: - ✅ Mantener todos los nombres y tipos de props existentes a menos que exista un equivalente directo en shadcn. - ✅ Mantener toda la obtención de datos, lógica de negocio y callbacks. - ✅ Envolver los primitivos de Radix usando `forwardRef` y propagar `...props` para preservar la flexibilidad. - ✅ Usar `cn()` para todas las combinaciones de className - nunca concatenación de cadenas. - ✅ Exportar sub-componentes compuestos con nombre si el componente de referencia los usa (por ejemplo, `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`). - ❌ NO importar el archivo shadcn generado y re-exportarlo - construir el primitivo en línea en el archivo refactorizado para mantener la lógica co-ubicada. - ❌ NO agregar clases de Tailwind que no estén presentes en el componente de referencia sin instrucción explícita. ### Comportamiento responsivo (`${responsive_breakpoints:sm md lg}`): Aplicar clases responsivas mobile-first. Confirmar que los breakpoints actuales en `tailwind.config.ts` coinciden con la convención del proyecto. Si la referencia usa container queries, instalar `@tailwindcss/container-queries`. ## Paso 5 - Proveedores de Contexto y Hooks Si el componente de referencia requiere un proveedor de contexto (por ejemplo, `ToastProvider`, `TooltipProvider`): 1. Verificar si ya está montado en `${provider_file:app/layout.tsx}` o `${provider_file:app/providers.tsx}`. 2. Si no, agregarlo al archivo de layout apropiado. Proporcionar el diff exacto. 3. Si se requiere un hook personalizado (por ejemplo, `useToast`, `useDialog`), colocarlo en `${hooks_dir:hooks/}` e importarlo desde allí. ## Paso 6 - Preguntas de Aclaración (preguntar antes de generar si es desconocido) Si cualquiera de los siguientes puntos no se puede determinar a partir del código existente, preguntar antes de escribir: 1. **Datos/props**: ¿Qué forma de datos se pasará? (Proporcionar un objeto de ejemplo si es útil.) 2. **Gestión de estado**: ¿El estado del componente es local o se gestiona externamente (Zustand, Redux, React Query)? 3. **Recursos**: ¿Hay imágenes, logotipos o iconos personalizados requeridos que no estén cubiertos por lucide-react? 4. **Responsivo**: ¿Cuál es el layout esperado en los breakpoints `${responsive_breakpoints:sm md lg}`? 5. **Ubicación**: ¿Dónde en el árbol de routing/layout de la aplicación vivirá este componente? (Importante para la ubicación del proveedor de contexto.) ## Paso 7 - Formato de Salida Proporcionar el resultado como: 1. **`${component_file_path}`** - archivo completo del componente refactorizado. 2. **`${components_dir:components/ui}/${shadcn_component_slug}.tsx`** - primitivo de shadcn (solo si es necesario y no generado por CLI). 3. **`lib/utils.ts`** - solo si necesita ser creado o actualizado. 4. **Diff de layout/provider** - solo si se necesita agregar un proveedor. 5. Una sección breve de **notas de migración** que liste: - Dependencias eliminadas - Props renombradas (si las hay) - Pasos manuales requeridos (por ejemplo, agregar variables CSS a `globals.css`) ## Variables CSS de Tailwind (tokens de diseño shadcn) Confirmar que `globals.css` contiene las propiedades personalizadas CSS requeridas. Si el componente de referencia usa tokens como `--radius`, `--background`, `--foreground`, `--primary`, `--ring`, agregar las variables faltantes. Usar el conjunto de tokens predeterminado de shadcn para `${color_theme:zinc}` a menos que el proyecto ya defina un tema personalizado. ## Restricciones - Framework: **${framework:Next.js 14+ App Router}** - Estilado: **Tailwind CSS ${tailwind_version:3}** solamente - sin estilos en línea, sin módulos CSS, sin styled-components. - TypeScript: **modo estricto**. Todo el código nuevo debe estar completamente tipado. - No actualizar ni degradar ninguna versión de dependencia existente a menos que haya un conflicto directo de pares.