TutorialTooltip.tsx

Обзор

Файл TutorialTooltip.tsx реализует React-компонент, предназначенный для отображения простого пошагового учебного всплывающего окна (tooltip) с описанием и навигацией между шагами. Этот компонент служит для проведения базового интерактивного обучения пользователя без сложной логики подсветки элементов интерфейса.

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

Составные части файла

Интерфейсы

TutorialStep

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

Свойство	Тип	Описание
`id`	`string`	Уникальный идентификатор шага
`title`	`string`	Заголовок подсказки
`description`	`string`	Текст описания шага
`targetSelector?`	`'string'` (опционально)	CSS-селектор целевого элемента (не используется для позиционирования в этом компоненте)
`position?`	`'top'	'bottom'
`action?`	`'click'	'hover'

TutorialTooltipProps

Определяет свойства, которые принимает компонент TutorialTooltip.

Свойство	Тип	Описание
`steps`	`TutorialStep[]`	Массив шагов туториала
`isActive`	`boolean`	Флаг активности туториала (отображать или нет)
`onComplete`	`() => void`	Коллбэк, вызываемый по завершении всех шагов туториала
`onSkip`	`() => void`	Коллбэк, вызываемый при пропуске всего туториала

Основной компонент: TutorialTooltip

const TutorialTooltip: React.FC<TutorialTooltipProps> = ({
  steps,
  isActive,
  onComplete,
  onSkip,
}) => { ... }

Описание

React-функциональный компонент, реализующий модальное окно с подсказкой для текущего шага из переданного массива steps. Поддерживает навигацию между шагами, отображение прогресса, кнопки управления ("пропустить", "следующий", "предыдущий") и корректно скрывается при завершении или пропуске.

Локальное состояние и эффекты

currentStep (number) — индекс текущего шага в массиве steps.
isVisible (boolean) — внутренний флаг видимости подсказки.

При изменении пропсов isActive и steps происходит эффект:

Если туториал активен и есть шаги, показывается подсказка и устанавливается текущий шаг на 0.
Иначе скрывается подсказка.

Методы компонента

handleNext()
Переход к следующему шагу. Если текущий шаг последний — скрывает подсказку и вызывает onComplete.
handlePrevious()
Переход к предыдущему шагу, если он существует.
handleSkip()
Скрывает подсказку и вызывает onSkip.

Рендеринг

Если подсказка не видима или текущий шаг отсутствует — возвращается null (ничего не отображается).
В противном случае рендерится модальное окно с:
- Затенённым фоном (tutorial-backdrop), который при клике вызывает пропуск туториала.
- Основной подсказкой (tutorial-tooltip) с:
  - Заголовком
  - Кнопкой закрытия (пропустить)
  - Описанием
  - Индикатором прогресса (число текущего шага из общего количества и прогресс-бар)
  - Кнопками навигации: «Предыдущий» (если не первый шаг) и «Следующий» или «Завершить» (если последний шаг).

Параметры и возвращаемые значения

Параметры:
Свойства компонента TutorialTooltipProps (см. выше).
Возвращаемое значение:
React-элемент с UI подсказки либо null.

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

import TutorialTooltip, { BATTLE_TUTORIAL_STEPS } from './TutorialTooltip';

const MyComponent = () => {
  const [tutorialActive, setTutorialActive] = React.useState(true);

  const handleComplete = () => {
    console.log('Tutorial completed');
    setTutorialActive(false);
  };

  const handleSkip = () => {
    console.log('Tutorial skipped');
    setTutorialActive(false);
  };

  return (
    <>
      <button onClick={() => setTutorialActive(true)}>Start Tutorial</button>
      <TutorialTooltip
        steps={BATTLE_TUTORIAL_STEPS}
        isActive={tutorialActive}
        onComplete={handleComplete}
        onSkip={handleSkip}
      />
    </>
  );
};

Предопределённые наборы шагов

В файле экспортируются две константы — массивы шагов для различных разделов приложения.

BATTLE_TUTORIAL_STEPS

Массив шагов для обучения в разделе "Битвы". Содержит базовую информацию о выборе локации, элемента, элементаля и навигации по клавиатуре. Пример шага:

{
  id: 'welcome',
  title: '🎮 Welcome to Elemental Arena!',
  description: 'Learn how to battle with elemental forces! This tutorial will guide you through the battle process step by step.',
}

COLLECTION_TUTORIAL_STEPS

Массив шагов для обучения в разделе "Коллекция". Объясняет работу с коллекцией элементалей, фильтрацию, просмотр карт и улучшение.

Важные подробности реализации

Компонент не реализует подсветку элементов интерфейса и не позиционирует подсказку относительно элементов страницы, несмотря на наличие в TutorialStep поля targetSelector и position. Это упрощённый вариант для общих информационных подсказок.
Визуальные и ARIA-атрибуты обеспечивают доступность модального окна (роль dialog, описания и заголовки).
Прогресс-бар динамически отображает процент выполнения туториала.
Кнопка закрытия и клик по затемнённому фону вызывают один и тот же обработчик пропуска.
Навигация по шагам реализована локально с помощью useState.

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

Этот компонент обычно используется в связке с более сложным компонентом StepByStepTutorial.tsx, который реализует полнофункциональный пошаговый туториал с подсветкой и позиционированием.
TutorialTooltip подходит для простых секций обучения, где достаточно показать серию подсказок без привязки к элементам интерфейса.
Константы BATTLE_TUTORIAL_STEPS и COLLECTION_TUTORIAL_STEPS могут импортироваться и использоваться из других модулей для запуска соответствующих обучающих последовательностей.
В системе обучения и поддержки пользователя этот компонент служит простым и универсальным средством показа последовательных подсказок.

Диаграмма структуры компонента

classDiagram
    class TutorialTooltip {
        - currentStep: number
        - isVisible: boolean
        + handleNext(): void
        + handlePrevious(): void
        + handleSkip(): void
        + render(): ReactElement | null
    }

    class TutorialStep {
        + id: string
        + title: string
        + description: string
        + targetSelector?: string
        + position?: 'top' | 'bottom' | 'left' | 'right'
        + action?: 'click' | 'hover' | 'focus'
    }

    class TutorialTooltipProps {
        + steps: TutorialStep[]
        + isActive: boolean
        + onComplete(): void
        + onSkip(): void
    }

    TutorialTooltip "1" o-- "*" TutorialStep : steps
    TutorialTooltip "1" -- TutorialTooltipProps : props

Итог

Компонент TutorialTooltip.tsx предоставляет базовую функциональность для отображения пошаговых учебных подсказок в приложении. Он ориентирован на простоту и универсальность, без сложной логики взаимодействия с DOM-элементами и позиционирования. Это позволяет быстро встроить обучающие сообщения в различные части интерфейса, дополняя более сложные модули обучения.

В связке с предопределёнными наборами шагов и коллбэками на завершение или пропуск, данный компонент помогает организовать удобное и понятное обучение пользователей.