@omnisass/library 0.2.1 → 0.4.0

package/modules/utilities/getters/misc/_get-uid.scss

@@ -0,0 +1,135 @@
+@use 'sass:math';
+@use 'sass:string';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-number' as *;
+@use '../../validators/type-of/is-string' as *;
+
+/// Генерирует уникальный строковый идентификатор с префиксом.
+///
+/// Функция создает гарантированно уникальный идентификатор,
+/// комбинируя пользовательский префикс, случайное число и
+/// встроенный уникальный временной штамп Sass. Это позволяет
+/// создавать идентификаторы, которые практически исключают
+/// вероятность коллизий даже при массовой генерации в разных
+/// контекстах выполнения.
+///
+/// Важные особенности функции:
+/// - Поддерживает настраиваемый префикс для семантического
+///   обозначения типа идентификатора
+/// - Использует криптографически безопасный генератор
+///   случайных чисел Sass
+/// - Добавляет встроенный временной штамп для уникальности
+/// - Выполняет строгую проверку типов входных параметров
+/// - Возвращает строку, готовую к использованию как CSS ID
+///   или имя класса
+/// - Полезна для генерации уникальных имен в CSS-in-JS
+///   решениях
+/// - Может использоваться для создания ключей в картах
+/// - Обеспечивает уникальность в пределах одной компиляции
+/// - Совместима с модульной системой Sass
+/// ---
+/// @name get-uid
+/// @group utilities-getters
+/// @since 2026.01.18
+/// @access public
+/// @author Murad Rustamov (therteenten)
+/// @link https://sourcecraft.dev/users/therteenten/overview SourceCraft - therteenten
+/// @link https://sourcecraft.dev/omnisass/library SourceCraft - OmniSass
+/// @link https://sass-lang.com/documentation/modules/math См. также: Официальная документация Sass - Модуль Math
+/// @link https://sass-lang.com/documentation/modules/string См. также: Официальная документация Sass - Модуль String
+/// @link https://sass-lang.com/documentation/values/numbers См. также: Официальная документация Sass - Тип данных "Числа"
+/// @link https://sass-lang.com/documentation/values/strings См. также: Официальная документация Sass - Тип данных "Строки"
+/// @link https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID См. также: MDN Web Docs - Метод Crypto.randomUUID()
+/// @link https://developer.mozilla.org/en-US/docs/Glossary/CSS_keyword См. также: MDN Web Docs - Глоссарий: CSS Keyword
+/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id См. также: MDN Web Docs - Глобальный атрибут id
+/// @link https://css-tricks.com/snippets/sass/unique-id-function/ См. также: CSS-Tricks - Функция уникального ID в Sass
+/// @link https://css-tricks.com/sass-generate-ids-classes/ См. также: CSS-Tricks - Генерация ID и классов в Sass
+/// @link https://sass-guidelin.es/ru/#section-44 См. также: Sass Guidelines - Раздел про функции
+/// @link https://github.com/sass/sass/issues/2848 См. также: GitHub - Обсуждение уникальных ID в Sass
+/// @example scss - Базовое использование с префиксом по умолчанию
+/// 	@debug get-uid();                    // "id-384756-uasgd7234"
+/// 	@debug get-uid();                    // "id-928173-kjhasd872"
+/// 	@debug get-uid();                    // "id-102938-poiuy1234"
+/// @example scss - Использование с кастомным префиксом
+/// 	@debug get-uid('user-');             // "user-473829-oiuyt9876"
+/// 	@debug get-uid('modal-');            // "modal-192837-zxcvb4567"
+/// 	@debug get-uid('component-');        // "component-564738-mnbvc0987"
+/// @example scss - Использование с разным диапазоном случайных чисел
+/// 	@debug get-uid('id-', 1000);         // "id-423-iuyt6543"
+/// 	@debug get-uid('id-', 9999999);      // "id-7823491-zxcv5432"
+/// 	@debug get-uid('id-', 100);          // "id-87-asdfg1234"
+/// @param {String} $prefix ["id-"] - Префикс для
+///   идентификатора. Добавляется в начало строки ID,
+///   позволяя семантически группировать идентификаторы
+///   по назначению. Должен быть строковым значением.
+/// @param {Number} $random-max [1000000] - Максимальное
+///   значение для генерации случайного числа. Определяет
+///   диапазон случайной части идентификатора (от 1 до
+///   указанного значения). Должен быть числовым значением.
+/// @return {String} - Уникальный строковый идентификатор
+///   в формате "префикс-случайное_число-временной_штамп".
+///   Гарантирует уникальность в пределах текущей сессии
+///   компиляции Sass.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$prefix` → `string`
+/// - `$random-max` → `number`
+@function get-uid($prefix: "id-", $random-max: 1000000) {
+
+	// Проверка типа первого параметра: ожидается строковый префикс.
+	// Префикс позволяет семантически обозначать тип идентификатора
+	// (например, 'user-', 'modal-', 'component-'), что улучшает
+	// читаемость и отладку сгенерированных идентификаторов.
+	@if not is-string($prefix) {
+
+		// Если $prefix не является строкой, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректную конкатенацию с нестроковыми значениями.
+		@return log-invalid-type(
+			'get-uid',
+			$prefix,
+			'$prefix',
+			'string'
+		);
+
+	}
+
+	// Проверка типа второго параметра: ожидается числовое значение
+	// для диапазона случайных чисел. Параметр определяет верхнюю
+	// границу для генератора случайных чисел (math.random).
+	@else if not is-number($random-max) {
+
+		// Если $random-max не является числом, возвращаем ошибку.
+		// Проверка выполняется только если $prefix прошел валидацию.
+		@return log-invalid-type(
+			'get-uid',
+			$random-max,
+			'$random-max',
+			'number'
+		);
+
+	}
+
+	// Все параметры прошли валидацию - генерируем уникальный ID.
+	@else {
+
+		// Генерация случайного числа в диапазоне от 1 до $random-max.
+		// Функция math.random() использует криптографически безопасный
+		// генератор, обеспечивающий хорошее распределение значений.
+		$-random: math.random($random-max);
+
+		// Генерация уникального временного штампа.
+		// Функция string.unique-id() возвращает гарантированно
+		// уникальную строку в пределах текущей компиляции Sass,
+		// основанную на времени и случайных факторах.
+		$-timestamp: string.unique-id();
+
+		// Конкатенация всех компонентов в финальный идентификатор.
+		// Формат: префикс + случайное_число + разделитель + штамп.
+		// Разделитель '-' улучшает читаемость и парсинг при отладке.
+		@return $prefix + $-random + "-" + $-timestamp;
+
+	}
+
+}

package/modules/utilities/getters/number/_get-number-from-percent.scss

@@ -96,8 +96,12 @@
 /// 	указанный процент от целого. Возвращает значение в тех же
 /// 	единицах измерения, что и параметр `$whole`.
 /// @throws {Error} - Может выбросить ошибку если `$percentage`
-/// 	не содержит единицы измерения '%' или если параметры
-/// 	не являются числами.
+/// 	не содержит единицы измерения '%'.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$percentage` → `number`
+/// - `$whole` → `number`
 @function get-number-from-percent($percentage, $whole) {
 
 	// ВАЛИДАЦИЯ ВХОДНЫХ ПАРАМЕТРОВ

package/modules/utilities/getters/number/_get-number-height-by-ratio.scss

@@ -152,6 +152,11 @@
 /// @throws {Error} - Выбрасывает ошибку деления на ноль, если
 /// 	`$ratio = 0`. Это соответствует математически невозможной
 /// 	ситуации, когда высота была бы бесконечной.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$width` → `number`
+/// - `$ratio` → `number`
 @function get-number-height-by-ratio($width, $ratio) {
 
 	@if not is-number($width) {

package/modules/utilities/getters/number/_get-number-max.scss

@@ -73,6 +73,10 @@
 /// 	значения.
 /// @throws {Error} - Может выбросить ошибку при попытке
 /// 	сравнить числа с несовместимыми единицами измерения.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$list` → `list`
 @function get-number-max($list) {
 
 	// Переменная для хранения текущего максимального значения.

package/modules/utilities/getters/number/_get-number-min.scss

@@ -72,6 +72,10 @@
 /// 	значения.
 /// @throws {Error} - Может выбросить ошибку при попытке
 /// 	сравнить числа с несовместимыми единицами измерения.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$list` → `list`
 @function get-number-min($list) {
 
 	// Инициализация переменной для хранения результата.

package/modules/utilities/getters/number/_get-number-percentage-of.scss

@@ -89,7 +89,12 @@
 /// 	представляющее отношение части к целому. Возвращаемое значение
 /// 	можно использовать напрямую в CSS-свойствах.
 /// @throws {Error} - Может выбросить ошибку деления на ноль,
-/// 	если `$whole` равно 0, или если параметры не являются числами.
+/// 	если `$whole` равно 0.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$part` → `number`
+/// - `$whole` → `number`
 @function get-number-percentage-of($part, $whole) {
 
 	@if not is-number($part) {

package/modules/utilities/getters/number/_get-number-unit.scss

@@ -64,8 +64,10 @@
 /// 	возвращается строка с этими единицами. Для
 /// 	безразмерных чисел и нечисловых значений
 /// 	возвращается пустая строка (`''`).
-/// @throws {Error} - Не выбрасывает ошибок, только
-/// 	если значение является числом.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$value` → `number`
 @function get-number-unit($value) {
 
 	@if not is-number($value) {

package/modules/utilities/getters/number/_get-number-width-by-ratio.scss

@@ -155,6 +155,11 @@
 /// @return {Number} - Ширина элемента, рассчитанная по формуле
 /// 	`width = height × ratio`. Сохраняет единицы измерения
 /// 	параметра `$height`.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$height` → `number`
+/// - `$ratio` → `number`
 @function get-number-width-by-ratio($height, $ratio) {
 
 	@if not is-number($height) {

package/modules/utilities/getters/string/_get-string-hash.scss

@@ -0,0 +1,143 @@
+@use 'sass:string';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-string' as *;
+
+/// Вычисляет числовой хеш-код для строки по алгоритму DJB2.
+///
+/// Функция преобразует произвольную строку в числовой хеш-код
+/// фиксированной длины (до 6 знаков). Алгоритм использует
+/// мультипликативный подход с множителем 31 и модульной
+/// арифметикой, что обеспечивает хорошее распределение
+/// значений при минимальных коллизиях для коротких строк.
+///
+/// Важные особенности функции:
+/// - Реализует упрощенную версию алгоритма хеширования DJB2
+/// - Использует множитель 31 для оптимального распределения
+/// - Ограничивает результат модулем 1,000,000 (6 знаков)
+/// - Работает только с алфавитно-цифровыми символами
+/// - Возвращает 0 для пустой строки или некорректных символов
+/// - Выполняет строгую проверку типа входного параметра
+/// - Подходит для создания коротких уникальных идентификаторов
+/// - Может использоваться для быстрого сравнения строк
+/// - Полезна для генерации ключей в картах или массивах
+/// - Обеспечивает детерминированный результат для одинаковых
+///   входных данных
+/// - Алгоритм использует ограниченный набор символов
+///   (a-z, A-Z, 0-9). Символы вне этого набора игнорируются
+///   и не влияют на итоговый хеш. Для поддержки Unicode или
+///   расширенных символов потребуется модификация функции.
+/// - Множитель 31 выбран как простое число, что
+///   способствует хорошему распределению хеш-значений.
+///   Этот множитель используется в реализации hashCode()
+///   языка Java для строк.
+/// - Модуль 1000000 ограничивает результат 6 знаками,
+///   что удобно для генерации коротких идентификаторов.
+///   При необходимости большего диапазона значение модуля
+///   можно увеличить.
+/// ---
+/// @name get-string-hash
+/// @group utilities-getters
+/// @since 2026.01.18
+/// @access public
+/// @author Murad Rustamov (therteenten)
+/// @link https://sourcecraft.dev/users/therteenten/overview SourceCraft - therteenten
+/// @link https://sourcecraft.dev/omnisass/library SourceCraft - OmniSass
+/// @link https://sass-lang.com/documentation/modules/string См. также: Официальная документация Sass - Модуль String
+/// @link https://sass-lang.com/documentation/values/numbers См. также: Официальная документация Sass - Тип данных "Числа"
+/// @link https://sass-lang.com/documentation/values/strings См. также: Официальная документация Sass - Тип данных "Строки"
+/// @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/charCodeAt См. также: MDN Web Docs - Метод String.charCodeAt()
+/// @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/hashCode См. также: MDN Web Docs - Метод String.hashCode()
+/// @link https://en.wikipedia.org/wiki/Hash_function См. также: Wikipedia - Хеш-функция
+/// @link https://en.wikipedia.org/wiki/Java_hashCode() См. также: Wikipedia - Метод hashCode() в Java
+/// @link https://en.wikipedia.org/wiki/DJB2 См. также: Wikipedia - Алгоритм хеширования DJB2
+/// @link https://css-tricks.com/snippets/sass/string-hashing-function/ См. также: CSS-Tricks - Функция хеширования строк в Sass
+/// @link https://css-tricks.com/sass-generate-unique-ids/ См. также: CSS-Tricks - Генерация уникальных ID в Sass
+/// @link https://sass-guidelin.es/ru/#section-44 См. также: Sass Guidelines - Раздел про функции
+/// @link https://github.com/sass/sass/issues/2864 См. также: GitHub - Обсуждение хеш-функций в Sass
+/// @link https://www.strchr.com/hash_functions См. также: strchr.com - Сравнение хеш-функций
+/// @example scss - Хеширование простых строк
+/// 	@debug get-string-hash('hello');   // 549042
+/// 	@debug get-string-hash('world');   // 705522
+/// 	@debug get-string-hash('test');    // 601234
+/// 	@debug get-string-hash('');        // 32
+/// @example scss - Хеширование строк с разным регистром
+/// 	@debug get-string-hash('Hello');   // 560588
+/// 	@debug get-string-hash('HELLO');   // 360972
+/// 	@debug get-string-hash('hElLo');   // 324414
+/// @example scss - Хеширование алфавитно-цифровых строк
+/// 	@debug get-string-hash('abc123');  // 619221
+/// 	@debug get-string-hash('ABC123');  // 763259
+/// 	@debug get-string-hash('user42');  // 927145
+/// @param {String} $string - Строка для хеширования.
+///   Функция ожидает строку, содержащую символы из набора
+///   a-z, A-Z, 0-9. Для символов вне этого набора функция
+///   string.index() вернет null, что приведет к нулевому
+///   вкладу в хеш-значение. Пустая строка вернет 0.
+/// @return {Number} - Числовой хеш-код в диапазоне от 0 до
+///   999999 (включительно). Результат детерминирован - одна
+///   и та же строка всегда дает одинаковый хеш-код в
+///   пределах одной версии функции.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$string` → `string`
+@function get-string-hash($string) {
+
+	// Проверка типа входного параметра: ожидается строковое значение.
+	// Функция предназначена для работы исключительно со строками,
+	// так как алгоритм хеширования оперирует последовательностью символов.
+	@if not is-string($string) {
+
+		// Если $string не является строкой, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные операции с нестроковыми типами данных.
+		@return log-invalid-type(
+			'get-string-hash',
+			$string,
+			'$string',
+			'string'
+		);
+
+	}
+
+	// Параметр прошел валидацию - вычисляем хеш-код строки.
+	@else {
+
+		// Инициализация переменной для хранения хеш-значения.
+		// Начальное значение 0 обеспечивает корректную работу
+		// алгоритма для пустых строк и первого символа.
+		$-hash: 0;
+
+		// Определение длины входной строки.
+		// Длина используется для итерации по всем символам строки
+		// в цикле for.
+		$-length: string.length($string);
+
+		// Итерация по всем символам строки от первого до последнего.
+		// Каждый символ вносит свой вклад в итоговое хеш-значение
+		// согласно алгоритму DJB2.
+		@for $i from 1 through $-length {
+
+			// Извлечение текущего символа строки по индексу.
+			// Индексация в Sass начинается с 1 (не с 0).
+			$-char: string.slice($string, $i, $i);
+
+			// Вычисление нового значения хеша по формуле:
+			// hash = ((hash * 31) + char_index) % 1000000
+			// Где:
+			// - hash * 31: сдвиг предыдущего значения
+			// - char_index: позиция символа в алфавите (1-62)
+			// - % 1000000: ограничение результата 6 знаками
+			// string.index() возвращает позицию символа в строке
+			// алфавита или null для отсутствующих символов.
+			$-hash: (($-hash * 31) + string.index("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789", $-char)) % 1000000;
+
+		}
+
+		// Возвращаем вычисленный хеш-код строки.
+		// Значение всегда будет в диапазоне 0-999999 включительно.
+		@return $-hash;
+
+	}
+
+}

package/modules/utilities/helpers/color/_color-blend-steps.scss

@@ -117,6 +117,12 @@
 /// - Последний элемент: чистый `$color-end` (100% смешивания)
 /// - Промежуточные элементы: равномерно распределенные смеси
 /// - Всего элементов: `$steps + 2`
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$color-start` → `color`
+/// - `$color-start` → `color`
+/// - `$steps` → `number`
 @function color-blend-steps($color-start, $color-end, $steps: 5) {
 
 	// Инициализация списка для хранения промежуточных цветов.

package/modules/utilities/helpers/color/_color-blend.scss

@@ -107,6 +107,12 @@
 /// 	интерполяцией между `$color-from` и `$color-to` в указанной пропорции.
 /// 	Использует цветовое пространство по умолчанию для
 /// 	смешивания (обычно sRGB).
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$color-from` → `color`
+/// - `$color-to` → `color`
+/// - `$percentage` → `number`
 @function color-blend($color-from, $color-to, $percentage) {
 
 	// Проверка типа первого параметра: ожидается начальный цвет.

package/modules/utilities/helpers/color/_color-hue-shift.scss

@@ -84,6 +84,11 @@
 /// @return {Color} - Новый цвет в формате HSL с измененным
 /// 	цветовым тоном, но с сохранением исходных значений
 /// 	насыщенности и светлоты.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$color` → `color`
+/// - `$degrees` → `number`
 @function color-hue-shift($color, $degrees) {
 
 	// Проверка типа первого параметра: ожидается цветовое значение.

package/modules/utilities/helpers/color/_color-scale.scss

@@ -129,6 +129,11 @@
 /// - Последний элемент: `color-shade($color, 100%)`
 /// - Промежуточные элементы: равномерно распределенные оттенки
 /// - Длина списка = `$steps + 1`
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$color` → `color`
+/// - `$steps` → `number`
 @function color-scale($color, $steps: 5) {
 
 	// Проверка типа первого параметра: ожидается базовый цвет.

package/modules/utilities/helpers/color/_color-shade.scss

@@ -53,6 +53,11 @@
 /// 	черный.
 /// @return {Color} - Затемненный цвет в том же формате,
 /// 	что и исходный.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$color` → `color`
+/// - `$percentage` → `number`
 @function color-shade($color, $percentage) {
 
 	// Проверка типа первого параметра: ожидается базовый цвет.

package/modules/utilities/helpers/color/_color-tint.scss

@@ -58,6 +58,11 @@
 /// 	При 0 вернется исходный цвет, при 100 — чистый белый.
 /// @return {Color} - Осветленный цвет в том же формате,
 /// 	что и входной.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$color` → `color`
+/// - `$percentage` → `number`
 @function color-tint($color, $percentage) {
 
 	// Проверка типа первого параметра: ожидается базовый цвет.

package/modules/utilities/helpers/color/_color-triad.scss

@@ -74,7 +74,6 @@
 /// 	(HEX, RGB, HSL, имя цвета).
 /// 	Цветовой тон (hue) этого цвета используется как отправная
 /// 	точка для расчета двух дополнительных цветов.
-///
 /// @return {List} - Список (list) из трех строковых
 /// 	представлений цветов в формате, который Sass использует
 /// 	для внутреннего хранения (обычно HEX для цветов в
@@ -84,6 +83,10 @@
 /// - Первый элемент: строковое представление исходного цвета
 /// - Второй элемент: цвет со смещением +120° по цветовому кругу
 /// - Третий элемент: цвет со смещением +240° по цветовому кругу
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$color` → `color`
 @function color-triad($color) {
 
 	// Проверка типа входного параметра: ожидается цветовое значение.

package/modules/utilities/helpers/list/_list-dedupe.scss

@@ -90,6 +90,10 @@
 /// 	Сохраняет порядок элементов, оставляя только первое
 /// 	вхождение каждого значения. Если исходный список
 /// 	пустой, возвращает пустой список.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$list` → `list`
 @function list-dedupe($list) {
 
 	// Проверка типа входного параметра: ожидается список или arglist.

package/modules/utilities/helpers/list/_list-insert-at.scss

@@ -76,6 +76,11 @@
 /// 	`$index` не является числом или если индекс меньше 1,
 /// 	а также предупреждение, если индекс превышает длину
 /// 	списка.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$list` → `list`
+/// - `$index` → `number`
 @function list-insert-at($list, $value, $index) {
 
 	// Проверка типа первого параметра: ожидается список или arglist.

package/modules/utilities/helpers/list/_list-merge.scss

@@ -1,4 +1,6 @@
 @use 'sass:list';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-list' as *;
 
 /// Объединяет несколько списков в один плоский список.
 ///
@@ -62,25 +64,69 @@
 /// 	.test {
 /// 		transition: opacity transform 0.3s 0.5s;
 /// 	}
-/// @param {ArgList} $lists... - Произвольное количество
+/// @param {ArgList | List} $lists... - Произвольное количество
 /// 	списков для объединения. Каждый аргумент должен быть
 /// 	списком. Функция использует `arglist` для поддержки
 /// 	переменного числа аргументов.
 /// @return {List} - Новый список, содержащий все элементы из
 /// 	входных списков в порядке их следования. Если ни одного
 /// 	списка не передано, возвращается пустой список `()`.
-/// @throws Не выбрасывает ошибок, но если передать не список,
+/// @throws {Warning} - Если передать не список,
 /// 	элемент будет добавлен как есть (не рекомендуется).
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$lists` → `list`, 'arglist'
 @function list-merge($lists...) {
 
-	$-result: ();
+	// Проверка типа входных параметров.
+	// Параметр $lists является arglist (переменное число аргументов),
+	// но функция также должна принимать единичный список.
+	// Функция is-list() проверяет, является ли $lists списком или arglist.
+	@if not is-list($lists) {
+
+		// Если $lists не является списком или arglist, возвращаем ошибку.
+		// Это предотвращает некорректные операции с некорректными данными.
+		@return log-invalid-type(
+			'list-merge',
+			$lists,
+			'$lists',
+			('arglist', 'list')
+		);
 
-	@each $-list in $lists {
-		@each $-item in $-list {
-			$-result: list.append($-result, $-item);
-		}
 	}
 
-	@return $-result;
+	// Основная логика выполняется только если $lists является
+	// корректным списком или arglist.
+	@else {
+
+		// Инициализация переменной для хранения результата.
+		// $-result будет содержать объединенный список всех элементов
+		// из переданных списков.
+		$-result: ();
+
+		// Внешний цикл: итерация по всем переданным спискам.
+		// Переменная $-list содержит текущий обрабатываемый список.
+		@each $-list in $lists {
+
+			// Внутренний цикл: итерация по всем элементам текущего списка.
+			// Переменная $-item содержит текущий обрабатываемый элемент.
+			@each $-item in $-list {
+
+				// Добавление элемента в результирующий список.
+				// Функция list.append() добавляет элемент в конец списка,
+				// сохраняя порядок элементов из исходных списков.
+				$-result: list.append($-result, $-item);
+
+			}
+
+		}
+
+		// Возвращаем объединенный список.
+		// Результат содержит все элементы из всех переданных списков
+		// в том порядке, в котором они были переданы.
+		@return $-result;
+
+	}
 
 }

package/modules/utilities/helpers/list/_list-remove-at.scss

@@ -84,6 +84,11 @@
 /// @throws {Error} - Не выбрасывает ошибок при невалидных
 /// 	индексах, но может выбросить ошибку если `$index` не
 /// 	является числом.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$list` → `list`
+/// - `$index` → `number`
 @function list-remove-at($list, $index) {
 
 	// Проверка типа первого параметра: ожидается список или arglist.

package/modules/utilities/helpers/list/_list-sum-numbers-safe.scss

@@ -84,6 +84,9 @@
 /// 	измерения первого найденного числа.
 /// @throws {Warning} - Выводит предупреждение при обнаружении
 /// 	чисел с несовместимыми единицами измерения.
+/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
+/// 	значение, не соответствующее типу `list`. Компиляция Sass
+/// 	будет остановлена с ошибкой.
 @function list-sum-numbers-safe($list) {
 
 	// Проверка типа входного параметра: ожидается список или arglist.

package/modules/utilities/helpers/list/_list-sum-numbers.scss

@@ -66,6 +66,9 @@
 /// @throws {Error} - Может выбросить ошибку при попытке
 /// 	сложить числа с несовместимыми единицами измерения
 /// 	(например, px + em).
+/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
+/// 	значение, не соответствующее типу `list`. Компиляция Sass
+/// 	будет остановлена с ошибкой.
 @function list-sum-numbers($list) {
 
 	// Проверка типа входного параметра: ожидается список или arglist.