Este tutorial es la primera parte de una guía completa para crear un sistema basado en la generación automática de páginas web utilizando React 19 y Next.js 15.Nuestro enfoque no es sólo en la velocidad, sino en la elegancia arquitectónica y el diseño consistente y de marca. Fuente abierta : (https://github.com/aifa-agi/aifa) Aquí está el roadmap: Parte 1 (Estás aquí): Arquitectura de núcleo profundamente sumergido - capturar todas las rutas, el componente PageHtmlTransformer, y las configuraciones de página fuertemente tipificadas. Parte 2: Tipos avanzados de páginas: páginas de documentación automatizadas y tutoriales interactivos. Parte 3: Integración de motores de IA: conectar modelos externos (ChatGPT, Claude) y nuestro agente interno de Aifa para una generación de contenido continua y autónoma. Bonus: Estudio de caso: despliegue, monetización y escalado de un SaaS de IA de nivel de producción con registro de usuarios y pagos Stripe. Este plan paso a paso te lleva a través de la construcción de tu propio clon enterprise-ready v0, completo con autenticación y flujos de pago.Un producto de IA en el mundo real desde el concepto hasta el lanzamiento—el código fuente completo disponible en . y Tecnología Stack: React 19 · Next.js 15 · Vercel · Prisma · Stripe · AI SDK · ChatGPT Nuestra plataforma combina la estabilidad de nivel empresarial con la innovación sangrienta: React 19 y Next.js 15 con App Router proporcionan rendimientos sub-100ms y auténticas rutas paralelas. Vercel potencia las implementaciones de tiempo cero y el escalado global. Prisma & Neon garantiza el acceso a datos de tipo seguro y rápido. Stripe maneja pagos instantáneos y compatibles con PCI fuera de la caja. AI SDK + ChatGPT capa en inteligencia generativa, por lo que AIFA Dev Starter puede girar UI completos, módulos de contenido y prototipos en minutos, completo con autenticación integrada y chat de IA multilingüe. Cómo funciona Prompt: Envía una única solicitud de lengua natural a ChatGPT. Generar: Recibe un PageConfig basado en JSON que define las secciones, metadatos y el diseño de su página. Build: Deje caer el archivo de configuración en su aplicación Next.js y ejecute npm run build. Instantaneamente tiene una página totalmente estilizada, lista para SEO, completa con chat auth y AI. ¿Necesita la integración de la empresa? Simplemente encienda nuestro “modo corporativo v0” en el próximo [aifa.dev(https://aifa.dev)] para obtener automatización avanzada, acceso basado en roles y arquitectura de microservicios escalables. En el caso de las empresas que no tengan acceso a los servicios de la empresa en el momento de la adquisición de la propiedad, se procederá a la adquisición de la propiedad de la empresa en el momento de la adquisición de la propiedad ( ) para automatización avanzada, acceso basado en roles y arquitectura de microservicios escalables. https://aifa.dev ¿Quién gana con un generador de sitios alimentado por IA? estudios, empresas, startups y freelancers La agencia de diseño de próxima generación: del mockup a la producción en masa en minutos Imagínese una agencia que arquitecta ecosistemas de tecnología escalables, no sólo mockups estáticos.Una única inversión anticipada en una biblioteca de componentes propietarios desbloquea la capacidad de generar y desplegar más de 50 sitios web de nivel de producción por hora. Esto no es ciencia ficción.Es un nuevo paradigma operativo donde el capital creativo se encuentra con la ejecución automatizada.Y con la integración de Stripe incorporada, puedes monetizar esta nueva velocidad desde el primer día. Despliegue empresarial: Consistencia de la marca y escalabilidad radical Un clásico caso de uso empresarial: una solución de menú QR de clave trasera para una franquicia nacional de restaurantes. Construye un sistema de diseño maestro para la experiencia del usuario principal, como tarjetas de producto o menús, solo una vez. Cada ubicación personaliza su marca y contenido a través de una interfaz simple, mientras que el UX básico, el rendimiento y la integridad del diseño permanecen cerrados y consistentes. , de , y . radical scalability bulletproof brand consistency unmatched speed-to-market El motor principal: nuestra arquitectura de transformadores JSON-to-React Todo este sistema está alimentado por dos componentes críticos: Intelligent Prompt Engineering We use highly-tuned instructions that command the AI to pull battle-tested section templates from a vector database and tailor them to your specific request. The Component Transformer Architecture Our React components are engineered to interpret these JSON configs, instantly transforming them into fully-rendered, interactive pages. Mientras que los modelos externos como ChatGPT y Claude se encargan de la generación de contenido, nuestros componentes de transformadores propietarios son el motor central del sistema, la parte que construimos para garantizar el rendimiento y la fidelidad del diseño. Documentación nativa de IA: use este tutorial como una base de conocimientos en vivo parada Documentación: Inicio Y eso. Lectura Comandante El verdadero poder de esta guía no está en leerla de cubierta a cubierta. Está diseñado para ser la base de conocimiento privada y experta de su proyecto. Cómo funciona: Envíe este documento completo a ChatGPT. Haga preguntas específicas y contextuales: "¿Cómo implementar una sección personalizada?", "¿Cuál es el propósito del FullScreenWrapper?", "Mostrarme el código para el componente DoublePresentation". Recibe respuestas precisas y listas para la producción con fragmentos de código completos. Pruebe este enfoque y comprenderá por qué toda la documentación técnica en 2025 necesita ser nativa de la IA. Introducción: Nuestra filosofía: la coherencia trampa la velocidad cruda Mientras que las herramientas de IA como v0 priorizan la velocidad de generación cruda, nuestra metodología se centra en una métrica de negocio más crítica: Nuestro objetivo principal es proporcionar consistencia de diseño a prueba de balas y armonía arquitectónica en toda su huella digital. Total Cost of Ownership (TCO) Mientras que la generación inicial de una sola página puede tardar un poco más, los ahorros subsiguientes en desarrollo, mantenimiento y gestión de marca son exponenciales. Consistencia de la marca a prueba de balas: Cada página generada por la IA es automáticamente compatible con su sistema de diseño establecido. Experiencia de usuario sin problemas: La arquitectura asegura un viaje armonioso y cohesivo para el usuario, eliminando las inconsistencias que son comunes en los sitios generados rápidamente. Reducción drástica de la reestructuración: Al aplicar las normas en el momento de la creación, minimizamos los ajustes manuales costosos y demorados que normalmente se requieren en la postgeneración. Escalabilidad arquitectónica verdadera: Nuestro enfoque se vuelve más eficiente a medida que escalas.Cuanto más páginas generas, mayores son los retornos en velocidad y consistencia. The result isn't just a collection of pages; it's a cohesive, professional-grade digital asset that scales gracefully with minimal maintenance overhead. Más allá de los fundamentos: manejo de la complejidad del mundo real Este tutorial inicial se centra en la construcción de páginas estándar con nuestro núcleo , de , y Sin embargo, la base de código de código abierto proporciona soluciones avanzadas, fuera de la caja para requisitos más complejos: Header Body Footer Páginas de documentación con navegación avanzada. Páginas de tutoriales interactivas con elementos estadísticos, paso a paso. Para características únicas y altamente interactivas, como presentaciones animadas, dashboards de datos en tiempo real o componentes con gestión de estado complejo, puede inyectar Esto le da la flexibilidad para implementar funcionalidades personalizadas sin comprometer nunca la integridad central del sistema. Custom Components Your Next Step: Hands-On with Custom Components Para dominar verdaderamente este sistema, su tarea práctica es explorar el proceso de crear e integrar un nuevo Componente Personalizado. El concepto: la IA como administrador de tu marca, no sólo un motor de contenido Las operaciones digitales modernas requieren velocidad, integridad de la marca y agilidad del mercado.Nuestra arquitectura logra esto tratando su sistema de diseño como una base de conocimiento estructurada e inteligente.Las definiciones formalizadas y pre-aprobadas para cada sección crítica de la marca (Hero, CTA, FAQ, Funciones, etc.) son ingeridas por la IA. Al alimentar a la IA sus estándares UI / UX exactos, se convierte en más que un generador de contenido: se convierte en el administrador final de su identidad de marca, aplicando la coherencia en cada etapa del ciclo de vida de la creación de la página. El flujo de trabajo de 5 pasos: del sistema de diseño a la construcción optimizada por SEO Ingesta tu sistema de diseño: cargamos la base de conocimientos de la IA con tus plantillas de componentes y instrucciones explícitas sobre cómo implementarlas visualmente y estructuralmente, asegurando un alineamiento de marca del 100%. Define el objetivo con un prompt: un usuario, gerente de proyecto o desarrollador envía un simple prompt de texto que describe la página deseada o sus elementos. Interpretación y Estructuración de la IA: El agente de IA analizará la solicitud, generará el contenido semántico y lo mapeará de forma inteligente a las plantillas apropiadas y pre-aprobadas de la base de conocimientos. Generar una Declarative PageConfig: Basado en las plantillas seleccionadas, el sistema emite una PageConfig fuertemente tipada, una descripción JSON declarativa de la página final. Construcción y implementación automatizada: La configuración es consumida por nuestros componentes de renderización durante el proceso de construcción.La salida es una página lista para la producción, optimizada para SEO que es visualmente y técnicamente compatible con sus estándares corporativos. Impacto en el negocio: Drive Conversions y Slash TCO Go-to-Market acelerado: Lanzar nuevas páginas de destino y productos con una única solicitud, aprovechando plantillas pre-aprobadas para una velocidad incomparable. Integridad de la marca de Ironclad: la coherencia de la marca y el control de calidad se automatizan, asegurando que cada nueva página refleje perfectamente su sistema de diseño. Reducción de las pruebas A/B manuales y escalables: habilite a los equipos de marketing para escalar las variaciones de la página y los contenidos de prueba A/B sin involucrar a los desarrolladores en el proceso de diseño. Construido a escala global: Todos los elementos de texto y interfaz de usuario están centralizados, lo que hace que la localización y la adaptación al mercado sean suaves. Flexibilidad arquitectónica: diseñado para integrarse perfectamente en las modernas tuberías CI/CD, plataformas de alojamiento y otros flujos de trabajo impulsados por la IA. 1.4. tu mapa de ruta a través de esta serie En este tutorial te guiaremos a través de: Desconstruir la arquitectura del núcleo: una profunda inmersión en el PageHtmlTransformer, el sistema Wrapper/FullScreenWrapper y cómo interactúan los componentes de la sección. Comprender la lógica detrás de la renderización de secciones, la tipografía de configuración y la relación entre los archivos de configuración y los componentes de React, para que pueda extender el sistema usted mismo. Aprender a instruir la IA: Aprende a crear instrucciones estructuradas para metadatos, encabezados y pies, y define las especificaciones para generar contenido corporal como un fragmento de JSX. Generar páginas a demanda: Aplica tus conocimientos para crear los archivos de configuración que la IA utiliza para generar páginas que cumplan plenamente con tus estándares de arquitectura y diseño. La anatomía de nuestra arquitectura alimentada por IA Nuestro proyecto está organizado para maximizar la escalabilidad, el mantenimiento y la velocidad de desarrollo. Utilizamos las convenciones Next.js 15 App Router, incluyendo rutas paralelas ( ) y las carpetas privadas ( ), para crear una estructura limpia y poderosa. @right _folder Archivo del proyecto Tree app/@right/ ├── public/ │ ├── (_routing)/ │ │ └── [[...slug]]/ │ │ └── page.tsx # 1. Dynamic Catch-All Route Handler │ └── (_service)/ │ ├── (_config)/ │ │ └── public-pages-config.ts # 6. AI-Generated Page Configurations │ └── (_libs)/ │ └── utils.ts # 7. Configuration Utilities └── (_service)/ ├── (_types) │ └── page-wrapper-types.ts # 5. The TypeScript Data Contract (AI <-> UI) └── (_components)/ └── page-transformer-components/ ├── page-html-transformer.tsx # 2. The Core Page Transformer Engine ├── custom-sections/ # Directory for complex, interactive components ├── wrappers/ │ ├── full-screen-wrapper.tsx # 3. Immersive Full-Screen Wrapper │ └── wrapper.tsx # 4. Standard Content Section Wrapper ├── header-sections-components/ │ ├── header-section.tsx # 8. Standardized Header Component │ ├── page-header-elements.tsx # 9. Atomic Header Elements (H1/H2) │ └── announcement.tsx # 10. Announcement Banner Component ├── body-sections-components/ │ └── body-section.tsx # 12. Flexible Body Content Container └── footer-sections-components/ └── footer-section.tsx # 11. Standardized Footer Component Entrar en modo de pantalla completa Salir en modo de pantalla completa Caminos de componentes clave 1. @/app/@right/public/(_routing)/[[...slug]]/page.tsx 2. @/app/@right/(_service)/(_components)/page-transformer-components/page-html-transformer.tsx 3. @/app/@right/(_service)/(_components)/page-transformer-components/wrappers/full-screen-wrapper.tsx 4. @/app/@right/(_service)/(_components)/page-transformer-components/wrappers/wrapper.tsx 5. @/app/@right/(_service)/(_types)/page-wrapper-types.ts 6. @/app/@right/public/(_service)/(_config)/public-pages-config.ts 7. @/app/@right/public/(_service)/(_libs)/utils.ts 8. @/app/@right/(_service)/(_components)/page-transformer-components/header-sections-components/header-section.tsx 9. @/app/@right/(_service)/(_components)/page-transformer-components/header-sections-components/page-header-elements.tsx 10. @/app/@right/(_service)/(_components)/page-transformer-components/header-sections-components/announcement.tsx 11. @/app/@right/(_service)/(_components)/page-transformer-components/footer-sections-components/footer-section.tsx 12. @/app/@right/(_service)/(_components)/page-transformer-components/body-sections-components/body-section.tsx Entrar en modo de pantalla completa Salir en modo de pantalla completa El kit de herramientas de componentes clave: páginas listas para la producción fuera de la caja El propósito Esta colección incluye los pilares arquitectónicos de nuestro sistema: el enrutamiento dinámico, un motor de transformador central, envases de contenido versátiles, secciones unificadas de encabezados y pies, y los archivos de configuración y los contratos de datos que los impulsan. Principios arquitectónicos básicos: Consistencia de la interfaz de usuario: Cada componente se adhiere a un sistema de diseño unificado y patrones de comportamiento, garantizando una experiencia de usuario suave y predecible. AI-Native by Design: La arquitectura está optimizada para la generación autónoma, lo que permite a la IA construir páginas complejas sin intervención manual. SEO-Optimizado desde el principio: Las mejores prácticas para la optimización de motores de búsqueda y el HTML semántico se cocinan, no se boltan. Type-Safe & Predictable: Aprovechamos la tipografía estricta de TypeScript para hacer cumplir un contrato de datos confiable entre la IA y la interfaz de usuario, asegurando la estabilidad del sistema. Modular y Composable: Cada componente es una unidad autónoma que resuelve un problema específico, diseñado para la máxima reutilizabilidad y extensibilidad. Juntos, estos componentes forman la base del sistema, garantizando que cada página generada por IA no sólo sea visualmente coherente, sino también técnicamente robusta y preparada para la empresa. 2.1 El Componente: Universal Catch-All Route para URL dinámicos [[...slug]]/page.tsx 2.1.1.1 El valor estratégico de Catch-All Routes: Agilidad y velocidad de despliegue Una ruta catch-all es un patrón de enrutamiento dinámico en Next.js que permite que un componente de página única maneje un número infinito de segmentos de URL. La Convención, el El parámetro se convierte en una matriz que contiene cada parte del camino de URL, sin importar cuán profundamente se encuentre. [[...slug]] slug Desde una perspectiva empresarial, esta elección arquitectónica es una enorme ventaja competitiva. Un URL como /public/category/nike/sneakers/black/12345 es manejado por el mismo componente exactamente como /public/test. Esto desbloquea la capacidad de construir catálogos de productos, sitios de documentación o bibliotecas de contenido profundamente jerárquicos sin requerir cambios en la base de código. Navegación sin fricción y lanzamiento instantáneo de páginas: Despliegar una nueva página es tan sencillo como agregar su configuración a un archivo central. La página se transmite instantáneamente sin crear nuevos componentes ni navegar por un sistema de archivos complejo. Automatización integrada: Esta arquitectura es la base para un ecosistema de contenido totalmente automatizado. Se puede programar una barra lateral o menú generado automáticamente para leer las configuraciones de la página y construir la navegación de forma dinámica.Cuando se agrega una nueva configuración de la página, la navegación se actualiza automáticamente, asegurando una experiencia de usuario consistente con cero esfuerzo manual. 2.1.1.2.El valor de las URL dinámicas para los asistentes de IA: Escalabilidad de contenido infinita In today's competitive landscape, modern SaaS and AI platforms demand the agility to generate new pages on the fly. Whether initiated by a user, an administrator, or an autonomous AI agent, content must be architected for instant creation and deployment. Our catch-all routing architecture is the engine that drives this capability. Strategic Business Advantages: It removes all limitations on content structure and nesting depth, allowing your digital presence to scale infinitely without requiring code changes. Eliminates Architectural Constraints: Build complex content hierarchies for any use case. Navigation is driven purely by your business logic, not constrained by a rigid file system. This decouples your content strategy from engineering cycles, empowering product and marketing teams to execute faster. Unlocks Unmatched Agility: This architecture is designed for an AI-first world. It provides a stable foundation for AI agents to autonomously generate, configure, and deploy entire sections of your site, from product catalogs to knowledge bases. Enables AI-Powered Automation: 2.1.1.3 Casos de uso en el mundo real a escala Esta arquitectura no es teórica; es un modelo probado para el despliegue de estructuras de contenido de alto valor y profundamente ancladas que impulsan el crecimiento del negocio: Turnkey QR Menu Systems: Despliega una solución de etiqueta blanca para una franquicia nacional de restaurantes. Cada ubicación puede tener un menú único y profundamente categorizado (por ejemplo, /public/menu/dallas-tx/dinner/mains/pasta-dishes), todo manteniendo la perfecta consistencia de la marca y la integridad de UX. Launch extensive product lines with infinite variations instantly. A URL like becomes trivial to create and manage, enabling rapid market expansion and granular product organization. E-commerce Product Catalogs: /public/shop/apparel/mens/jackets/leather/fall-2025/black/sku-12345 Portales corporativos y educativos: Construya vastas bases de conocimientos o plataformas de tutoria donde el contenido pueda organizarse de forma lógica, sin importar lo profundo que la jerarquía tenga que ir (por ejemplo, /public/tutorials/enterprise-ai/onboarding/module-3/advanced-prompting). #### 2.1.1.4. En su núcleo, el proceso es elegantemente simple pero poderoso: traduce dinámicamente cualquier ruta de URL a una configuración de página correspondiente, que luego se renderiza en el vuelo. The component's primary tasks are: It captures the incoming URL path as an array of segments (e.g., ). Receive the URL: ["category", "nike", "sneakers"] The function proactively reads your file. It informs Next.js of all valid page routes defined in your configuration. For the business, this translates to comprehensive Static Site Generation (SSG), ensuring every page is pre-built for lightning-fast load times and optimal SEO. Generate Static Paths: generateStaticParams public-pages-config.ts export async function generateStaticParams() { const pages: PageConfig[] = getAllPublicPages(); return pages.map((page: PageConfig) => ({ slug: page.metadata.slug ? page.metadata.slug.slice(1) : [], })); } When a user requests a URL, the component receives the array. It then uses the utility to perform a high-speed lookup against the configuration array (prepending for an accurate match). If a match is found, the configuration is passed to our universal component for rendering. Fetch and Render: slug getPageBySlug "public" PageHtmlTransformer export default async function PublicDynamicSlugPage({ params }: Props) { const resolvedParams = await params; const slugArr = resolvedParams.slug ?? []; const pageConfig = getPageBySlug(["public", ...slugArr]); if (!pageConfig) { return Page not found; } return ; } Porque el Puede ser de cualquier longitud y la búsqueda es una combinación directa, este sistema proporciona profundidad de nicho infinita con cero riesgo de colisiones de ruta. slugArr 2.1.1.5. Key Functions and Their Business Impact generateStaticParams: impulsa el rendimiento y el SEO diciendo a Next.js cuál 2.1.1.7 El Componente: El motor de ejecución Este componente es el motor que trae a la vida nuestra arquitectura alimentada por la IA. Es un componente de servidor Next.js único y potente que actúa como un manipulador universal para cada página pública generada dinámicamente. Es responsable de obtener la configuración correcta de la página basada en la URL y orquestar el rendimiento final, asegurando tanto el rendimiento máximo como la conformidad SEO fuera de la caja. // @/app/@right/public/(_routing)/[[...slug]]/page.tsx import { PageHtmlTransformer } from "@/app/@right/(_service)/(_components)/page-transformer-components/page-html-transformer"; import { getPageBySlug } from "@/app/@right/(_service)/(_config)/pages-config"; import { constructMetadata } from "@/lib/construct-metadata"; import type { PageConfig } from "@/app/@right/(_service)/(_types)/page-wrapper-types"; import { getAllPublicPages } from "../../(_servise)/(_libs)/get-all-public-pages"; interface Props { params: Promise<{ slug?: string[] }>; } export async function generateStaticParams() { const pages: PageConfig[] = getAllPublicPages(); return pages.map((page: PageConfig) => ({ slug: page.metadata.slug || [], })); } export async function generateMetadata({ params }: Props) { const resolvedParams = await params; const slugArr = resolvedParams.slug ?? []; const pageConfig = getPageBySlug(["public", ...slugArr]); if (!pageConfig) return {}; return constructMetadata(pageConfig.metadata); } export default async function PublicDynamicSlugPage({ params }: Props) { const resolvedParams = await params; const slugArr = resolvedParams.slug ?? []; const publicPageConfig = getPageBySlug(["public", ...slugArr]); if (!publicPageConfig) { return <div>Page not found</div>; } return <PageHtmlTransformer data={publicPageConfig} />; } Entrar en modo de pantalla completa Salir en modo de pantalla completa La línea de fondo: Catch-All Routes como su motor de contenido de IA La combinación de todas las rutas de captura con una configuración de página centralizada crea una arquitectura que es lo más flexible, extensible y diseñada para la orquestación de contenido impulsada por la IA. Este enfoque es amigable tanto para los desarrolladores como para los agentes de IA, creando un flujo de trabajo suave desde el concepto hasta la implementación. The core principle is simple but transformative: No new code files, no complex folder structures. The navigation and rendering systems adapt automatically, making this the cornerstone of a truly agile and scalable AI-powered platform. A new page is just a new entry in a configuration file. FullScreenWrapper vs. Wrapper: Crafting experiencias inmersivas de pantalla completa 2.1.3.1. Core Purpose El is specifically engineered for sections that require an immersive, full-screen presentation with background video or image support. It serves as the foundational container for "hero" sections, where content is elegantly overlaid on top of rich media elements. FullScreenWrapper 2.1.3.2. Layered Architecture El componente utiliza una sofisticada estructura de capas para garantizar que el contenido permanezca legible y visualmente distinto del fondo. Technical Highlights: : Guarantees the section fills the entire viewport height, creating a captivating, full-bleed effect. min-h-screen Positioning: Enables precise control for stacking elements. relative z-index / ): Positioned with and to sit behind all other content. Background Elements ( video img absolute z-0 : Uses positioning with to ensure it always appears above the background. Content Container relative z-10 <section className="relative flex min-h-screen flex-col py-10 lg:py-14 bg-background"> {backgroundElement} // z-0 <div className="relative z-10 flex flex-col flex-1"> {children} // Header → Body → Footer </div> </section> Entrar en modo de pantalla completa Salir en modo de pantalla completa 2.1.3.3 Personalización y extensibilidad El está diseñado para una fácil personalización. Puede agregar efectos visuales complejos directamente a través del prop. FullScreenWrapper className <FullScreenWrapper className="bg-gradient-to-br from-blue-900 to-purple-900"> Enter fullscreen mode Exit fullscreen mode Control de opacidad: los videos de fondo reciben automáticamente una clase de opacidad-40 para mejorar la legibilidad del texto, pero esto puede ser superado fácilmente. Transiciones suaves: Una clase de transición de toda la duración-500 está integrada para garantizar cambios suaves en las propiedades de fondo. 2.1.3.4 Estilos avanzados y plantillas reutilizables Cuando se necesiten divisores de sección, límites, efectos de brillo o oscuras de fondo, el provides the ideal foundation for implementing these styles. This makes it perfect for creating highly stylized, reusable templates. FullScreenWrapper typescript <FullScreenWrapper className="border-t-4 border-gradient bg-blur-effect"> Enter fullscreen mode Exit fullscreen mode 2.1.3.5. The Component // @/app/@right/(_service)/(_components)/page-transformer-components/wrappers/full-screen-wrapper.tsx import React, { HTMLAttributes } from "react"; import { cn } from "@/lib/utils"; interface FullScreenWrapperProps extends HTMLAttributes<HTMLDivElement> { videoUrl?: string; imageUrl?: string; className?: string; children: React.ReactNode; } export function FullScreenWrapper({ videoUrl, imageUrl, className, children, ...props }: FullScreenWrapperProps) { let backgroundElement: React.ReactNode = null; if (videoUrl) { backgroundElement = ( <video className="absolute inset-0 size-full object-cover z-0 opacity-40 transition-all duration-500" autoPlay loop muted playsInline src={videoUrl} /> ); } else if (imageUrl) { backgroundElement = ( <img className="absolute inset-0 size-full object-cover z-0" src={imageUrl || "/placeholder.svg"} alt="Background" /> ); } return ( <section className={cn( "relative flex min-h-screen flex-col py-10 lg:py-14 bg-background", className )} {...props} > {backgroundElement} <div className="relative z-10 flex flex-col flex-1">{children}</div> </section> ); } Enter fullscreen mode Exit fullscreen mode 2.1.4. Wrapper: The Standard Sectional Container 2.1.4.1. Primary Use Case The Es el contenedor por defecto para la mayoría de las secciones de contenido y está diseñado para proporcionar el padding estándar, el centro de contenido y un diseño consistente y predecible para los bloques de información. Wrapper 2.1.4.2 Estructura y estilo typescript <section className="py-10 lg:py-14 bg-background"> <div className="container mx-auto px-4"> {children} // Header → Body → Footer </div> </section> Entrar en modo de pantalla completa Salir en modo de pantalla completa La estructura del componente es simple y optimizada para el rendimiento, basándose en algunas clases clave de CSS de Tailwind: : Applies responsive vertical padding for consistent spacing across devices. py-10 lg:py-14 Contenedor mx-auto px-4: Crea un contenedor centrado, de ancho máximo con plegado horizontal, asegurando que el contenido esté bien alineado y legible. : Utilizes the current theme's CSS variable for the background color, ensuring seamless integration with light/dark modes. bg-background 2.1.4.3. Customization Points While minimalist by design, the is a flexible foundation for custom styling via the prop. It's the perfect base for adding: Wrapper className Custom background colors or gradient effects. Borders or dividers between sections. Subtle visual enhancements like blur or glow effects. 2.1.4.4. Building Reusable Templates typescript // Пример для pricing-секций <Wrapper className="bg-gradient-to-br from-green-50 to-green-100 border-2 border-green-200"> <HeaderSection /> <PricingTable /> <FooterSection /> </Wrapper> Enter fullscreen mode Exit fullscreen mode When your design calls for a template with unique styling but a standard, centered content structure, is the ideal choice. It provides the structural backbone, allowing you to focus on the specific styles of the template. Wrapper 2.1.4.5. The Component // app/@right/(_service)/(_components)/page-transformer-components/wrappers/wrapper.tsx import React, { HTMLAttributes } from "react"; import { cn } from "@/lib/utils"; interface WrapperProps extends HTMLAttributes<HTMLDivElement> { className?: string; children: React.ReactNode; } export function Wrapper({ className, children, ...props }: WrapperProps) { return ( <section className={cn("py-10 lg:py-14 bg-background", className)} {...props} > <div className="container mx-auto px-4">{children}</div> </section> ); } Entrar en modo de pantalla completa Salir en modo de pantalla completa 2.1.5. page-wrapper-types.ts: El contrato AI-to-UI TypeScript 2.1.5.1. The Core Contract: Bridging AI Generation and UI Rendering The file establishes a formal, strictly-typed contract between our AI content generator and the UI rendering system. This contract is fundamental to our architecture, defining the structure of all possible page components and the rules governing their interactions to ensure seamless integration and predictability. page-wrapper-types.ts 2.1.5.2. SectionType Categorías y generación impulsada por la IA El modelo operativo de la IA se centra en En primer lugar, la IA analiza los tipos de secciones disponibles definidos dentro de esta enum. Luego, en base a la solicitud del usuario, selecciona estratégicamente qué secciones se deben montar para una página dada. Para facilitar la generación de contenido totalmente autónoma y de alta calidad, la base de conocimiento de la IA debe estar llena de instrucciones completas y ejemplos diversos para cada uno de los 25 tipos de secciones. SectionType typescript export type SectionType = | "hero-section" | "cta-section" | "faq-section" | "features-section" | "testimonials-section" | "pricing-section" Enter fullscreen mode Exit fullscreen mode 2.1.5.3. SEO Optimization and Metadata The interface ensures the standards-compliant generation of meta tags, which is critical for search engine optimization (SEO). Meta tags are generated automatically via the function. This function retrieves data from the page configuration and passes it to the utility, which in turn constructs well-formed HTML headers. PageMetadata generateMetadata() constructMetadata() typescript export interface PageMetadata { id: string; // Уникальный идентификатор title: string; // <title> тег для SEO description: string; // <meta description> для сниппетов image?: string; // Open Graph изображение slug?: string[]; // URL-структура страницы type: SectionType; // Тип основной секции } Enter fullscreen mode Exit fullscreen mode 2.1.5.4. HeaderContentConfig: Gestionar la jerarquía de SEO Managing the heading hierarchy is critical for on-page SEO. The section is optional. This is an intentional design choice because certain section types may embed / Los días directos dentro de su Si bien esto proporciona flexibilidad, introduce un riesgo potencial para la consistencia de la interfaz de usuario, que es un objetivo primario de esta arquitectura. A note of caution: Header H1 H2 bodyContent typescript interface HeaderContentConfig { heading: string; headingLevel?: 1 | 2; // H1/H2 для поисковой иерархии description?: string; showBorder?: boolean; } Entrar en modo de pantalla completa Salir en modo de pantalla completa 2.1.5.5 BodySection: Permite la máxima libertad de diseño typescript bodyContent?: React.ReactNode; Entrar en modo de pantalla completa Salir en modo de pantalla completa By design, the body of a section is granted complete freedom to implement any layout or design. This architectural choice allows for maximum creative flexibility, enabling the AI to generate rich and varied content. This approach deliberately contrasts with the and , which are standardized to maintain a consistent look and feel across the entire application. Header Footer typescript interface FooterContentConfig { actions?: { label: string; href: string; variant?: "default" | "secondary" | "outline" | "ghost" | "link"; }[]; } Enter fullscreen mode Exit fullscreen mode 2.1.5.6. FooterContentConfig: A Minimalist Approach La implementación actual del footer es intencionalmente minimalista. sólo admite botones de llamada a acción opcionales. No se incluyen elementos adicionales, una decisión tomada para priorizar la simplicidad, la velocidad y la uniformidad en todas las páginas generadas. 2.1.5.7. Principles for Extending Type Definitions Para introducir una nueva , deben tomarse los siguientes pasos: SectionType The AI's knowledge base must be updated with comprehensive instructions and examples for the new section type. Update AI Knowledge: The new type must be added to the enum. Extend Enum: SectionType If the new section requires unique configuration parameters, the corresponding configuration interface must be extended. Expand Interfaces: Este proceso atraviesa un crucial equilibrio arquitectónico: el y are strictly typed to enforce SEO best practices and UI consistency, while the offers maximum flexibility for innovative, AI-driven design solutions. Header Footer Body 2.1.5.8. Component // app/@right/(_service)/(_types)/page-wrapper-types.ts export interface MetadataConfig { title?: string; description?: string; } export interface PageMetadata { id: string; title: string; description: string; image?: string; slug?: string[]; type: SectionType; } export type SectionType = | "hero-section" | "cta-section" | "faq-section" | "features-section" | "testimonials-section" | "pricing-section" | "contact-section" | "blog-posts-section" | "product-grid-section" | "image-gallery-section" | "text-block-section" | "video-section" | "team-section" | "about-us-section" | "newsletter-section" | "social-proof-section" | "comparison-table-section" | "map-section" | "custom-html-section" | "changelog-section" | "comparison-two-column-section" | "comparison-three-column-section" | "feature-showcase-section"; export interface BaseSection { id: string; type: SectionType; className?: string; } export interface HeaderContentConfig { announcement?: { badgeText?: string; descriptionText?: string; href?: string; }; heading: string; headingLevel?: 1 | 2; description?: string; showBorder?: boolean; } export interface FooterContentConfig { actions?: { label: string; href: string; variant?: | "default" | "secondary" | "destructive" | "outline" | "ghost" | "link"; }[]; } export interface SectionConfig extends BaseSection { type: SectionType; headerContent: HeaderContentConfig; bodyContent?: React.ReactNode; footerContent?: FooterContentConfig; videoUrl?: string; imageUrl?: string; sectionClassName?: string; contentWrapperClassName?: string; customComponentsAnyTypeData?: any; } export type Section = SectionConfig; export interface PageConfig { metadata: PageMetadata; sections: Section[]; } export type SlugType = string[]; Enter fullscreen mode Exit fullscreen mode 2.1.5.9. customComponentsAnyTypeData: Soporte para componentes personalizados arbitrarios The field within serves as a powerful "escape hatch." It is designed for passing unstructured data to sections that leverage complex or unique custom components that do not conform to our standard interfaces. customComponentsAnyTypeData?: any; SectionConfig To maintain architectural integrity, the type and structure of this data must be rigorously defined and documented . This design choice provides the necessary flexibility to integrate highly interactive, dynamic, and advanced user-facing sections without compromising the core typing contract of the main page architecture. within the custom component itself 2.1.6. public-pages-config.ts: The Public Page and Slug Route Registry 2.1.6.1. Role in System Architecture El file is an AI-generated registry of all public-facing pages within the application. This configuration is automatically generated by our AI based on system instructions and user prompts. Its structure is directly influenced by the available components in our knowledge base examples and the enumerations within the definitions. public-pages-config.ts SectionType La configuración resultante actúa como un puente, traduciendo el análisis de los requisitos de los usuarios de la IA en una estructura que nuestro sistema de renderización de páginas puede interpretar y mostrar. 2.1.6.2. When to Use This File-Based Configuration This approach is ideal for: Proyectos con un número limitado de páginas (típicamente 10-15). Websites with static content that requires infrequent updates. Prototipos rápidos y productos mínimos viables (MVPs), permitiendo un inicio rápido sin instalación de base de datos. Landing pages with a fixed, predefined structure. When to Transition to a Database: For large-scale production applications, a file-based approach is only practical for a small set of pages. Most scenarios will benefit from storing this information in a database to enable dynamic content management and scalability. 2.1.6.3. Configuration Structure typescript export const PublicPagesConfig = { pages: [ { metadata: { id: "public", title: "Enterprise-Grade AI Next.js starter", description: "Free Open-Source starter kit...", slug: ["public", "test"], type: "hero-section", }, sections: [ { id: "test-block", type: "hero-section", headerContent: { /* SEO-заголовки */ }, bodyContent: {}, footerContent: { /* Кнопки действий */ }, videoUrl: "/_static/video/ai-loop.mp4", contentWrapperClassName: "text-white", } as SectionConfig, ], }, ] as PageConfig[], }; Enter fullscreen mode Exit fullscreen mode 2.1.6.4. Configuration Categorization Principle Placing the configuration file in the directory signifies its role in managing public-facing pages. Key Architectural Decision: public/(_service)/(_config)/ Scaling by Category: Nuestra arquitectura soporta la escalación mediante la categorización de configuraciones, asegurando una estructura limpia y organizada: public-pages-config.ts - para páginas públicas (por ejemplo, aterrizaje, sobre, contacto). — for documentation sites with advanced navigation. docs-pages-config.ts — for administrative dashboards. admin-pages-config.ts blog-pages-config.ts – para publicaciones de blogs y artículos. Each category is designed to have its own: Dedicated configuration file. Tipos de Secciones Especializadas. Unique rendering logic. 2.1.6.5 Interacción con el sistema de generación de IA Para nuestro sistema de IA, este archivo de configuración sirve como: Modelo estructural: Define cómo se deben formar los objetos de PageConfig. Ejemplo de datos: Proporcionar valores de referencia para el proceso de generación. Un esquema de validación de tipo: Impuesto por TypeScript para la seguridad de tipo estricta. The workflow is as follows: The AI analyzes the existing configuration file. It generates a new object based on the user's prompt. PageConfig A developer then adds the new configuration to the array. pages El sistema reconoce y registra automáticamente las nuevas rutas. 2.1.6 Ventajas y limitaciones Advantages of the File-Based Approach: Control de versiones: fácil de administrar y versionar a través de Git. Seguridad de tipo: Beneficios de la seguridad de tipo de compilación con TypeScript. No database queries result in faster page loads. Zero Latency: Works seamlessly with static site generation (SSG). Simplified Deployment: Limitations: No hay actualizaciones dinámicas: carece de capacidades de gestión de contenido dinámico. Any change necessitates a new build and deployment. Requires Redeployment: No para UGC: No adecuado para contenido generado por el usuario. Preocupaciones de escalabilidad: Se vuelve difícil gestionar más allá de 20-30 páginas. 2.1.6 Componentes // @/app/@right/public/(_servise)/(_config)/public-pages-config.ts import { PageConfig, SectionConfig, } from "@/app/@right/(_service)/(_types)/page-wrapper-types"; export const PublicPagesConfig = { pages: [ { metadata: { id: "public", title: "Enterprise-Grade AI Next.js starter", description: "Free Open-Source starter kit...", slug: ["public", "test"], type: "hero-section", }, sections: [ { id: "test-block", type: "hero-section", headerContent: { announcement: { badgeText: "Thanks", descriptionText: "AI-SDK V5 & Vercel AI", href: "https://github.com/aifa-agi/aifa", }, heading: "Enterprise-Grade AI Next.js starter", description: "Free Open-Source starter kit to build, deploy, and scale intelligent AI applications. Artifacts Feature, features secure multi-provider auth, Stripe payments, vector knowledge bases, deep-research agents, and a unique fractal architecture designed for the future of AI.", showBorder: false, headingLevel: 1, }, bodyContent: {}, footerContent: { actions: [ { label: "Get Started", href: "/https://github.com/aifa-agi/aifa", variant: "default", }, { label: "Browse Docs", href: "/docs", variant: "ghost" }, ], }, videoUrl: "/_static/video/ai-loop.mp4", contentWrapperClassName: "text-white", } as SectionConfig, ], }, ] as PageConfig[], }; Entrar en modo de pantalla completa Salir en modo de pantalla completa 2.1.6 Conclusión is a practical solution for small to medium-sized projects, offering a balance between ease of management and functionality. For larger-scale applications, it serves as an excellent starting point before transitioning to a more robust, database-driven architecture. public-pages-config.ts 2.1.7. utils.ts: Funciones de utilidad de configuración This module provides utility functions for managing page configurations. It includes two primary functions: , que filtra todas las páginas con el prefixo "público" para la generación estática, y , que localiza una página específica por una coincidencia exacta, sensible al caso de su array de escamas. getAllPublicPages() getPageBySlug() // @app/@right/public/(_servise)/(_libs)/utils.ts import { PageConfig, SlugType, } from "@/app/@right/(_service)/(_types)/page-wrapper-types"; import { PublicPagesConfig } from "../(_config)/public-pages-config"; export function getAllPublicPages(): PageConfig[] { return PublicPagesConfig.pages.filter( (page: PageConfig) => page.metadata.slug?.[0] === "public" ); } export function getPageBySlug(slug: SlugType): PageConfig | undefined { return PublicPagesConfig.pages.find( (page: PageConfig) => JSON.stringify( page.metadata.slug?.map((s: string) => s.toLowerCase()) ) === JSON.stringify(slug.map((s: string) => s.toLowerCase())) ); } Entrar en modo de pantalla completa Salir en modo de pantalla completa 2.1.8. header-section.tsx: Header de Sección Unificado This standardized component serves as a universal header for all section types, ensuring consistency across the application. It offers optional elements such as an announcement, an H1/H2 heading, and a description. This component plays a crucial role in SEO optimization and maintaining visual consistency for AI-generated pages. // @/app/@right/(_service)/(_components)/page-transformer-components/header-sections-components/header-section.tsx import React from "react"; import { cn } from "@/lib/utils"; import { PageHeaderDescription, PageHeaderHeading, } from "./page-header-elements"; import { Announcement } from "./announcement"; import { HeaderContentConfig } from "../../../(_types)/page-wrapper-types"; export type HeaderSectionProps = { headerContent: HeaderContentConfig; } & React.HTMLAttributes<HTMLDivElement>; export function HeaderSection({ headerContent, className, ...props }: HeaderSectionProps) { if (!headerContent) return null; const { announcement, heading, headingLevel = 1, description, showBorder = false, } = headerContent; return ( <section className={cn( showBorder && "border-t-4 border-b-4 border-primary", className )} {...props} > <div className="container mx-auto px-4"> <div className="flex flex-col items-center gap-1 py-8 md:py-10 lg:py-12"> {announcement && ( <Announcement badgeText={announcement.badgeText} descriptionText={announcement.descriptionText} href={announcement.href} /> )} <PageHeaderHeading level={headingLevel}>{heading}</PageHeaderHeading> {description && ( <PageHeaderDescription>{description}</PageHeaderDescription> )} </div> </div> </section> ); } Entrar en modo de pantalla completa Salir en modo de pantalla completa 2.1.9. header-section.tsx: Capítulo de sección unificado (Componentes atómicos) Esta sección detalla los componentes atómicos utilizados para construir cabezas: (con el soporte de H1 y H2), para las subdivisiones, y for placing buttons. These components leverage para la generación dinámica de etiquetas HTML, asegurando la jerarquía correcta de SEO. PageHeaderHeading PageHeaderDescription PageActions createElement // @app/@right/(_service)/(_components)/page-transformer-components/header-sections-components/page-header-elements.tsx import { HTMLAttributes, createElement } from "react"; import { cn } from "@/lib/utils"; type HeadingTag = "h1" | "h2"; interface PageHeaderHeadingProps extends HTMLAttributes<HTMLHeadingElement> { level?: 1 | 2; } function PageHeaderHeading({ className, level = 1, ...props }: PageHeaderHeadingProps) { const Heading: HeadingTag = level === 1 ? "h1" : "h2"; const h1Classes = "text-2xl sm:text-3xl md:text-6xl lg:text-7xl"; const h2Classes = "text-lg sm:text-xl md:text-3xl lg:text-4xl"; return createElement(Heading, { className: cn( "text-center font-bold leading-tight tracking-tighter font-serif", level === 1 ? h1Classes : h2Classes, className ), ...props, }); } function PageHeaderDescription({ className, ...props }: HTMLAttributes<HTMLParagraphElement>) { return ( <p className={cn( "max-w-2xl text-balance text-center text-base font-light text-muted-foreground sm:text-lg", className )} {...props} /> ); } function PageActions({ className, ...props }: HTMLAttributes<HTMLDivElement>) { return ( <div className={cn( "flex w-full items-center justify-center gap-2 pt-2", className )} {...props} /> ); } export { PageActions, PageHeaderDescription, PageHeaderHeading }; Entrar en modo de pantalla completa Salir en modo de pantalla completa 2.1.10. announcement.tsx: Announcement Component Este componente de badge interactivo está diseñado para anuncios y notificaciones. Soporta la navegación, el control de teclado y el rendimiento condicional, ocultando automáticamente cuando no hay contenido. Se utiliza para llamar la atención a actualizaciones o enlaces importantes. // @app/@right/(_service)/(_components)/page-transformer-components/header-sections-components/announcement.tsx "use client"; import { useRouter } from "next/navigation"; import { Badge } from "@/components/ui/badge"; import { ArrowRight } from "lucide-react"; import { cn } from "@/lib/utils"; interface AnnouncementProps { badgeText?: string; descriptionText?: string; href?: string; className?: string; } export function Announcement({ badgeText, descriptionText, href, className, }: AnnouncementProps) { const router = useRouter(); const handleOnClick = () => { if (href) { router.push(href); } }; // Если нет текста для бейджа, описания или ссылки, возвращаем null if (!badgeText && !descriptionText && !href) { return null; } return ( <div className={cn( "flex cursor-pointer items-center gap-2 rounded-full border border-primary bg-muted px-3 py-1 text-sm transition-colors hover:bg-muted/80", className )} onClick={handleOnClick} role="link" tabIndex={0} onKeyDown={(e) => { if (e.key === "Enter" || e.key === " ") { handleOnClick(); } }} > {badgeText && ( <Badge variant="secondary" className="text-xs"> {badgeText} </Badge> )} {descriptionText && ( <span className="text-muted-foreground">{descriptionText}</span> )} {href && <ArrowRight className=" h-3 w-3 text-muted-foreground" />} </div> ); } Enter fullscreen mode Exit fullscreen mode 2.1.11. footer-section.tsx: Unified Section Actions Este componente de pie estándar incluye botones de acción. Soporta múltiples botones con varias opciones de estilo, asegurando la uniformidad de los elementos de Call-to-Action (CTA) en todas las secciones. Se oculta automáticamente cuando no se definen acciones. // @app/@right/(_service)/(_components)/page-transformer-components/footer-sections-components/footer-section.tsx "use client"; import { useRouter } from "next/navigation"; import type { HTMLAttributes } from "react"; import { cn } from "@/lib/utils"; import { Button } from "@/components/ui/button"; import { PageActions } from "../header-sections-components/page-header-elements"; interface FooterAction { label: string; href: string; variant?: | "default" | "secondary" | "destructive" | "outline" | "ghost" | "link"; } interface FooterSectionProps extends HTMLAttributes<HTMLDivElement> { actions?: FooterAction[]; } export function FooterSection({ actions, className, ...props }: FooterSectionProps) { const router = useRouter(); if (!actions || actions.length === 0) { return null; } return ( <section className={cn("py-4 md:py-6 lg:py-8", className)} {...props}> <div className="container mx-auto px-4"> <PageActions> {actions.map((action) => ( <Button key={action.href} // href должен быть уникальным! size="sm" variant={action.variant || "default"} onClick={() => router.push(action.href)} > {action.label} </Button> ))} </PageActions> </div> </section> ); } Entrar en modo de pantalla completa Salir en modo de pantalla completa 2.1.12. body-section.tsx: Contenedor de contenido arbitrario 2.1 Objetivo y filosofía serves as a highly flexible container for the main content within sections. Unlike the strictly standardized Header and Footer components, Ofrece total libertad para colocar cualquier contenido de React. BodySection BodySection 2.1.12.2 Principios de generación de contenido Contenido para must be generated as plain TSX without using elementos, donde todos los elementos se presentan en un formato expandido. Crucially: bodyContent .map() typescript // ✅ bodyContent: ( <> <div className="grid grid-cols-1 md:grid-cols-3 gap-6"> <div className="feature-card"> <h3>Feature 1</h3> <p>Description 1</p> </div> <div className="feature-card"> <h3>Feature 2</h3> <p>Description 2</p> </div> <div className="feature-card"> <h3>Feature 3</h3> <p>Description 3</p> </div> </div> </> ) Enter fullscreen mode Exit fullscreen mode // ❌ bodyContent: ( <div className="grid"> {features.map(feature => <FeatureCard key={feature.id} {...feature} />)} </div> ) Entrar en modo de pantalla completa Salir en modo de pantalla completa 2.1.12.3 Cuándo utilizar los componentes personalizados Si una sección requiere lógica compleja (estado, efectos, interactividad), crea un componente independiente y lo agrega a as a separate entity. PageHtmlTransformer typescript // @/app/@right/(_service)/(_components)/page-transformer-components/body-sections-components/body-section.tsx export function BodySection({ children, className, ...props }: BodySectionProps) { const hasChildren = children !== null && children !== undefined && !(Array.isArray(children) && children.length === 0) && !(typeof children === "string" && children === ""); if (!hasChildren) return null; return ( <div className={cn(className)} {...props}> {children} </div> ); } Entrar en modo de pantalla completa Salir en modo de pantalla completa 2.1.12.4 Los componentes // @app/@right/(_service)/(_components)/page-transformer-components/body-sections-components/body-section.tsx import type { HTMLAttributes, ReactNode } from "react"; import { cn } from "@/lib/utils"; import { SectionType } from "../../../(_types)/page-wrapper-types"; interface BodySectionProps extends HTMLAttributes<HTMLDivElement> { children?: ReactNode | null; type: SectionType; } export function BodySection({ children, className, ...props }: BodySectionProps) { const defaultHeightRem = 0; const hasChildren = children !== null && children !== undefined && // Covers case when children = [] or "" !(Array.isArray(children) && children.length === 0) && !(typeof children === "string" && children === ""); if (!hasChildren && defaultHeightRem) { return ( <div className={cn(className)} style={{ height: `${defaultHeightRem}rem` }} {...props} > {/* Empty section with default height */} </div> ); } if (!hasChildren) { return null; } return ( <div className={cn(className)} {...props}> {children} </div> ); } Enter fullscreen mode Exit fullscreen mode 2.1.12.5 Conclusiones acts as a bridge between the system's standardized architecture and the creative freedom of AI generation, striking a balance between control and flexibility. BodySection 2.2 Componentes personalizados avanzados Los componentes personalizados avanzados están diseñados para ofrecer funcionalidades complejas e interactivas que van más allá de las capacidades de nuestros patrones arquitectónicos estándar.Estos componentes están reservados para escenarios que requieren gestión de estado, animaciones sofisticadas, manejo de datos en tiempo real o lógica empresarial única. Cuando utilizar los componentes personalizados: Elementos interactivos: Formularios con validación, calculadoras, configuradores de productos. Presentaciones animadas: transiciones complejas, efectos de paralaje, deslizamientos automáticos. Funcionalidad en tiempo real: chats, notificaciones, feeds de datos en vivo. Lógica adaptativa: Componentes con comportamiento fundamentalmente diferente en escritorio vs. móvil. Modelos de interfaz de usuario únicos: elementos de interfaz no estándar específicos para el proyecto. Architectural Integration: Custom components are integrated into the como distintivo Declaraciones dentro de la Este enfoque les permite acceder a contextos de todo el sistema, como el tema y la información del dispositivo, mientras mantienen un aspecto y una sensación consistentes a través de clases compartidas de CSS y tokens de diseño.Aunque se adhieren al lenguaje visual del sistema, mantienen completa libertad en su lógica interna y implementación.Esta estrategia proporciona un equilibrio entre estandarizar la mayoría del contenido y permitir la libertad creativa en la implementación de elementos interactivos complejos. PageHtmlTransformer case switch 2.2.1 Directrices para la implementación de componentes personalizados 2.2.1.1 La política de engranajes : Custom components must be returned directly without being enclosed in o Son responsables de administrar su propio diseño, colocación y capaje para garantizar el control total sobre su presentación. No External Wrappers Wrapper FullScreenWrapper 2.2.1.2. Component-Scoped Typing : The prop interfaces for a custom component should be declared at the top of the component file itself. All data is passed from the page configuration into the component via the en la sección Config. Local Prop Interfaces customComponentsAnyTypeData 2.2.1.3. Extending SectionType Secciones : Cada componente personalizado requiere que se añada un tipo único a la Enum en Esto garantiza una correcta verificación de tipo y permite declaración en el transformador para identificar y renderizar correctamente el componente. Add a New Section Type SectionType page-wrapper-types.ts switch typescript // @/app/@right/(_service)/(_types)/page-wrapper-types.ts // ... export type SectionType ="hero-section" | “new-custom-section”; Entrar en modo de pantalla completa Salir en modo de pantalla completa 2.2.1.4. casos de actualización en el ageHtmlTransformer Procesamiento de casos personalizadosUn nuevo caso se añade al PageHtmlTransformer para manejar un tipo de sección personalizado con un // В PageHtmlTransformer: case "new-custom-section": return ( <NewCustomSection key={config.id} customData={section.customComponentsAnyTypeData.customData} /> ); Entrar en modo de pantalla completa Salir en modo de pantalla completa 2.2.1.5 Estructura de configuración personalizada : A continuación se muestra un ejemplo de una configuración de página que incluye una sección personalizada. Todos los datos específicos de componentes se colocan en el objeto, que puede tener cualquier estructura requerida por el componente. Configuration Structure customComponentsAnyTypeData export const PublicPagesConfig = { pages: [ { metadata: { id: "CIUD", title: "1", description: "2", slug: ["public", "name"], type: "new-custom-section", }, sections: [ { id: "new-custom-section", type: "new-custom-section", customComponentsAnyTypeData: { metaData: { metaTitle: "1", metaDescription: "2", }, customData: { mediaUrl: "/_static/illustrations/3.png", title: "4", description: "5", }, }, } as SectionConfig, ], }, ] as PageConfig[], Entrar en modo de pantalla completa Salir en modo de pantalla completa 2.2.2. Custom Component Example El 2.2.1 DoublePresentation Doble Presentación y 2.2.2.1.1 Actualizar tipos de núcleos Primero, agregue el nuevo tipo de sección al y enum. SectionType typescript // @/app/@right/(_service)/(_types)/page-wrapper-types.ts export type SectionType = | "hero-section" | "cta-section" | "double-presentation-section" Entrar en modo de pantalla completa Salir en modo de pantalla completa 2.2.2.1.2 Añadir un nuevo caso a Página de Transformación Página de Transformación A continuación, agregue el correspondiente Para el para formar el componente. case PageHtmlTransformer case "double-presentation-section": return ( <DoublePresentation key={section.id} metaData={section.customComponentsAnyTypeData.metaData} leftItem={section.customComponentsAnyTypeData.leftItem} rightItem={section.customComponentsAnyTypeData.rightItem} /> ); Entrar en modo de pantalla completa Salir en modo de pantalla completa 2.2.2.1.4. Config Example Aquí hay un ejemplo de cómo configurar el Componentes en . DoublePresentation public-pages-config.ts // app/@right/(_service)/(_types)/page-wrapper-types.ts export interface MetadataConfig { title?: string; description?: string; } export type CuidString = string; export interface PageMetadata { id: CuidString; title: string; description: string; image?: string; slug?: string[]; type: SectionType; } export type SectionType = | "hero-section" | "cta-section" | "faq-section" | "features-section" | "testimonials-section" | "pricing-section" | "contact-section" | "blog-posts-section" | "product-grid-section" | "image-gallery-section" | "text-block-section" | "video-section" | "team-section" | "about-us-section" | "newsletter-section" | "social-proof-section" | "comparison-table-section" | "map-section" | "custom-html-section" | "changelog-section" | "comparison-two-column-section" | "comparison-three-column-section" | "feature-showcase-section" | "double-presentation-section"; export interface BaseSection { id: string; type: SectionType; className?: string; } export interface HeaderContentConfig { announcement?: { badgeText?: string; descriptionText?: string; href?: string; }; heading: string; headingLevel?: 1 | 2; description?: string; showBorder?: boolean; } export interface FooterContentConfig { actions?: { label: string; href: string; variant?: | "default" | "secondary" | "destructive" | "outline" | "ghost" | "link"; }[]; } export interface SectionConfig extends BaseSection { type: SectionType; headerContent: HeaderContentConfig; bodyContent?: React.ReactNode; footerContent?: FooterContentConfig; videoUrl?: string; imageUrl?: string; sectionClassName?: string; contentWrapperClassName?: string; customComponentsAnyTypeData?: any; } export type Section = SectionConfig; export interface PageConfig { metadata: PageMetadata; sections: Section[]; } export type SlugType = string[]; Entrar en modo de pantalla completa Salir en modo de pantalla completa 2.2 Componentes El código completo para el El componente . DoublePresentation // @/app/@right/public/(_servise)/(_config)/public-pages-config.ts import { PageConfig, SectionConfig, } from "@/app/@right/(_service)/(_types)/page-wrapper-types"; export const PublicPagesConfig = { pages: [ { metadata: { id: "public", title: "Enterprise-Grade AI Next.js starter", description: "Free Open-Source starter kit...", slug: ["public", "test"], type: "hero-section", }, sections: [ { id: "test-block", type: "hero-section", headerContent: { announcement: { badgeText: "Thanks", descriptionText: "AI-SDK V5 & Vercel AI", href: "https://github.com/aifa-agi/aifa", }, heading: "Enterprise-Grade AI Next.js starter", description: "Free Open-Source starter kit to build, deploy, and scale intelligent AI applications. Artifacts Feature, features secure multi-provider auth, Stripe payments, vector knowledge bases, deep-research agents, and a unique fractal architecture designed for the future of AI.", showBorder: false, headingLevel: 1, }, bodyContent: {}, footerContent: { actions: [ { label: "Get Started", href: "/https://github.com/aifa-agi/aifa", variant: "default", }, { label: "Browse Docs", href: "/docs", variant: "ghost" }, ], }, videoUrl: "/_static/video/ai-loop.mp4", contentWrapperClassName: "text-white", } as SectionConfig, ], }, { metadata: { id: "interactive-ai", title: "Interactive AI Demo", description: "Demo: DoublePresentation custom case", slug: ["public", "example"], type: "double-presentation-section", }, sections: [ { id: "double-presentation-demo", type: "double-presentation-section", customComponentsAnyTypeData: { metaData: { metaTitle: "Interactive AI: Where Conversation Builds the UI", metaDescription: "Discover what makes AIFA revolutionary...", }, leftItem: { mediaUrl: "/_static/illustrations/ai-chat.png", title: "Ai Artifacts Chatbot", description: "As the AI chatbot speaks, it highlights elements...", }, rightItem: { mediaUrl: "/_static/illustrations/ai-web.png", title: "Related Pages", description: "Click any UI element, and the AI provides instant context...", }, }, } as SectionConfig, ], }, ] as PageConfig[], }; Entrar en modo de pantalla completa Salir en modo de pantalla completa 2.2.2 El 1.3. Página de Tipos.es Página de Tipos.es Here is the complete archivo con el nuevo tipo incluido. page-wrapper-types.ts // @/app/@right/(_service)/(_components)/page-transformer-components/custom-sections/custom-double-prsentation.tsx "use client"; import React, { useState, useEffect } from "react"; import { motion } from "framer-motion"; import Image from "next/image"; import { cn } from "@/lib/utils"; import { useMediaQuery } from "@/hooks/use-media-query"; interface PresentationMeta { metaTitle: string; metaDescription: string; } interface PresentationItem { mediaUrl: string; title: string; description: string; } interface DoublePresentationProps { metaData: PresentationMeta; leftItem: PresentationItem; rightItem: PresentationItem; } export default function DoublePresentation({ metaData, leftItem, rightItem, }: DoublePresentationProps) { const { isMobile } = useMediaQuery(); // Desktop animation state const [activeContainer, setActiveContainer] = useState<"left" | "right">( "left" ); const [sliderKey, setSliderKey] = useState(0); // Desktop auto-switching effect useEffect(() => { // Only run animation cycle on desktop if (isMobile) return; let sliderTimer: NodeJS.Timeout; let transitionTimer: NodeJS.Timeout; const startAnimationCycle = () => { setSliderKey((prev) => prev + 1); sliderTimer = setTimeout(() => { setActiveContainer((prev) => (prev === "left" ? "right" : "left")); transitionTimer = setTimeout(() => { startAnimationCycle(); }, 500); }, 9000); }; startAnimationCycle(); return () => { clearTimeout(sliderTimer); clearTimeout(transitionTimer); }; }, [isMobile]); // Return null while determining screen size if (isMobile === null) { return null; } // Common CSS classes const metaBlockClass = "text-center max-w-3xl flex flex-col items-center"; const descriptionClass = "mb-12 max-w-xl text-base text-muted-foreground text-center"; const desktopTitleClass = "mb-6 max-w-3xl font-serif font-bold leading-tight md:text-2xl lg:text-4xl"; const desktopDescriptionClass = "mb-12 max-w-xl text-lg text-muted-foreground md:text-xl text-center"; // Mobile card renderer const renderMobileCard = (item: PresentationItem) => ( <div className="relative flex flex-col rounded-xl bg-gray-900 text-white shadow-lg mb-6 overflow-hidden"> <div className="w-full relative" style={{ paddingTop: "56.25%" }}> <Image src={item.mediaUrl} alt={item.title} fill className="object-cover rounded-t-xl" sizes="100vw" priority /> </div> <div className="flex flex-col p-4"> <h2 className="text-xl font-bold mb-2">{item.title}</h2> <p className="text-gray-300 mb-2 text-base min-h-16"> {item.description} </p> </div> </div> ); // Desktop card renderer const renderDesktopCard = (item: PresentationItem, isActive: boolean) => ( <motion.div layout animate={{ flex: isActive ? "7 1 0%" : "3 1 0%" }} transition={{ duration: 0.5 }} className="relative flex flex-col rounded-lg overflow-hidden bg-transparent text-white p-0 shadow-lg h-[30rem] flex-shrink-0" > <div className="relative w-full h-60 mb-4 rounded-xl overflow-hidden border-4 border-gray-700"> <Image src={item.mediaUrl} alt={item.title} fill className="object-cover" priority sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw" /> </div> <div className="flex flex-col pt-6"> <h2 className="text-2xl font-bold mb-2 whitespace-nowrap overflow-hidden text-ellipsis"> {item.title} </h2> <div className="relative w-full h-px bg-gray-700 mb-4"> <motion.div key={`slider-${item.title}-${sliderKey}`} className={cn( "absolute top-0 left-0 h-full", isActive ? "bg-primary" : "bg-gray-700" )} initial={{ width: 0 }} animate={{ width: isActive ? "100%" : "0%" }} transition={ isActive ? { duration: 9, ease: "linear" } : { duration: 0 } } /> </div> <p className="text-gray-300 mb-4 text-sm line-clamp-4 min-h-[4rem]"> {item.description} </p> </div> </motion.div> ); // Mobile layout if (isMobile) { return ( <section className="w-full pt-20"> <div className="container mx-auto px-4 flex flex-col items-center"> <div className={metaBlockClass}> <h2 className="text-xl font-bold mb-4">{metaData.metaTitle}</h2> <p className={descriptionClass}>{metaData.metaDescription}</p> </div> <div className="w-full flex flex-col"> {renderMobileCard(leftItem)} {renderMobileCard(rightItem)} </div> </div> </section> ); } // Desktop layout return ( <section className="w-full pt-28"> <div className="container mx-auto px-4 flex flex-col items-center gap-12"> <div className={metaBlockClass}> <h2 className={desktopTitleClass}>{metaData.metaTitle}</h2> <p className={desktopDescriptionClass}>{metaData.metaDescription}</p> </div> <div className="flex gap-6 w-full max-w-6xl"> {renderDesktopCard(leftItem, activeContainer === "left")} {renderDesktopCard(rightItem, activeContainer === "right")} </div> </div> </section> ); } Entrar en modo de pantalla completa Salir en modo de pantalla completa Conclusión: Cómo sacar el máximo provecho de esta documentación We understand that the instructions and components presented here might seem extensive for a single post. You might even feel that this isn't the most exciting read, and you'd be right. This isn't entertainment; it's a detailed technical guide designed to give you complete control over a powerful system. To transform the study of this complex system into an interactive and productive process, we recommend the following approach. Uso de la IA para el aprendizaje acelerado En lugar de leer pasivamente, use esta documentación como el "cerebro" para su asistente de IA. Your Action Plan: Copie el contenido completo de este artículo, desde la introducción a esta sección. Utilízalo como un prompt de sistema para ChatGPT. Esto proporcionará a la IA el contexto completo de la arquitectura que estamos discutiendo. You can now have a dialogue with an AI that "understands" our rules and conventions. For example: Ask questions about the source code. "Based on the provided documentation, explain how to create a new custom component to display customer testimonials." and ." "Show me a configuration example for a page that uses both DoublePresentation HeroSection Este método le ayudará a comprender los principios de la aplicación mucho más rápido. Puede encontrar el código fuente completo para este proyecto en nuestro sitio web. . GitHub repository ¿Qué es lo siguiente? En este artículo, hemos construido una de las dos piezas críticas de nuestro sistema de generación de sitios: archivo en componentes React listos para el uso. Esto abre el camino para la creación automática de páginas, donde una IA puede generar la configuración, y nuestra Lo convierte en una hermosa interfaz. a tool that transforms a Config Transformer Para ver nuestro proyecto en acción, visite la demo en vivo en . aifa.dev Página web.dev A Glimpse into Future Posts: El siguiente artículo se centrará en la segunda tecnología clave: generar páginas (documentación, tutoriales, páginas de productos) a partir de archivos de Markdown. Parte 3: De Config a UI. Revisaremos el tema de este artículo y profundizaremos en cómo una configuración generada por ChatGPT se transforma en componentes de React y cómo se puede ampliar este proceso. En el siguiente tutorial, comenzaremos respondiendo a una pregunta clave: ¡Quédate atento! Why was Markdown chosen for content management?
