Подробные комментарии ко всем JS-файлам фронтенда

site/static/js/snackbar.js

@@ -1,28 +1,47 @@
-// snackbar.js — лёгкие уведомления (без зависимостей)
-// showSnackbar(msg, type='info') — type: info, success, error
+// snackbar.js — лёгкие toast-уведомления (без зависимостей)
+//
+// Использование: showSnackbar('Сообщение', 'success')
+// Типы: 'info' (по умолчанию), 'success', 'error'
+//
+// Поведение:
+//   - Показывается в правом нижнем углу (position: fixed)
+//   - Автоматически исчезает: info/success через 4с, error через 8с
+//   - Клик по уведомлению — мгновенное закрытие
+//   - Максимум 4 уведомления одновременно (старые удаляются)
 
+/**
+ * Показать snackbar-уведомление.
+ *
+ * @param {string} msg  — текст уведомления
+ * @param {string} type — 'info' | 'success' | 'error' (по умолчанию 'info')
+ */
 function showSnackbar(msg, type) {
     type = type || 'info';
+
+    // Найти или создать контейнер для всех уведомлений
     let container = document.getElementById('snackbar-container');
     if (!container) {
         container = document.createElement('div');
         container.id = 'snackbar-container';
         container.className = 'snackbar-container';
-        container.setAttribute('role', 'status');
-        container.setAttribute('aria-live', 'polite');
+        container.setAttribute('role', 'status');      // accessibility
+        container.setAttribute('aria-live', 'polite'); // screen-reader зачитает
         document.body.appendChild(container);
     }
+
+    // Создать элемент уведомления
     const el = document.createElement('div');
     el.className = 'snackbar ' + type;
     el.textContent = msg;
+    // Клик — закрыть
     el.onclick = function() { el.remove(); };
     container.appendChild(el);
 
-    // Limit stacking
+    // Ограничение: максимум 4 уведомления
     const all = container.querySelectorAll('.snackbar');
-    if (all.length > 4) all[0].remove();
+    if (all.length > 4) all[0].remove();  // удаляем самое старое
 
-    // Auto-hide: info/success 4s, error 8s
+    // Автоматическое скрытие: error — 8 секунд, остальные — 4
     const delay = (type === 'error') ? 8000 : 4000;
     setTimeout(function() {
         if (el.parentNode) el.remove();