Corp/backend/docs/guides/BUBBLE_REFACTORING.md

Рефакторинг архитектуры .bubble - BEM миграция

Дата: 21 января 2026
Статус: ✅ Завершено

📋 Обзор изменений

Проведен полный рефакторинг системы стилей для сообщений чата с переходом на BEM-методологию и CSS-переменные.

Было

// Хаотичное распределение по файлам
.bubble { }
.bubble-me { }
.bubble-other { }
.msg .bubble { }
.bubble .attachment-item { }
// + использование !important
// + глубокая вложенность (4+ уровня)
// + конфликты white-space

Стало

// Модульная BEM-архитектура
.bubble { }                 // Базовый блок
.bubble--me { }             // Модификатор типа
.bubble--other { }          // Модификатор типа
.bubble__content { }        // Элемент
.bubble__attachment { }     // Элемент
.bubble--pending { }        // Модификатор состояния

---

🗂️ Структура новых файлов

1. _bubble-base.scss - Базовый блок

Назначение: Структурные и типографские свойства без цветовой темизации

.bubble {
  display: block;
  border-radius: $radius-lg;
  padding: var(--space-1) var(--space-2);
  max-width: 70%;
  white-space: pre-line;
  
  // Темизация через CSS-переменные
  background: var(--bubble-bg);
  color: var(--bubble-text);
}

Элементы:

• .bubble__author - Имя автора
• .bubble__content - Текст сообщения
• .bubble__edited - Индикатор редактирования
• .bubble__time - Время отправки
• .bubble__attachments - Контейнер вложений
• .bubble__poll - Контейнер голосования
• .bubble__reply-preview - Превью ответа
• .bubble__reactions - Контейнер реакций

2. _bubble-variants.scss - Модификаторы типов

Назначение: Цветовая темизация для разных типов сообщений

Модификаторы:

• .bubble--me - Мои сообщения (синий фон)
• .bubble--other - Чужие сообщения (серый фон)
• .bubble--system - Системные сообщения (пунктирная рамка)
• .bubble--pending - В процессе отправки (spinner)
• .bubble--failed - Ошибка отправки (красная рамка)
• .bubble--deleted - Удалённое сообщение (зачеркнутое)

Примеры CSS-переменных:

.bubble--me {
  --bubble-bg: color-mix(in srgb, var(--bs-primary) 92%, #fff);
  --bubble-text: #fff;
  --bubble-attachment-bg: rgba(255, 255, 255, 0.15);
  --bubble-poll-progress-bg: rgba(255, 255, 255, 0.2);
}

3. _bubble-content.scss - Вложенный контент

Назначение: Стили для attachments, polls, media внутри bubble

Компоненты:

• .bubble__attachment--media - Изображения и видео
• .bubble__attachment--file - Документы с иконками
• .bubble__attachment--audio - Аудио-плеер
• .bubble__poll - Виджет голосования
• .bubble__reactions - Реакции пользователей
• .bubble__link-preview - Open Graph превью

4. _bubble-states.scss - Интерактивные состояния

Назначение: Hover, focus, selection, drag&drop состояния

Компоненты:

• .msg__actions - Панель действий при hover
• .msg__quick-reactions - Быстрые реакции при hover
• .msg--selected - Выделенное сообщение
• .msg--selectable - Режим множественного выделения
• .msg--dragging - В процессе перетаскивания

---

🔄 Таблица миграции классов

HTML классы

Старый класс	Новый класс	Комментарий
.bubble	.bubble	Базовый класс остался
.bubble-me	.bubble--me	BEM модификатор
.bubble-other	.bubble--other	BEM модификатор
.message-author	.bubble__author	BEM элемент
.message-content	.bubble__content	BEM элемент
.edited-indicator	.bubble__edited	BEM элемент
.message-time	.bubble__time	BEM элемент
.message-attachments	.bubble__attachments	BEM элемент
.attachment-item	.bubble__attachment	BEM элемент
.message-reply-preview	.bubble__reply-preview	BEM элемент
.message-reactions	.bubble__reactions	BEM элемент
.message-actions	.msg__actions	Изменен контекст
.quick-reactions	.msg__quick-reactions	Изменен контекст
.msg.new	.bubble--animating	BEM модификатор
.message-pending	.bubble--pending	BEM модификатор
.message-failed	.bubble--failed	BEM модификатор

JavaScript селекторы

Старый селектор	Новый селектор
.querySelector('.bubble')	.querySelector('.bubble')
.classList.add('bubble-me')	.classList.add('bubble--me')
.querySelector('.message-content')	.querySelector('.bubble__content')
.querySelector('.message-attachments')	.querySelector('.bubble__attachments')

---

🛠️ Измененные файлы

Созданы новые файлы

✅ backend/static/scss/components/chat/_bubble-base.scss (180 строк)
✅ backend/static/scss/components/chat/_bubble-variants.scss (150 строк)
✅ backend/static/scss/components/chat/_bubble-content.scss (220 строк)
✅ backend/static/scss/components/chat/_bubble-states.scss (210 строк)

Обновлены существующие файлы

✅ backend/static/scss/custom-bootstrap.scss - добавлены импорты
✅ backend/static/scss/components/chat/_chat-enhanced.scss - удалены дубликаты
✅ backend/static/js/renderers/messageRendererV2.js - BEM классы в рендерере

Требуют обновления

⚠️ backend/static/scss/components/chat/_chat-detail.scss - удалить старые стили bubble (строки 772-810, 287-360, 412-430, 490-505)
⚠️ backend/static/scss/components/chat/_chat-polls.scss - использовать CSS-переменные вместо .bubble-me/.bubble-other

---

🎯 Преимущества новой архитектуры

1. Модульность

• Каждый аспект в отдельном файле
• Легко найти и изменить стили
• Простое добавление новых модификаторов

2. Переиспользуемость

// Добавить новый тип сообщения - 5 строк
.bubble--draft {
  --bubble-bg: #fffbeb;
  --bubble-text: #92400e;
}

3. Производительность

• Без !important - меньше специфичности
• CSS-переменные вычисляются браузером
• Уменьшен размер итогового CSS (меньше дублирования)

4. Поддерживаемость

// ❌ Было (специфичность 0,0,4,0)
.bubble-me .message-attachments .text-secondary {
  color: #fff !important;
}

// ✅ Стало (специфичность 0,0,1,0)
.bubble__attachment-meta {
  color: var(--bubble-attachment-meta);
}

5. Темизация

Легко добавить темную тему или корпоративные цвета:

[data-theme="dark"] {
  .bubble--me {
    --bubble-bg: #1e3a8a;
  }
  .bubble--other {
    --bubble-bg: #1f2937;
  }
}

---

📝 Рекомендации по использованию

Создание сообщения в JavaScript

// ✅ Правильно
const bubbleModifier = isOwn ? 'bubble--me' : 'bubble--other';
const html = `
  <div class="bubble ${bubbleModifier}">
    <div class="bubble__author">
      <a href="${authorUrl}">${authorName}</a>
    </div>
    <div class="bubble__content">${content}</div>
    <div class="bubble__time">${time}</div>
  </div>
`;

Добавление нового состояния

// _bubble-variants.scss
.bubble--forwarded {
  --bubble-bg: #f0f9ff;
  border-left: 4px solid var(--bs-info);
}

Стилизация вложений

// _bubble-content.scss
.bubble__attachment--video {
  video {
    max-width: 400px;
    border-radius: $radius-md;
  }
}

---

⚠️ Breaking Changes

JavaScript

Необходимо обновить селекторы в следующих файлах:

• backend/static/js/components/chatMarkRead.js
• backend/static/js/components/chatMessageTemplates.js
• backend/static/js/renderers/messageRendererV2.js ✅ Обновлено

SCSS

Если есть кастомные стили, использующие:

• .bubble-me → заменить на .bubble--me
• .bubble-other → заменить на .bubble--other
• .message-attachments → заменить на .bubble__attachments

---

🧪 Тестирование

Чек-лист после миграции

• Отображение своих сообщений (синий фон)
• Отображение чужих сообщений (серый фон)
• Системные сообщения по центру
• Вложения (изображения, файлы, аудио)
• Голосования внутри сообщений
• Реакции под сообщениями
• Reply preview кликабелен
• Hover actions появляются
• Mobile responsive (кнопки всегда видны)
• Анимация новых сообщений
• Pending состояние (spinner)
• Failed состояние (warning icon)
• Выделение сообщений (selection mode)

Команда для проверки SCSS компиляции

cd backend/static
sass scss/custom-bootstrap.scss:css/custom-bootstrap.css --no-source-map

Тестовые сценарии

1. Отправить сообщение
2. Ответить на сообщение (reply)
3. Прикрепить файл
4. Создать голосование
5. Добавить реакцию
6. Открыть на мобильном устройстве

---

🔮 Дальнейшие улучшения

Краткосрочные (1-2 недели)

1. Обновить _chat-detail.scss - удалить старые стили bubble
2. Обновить _chat-polls.scss - использовать CSS-переменные
3. Обновить остальные JS файлы с селекторами bubble
4. Добавить unit-тесты для CSS классов

Среднесрочные (1-2 месяца)

1. Добавить темную тему через CSS-переменные
2. Создать Storybook для bubble компонентов
3. Оптимизировать анимации для low-end устройств
4. Добавить accessibility тесты

Долгосрочные (3+ месяца)

1. Перенести на CSS Container Queries для адаптивности
2. Использовать CSS Cascade Layers для изоляции
3. Добавить View Transitions API для анимаций
4. Создать дизайн-систему на основе bubble

---

📚 Дополнительные ресурсы

• BEM Methodology
• CSS Variables (MDN)
• SCSS Best Practices

---

Автор: GitHub Copilot
Дата создания: 21 января 2026
Версия: 1.0