# Компонент SuccessModal - Полная документация

## Назначение компонента

`SuccessModal` - компонент модального окна для отображения успешных операций, подтверждений и уведомлений. Предоставляет стандартизированный интерфейс для информирования пользователя о успешном выполнении действий с возможностью кастомизации контента и поведения.

## git репозитарий
https://gogs.osvoj.ru/s5l.ru/borbad.s5l.ru/src/master/vue/app/shared/SuccessModal/

## Импорт и регистрация

```coffee
# В основном файле приложения (app/temp.coffee)
components:
    'success-modal': require 'app/shared/SuccessModal'
```

## Базовое использование

### 1. Простое модальное окно
```pug
success-modal(
    :show="showSuccess"
    title="Операция выполнена"
    message="Данные успешно сохранены"
    @close="showSuccess = false"
)
```

### 2. Модальное окно с кастомными действиями
```pug
success-modal(
    :show="showSuccess"
    title="Заказ оформлен"
    message="Ваш заказ успешно создан и передан в обработку"
    @close="handleOrderSuccess"
)
```

## Полный список props

### `show` (обязательный)
- **Тип:** `Boolean`
- **Описание:** Управляет видимостью модального окна
- **Пример:**
  ```pug
  success-modal(:show="isModalVisible" @close="isModalVisible = false")
  ```

### `title` (опциональный)
- **Тип:** `String`
- **По умолчанию:** `'Успешно!'`
- **Описание:** Заголовок модального окна
- **Пример:**
  ```pug
  success-modal(:show="showModal" title="Профиль обновлен")
  ```

### `message` (опциональный)
- **Тип:** `String`
- **По умолчанию:** `''`
- **Описание:** Основное сообщение модального окна
- **Пример:**
  ```pug
  success-modal(
      :show="showModal"
      message="Изменения успешно сохранены и применены к вашему профилю"
  )
  ```

### `buttonText` (опциональный)
- **Тип:** `String`
- **По умолчанию:** `'Понятно'`
- **Описание:** Текст на кнопке подтверждения
- **Пример:**
  ```pug
  success-modal(:show="showModal" buttonText="Отлично!")
  ```

### `icon` (опциональный)
- **Тип:** `String`
- **По умолчанию:** `'check-circle'`
- **Описание:** Название иконки для отображения
- **Допустимые значения:** Любое название иконки из используемой иконной библиотеки
- **Пример:**
  ```pug
  success-modal(:show="showModal" icon="check")
  ```

### `size` (опциональный)
- **Тип:** `String`
- **По умолчанию:** `'md'`
- **Описание:** Размер модального окна
- **Допустимые значения:** `'sm'`, `'md'`, `'lg'`, `'xl'`
- **Пример:**
  ```pug
  success-modal(:show="showModal" size="lg")
  ```

### `closeOnBackdrop` (опциональный)
- **Тип:** `Boolean`
- **По умолчанию:** `true`
- **Описание:** Закрывать ли модальное окно при клике на бэкдроп
- **Пример:**
  ```pug
  success-modal(:show="showModal" :closeOnBackdrop="false")
  ```

### `showCloseButton` (опциональный)
- **Тип:** `Boolean`
- **По умолчанию:** `true`
- **Описание:** Показывать ли кнопку закрытия в заголовке
- **Пример:**
  ```pug
  success-modal(:show="showModal" :showCloseButton="false")
  ```

### `autoClose` (опциональный)
- **Тип:** `Boolean | Number`
- **По умолчанию:** `false`
- **Описание:** Автоматическое закрытие модального окна. Если `true` - 3000ms, если число - указанное время в ms
- **Примеры:**
  ```pug
  success-modal(:show="showModal" :autoClose="true") // Закроется через 3 секунды
  success-modal(:show="showModal" :autoClose="5000") // Закроется через 5 секунд
  ```

## События (Events)

### `@close`
- **Описание:** Событие закрытия модального окна
- **Payload:** `null`
- **Когда вызывается:**
  - Клик на кнопку закрытия
  - Клик на бэкдроп (если `closeOnBackdrop = true`)
  - Нажатие клавиши ESC
  - Автоматическое закрытие (если `autoClose` включен)
- **Пример:**
  ```pug
  success-modal(:show="showModal" @close="handleModalClose")
  ```

### `@confirm`
- **Описание:** Событие подтверждения (клик на основную кнопку)
- **Payload:** `null`
- **Пример:**
  ```pug
  success-modal(:show="showModal" @confirm="handleSuccessAction")
  ```

## Слоты (Slots)

### `[body]` (основной слот)
- **Описание:** Кастомное содержимое модального окна вместо стандартного message
- **Примеры:**
  ```pug
  success-modal(:show="showModal" title="Заказ оформлен")
      div(class="space-y-4")
          p Ваш заказ №{{ orderId }} успешно создан
          div(class="bg-gray-50 p-4 rounded")
              h4(class="font-semibold") Детали заказа:
              p Сумма: {{ orderAmount }} TJS
              p Статус: В обработке
  ```

### `[icon]` (опциональный)
- **Описание:** Кастомная иконка вместо стандартной
- **Пример:**
  ```pug
  success-modal(:show="showModal")
      template([icon])
          div(class="w-16 h-16 bg-green-100 rounded-full flex items-center justify-center")
              icon(name="trophy" class="w-8 h-8 text-green-600")
  ```

### `[actions]` (опциональный)
- **Описание:** Кастомные действия вместо стандартной кнопки
- **Пример:**
  ```pug
  success-modal(:show="showModal" title="Заказ создан")
      template([actions])
          div(class="flex space-x-3")
              button(
                  @click="$emit('close')"
                  class="px-4 py-2 border border-gray-300 rounded hover:bg-gray-50"
              ) Закрыть
              app-link(
                  to="/orders"
                  class="app-link--primary"
              ) Перейти к заказам
              app-link(
                  to="/products"
                  class="app-link--secondary"
              ) Продолжить покупки
  ```

## Примеры использования в различных сценариях

### 1. Успешное создание заказа
```pug
success-modal(
    :show="orderSuccess"
    title="Заказ оформлен!"
    message="Ваш заказ успешно создан. Номер заказа: #12345"
    icon="shopping-bag"
    @close="handleOrderSuccessClose"
)
```

### 2. Успешная регистрация
```pug
success-modal(
    :show="registrationSuccess"
    title="Добро пожаловать!"
    message="Регистрация завершена успешно. На ваш email отправлено письмо с подтверждением."
    buttonText="Начать"
    @confirm="redirectToDashboard"
)
```

### 3. Успешное сохранение настроек
```pug
success-modal(
    :show="settingsSaved"
    title="Настройки сохранены"
    message="Изменения в настройках профиля успешно применены"
    autoClose="2000"
    @close="resetSettingsState"
)
```

### 4. Кастомное модальное окно с дополнительной информацией
```pug
success-modal(
    :show="showCustomSuccess"
    title="Билеты забронированы"
    size="lg"
)
    div(class="space-y-4")
        p(class="text-lg") Ваши билеты успешно забронированы!
        
        div(class="bg-blue-50 border border-blue-200 rounded-lg p-4")
            h4(class="font-semibold text-blue-900 mb-2") Важная информация:
            ul(class="list-disc list-inside space-y-1 text-blue-800")
                li Сохраните QR-код из письма
                li Приходите за 30 минут до начала
                li Иметь при себе документ, удостоверяющий личность
        
        p(class="text-sm text-gray-600") Подробности отправлены на ваш email

    template([actions])
        div(class="flex flex-col sm:flex-row gap-3")
            button(
                @click="$emit('close')"
                class="px-6 py-3 border border-gray-300 rounded-lg hover:bg-gray-50 flex-1"
            ) Закрыть
            app-link(
                to="/tickets"
                class="app-link--primary text-center flex-1"
            ) Мои билеты
```

### 5. Модальное окно с автоматическим закрытием
```pug
success-modal(
    :show="showAutoClose"
    title="Форма отправлена"
    message="Ваше сообщение успешно отправлено. Мы свяжемся с вами в ближайшее время."
    autoClose="4000"
    @close="resetContactForm"
)
```

### 6. Модальное окно без возможности закрытия
```pug
success-modal(
    :show="processingComplete"
    title="Обработка завершена"
    message="Все данные успешно обработаны и сохранены в системе."
    :closeOnBackdrop="false"
    :showCloseButton="false"
    @confirm="redirectToNextStep"
)
```

## Интеграция с глобальным состоянием приложения

### Использование через EventBus
```coffee
# В компоненте
methods:
    showSuccessModal: (title, message) ->
        EventBus.emit('show_success_modal', { title, message })

# В основном приложении (app/temp.coffee)
EventBus.on 'show_success_modal', (data) ->
    _.openModal('success-modal', data)
```

### Использование с глобальным modalState
```pug
success-modal(
    :show="_.modalState.isVisible && _.modalState.component === 'success-modal'"
    :title="_.modalState.props.title"
    :message="_.modalState.props.message"
    @close="_.closeModal()"
)
```

## Стили и кастомизация

### Размеры модального окна
```pug
//- Маленький (sm)
success-modal(:show="showModal" size="sm")

//- Средний (md) - по умолчанию
success-modal(:show="showModal" size="md")

//- Большой (lg)
success-modal(:show="showModal" size="lg")

//- Очень большой (xl)
success-modal(:show="showModal" size="xl")
```

### Кастомные CSS классы
Компонент поддерживает стандартные классы Tailwind CSS для дополнительной стилизации:

```pug
success-modal(
    :show="showModal"
    class="success-modal-custom"
)
```

## Особенности поведения

### Управление фокусом
- Автоматически фокусируется на кнопке подтверждения при открытии
- Захватывает фокус внутри модального окна (accessibility)
- Возвращает фокус предыдущему элементу при закрытии

### Обработка клавиатуры
- **ESC** - закрывает модальное окно
- **Enter** - активирует основную кнопку
- **Tab** - циклическое перемещение по фокусируемым элементам внутри модального окна

### Анимации
- Плавное появление и исчезновение
- Анимация масштабирования
- Затемнение фона с переходом

## Best Practices

### 1. Всегда обрабатывайте событие закрытия
```pug
//- Правильно
success-modal(:show="showModal" @close="showModal = false")

//- Опасно (модальное окно не сможет закрыться)
success-modal(:show="showModal")
```

### 2. Используйте autoClose для временных уведомлений
```pug
//- Для кратковременных сообщений
success-modal(
    :show="showTempMessage"
    message="Настройки сохранены"
    autoClose="2000"
    @close="showTempMessage = false"
)
```

### 3. Предоставляйте понятные заголовки и сообщения
```pug
//- Хорошо
success-modal(
    :show="showSuccess"
    title="Профиль обновлен"
    message="Изменения в вашем профиле успешно сохранены и применены"
)

//- Плохо
success-modal(:show="showSuccess" message="Успешно")
```

### 4. Используйте слоты для сложного контента
```pug
//- Вместо длинного message
success-modal(:show="showComplex" title="Отчет готов")
    div(class="space-y-3")
        p Отчет успешно сгенерирован и содержит:
        ul(class="list-disc list-inside")
            li 25 записей о мероприятиях
            li Статистику посещаемости
            li Финансовые показатели
        p(class="text-sm text-gray-600") Файл доступен для скачивания в вашем кабинете
```

### 5. Соответствуйте контексту действия
```pug
//- Для финансовых операций
success-modal(
    :show="paymentSuccess"
    title="Платеж выполнен"
    icon="credit-card"
    buttonText="Перейти к заказу"
)

//- Для создания контента
success-modal(
    :show="contentCreated"
    title="Материал опубликован"
    icon="edit"
    buttonText="Посмотреть"
)
```

## Отладка и разработка

### Проверка состояния модального окна
```coffee
# В методах компонента
checkModalState: ->
    debug.log "Modal visible: "+@show
    debug.log "Modal title: "+@title
    debug.log "Modal message: "+@message
```

### Отслеживание событий
```coffee
# В основном приложении
EventBus.on 'success_modal_closed', (data) ->
    debug.log "Success modal closed"

EventBus.on 'success_modal_confirmed', (data) ->
    debug.log "Success modal confirmed"
```

Компонент SuccessModal предоставляет унифицированный и гибкий способ отображения успешных операций в приложении, обеспечивая согласованный пользовательский опыт и широкие возможности для кастомизации под конкретные сценарии использования.