# Шаблоны экранов и конструктор воронки Этот документ описывает, из каких частей состоит JSON-конфигурация воронки, какие шаблоны экранов доступны в рантайме и как с ними работает конструктор (builder). Используйте его как справочник при ручном редактировании JSON или при настройке воронки через интерфейс администратора. ## Архитектура воронки Воронка описывается объектом `FunnelDefinition` и состоит из двух частей: метаданных и списка экранов. Навигация осуществляется по идентификаторам экранов, а состояние (выборы пользователя) хранится отдельно в рантайме. ```ts interface FunnelDefinition { meta: { id: string; version?: string; title?: string; description?: string; firstScreenId?: string; // стартовый экран, по умолчанию первый в списке }; defaultTexts?: { nextButton?: string; continueButton?: string; }; screens: ScreenDefinition[]; // набор экранов разных шаблонов } ``` Каждый экран обязан иметь уникальный `id` и поле `template`, которое выбирает шаблон визуализации. Дополнительно поддерживаются: - `header` — управляет прогресс-баром, заголовком и кнопкой «Назад». По умолчанию шапка показывается, а прогресс вычисляется автоматически в рантайме. - `bottomActionButton` — универсальное описание основной кнопки («Продолжить», «Далее» и т. п.). Шаблон может переопределить или скрыть её. - `navigation` — правила переходов между экранами. ### Навигация Навигация описывается объектом `NavigationDefinition`: ```ts interface NavigationDefinition { defaultNextScreenId?: string; // переход по умолчанию rules?: Array<{ nextScreenId: string; // куда перейти, если условие выполнено conditions: Array<{ screenId: string; // экран, чьи ответы проверяем operator?: "includesAny" | "includesAll" | "includesExactly"; optionIds: string[]; // выбранные опции, которые проверяются }>; }>; } ``` Рантайм использует первый сработавший `rule` и только после этого обращается к `defaultNextScreenId`. Для списков с одиночным выбором и скрытой кнопкой переход совершается автоматически при изменении ответа. Для всех прочих шаблонов пользователь должен нажать действие, сконфигурированное для текущего экрана. ## Шаблоны экранов Ниже приведено краткое описание каждого шаблона и JSON-поле, которое его конфигурирует. ### Информационный экран (`template: "info"`) Используется для показа статических сообщений, промо-блоков или инструкций. Обязательные поля — `id`, `template`, `title`. Дополнительно поддерживаются: - `description` — расширенный текст под заголовком. - `icon` — эмодзи или картинка. `type` принимает значения `emoji` или `image`, `value` — символ или URL, `size` — `sm | md | lg | xl`. - `bottomActionButton` — описание кнопки внизу, если нужно отличное от дефолтного текста. ```json { "id": "welcome", "template": "info", "title": { "text": "Добро пожаловать" }, "description": { "text": "Заполните короткую анкету, чтобы получить персональное предложение." }, "icon": { "type": "emoji", "value": "👋", "size": "lg" }, "navigation": { "defaultNextScreenId": "question-1" } } ``` Рантайм выводит заголовок по центру, кнопку «Next» (или `defaultTexts.nextButton`) и позволяет вернуться назад, если это разрешено в `header`. Логика описана в `InfoTemplate` и `buildLayoutQuestionProps` — дополнительные параметры (`font`, `color`, `align`) влияют на типографику.【F:src/components/funnel/templates/InfoTemplate.tsx†L1-L99】【F:src/lib/funnel/types.ts†L74-L131】 ### Экран с вопросом и вариантами (`template: "list"`) Базовый интерактивный экран. Поле `list` описывает варианты ответов: ```json { "id": "question-1", "template": "list", "title": { "text": "Какой формат подходит?" }, "subtitle": { "text": "Можно выбрать несколько", "color": "muted" }, "list": { "selectionType": "multi", // или "single" "options": [ { "id": "opt-online", "label": "Онлайн" }, { "id": "opt-offline", "label": "Офлайн", "description": "в вашем городе" } ], "bottomActionButton": { "text": "Сохранить выбор" } }, "bottomActionButton": { "show": false }, "navigation": { "defaultNextScreenId": "calendar", "rules": [ { "nextScreenId": "coupon", "conditions": [{ "screenId": "question-1", "operator": "includesAll", "optionIds": ["opt-online", "opt-offline"] }] } ] } } ``` Особенности: - `selectionType` определяет поведение: `single` строит радиокнопки, `multi` — чекбоксы. Компоненты `RadioAnswersList` и `SelectAnswersList` получают подготовленные данные из `mapListOptionsToButtons`. - Кнопка действия может описываться либо на уровне `list.bottomActionButton`, либо через общий `bottomActionButton`. В рантайме она скрывается, если `show: false`. Для списков с одиночным выбором и скрытой кнопкой включается автопереход на следующий экран при изменении ответа.【F:src/components/funnel/templates/ListTemplate.tsx†L1-L109】【F:src/components/funnel/FunnelRuntime.tsx†L73-L199】 - Ответы сохраняются в массиве строк (идентификаторы опций) и используются навигацией и аналитикой. ### Экран выбора даты (`template: "date"`) Предлагает три выпадающих списка (месяц, день, год) и опциональный блок с отформатированной датой. ```json { "id": "calendar", "template": "date", "title": { "text": "Когда планируете начать?" }, "subtitle": { "text": "Выберите ориентировочную дату", "color": "muted" }, "dateInput": { "monthLabel": "Месяц", "dayLabel": "День", "yearLabel": "Год", "showSelectedDate": true, "selectedDateLabel": "Вы выбрали" }, "infoMessage": { "text": "Мы не будем делиться датой с третьими лицами." }, "navigation": { "defaultNextScreenId": "contact" } } ``` Особенности: - Значение сохраняется как массив `[month, day, year]` внутри `answers` рантайма. - Кнопка «Next» активируется только после заполнения всех полей. Настройка текстов и подсказок — через объект `dateInput` (placeholder, label, формат для превью). - При `showSelectedDate: true` под кнопкой появляется подтверждающий блок с читабельной датой.【F:src/components/funnel/templates/DateTemplate.tsx†L1-L209】【F:src/lib/funnel/types.ts†L133-L189】 ### Экран формы (`template: "form"`) Подходит для сбора контактных данных. Поле `fields` содержит список текстовых инпутов со своими правилами. ```json { "id": "contact", "template": "form", "title": { "text": "Оставьте контакты" }, "fields": [ { "id": "name", "label": "Имя", "required": true, "maxLength": 60 }, { "id": "email", "label": "E-mail", "type": "email", "validation": { "pattern": "^\\S+@\\S+\\.\\S+$", "message": "Введите корректный e-mail" } } ], "validationMessages": { "required": "Поле ${field} обязательно", "invalidFormat": "Неверный формат" }, "navigation": { "defaultNextScreenId": "coupon" } } ``` Особенности рантайма: - Локальное состояние синхронизируется с глобальным через `onFormDataChange` — данные сериализуются в JSON-строку и хранятся в массиве ответов (первый элемент).【F:src/components/funnel/FunnelRuntime.tsx†L46-L118】 - Кнопка продолжения (`defaultTexts.continueButton` или «Continue») активна, если все обязательные поля заполнены. Валидаторы проверяют `required`, `maxLength` и регулярное выражение из `validation.pattern` с кастомными сообщениями.【F:src/components/funnel/templates/FormTemplate.tsx†L1-L119】【F:src/lib/funnel/types.ts†L191-L238】 ### Экран промокода (`template: "coupon"`) Отображает купон с акцией и позволяет скопировать промокод. ```json { "id": "coupon", "template": "coupon", "title": { "text": "Поздравляем!" }, "subtitle": { "text": "Получите скидку" }, "coupon": { "title": { "text": "Скидка 20%" }, "offer": { "title": { "text": "-20% на первый заказ" }, "description": { "text": "Действует до конца месяца" } }, "promoCode": { "text": "START20" }, "footer": { "text": "Скопируйте код и введите при оформлении" } }, "copiedMessage": "Код {code} скопирован!", "navigation": { "defaultNextScreenId": "final-info" } } ``` `CouponTemplate` копирует код в буфер обмена и показывает уведомление `copiedMessage` (строка с подстановкой `{code}`). Кнопка продолжения использует `defaultTexts.continueButton` или значение «Continue».【F:src/components/funnel/templates/CouponTemplate.tsx†L1-L111】【F:src/lib/funnel/types.ts†L191-L230】 ## Конструктор (Builder) Конструктор помогает собирать JSON-конфигурацию и состоит из трёх основных областей: 1. **Верхняя панель** (`BuilderTopBar`). Позволяет создать пустой проект, загрузить готовый JSON и экспортировать текущую конфигурацию. Импорт использует `deserializeFunnelDefinition`, добавляющий служебные координаты для канваса. Экспорт сериализует состояние обратно в формат `FunnelDefinition` (`serializeBuilderState`).【F:src/components/admin/builder/BuilderTopBar.tsx†L1-L79】【F:src/lib/admin/builder/utils.ts†L1-L58】 2. **Канвас** (`BuilderCanvas`). Отображает экраны цепочкой, даёт возможность добавлять новые (`add-screen`), менять порядок drag-and-drop (`reorder-screens`) и выбирать экран для редактирования. Каждый экран показывает тип шаблона, количество опций и ссылку на следующий экран по умолчанию.【F:src/components/admin/builder/BuilderCanvas.tsx†L1-L132】 3. **Боковая панель** (`BuilderSidebar`). Содержит две вкладки состояния: - Когда экран не выбран, показываются настройки воронки (ID, заголовок, описание, стартовый экран) и сводка валидации (`validateBuilderState`).【F:src/components/admin/builder/BuilderSidebar.tsx†L1-L188】【F:src/lib/admin/builder/validation.ts†L1-L168】 - Для выбранного экрана доступны поля заголовков, параметры списка (тип выбора, опции), правила навигации, кастомизация кнопок и инструмент удаления. Все изменения отправляются через `update-screen`, `update-navigation` и вспомогательные обработчики, формируя корректный JSON. ### Предпросмотр Компонент `BuilderPreview` визуализирует выбранный экран, используя те же шаблоны, что и боевой рантайм (`ListTemplate`, `InfoTemplate` и др.). Для симуляции действий используются заглушки — выбор опций, заполнение формы и навигация обновляют локальное состояние предпросмотра, но не меняют структуру воронки. При переключении экрана состояние сбрасывается, что позволяет увидеть дефолтное поведение каждого шаблона.【F:src/components/admin/builder/BuilderPreview.tsx†L1-L123】 ### Валидация и сериализация `validateBuilderState` проверяет уникальность идентификаторов экранов и опций, корректность ссылок в навигации и наличие переходов. Ошибки и предупреждения отображаются в боковой панели. При экспорте координаты канваса удаляются, чтобы JSON соответствовал ожиданиям рантайма. Ответы пользователей рантайм хранит в структуре `Record`, где ключ — `id` экрана, а значение — массив выбранных значений (опций, компонентов даты или сериализованные данные формы).【F:src/lib/admin/builder/validation.ts†L1-L168】【F:src/lib/admin/builder/utils.ts†L1-L86】【F:src/components/funnel/FunnelRuntime.tsx†L1-L215】 ## Рабочий процесс 1. Создайте экраны через верхнюю панель или кнопку на канвасе. Каждый новый экран получает уникальный ID (`screen-{n}`). 2. Настройте порядок переходов drag-and-drop и установите `firstScreenId`, если стартовать нужно не с первого элемента. 3. Заполните контент для каждого шаблона, настройте условия в `navigation.rules` и убедитесь, что `defaultNextScreenId` указан для веток без правил. 4. Проверьте сводку валидации — при ошибках экспорт JSON будет возможен, но рантайм может не смочь построить маршрут. 5. Экспортируйте JSON и передайте его рантайму (``). Такой подход гарантирует, что конструктор и рантайм используют одну и ту же схему данных, а визуальные шаблоны ведут себя предсказуемо при изменении конфигурации.