Этот туториал — первая часть большого путешествия, в котором мы создадим AI-систему для автоматической генерации веб-страниц на React 19 и Next.js 15. Наша цель — не просто скорость, а архитектурная элегантность и идеальная консистентность дизайна.
План такой:
Часть 1 (Вы здесь): Разбираем базовую архитектуру: «жадные» маршруты, компонент‑трансформер и типизированные конфиги для стандартных страниц.
Часть 2: Усложняем задачу: генерация страниц документации и интерактивных туториалов.
Часть 3: Подключаем интеллект: настраиваем AI для автономной генерации контента.
Бонус: Практический кейс — разворачиваем, монетизируем и масштабируем реальное приложение.
Это пошаговая инструкция по созданию собственного v0-аналога корпоративного уровня с регистрациями и оплатами. Реальный бизнес на генерации красивых приложений с революционным интерфейсом от А до Я, в конце четвертой публикации . Чтобы собрать всю систему целиком, подписывайтесь. Дальше будет только интереснее.
Как всегда представляю исходный код готового решения чтобы вы могли сразу же приступить в созданию блогов магазинов лендингов и тп. Ссылка.
Технологический стек проекта: React 19, Next.js 15, Vercel, Prisma, Stripe, AI SDK, Chat GPT
Технологический стек сочетает стабильность и передовые возможности: React 19 и Next.js 15 с App Router обеспечивают молниеносный рендер и параллельные маршруты, Vercel гарантирует без‑доуночные деплои, а Prisma и Neon формируют типобезопасный доступ к данным. Stripe интегрирует мгновенные платежи, AI SDK с ChatGPT добавляет интеллектуальный слой, позволяя AIFA Dev Starter генерировать интерфейсы, контент и прототипы за считанные минуты, уже включая авторизацию и многоязычный AI‑чат.
На практике это сводится к простому циклу: вы отправляете промпт в ChatGPT, получаете в ответ конфигурационный файл, загружаете его в приложение и одной командой сборки создаёте готовые, стилизованные страницы. Всё это уже настроено в стартовом шаблоне, включая авторизацию и многоязычный AI‑чат.
Или используйте полную автоматизацию так же как в v0, но с прицелом под крупные корпоративные интеграции (в обновленном https://aifa.dev после третьей публикации).
Вот пример:
Кому выгодна AI-система генерации сайтов: студии, корпорации, стартапы, фрилансеры
Дизайн-студии нового формата: от макета к массовому запуску сайтов за минуты
Представьте дизайн-агентство, которое создает не просто красивые макеты, а целые технологические экосистемы. Один раз вложившись в разработку уникальных компонентов и фирменного стиля, дизайнеры получают возможность генерировать профессиональные сайты со скоростью 50+ проектов в час.
Это не фантастика — это новая бизнес-модель, где креатив встречается с автоматизацией. И да, монетизация уже встроена через Stripe — об этом расскажу в следующих частях!
Корпоративные внедрения: единый стиль и масштабируемость для Enterprise-сайтов
Классический кейс — QR-меню для сети ресторанов. Один раз создав профессиональную систему карточек блюд, владелец бизнеса может предложить готовое решение сотням заведений. Рестораны адаптируют только цвета под свой бренд и наполняют контентом голосом — а профессиональный дизайн и UX остаются неизменными.
Масштабируемость, единообразие, скорость внедрения — именно то, что нужно корпоративному сегменту в 2025 году.
Transformer-архитектура компонентов: JSON → React без ручной верстки
В основе технологии AIFA Dev лежат два критически важных компонента:
Интеллектуальный промпт-инжиниринг
Специально обученные инструкции для ИИ, способные извлекать из векторных баз данных точные примеры секций и адаптировать их под конкретные задачи.Компонентная архитектура‑трансформер
React‑компоненты, которые «понимают» конфигурационные файлы и превращают JSON‑описания в живые, интерактивные страницы.
Внешние модели (ChatGPT, Claude) отлично справляются с генерацией контента, но компоненты-распаковщики — это сердце системы, которое мы создаем собственными силами.
AI-ready документация: как использовать текст как базу знаний для ChatGPT
Не читайте этот туториал — используйте его как AI‑ассистента!
Основная ценность этого объемного материала не в последовательном чтении, а в том, что он становится персональной базой знаний для ваших проектов.
Как это работает:
Скопируйте весь текст в ChatGPT
Задавайте конкретные вопросы: «Как реализовать...?», «Зачем нужно...?», «Покажи код для...»
Получайте точные ответы с готовыми компонентами
Это не документация для чтения — это интерактивный справочник для быстрого решения задач. Попробуйте такой подход, и вы поймете, почему современная техническая документация должна быть AI‑ready!
1.Введение: цель, выгоды и место метода среди генераторов v0-поколения
Данный туториал не ставит своей задачей создание решения, превосходящего v0 по скорости генерации. Основная цель — обеспечение единообразия и гармоничности дизайна на всех страницах проекта.
Да, создание каждой отдельной страницы может потребовать несколько больше времени по сравнению с универсальными генераторами. Однако совокупные затраты на проект значительно снижаются благодаря следующим преимуществам:
Единый стиль всех компонентов — каждая новая страница автоматически вписывается в общую дизайн‑систему
Гармоничность всего проекта — отсутствие стилистических разрывов между разными разделами сайта
Снижение затрат на доработку — минимальная необходимость в последующей стилизации и адаптации
Масштабируемость решения — чем больше страниц, тем выше эффективность подхода
Результат: проект получается визуально целостным, профессиональным и требует минимальных усилий на поддержание единообразия интерфейса при масштабировании.
В основном туториале рассматривается создание стандартных страниц с использованием базовых компонентов header и footer.
Однако в исходном коде проекта вы найдете кастомные реализации для специализированных типов страниц:
Страницы документации с расширенной навигацией
Страницы Tutorial с интерактивными элементами
Работа со сложными компонентами:
Обратите внимание, что некоторые компоненты на главной странице обладают более сложной логикой:
Управление состоянием (state management)
Анимации и переходы
Интерактивные элементы
Интеграция продвинутых решений:
Для интеграции таких сложных компонентов предусмотрена возможность добавления Custom-компонентов вместо стандартных секций. Это позволяет:
Сохранить гибкость системы
Внедрить уникальную функциональность
Поддержать единый стиль даже для нестандартных решений
Практическое задание:
Изучение процесса создания и интеграции Custom-компонентов остается вашим практическим заданием для закрепления полученных знаний.
1.1.Концепция: единообразные страницы бренда, создаваемые ИИ по шаблонам
Современный процесс разработки требует скорости, однородности интерфейса и возможности быстрого реагирования на бизнес-требования. Мы предлагаем архитектуру, в которой стандартные, формализованные описания дизайн-секций (Hero, CTA, FAQ, Features и др.) хранятся в структурированной базе знаний ИИ.
Загружая туда ваши актуальные стандарты UI/UX для каждой секции, вы позволяете искусственному интеллекту выступать не только генератором контента, но и гарантом единого фирменного стиля на всех уровнях создания страниц.
1.2. Пять этапов: от загрузки дизайн-шаблонов до SEO-оптимизированного билда
Загрузка стандартов дизайна:
В базу знаний ИИ добавляются шаблоны и инструкции для каждой секции — как их визуально и структурно реализовывать в рамках единого стиля вашего бренда.Обработка текстового запроса:
Пользователь, менеджер проекта или программист формирует задание в виде текстового промпта — описывает желаемую страницу или её элементы.AI-интерпретация и структурирование:
Искусственный интеллект анализирует запрос, генерирует семантический контент, разбивает его на логические секции и подбирает подходящие шаблоны из базы знаний.Генерация кода страниц:
На основании выбранных шаблонов и сгенерированного контента система формирует строгие PageConfig’и — декларативные JSON/Type-описания будущих страниц. Они гарантируют соблюдение всех дизайн-стандартов и упрощают downstream-разработку.Автоматическая сборка и билдинг:
Готовые конфигурации применяются для статической генерации страниц с использованием рендер-компонентов, в результате чего вы получаете полноценную, SEO-оптимизированную страницу, визуально и технически выдержанную по вашим корпоративным стандартам.
1.3. Экономия ресурсов и рост конверсий: бизнес-преимущества AI-генерации
Быстрота вывода новых landing pages и product pages — достаточно промпта, чтобы ИИ сгенерировал страницу на основе актуальных шаблонов.
Единый фирменный стиль и качество — извлекается и соблюдается автоматически для каждой новой страницы.
Минимизация ручной работы и A/B тестирование — масштабирование вариантов страниц и изменение контента силами AI без участия разработчика в вёрстке.
Готовность к многоязычности — все тексты и элементы хранятся централизованно, легко поддаются локализации и адаптации.
Инфраструктурная гибкость — легко интегрируется в CI/CD пайплайны, современные хостинги и AI-driven процессы.
1.4. Как продолжить: дорожная карта из трёх статей и бонус-кейса
h4В данном туториале мы пошагово рассмотрим:
Архитектура существующих компонентов — детальный разбор структуры PageHtmlTransformer, системы обёрток (Wrapper/FullScreenWrapper), компонентов секций и их взаимодействия для понимания внутренних механизмов работы.
Принципы работы системы — изучение логики рендеринга секций, типизации конфигураций, механизмов роутинга и связи между конфигурационными файлами и React-компонентами. Это необходимо для того, чтобы разработчики могли самостоятельно расширять данные представления.
Создание инструкций для искусственного интеллекта — формирование структурированного описания существующих доступных типов для метаданных, header section, footer section. Добавление требований к созданию JSX fragment для body section с детальными спецификациями и ограничениями.
Генерация конфигурационных файлов — практическое применение полученных знаний для создания config-файлов, которые будут использоваться AI для автоматической генерации страниц с соблюдением всех архитектурных принципов и стандартов дизайна.
2. Структура проекта: папки, файлы и логика маршрутизации Next.js 15
Tree
app/@right/
├── public/
│ ├── (_routing)/
│ │ └── [[...slug]]/
│ │ └── page.tsx # 1. Динамический роутинг
│ └── (_service)/
│ ├── (_config)/
│ │ └── public-pages-config.ts # 6. Конфигурация публичных страниц
│ └── (_libs)/
│ └── utils.ts # 7. Утилиты
└── (_service)/
├── (_types)
│ ├── /page-transformer-custom-types/
│ └── page-wrapper-types.ts # 5. Типы и интерфейсы
└── (_components)/
└── page-transformer-components/
├── page-html-transformer.tsx # 2. Главный трансформер
├── custom-sections/
├── wrappers/
│ ├── full-screen-wrapper.tsx # 3. Полноэкранная обёртка
│ └── wrapper.tsx # 4. Стандартная обёртка
├── header-sections-components/
│ ├── header-section.tsx # 8. Компонент заголовка
│ ├── page-header-elements.tsx # 9. Элементы заголовка
│ └── announcement.tsx # 10. Компонент анонса
├── body-sections-components/
│ └── body-section.tsx # 12. Компонент Body
└── footer-sections-components/
└── footer-section.tsx # 11. Компонент футера
Components:
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/(_servise)/(_config)/public-pages-config.ts
7-//@app/@right/public/(_servise)/(_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
2.1. Базовый набор компонентов: рендер шаблонных страниц «из коробки»
Назначение
Стандартные компоненты представляют собой базовый набор элементов для создания типизированных страниц в едином стиле. Эта коллекция включает в себя системообразующие элементы архитектуры: динамический роутинг, центральный трансформер, обёртки для разных типов контента, унифицированные секции заголовков и футеров, а также конфигурационные файлы и типизацию.
Ключевые принципы стандартных компонентов:
Единообразие интерфейса — все компоненты следуют общим принципам дизайна и поведения
AI-совместимость — структура оптимизирована для автоматической генерации контента
SEO-оптимизация — встроенная поддержка поисковой оптимизации и правильной HTML-семантики
Типизированная архитектура — строгая типизация через TypeScript для предсказуемого поведения
Модульность — каждый компонент решает конкретную задачу и может использоваться независимо
Эти компоненты формируют основу системы, которая гарантирует визуальную консистентность и техническое единообразие всех AI-генерируемых страниц.
2.1.1. Компонент [[...slug]]/page.tsx: универсальный catch-all route для динамических URL
2.1.1.1. Почему Next.js использует catch-all routes: гибкость, скорость деплоя
Жадный маршрут (catch-all route) — это тип динамического роута в Next.js, который позволяет обрабатывать неограниченное количество вложенных сегментов URL с помощью одной единственной страницы-компонента. В конструкции [...slug] или [[...slug]] (опциональный) массив slug в параметрах будет содержать все части пути, независимо от их количества.
Почему это круто:
Произвольное количество уровней вложенности.
Вам не нужно создавать отдельные папки и файлы в структуре проекта под каждый новый путь. Например, путь /public/category/nike/sneakers/black/12345 обработается ровно тем же компонентом, что и /public/test.Гибкая навигация и быстрый запуск новых страниц.
Достаточно добавить соответствующий конфиг — и страница мгновенно появляется в приложении, без необходимости заводить новые компоненты или поддерживать сложную файловую структуру.Автоматизация:
Такое построение идеально сочетается с auto-generated sidebar/menu: создаём нужный пункт в навигации и "умный" роутинг автоматом отрабатывает отображение нужной страницы.
2.1.1.2. Значение динамических URL для AI-ассистентов: бесконечное расширение контента
В современных SaaS/AI-продуктах или headless сайтах зачастую требуется быстро создавать новые страницы "на лету" по запросу юзера или администратора — страница конструируется и конфигурируется не руками, а через генерацию (AI или админ-панель).
Архитектура с жадным роутом:
Снимает ограничения структуры и глубины вложенности страниц,
Позволяет работать с любым количеством уровней иерархии (например, меню ресторанов с многоуровневой категоризацией; карточки товаров по структуре каталог/категория/производитель/линейка/артикул),
Обеспечивает свободу для пользователей и разработчиков — навигация строится только по логике проекта, а не привязана к файловой структуре.
2.1.1.3. Примеры использования:
QR-меню для ресторана:
/public/menu/bar/beer и /public/menu/hot-dishes/italian/pasta → любые глубины подкатегорий.Интернет-магазин:
/public/shop/clothes/mens/jackets/leather/2023/black/style123Образовательный портал:
/public/tutorials/python/basics/loops/while-loop/example1
2.1.1.4. Как работает компонент page.tsx
Основные задачи:
Приходит массив slug из URL (например, ["category", "nike", "sneakers"]).
Функция generateStaticParams собирает все маршруты, которые присутствуют в вашем конфиге (pages-config.ts), и передаёт Next.js их для статической генерации.
Функция getPageBySlug быстро находит в массиве конфигов нужную страницу ровно по тому slug, который пришёл (обычно с добавлением "public" в начало).
export async function generateStaticParams() {
const pages: PageConfig[] = getAllPublicPages();
return pages.map((page: PageConfig) => ({
slug: page.metadata.slug ? page.metadata.slug.slice(1) : [],
}));
}Здесь мы формируем все возможные пути для статической генерации: если в конфиге есть ["public","cat","subcat","product"], то будет сгенерирован путь /public/cat/subcat/product.
Далее, когда происходит рендеринг:
export default async function PublicDynamicSlugPage({ params }: Props) {
const resolvedParams = await params;
const slugArr = resolvedParams.slug ?? [];
const pageConfig = getPageBySlug(["public", ...slugArr]);
if (!pageConfig) {
return <div>Page not found</div>;
}
return <PageHtmlTransformer data={pageConfig} />;
}slugArr может быть любой длины!
"public" добавляется для корректного поиска в массиве.
Функция поиска работает по полному совпадению slug, что исключает коллизии.
h5 2.1.1.5. Кратко о ключевых функциях:
generateStaticParams — сообщает Next.js ВСЕ существующие вложенные пути для генерации.
getPageBySlug — ищет нужную страницу в массиве по полному match slug-массива.
PageHtmlTransformer — универсальный отрисовщик, которому неважно, какой глубины вложенности страница: он строит компонент на лету из твоего формализованного конфига.
2.1.1.6. Заключение. Почему выбран именно такой подход
Гибкость для новых разделов: не надо думать о папках — просто добавь конфиг, и страница появится!
Удобство редактирования и масштабирования навигации: весь роутинг и навигация управляются на уровне данных (массивы slugs), а не файлов.
Сценарии реального бизнеса: автоматизация генерации меню, товаров, курсов, документации, блогов и всего, что только может прийти в голову.
Унификация для AI-ассистентов: такой подход идеально сочетается с автоматической генерацией контента по текстовому описанию (prompt) — любые новые страницы появляются мгновенно и не ограничены глубиной маршрута.
2.1.1.7. Компонент
// @/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} />;
}2.1.1.7. TL;DR по catch-all: когда и как использовать в AI-проекте
Жадные маршруты и централизованный конфиг страниц делают архитектуру твоего приложения максимально гибкой, расширяемой и дружественной как для разработчиков, так и для AI-оркестрации контента. Новая страница = новая строка в конфиге, никаких новых файлов или папок — навигация и рендер подстраиваются автоматически!
2.1.2. Реальные кейсы catch-all route: магазин, меню ресторана, образовательный портал
2.1.2.1. Архитектурная роль и назначение компонента
PageHtmlTransformer является ядром всей системы рендеринга — это универсальный "дирижёр", который получает декларативное описание страницы (PageConfig) и превращает его в живые React-компоненты. Его главная задача — обеспечить единообразие визуального представления при максимальной гибкости содержимого.
h6 Ключевые функции:
Централизованная логика рендеринга — один компонент управляет всем процессом отображения секций
Типизированная обработка — каждый тип секции получает соответствующую обёртку и рендеринг
Управление темами и адаптивностью — центральная точка для проброса контекстных данных
Унификация стилей — гарантирует единообразие header/footer секций across всех страниц
2.1.2.2. Принципиальное решение: почему header и footer вынесены отдельно
Решение вынести HeaderSection и FooterSection за рамки дефолтной логики BodySection продиктовано фундаментальными требованиями к единообразию дизайна:
h6 Проблема с AI-генераторами контента:
Автоматизированные ИИ-генераторы часто создают непоследовательный контент в части оформления заголовков и заключений
Каждая секция может иметь уникальное body-содержание, но начало и конец должны следовать строгим стандартам бренда
Header и Footer — это "якоря стиля", которые задают тон всей секции и обеспечивают визуальную связность
Архитектурные преимущества:
Гарантированное единообразие — независимо от того, как AI сгенерирует body-контент, header и footer всегда будут выдержаны в корпоративном стиле
Централизованный контроль — изменения в стилях заголовков применяются мгновенно ко всем страницам
Предсказуемая структура — разработчики и дизайнеры могут рассчитывать на стабильные паттерны
2.1.2.3. Управление темами и контекстом
export function PageHtmlTransformer({ data }: PageHtmlTransformerProps) {
const { theme } = useTheme();
// ... rest of logic
}Зачем пробрасывать тему именно отсюда:
Сценарии, требующие theme-aware логики:
Условные изображения: В светлой теме используется одна картинка, в темной — другая
Динамические стили: Компоненты с особой логикой цветовых схем
Анимации и переходы: Разные эффекты для light/dark режимов
Аналогично с мобильной версией (isMobile):
Условный рендеринг: Некоторые компоненты полностью отключаются на мобильных
Кардинально разная вёрстка: Когда Tailwind CSS недостаточно гибкий
Производительность: Отказ от тяжёлых элементов на слабых устройствах
Пример использования:
// В дочернем компоненте
{theme === 'dark' ? <DarkModeImage /> : <LightModeImage />}
{!isMobile && <DesktopOnlyFeature />}2.1.2.4. Два типа Wrapper: зачем нужна дифференциация
FullScreenWrapper vs Wrapper — принципиальные различия:
FullScreenWrapper (для hero-section и подобных):
Полноэкранная компоновка — занимает всю высоту viewport
Поддержка фоновых медиа — video/image backgrounds с наложением контента
Z-index управление — сложная слоистая структура для overlay-эффектов
Позиционирование — absolute/relative позиционирование для центрирования контента
Wrapper (стандартный):
Секционная вёрстка — обычные блоки с padding/margin
Container-based — стандартная сетка и отступы
Простота и производительность — минимальные CSS-свойства
Почему нельзя объединить в один компонент:
Конфликты CSS — fullscreen и container логики несовместимы
Производительность — лишние стили влияют на рендеринг
Семантическая ясность — разные задачи требуют разных подходов
Maintenance — проще поддерживать два специализированных компонента
2.1.2.5. Ограничения renderSectionContent и кастомные случаи
Проблемы со стандартной функцией renderSectionContent:
function renderSectionContent(config: any) {
return (
<>
{config.headerContent && <HeaderSection headerContent={config.headerContent} />}
{config.bodyContent && <BodySection type={config.type}>{config.bodyContent.content}</BodySection>}
{config.footerContent && <FooterSection actions={config.footerContent.actions} />}
</>
);
}Ограничения этого подхода:
Отсутствие state management — нет возможности использовать useState, useEffect
Статичность данных — контент передается как готовые данные, без интерактивности
Отсутствие event handling — невозможно обрабатывать пользовательские события
Нет lifecycle методов — компоненты не могут реагировать на mount/unmount
Когда нужны кастомные случаи:
Интерактивные формы — компоненты с валидацией и отправкой данных
Анимированные секции — сложные transitions и animations
Real-time данные — компоненты с подпиской на WebSocket или API
Условная логика — сложные вычисления на основе пользовательского ввода
Решение через кастомные кейсы:
switch (section.type) {
case "interactive-form-section": {
return <CustomInteractiveForm key={config.id} {...config} />;
}
case "real-time-dashboard": {
return <CustomDashboard key={config.id} {...config} theme={theme} />;
}
// стандартные случаи...
default: {
return (
<Wrapper key={config.id}>
{renderSectionContent(config)}
</Wrapper>
);
}
}2.1.2.6. Анализ архитектурной роли и рабочего процесса
PageHtmlTransformer выполняет несколько ключевых архитектурных ролей:
Фасад паттерн — предоставляет простой интерфейс для сложной системы рендеринга
Factory паттерн — создает нужные компоненты на основе типа секции
Strategy паттерн — выбирает стратегию рендеринга (Wrapper/FullScreenWrapper) в зависимости от контекста
Template Method паттерн — определяет скелет алгоритма рендеринга с возможностью переопределения отдельных шагов
Рабочий процесс:
Получение конфигурации — принимает PageConfig с массивом секций
Инициализация контекста — получает theme, определяет isMobile
Итерация по секциям — для каждой секции определяет тип и способ рендеринга
Выбор обёртки — FullScreenWrapper для hero-секций, Wrapper для остальных
Рендеринг контента — применяет renderSectionContent или кастомный компонент
Сборка финальной страницы — объединяет все секции в единую структуру
2.1.2.7. Компонент
// @/app/@right/(_service)/(_components)/page-transformer-components/page-html-transformer.tsx
"use client";
import {
PageConfig,
Section,
SectionConfig,
} from "../../(_types)/page-wrapper-types";
import { BodySection } from "./body-sections-components/body-section";
import { FooterSection } from "./footer-sections-components/footer-section";
import { HeaderSection } from "./header-sections-components/header-section";
import { useTheme } from "next-themes";
import { FullScreenWrapper } from "./wrappers/full-screen-wrapper";
import { Wrapper } from "./wrappers/wrapper";
interface PageHtmlTransformerProps {
data: PageConfig;
}
function renderSectionContent(config: any) {
return (
<>
{config.headerContent && (
<HeaderSection headerContent={config.headerContent} />
)}
{config.bodyContent && (
<BodySection type={config.type}>
{config.bodyContent.content}
</BodySection>
)}
{config.footerContent && (
<FooterSection actions={config.footerContent.actions} />
)}
</>
);
}
export function PageHtmlTransformer({ data }: PageHtmlTransformerProps) {
const { theme } = useTheme();
if (!data?.sections?.length) return null;
return (
<>
{data.sections.map((section: Section, idx: number) => {
switch (section.type) {
case "hero-section": {
const config = section as SectionConfig;
return (
<FullScreenWrapper
key={config.id || idx}
videoUrl={config.videoUrl}
imageUrl={config.imageUrl}
className={config.sectionClassName}
>
{renderSectionContent(config)}
</FullScreenWrapper>
);
}
// ...другие case без изменений
default: {
const config = section as any;
return (
<Wrapper
key={config.id || idx}
className={config.sectionClassName}
>
{renderSectionContent(config)}
</Wrapper>
);
}
}
})}
</>
);
}2.1.2.7.Заключение
PageHtmlTransformer — это сердце системы, которое превращает декларативные описания в живые, интерактивные и стилистически единообразные веб-страницы. Его архитектура балансирует между гибкостью (поддержка кастомных компонентов) и последовательностью (стандартизированные header/footer), что делает его идеальным инструментом для AI-управляемой генерации контента.
2.1.3. FullScreenWrapper vs Wrapper: когда использовать полноэкранную оболочку
2.1.3.1. Основное назначение
FullScreenWrapper предназначен для секций, требующих полноэкранного отображения с поддержкой видео/изображений на фоне. Это базовый контейнер для hero-секций, где контент накладывается поверх медиа-элементов.
2.1.3.2. Слоистая структура
<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>Технические особенности:
min-h-screen — гарантирует заполнение всего viewport
relative позиционирование для z-index управления
Background элементы (видео/изображение) с absolute и z-0
Контент с relative z-10 всегда поверх фона
2.1.3.3. Кастомизация и расширения
Место для градиентов и анимаций: Добавляйте эффекты через className prop:
<FullScreenWrapper className="bg-gradient-to-br from-blue-900 to-purple-900">
Контроль прозрачности фона: Видео автоматически получает opacity-40 для читаемости текста, но это легко переопределить.
Анимации переходов: transition-all duration-500 уже встроен для плавных изменений фона.
2.1.3.4. Применение для кастомных шаблонов
Если нужны разделители между секциями, бордюры, подсветка или управление размытием — FullScreenWrapper идеальное место для реализации:
// Пример с бордюром и градиентом
<FullScreenWrapper className="border-t-4 border-gradient bg-blur-effect">
2.1.3.5. Компонент
// @/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>
);
}2.1.4. Wrapper: базовая секционная оболочка с container mx-auto
2.1.4.1. Назначение
Wrapper — базовая обёртка для большинства контентных секций. Обеспечивает стандартные отступы, центрирование контента и контейнеризацию.
2.1.4.2. Структура
<section className="py-10 lg:py-14 bg-background">
<div className="container mx-auto px-4">
{children} // Header → Body → Footer
</div>
</section>Ключевые параметры:
py-10 lg:py-14 — адаптивные вертикальные отступы
container mx-auto px-4 — центрированный контент с горизонтальными отступами
bg-background — использует CSS-переменную темы
2.1.4.3. Точки кастомизации
Фоновые эффекты:
Легко добавлять через className:
<Wrapper className="bg-gradient-to-r from-slate-50 to-slate-100 dark:from-slate-900 dark:to-slate-800">
Разделители между секциями:
<Wrapper className="border-t border-border/50">
Анимации появления:
<Wrapper className="animate-fade-in transition-all duration-700">
Управление размытием и подсветкой:
<Wrapper className="backdrop-blur-sm shadow-inner">
2.1.4.4. Средне-кастомные переиспользуемые шаблоны
Когда нужен шаблон с уникальной стилизацией, но стандартной структурой — Wrapper ваш выбор:
// Пример для pricing-секций
<Wrapper className="bg-gradient-to-br from-green-50 to-green-100 border-2 border-green-200">
<HeaderSection />
<PricingTable />
<FooterSection />
</Wrapper>2.1.3.5. Компонент
// 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>
);
}Зачем два отдельных wrapper'а?
Технические причины:
FullScreenWrapper содержит сложную логику медиа-фонов и z-index управления
Wrapper оптимизирован для производительности — минимум CSS-правил
Разные подходы к позиционированию: relative vs static
Несовместимые CSS-свойства: min-h-screen vs py-*
Практические выгоды:
Четкое разделение ответственности
Легкость кастомизации под конкретные задачи
Предсказуемое поведение для AI-генерации
Отсутствие CSS-конфликтов между типами секций
Для AI-систем: Простое правило выбора — immersive контент (hero, showcases) = FullScreenWrapper, информационный контент = Wrapper.
2.1.5. page-wrapper-types.ts: TypeScript-контракт между ИИ и UI
2.1.5.1. Роль типизации: контракт между AI и рендером.
Файл page-wrapper-types.ts — это формальный контракт между AI-генератором и системой рендеринга. Здесь определяется архитектура всех возможных компонентов страницы и правила их взаимодействия.
2.1.5.2. Категории SectionType и AI-генерация.
Принцип работы AI: Искусственный интеллект сначала анализирует доступные типы секций из enum SectionType, затем принимает решение о том, какие из них добавить к конкретной странице на основе пользовательского запроса.
Ожидается, что для каждого из 25+ типов секций в базе знаний AI будут загружены исчерпывающие инструкции и примеры, достаточные для автономной генерации контента.
export type SectionType =
| "hero-section" | "cta-section" | "faq-section"
| "features-section" | "testimonials-section" | "pricing-section"
// ... и другие типы2.1.5.3. SEO-оптимизация и метаданные.
PageMetadata обеспечивает корректное формирование мета-тегов для поисковых систем:
export interface PageMetadata {
id: string; // Уникальный идентификатор
title: string; // <title> тег для SEO
description: string; // <meta description> для сниппетов
image?: string; // Open Graph изображение
slug?: string[]; // URL-структура страницы
type: SectionType; // Тип основной секции
}Автоматическая генерация мета-тегов происходит в generateMetadata() функции, которая извлекает данные из конфига и передает их в constructMetadata() для формирования корректных HTML-заголовков.
2.1.5.4. HeaderContentConfig: контроль SEO-иерархии.
Критически важно для SEO:
interface HeaderContentConfig {
heading: string;
headingLevel?: 1 | 2; // H1/H2 для поисковой иерархии
description?: string;
showBorder?: boolean;
}Осторожно с заголовками: Header-секция опциональна, поскольку в некоторых типах секций заголовки H1/H2 могут размещаться внутри bodyContent. Это потенциально опасно для единообразия интерфейса — основной цели данного туториала.
2.1.5.5. BodySection: максимальная свобода дизайна.
bodyContent?: React.ReactNode;
Архитектурное решение: Тело секции получает полную свободу для реализации любого дизайна, в то время как Header и Footer жестко стандартизированы для поддержания единого стиля.
interface FooterContentConfig {
actions?: {
label: string;
href: string;
variant?: "default" | "secondary" | "outline" | "ghost" | "link";
}[];
}2.1.5.6. FooterContentConfig: минимализм по дизайну.
Текущая реализация предполагает только опциональные кнопки действий. Никаких дополнительных элементов — максимальная простота и единообразие.
2.1.5.7. Принципы расширения типизации.
Для добавления новых SectionType:
AI получает новые инструкции в базу знаний
Добавляется тип в enum SectionType
При необходимости расширяется интерфейс конфигурации
Баланс стандартизации: Header и Footer строго типизированы для SEO и единообразия, Body получает максимальную гибкость для творческих решений AI-генераторов
2.1.5.8. Компонент
2.1.5.9. customComponentsAnyTypeData: поддержка произвольных кастомных компонентов
Поле customComponentsAnyTypeData?: any; в SectionConfig предназначено для передачи данных в секции, реализованные через сложные или уникальные кастомные компоненты, не вписывающиеся в стандартные интерфейсы.
Тип и структура этих данных должны быть подробно и строго описаны внутри самого кастомного компонента. Это решение обеспечивает гибкость для интеграции интерактивных, динамических и продвинутых пользовательских секций без нарушения общего контракта типизации основной архитектуры страниц.
// 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[];
2.1.6. public-pages-config.ts: реестр публичных страниц и Slug-маршрутов
2.1.6.1. Роль конфига в архитектуре системы
Файл public-pages-config.ts является результатом работы искусственного интеллекта — автоматически генерируемым реестром всех публичных страниц приложения. Этот конфиг создается ИИ в автоматическом режиме на основе системных инструкций и пользовательского запроса, напрямую зависит от доступных компонентов в примерах базы знаний и перечислений в типизации SectionType, которые мы рассматривали выше. Сгенерированная структура служит мостом между AI-анализом требований пользователя и системой рендеринга страниц.
2.1.6.2. Когда использовать файловый конфиг
Оптимальные сценарии для конфиг-файла:
Проекты с не более 10-15 страниц
Статичный контент, который редко изменяется
Прототипирование и MVP — быстрый старт без базы данных
Landing pages с фиксированной структурой
Когда переходить на базу данных:
В production-версии на крупном проекте файловый подход имеет смысл только при небольшом количестве страниц. Большинство случаев требуют хранения этой информации в базе данных для динамического управления контентом.
2.1.6.3. Структура конфига
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[],
};
2.1.6.4. Принцип категоризации конфигов
Важное архитектурное решение: Размещение конфига в директории public/(_service)/(_config)/ указывает на его принадлежность к публичным страницам.
Масштабирование по категориям:
public-pages-config.ts — публичные страницы (landing, about, contact)
docs-pages-config.ts — документация с расширенной навигацией
admin-pages-config.ts — административные панели
blog-pages-config.ts — блоговые записи и статьи
Каждая категория получает:
Собственный файл конфигурации
Специализированные типы секций
Уникальную логику рендеринга
2.1.6.5. Взаимодействие с AI-генерацией
Для AI-систем конфиг служит:
Шаблоном структуры — как должны выглядеть PageConfig объекты
Примером данных — референсные значения для генерации
Валидацией типов — строгая типизация через TypeScript
Рабочий процесс:
AI анализирует существующий конфиг
Генерирует новый PageConfig на основе промпта
Разработчик добавляет конфиг в массив pages
Система автоматически подхватывает новые маршруты
2.1.6.6. Преимущества и ограничения
Преимущества файлового подхода:
Версионирование через Git
Type safety на этапе компиляции
Нулевая латентность — нет запросов к БД
Простота деплоя — статическая генерация
Ограничения:
Отсутствие динамического управления
Необходимость перебилда при изменениях
Неподходящ для user-generated content
Сложность масштабирования свыше 20-30 страниц
2.1.6.7. Компонент
// @/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[],
};
2.1.6.7. Заключение
public-pages-config.ts представляет собой практичное решение для небольших и средних проектов, обеспечивающее баланс между простотой управления и функциональностью. Для крупных проектов этот подход служит отличной отправной точкой перед миграцией на database-driven архитектуру.
2.1.7. utils.ts: вспомогательные функции конфигурации
Утилиты для работы с конфигами страниц. Содержит две ключевые функции: getAllPublicPages() — фильтрует все страницы с префиксом "public" для статической генерации, и getPageBySlug() — находит конкретную страницу по полному совпадению slug-массива с учетом регистра.
// @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()))
);
}2.1.8. header-section.tsx: унифицированный заголовок секций
Стандартизированный компонент заголовка для всех типов секций. Обеспечивает единообразие через опциональные элементы: анонс, заголовок H1/H2, описание. Ключевая роль в SEO-оптимизации и визуальной консистентности AI-генерируемых страниц.
// @/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>
);
}
2.1.9. header-section.tsx: унифицированный заголовок секций
Атомарные компоненты для построения заголовков: PageHeaderHeading с поддержкой H1/H2, PageHeaderDescription для подзаголовков, PageActions для размещения кнопок. Используют createElement для динамической генерации HTML-тегов с правильной SEO-иерархией.
// @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";
// Правильное использование createElement
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 };
2.1.10. announcement.tsx: компонент анонсов
Интерактивный бейдж для анонсов и уведомлений. Поддерживает навигацию, клавиатурное управление и условный рендеринг. Автоматически скрывается при отсутствии контента. Используется для привлечения внимания к важным обновлениям или ссылкам.
// @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>
);
}
2.1.11. footer-section.tsx: унифицированные действия секций
Стандартизированный футер с кнопками действий. Поддерживает множественные кнопки с разными вариантами стилизации. Обеспечивает единообразие CTA-элементов across всех секций. Автоматически скрывается при отсутствии действий.
// @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>
);
}2.1.12. body-section.tsx: контейнер для произвольного контента
2.1.12.1. Назначение и философия
BodySection — это максимально гибкий контейнер для основного содержимого секций. В отличие от строго стандартизированных Header и Footer, этот компонент предоставляет полную свободу для размещения любого React-контента.
2.1.12.2. Принципы генерации контента
Критически важно: Контент для bodyContent должен генерироваться как обычный TSX без элементов .map(), где все элементы представлены в развернутом виде:
// ✅ Правильно - развернутый TSX
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>
</>
)
```
```
// ❌ Неправильно - использование .map()
bodyContent: (
<div className="grid">
{features.map(feature => <FeatureCard key={feature.id} {...feature} />)}
</div>
)
2.1.12.3. Когда использовать кастомные компоненты
Если секция требует сложной логики (состояние, эффекты, интерактивность), создавайте самостоятельный компонент и добавляйте его в PageHtmlTransformer как отдельный
case:
switch (section.type) {
case "interactive-pricing-section": {
return <CustomPricingCalculator key={config.id} {...config} />;
}
// стандартные случаи...
}2.1.12.3. Техническая реализация
Компонент проверяет наличие children и рендерит их без дополнительной обработки. При отсутствии контента возвращает null, обеспечивая чистую разметку без пустых блоков.
// @/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>
);
}2.1.12.4. Компонент
// @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;
}
/**
* BodySection component.
* Renders children if present,
* otherwise renders an empty section with a default height (in rem) if provided,
* or renders nothing.
*/
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;
}
// Normal case: render content
return (
<div className={cn(className)} {...props}>
{children}
</div>
);
}2.1.12.5. ЗаключениеBodySection служит мостом между стандартизированной архитектурой системы и творческой свободой AI-генерации, обеспечивая баланс между контролем и гибкостью.
2.2. Custom сложные компонентыCustom компоненты предназначены для реализации сложной интерактивной функциональности, которая выходит за рамки возможностей стандартной архитектуры. Эти компоненты используются в случаях, когда требуется управление состоянием, сложные анимации, real-time взаимодействие или уникальная бизнес-логика.
h4 Когда использовать Custom компоненты:
Интерактивные элементы — формы с валидацией, калькуляторы, конфигураторы продуктов
Анимированные презентации — сложные transitions, параллакс-эффекты, автоматические слайдеры
Real-time функциональность — чаты, уведомления, live-данные
Адаптивная логика — компоненты с кардинально разным поведением на desktop/mobile
Уникальные UI-паттерны — нестандартные элементы интерфейса, специфичные для проекта
Интеграция с архитектурой:
Custom компоненты добавляются в PageHtmlTransformer как отдельные case в switch-конструкции, получая доступ к контексту темы, устройства и другим системным параметрам. Они сохраняют единый стиль через использование общих CSS-классов и дизайн-токенов, но получают полную свободу в реализации внутренней логики.
Такой подход обеспечивает баланс между стандартизацией большинства контента и творческой свободой в реализации сложных интерактивных элементов.
2.2.1. Директива по обработке кастомных компонентов
2.2.1.1. About Wrappers
Запрет на обёртки для кастомных компонентов
Custom-компоненты должны возвращаться напрямую без Wrapper или FullScreenWrapper, так как они сами управляют своей структурой, отступами и слоями.
2.2.1.2. About custom component types
Размещение типов в компоненте
Интерфейсы пропсов кастомного компонента объявляются в верхней части самого компонента. Данные передаются через поле customComponentsAnyTypeData в конфиге секции.
2.2.1.3 Расширенный тип SectionType:
Добавление нового типа секции
Для каждого кастомного компонента добавляется уникальный тип в enum SectionType файла page-wrapper-types.ts для корректной типизации и обработки в switch-конструкции.
// @/app/@right/(_service)/(_types)/page-wrapper-types.ts
// ...
export type SectionType ="hero-section" | “new-custom-section”;
2.2.1.4. Update cases in the ageHtmlTransformer
Обработка кастомного кейса
В PageHtmlTransformer добавляется новый case для обработки кастомного типа секции с прямой передачей данных из customComponentsAnyTypeData в пропсы компонента.
case "new-custom-section":
return (
<NewCustomSection
key={config.id}
customData={section.customComponentsAnyTypeData.customData}
/>
);2.2.1.5. Custom Config
Структура конфигурации
Пример конфигурации страницы с кастомной секцией, где все специфичные данные размещаются в объекте 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[],
2.2.2. Custom component example
2.3.2.1. DoublePresentation
2.3.2.1.1. Обновление основных типов
// @/app/@right/(_service)/(_types)/page-wrapper-types.ts
// Добавляем новый тип секции
export type SectionType =
| "hero-section"
| "cta-section"
| "double-presentation-section" // Новый тип
// ... остальные типы2.3.2.1.2. Add new case with current data to : PageHtmlTransformer
case "double-presentation-section":
return (
<DoublePresentation
key={section.id}
metaData={section.customComponentsAnyTypeData.metaData}
leftItem={section.customComponentsAnyTypeData.leftItem}
rightItem={section.customComponentsAnyTypeData.rightItem}
/>
);2.3.2.1.3. page-wrapper-types.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[];
2.3.2.1.4. Config, example:
// @/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[],
};2.3.2.1.5. Component
// @/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>
);
}
Roma Armstromg
AI Architector
Как всегда представляю исходный код готового решения чтобы вы могли сразу же приступить в созданию блогов магазинов лендингов и тп. Ссылка.
