GuidedTour.tsx

Обзор

GuidedTour.tsx — это React-компонент, реализующий интерактивный пошаговый гид (тур) для пользователей приложения. Его основное назначение — провести пользователя через ключевые элементы интерфейса с подсказками, выделить важные области, и предоставить контекстно-зависимые советы и инструкции. Компонент поддерживает несколько «персон» (типов пользователей), для каждой из которых предусмотрен свой набор шагов и рекомендации.

Функциональность включает:

Отображение всплывающих подсказок с информацией и действиями.
Выделение элементов интерфейса с помощью подсветки.
Автоматическое позиционирование подсказок относительно целевых элементов.
Управление навигацией между шагами тура.
Обработка событий пропуска и завершения тура.
Адаптация отображения под различные роли пользователя (persona).

Классы и типы

Интерфейс `TourStep`

Определяет структуру одного шага тура.

Поле	Тип	Описание
`id`	`string`	Уникальный идентификатор шага.
`target`	`string`	CSS-селектор элемента, к которому будет привязана подсказка.
`title`	`string`	Заголовок подсказки.
`content`	`string`	Основной текст подсказки.
`position`	`'top'	'bottom'
`action?`	`string` (необязательно)	Текст действия, которое рекомендуется выполнить на этом шаге.
`highlight?`	`boolean` (необязательно)	Флаг, указывающий, нужно ли выделять целевой элемент визуально.

Интерфейс `GuidedTourProps`

Пропсы компонента GuidedTour.

Поле	Тип	Описание
`steps`	`TourStep[]`	Массив шагов тура, описывающих последовательность подсказок.
`isActive`	`boolean`	Флаг активности тура (отображается ли тур в данный момент).
`onComplete`	`() => void`	Коллбэк, вызываемый при успешном завершении тура.
`onSkip`	`() => void`	Коллбэк, вызываемый при пропуске тура пользователем.
`persona`	`string`	Тип пользователя/персоны (например, "casual_gamer", "power_user", "validator").

Компонент `GuidedTour`

Описание

Основной React-функциональный компонент, который управляет отображением и поведением пошагового гида.

Внутреннее состояние

currentStep: number — индекс текущего шага в массиве steps.
tooltipPosition: { x: number, y: number } — координаты положения подсказки на экране.
isVisible: boolean — видимость подсказки и оверлея.
tooltipRef — реф на DOM-элемент подсказки.
overlayRef — реф на DOM-элемент затемнённого оверлея.

Основные методы и функции

`updateTooltipPosition()`

Обновляет координаты подсказки на основе положения целевого элемента на странице и выбранной позиции (top, bottom, left, right).
Обеспечивает, чтобы подсказка не выходила за границы окна браузера.
Если для шага задан флаг highlight, вызывает highlightElement для подсветки целевого элемента.

`highlightElement(element: Element)`

Удаляет подсветку с любых ранее выделенных элементов.
Добавляет класс tour-highlight к текущему целевому элементу.
Прокручивает страницу так, чтобы целевой элемент оказался по центру видимой области.

`nextStep()`

Переходит к следующему шагу тура, если он существует.
Если это последний шаг, вызывает completeTour().

`prevStep()`

Возвращается к предыдущему шагу, если он существует.

`completeTour()`

Убирает все подсветки.
Скрывает подсказку.
Вызывает onComplete коллбэк.

`skipTour()`

Аналогично completeTour(), но вызывает onSkip коллбэк.

Жизненный цикл и эффекты

При изменении isActive, currentStep или steps обновляется видимость подсказки и позиция.
При изменении размера окна, если тур активен, пересчитывается позиция подсказки.

Рендеринг

Если тур неактивен или нет текущего шага — возвращается null.
Отрисовывается затемнённый оверлей, блокирующий взаимодействие с остальной страницей.
Отображается подсказка с:
- Стрелкой, указывающей на целевой элемент.
- Заголовком с номером шага.
- Основным текстом и, при необходимости, дополнительным блоком с описанием действия.
- Специальные советы, зависящие от persona (например, советы для новичков, продвинутых пользователей и валидаторов).
- Навигационными кнопками: Назад, Пропустить тур, Далее / Завершить.
- Индикатором прогресса (прогресс-баром).

Пример использования

import GuidedTour, { tourSteps } from './GuidedTour';

function App() {
  const [tourActive, setTourActive] = React.useState(true);

  const handleComplete = () => {
    console.log('Тур завершён');
    setTourActive(false);
  };

  const handleSkip = () => {
    console.log('Тур пропущен');
    setTourActive(false);
  };

  return (
    <div>
      <GuidedTour
        steps={tourSteps.casual_gamer}
        isActive={tourActive}
        onComplete={handleComplete}
        onSkip={handleSkip}
        persona="casual_gamer"
      />
      {/* остальная часть приложения */}
    </div>
  );
}

Важные детали реализации

Подсказки позиционируются динамически относительно целевых элементов, учитывая размеры окна и элементы.
Подсветка реализована через добавление CSS-класса с тенями и анимацией пульсации.
Используется scrollIntoView с плавной прокруткой для удобства пользователя.
Управление шагами тура происходит через внутреннее состояние React (useState).
Обработчики событий (resize, кнопки навигации) корректно очищаются и обновляются.
Визуальный стиль подсказок использует Tailwind CSS классы иконок из lucide-react.

Взаимодействие с другими частями системы

Компонент требует, чтобы в DOM присутствовали элементы с селекторами, указанными в шагах тура (target в TourStep).
Используется в приложении для обучения пользователей, демонстрации ключевых возможностей и повышения вовлечённости.
Передаёт события завершения и пропуска через коллбэки onComplete и onSkip для дальнейшей обработки (например, сохранения состояния или аналитики).
Использует иконки из библиотеки lucide-react для визуального оформления.

Наборы шагов тура для разных персон

Экспортируется объект tourSteps с предопределёнными наборами шагов для трёх типов пользователей:

casual_gamer — простой и дружелюбный тур для обычных игроков.
power_user — более продвинутый тур с акцентом на сложные функции.
validator — технический тур для пользователей, участвующих в валидации блокчейна.

Каждый набор содержит 4-6 шагов с выделением и действиями.

Mermaid-диаграмма структуры компонента

classDiagram
    class GuidedTour {
        -currentStep: number
        -tooltipPosition: { x: number, y: number }
        -isVisible: boolean
        -tooltipRef: RefObject<HTMLDivElement>
        -overlayRef: RefObject<HTMLDivElement>
        +GuidedTour(props: GuidedTourProps)
        +updateTooltipPosition(): void
        +highlightElement(element: Element): void
        +nextStep(): void
        +prevStep(): void
        +completeTour(): void
        +skipTour(): void
        +render(): JSX.Element | null
    }

    class TourStep {
        +id: string
        +target: string
        +title: string
        +content: string
        +position: 'top' | 'bottom' | 'left' | 'right'
        +action?: string
        +highlight?: boolean
    }

    class GuidedTourProps {
        +steps: TourStep[]
        +isActive: boolean
        +onComplete: () => void
        +onSkip: () => void
        +persona: string
    }

    GuidedTour ..> GuidedTourProps
    GuidedTourProps ..> TourStep

Итог

GuidedTour.tsx — это мощный и гибкий компонент для организации интерактивных обучающих туров в React-приложениях. Его адаптивность под разные типы пользователей и динамическое позиционирование подсказок делают его удобным инструментом для улучшения пользовательского опыта при знакомстве с функционалом.