@omnisass/library 0.2.0 → 0.3.0

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.

package/modules/utilities/helpers/misc/_url-encode.scss

@@ -66,12 +66,11 @@
 /// 	значение - процентное представление символа.
 /// @return {String} - Закодированная строка, где все символы
 /// 	из карты замены преобразованы в их процентное
-/// 	представление. Строка безопасна для использования в
-/// 	любой части URL (path, query, fragment).
-/// @throws {Error} - Может выбросить ошибку при передаче
-/// 	нестрокового значения или если функция `string-replace`
-/// 	не определена. Требуется наличие функции `string-replace`
-/// 	в доступном scope.
+/// 	представление.
+/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
+/// 	значение, не соответствующее типу `string` (`$value`) или
+/// 	`map` (`$chars-map`). Компиляция Sass будет остановлена
+/// 	с ошибкой.
 /// @require {function} string-replace - Вспомогательная
 /// 	функция замены подстрок в строке. Должна быть определена
 /// 	и доступна для корректной работы данной функции.

package/modules/utilities/helpers/number/_number-ceil-to.scss

@@ -1,4 +1,6 @@
 @use 'sass:math';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-number' as *;
 
 /// Округляет число вверх до ближайшего кратного значения.
 ///
@@ -103,9 +105,59 @@
 /// @return {Number} - Число, округленное вверх до ближайшего
 /// 	значения, кратного `$nearest`. Сохраняет единицы
 /// 	измерения исходного числа `$value`.
-/// @throws {Error} - Может выбросить ошибку если `$value` или
-/// 	`$nearest` не являются числами, или если происходит
-/// 	деление на ноль.
+/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
+/// 	значение, не соответствующее типу `number`. Компиляция Sass
+/// 	будет остановлена с ошибкой.
 @function number-ceil-to($value, $nearest) {
-	@return math.ceil(math.div($value, $nearest)) * $nearest;
+
+	// Проверка типа первого параметра: ожидается числовое значение.
+	// Функция is-number() проверяет, является ли $value числом.
+	// Это может быть целое число, дробное число или число с единицами измерения.
+	@if not is-number($value) {
+
+		// Если $value не является числом, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные вычисления с нечисловыми данными.
+		@return log-invalid-type(
+			'number-ceil-to',
+			$value,
+			'$value',
+			'number'
+		);
+
+	}
+
+	// Проверка типа второго параметра: ожидается числовое значение
+	// для шага округления. $nearest определяет, до какого ближайшего
+	// кратного значения нужно округлить исходное число.
+	@else if not is-number($nearest) {
+
+		// Если $nearest не является числом, возвращаем ошибку.
+		// Проверка выполняется только если $value прошел валидацию.
+		@return log-invalid-type(
+			'number-ceil-to',
+			$nearest,
+			'$nearest',
+			'number'
+		);
+
+	}
+
+	// Все параметры прошли валидацию - выполняем округление вверх.
+	@else {
+
+		// Формула округления вверх до ближайшего кратного значения:
+		// 1. math.div($value, $nearest) - делим исходное значение на шаг округления
+		// 2. math.ceil() - округляем результат деления вверх до ближайшего целого
+		// 3. * $nearest - умножаем округленное целое на шаг округления
+		//
+		// Математическая формула:
+		// result = ceil(value / nearest) × nearest
+		//
+		// Ключевая особенность: функция всегда округляет ВВЕРХ до ближайшего
+		// кратного значения, даже если исходное число уже близко к нижнему крайнему.
+		@return math.ceil(math.div($value, $nearest)) * $nearest;
+
+	}
+
 }

package/modules/utilities/helpers/number/_number-clamp-max.scss

@@ -1,4 +1,6 @@
 @use 'sass:math';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-number' as *;
 
 /// Ограничивает число сверху, обеспечивая максимальное
 /// значение.
@@ -13,7 +15,7 @@
 /// - Если `value ≤ max` → возвращает `value`
 ///
 /// Важные особенности функции:
-/// - Гарантирует, что результат будет не больше `$max`
+/// - Гарантирует, что результат будет не больше `$value-max`
 /// - Использует встроенную функцию `math.min()`
 /// - Работает с любыми числовыми значениями (целые, дробные,
 /// 	с единицами)
@@ -78,15 +80,68 @@
 /// 	сверху. Может быть любым числом: целым, дробным,
 /// 	положительным, отрицательным, с единицами измерения
 /// 	или без.
-/// @param {Number} $max - Максимальное допустимое значение.
-/// 	Если `$value` больше `$max`, возвращается `$max`.
+/// @param {Number} $value-max - Максимальное допустимое значение.
+/// 	Если `$value` больше `$value-max`, возвращается `$value-max`.
 /// @return {Number} - Наименьшее из двух значений: `$value`
-/// 	или `$max`. Если `$value` меньше или равно `$max`,
+/// 	или `$value-max`. Если `$value` меньше или равно `$value-max`,
 /// 	возвращается `$value`. В противном случае возвращается
-/// 	`$max`.
-/// @throws Не выбрасывает ошибок, безопасно обрабатывает
-/// 	все числовые значения. Оба аргумента должны быть
-/// 	числами для корректной работы.
-@function number-clamp-max($value, $max) {
-	@return math.min($value, $max);
+/// 	`$value-max`.
+/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
+/// 	значение, не соответствующее типу `number`. Компиляция Sass
+/// 	будет остановлена с ошибкой.
+@function number-clamp-max($value, $value-max) {
+
+	// Проверка типа первого параметра: ожидается числовое значение.
+	// Функция is-number() проверяет, является ли $value числом.
+	// Это может быть целое число, дробное число или число с единицами измерения.
+	@if not is-number($value) {
+
+		// Если $value не является числом, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные вычисления с нечисловыми данными.
+		@return log-invalid-type(
+			'number-clamp-max',
+			$value,
+			'$value',
+			'number'
+		);
+
+	}
+
+	// Проверка типа второго параметра: ожидается числовое значение
+	// максимального предела. $value-max определяет верхнюю границу,
+	// которую не может превышать возвращаемое значение.
+	@else if not is-number($value-max) {
+
+		// Если $value-max не является числом, возвращаем ошибку.
+		// Проверка выполняется только если $value прошел валидацию.
+		@return log-invalid-type(
+			'number-clamp-max',
+			$value-max,
+			'$value-max',
+			'number'
+		);
+
+	}
+
+	// Все параметры прошли валидацию - выполняем ограничение сверху.
+	@else {
+
+		// Формула ограничения значения сверху:
+		// Используем встроенную функцию math.min() для выбора
+		// меньшего из двух значений.
+		//
+		// Логика работы:
+		// - Если $value меньше или равен $value-max, возвращается $value
+		// - Если $value больше $value-max, возвращается $value-max
+		//
+		// Математическая формула:
+		// result = min(value, max-value)
+		//
+		// Ключевая особенность: функция гарантирует, что возвращаемое
+		// значение никогда не превысит указанный максимальный предел.
+		@return math.min($value, $value-max);
+
+	}
+
 }

package/modules/utilities/helpers/number/_number-clamp-min.scss

@@ -1,4 +1,6 @@
 @use 'sass:math';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-number' as *;
 
 /// Ограничивает число снизу, обеспечивая минимальное значение.
 ///
@@ -12,7 +14,7 @@
 /// - Если `value ≥ min` → возвращает `value`
 ///
 /// Важные особенности функции:
-/// - Гарантирует, что результат будет не меньше `$min`
+/// - Гарантирует, что результат будет не меньше `$value-min`
 /// - Использует встроенную функцию `math.max()`
 /// - Работает с любыми числовыми значениями (целые, дробные,
 /// 	с единицами)
@@ -86,15 +88,68 @@
 /// 	снизу. Может быть любым числом: целым, дробным,
 /// 	положительным, отрицательным, с единицами измерения или
 /// 	без.
-/// @param {Number} $min - Минимальное допустимое значение.
-/// 	Если `$value` меньше `$min`, возвращается `$min`.
+/// @param {Number} $value-min - Минимальное допустимое значение.
+/// 	Если `$value` меньше `$value-min`, возвращается `$value-min`.
 /// @return {Number} - Наибольшее из двух значений: `$value`
-/// 	или `$min`. Если `$value` больше или равно `$min`,
+/// 	или `$value-min`. Если `$value` больше или равно `$value-min`,
 /// 	возвращается `$value`. В противном случае возвращается
-/// 	`$min`.
-/// @throws Не выбрасывает ошибок, безопасно обрабатывает все
-/// 	числовые значения. Оба аргумента должны быть числами
-/// 	для корректной работы.
-@function number-clamp-min($value, $min) {
-	@return math.max($value, $min);
+/// 	`$value-min`.
+/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
+/// 	значение, не соответствующее типу `number`. Компиляция Sass
+/// 	будет остановлена с ошибкой.
+@function number-clamp-min($value, $value-min) {
+
+	// Проверка типа первого параметра: ожидается числовое значение.
+	// Функция is-number() проверяет, является ли $value числом.
+	// Это может быть целое число, дробное число или число с единицами измерения.
+	@if not is-number($value) {
+
+		// Если $value не является числом, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные вычисления с нечисловыми данными.
+		@return log-invalid-type(
+			'number-clamp-min',
+			$value,
+			'$value',
+			'number'
+		);
+
+	}
+
+	// Проверка типа второго параметра: ожидается числовое значение
+	// минимального предела. $value-min определяет нижнюю границу,
+	// ниже которой не может опускаться возвращаемое значение.
+	@else if not is-number($value-min) {
+
+		// Если $value-min не является числом, возвращаем ошибку.
+		// Проверка выполняется только если $value прошел валидацию.
+		@return log-invalid-type(
+			'number-clamp-min',
+			$value-min,
+			'$value-min',
+			'number'
+		);
+
+	}
+
+	// Все параметры прошли валидацию - выполняем ограничение снизу.
+	@else {
+
+		// Формула ограничения значения снизу:
+		// Используем встроенную функцию math.max() для выбора
+		// большего из двух значений.
+		//
+		// Логика работы:
+		// - Если $value больше или равен $value-min, возвращается $value
+		// - Если $value меньше $value-min, возвращается $value-min
+		//
+		// Математическая формула:
+		// result = max(value, min-value)
+		//
+		// Ключевая особенность: функция гарантирует, что возвращаемое
+		// значение никогда не будет меньше указанного минимального предела.
+		@return math.max($value, $value-min);
+
+	}
+
 }

package/modules/utilities/helpers/number/_number-clamp.scss

@@ -1,4 +1,6 @@
 @use 'sass:math';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-number' as *;
 
 /// Ограничивает число заданным диапазоном значений.
 ///
@@ -16,7 +18,7 @@
 /// - Если `min ≤ value ≤ max` → возвращает `value`
 ///
 /// Важные особенности функции:
-/// - Гарантирует, что результат будет в диапазоне `[$min, $max]`
+/// - Гарантирует, что результат будет в диапазоне `[$value-min, $value-max]`
 /// - Использует встроенные функции `math.max()` и `math.min()`
 /// - Работает с любыми числовыми значениями (целые, дробные,
 /// 	с единицами)
@@ -32,7 +34,7 @@
 /// > `number-clamp()` вычисляется один раз при компиляции и
 /// > возвращает фиксированное значение. Для обеспечения
 /// > корректной работы рекомендуется всегда передавать
-/// > `$min ≤ $max`. При `$min > $max` функция все равно
+/// > `$value-min ≤ $value-max`. При `$value-min > $value-max` функция все равно
 /// > работает, но результат может отличаться от ожидаемого.
 /// ---
 /// @name number-clamp
@@ -92,18 +94,92 @@
 /// @param {Number} $value - Число, которое нужно ограничить.
 /// 	Может быть любым числом: целым, дробным, положительным,
 /// 	отрицательным, с единицами измерения или без.
-/// @param {Number} $min - Минимальное допустимое значение.
-/// 	Если `$value` меньше `$min`, возвращается `$min`.
-/// @param {Number} $max - Максимальное допустимое значение.
-/// 	Если `$value` больше `$max`, возвращается `$max`.
+/// @param {Number} $value-min - Минимальное допустимое значение.
+/// 	Если `$value` меньше `$value-min`, возвращается `$value-min`.
+/// @param {Number} $value-max - Максимальное допустимое значение.
+/// 	Если `$value` больше `$value-max`, возвращается `$value-max`.
 /// @return {Number} - Значение `$value`, ограниченное
-/// 	диапазоном `[$min, $max]`. Если `$value` находится в
+/// 	диапазоном `[$value-min, $value-max]`. Если `$value` находится в
 /// 	пределах диапазона, возвращается исходное значение. В
 /// 	противном случае возвращается соответствующая граница
 /// 	диапазона.
-/// @throws {Error} - Не выбрасывает ошибок, даже при
-/// 	некорректных диапазонах (когда `$min > $max`). Однако
-/// 	в таких случаях поведение функции может быть неинтуитивным.
-@function number-clamp($value, $min, $max) {
-	@return math.min(math.max($value, $min), $max);
+/// @throws {Warning} - когда `$value-min > $value-max` поведение
+/// 	функции может быть неинтуитивным.
+/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
+/// 	значение, не соответствующее типу `number`. Компиляция Sass
+/// 	будет остановлена с ошибкой.
+@function number-clamp($value, $value-min, $value-max) {
+
+	// Проверка типа первого параметра: ожидается числовое значение.
+	// Функция is-number() проверяет, является ли $value числом.
+	// Это может быть целое число, дробное число или число с единицами измерения.
+	@if not is-number($value) {
+
+		// Если $value не является числом, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные вычисления с нечисловыми данными.
+		@return log-invalid-type(
+			'number-clamp',
+			$value,
+			'$value',
+			'number'
+		);
+
+	}
+
+	// Проверка типа второго параметра: ожидается числовое значение
+	// минимального предела. $value-min определяет нижнюю границу,
+	// ниже которой не может опускаться возвращаемое значение.
+	@else if not is-number($value-min) {
+
+		// Если $value-min не является числом, возвращаем ошибку.
+		// Проверка выполняется только если $value прошел валидацию.
+		@return log-invalid-type(
+			'number-clamp',
+			$value-min,
+			'$value-min',
+			'number'
+		);
+
+	}
+
+	// Проверка типа третьего параметра: ожидается числовое значение
+	// максимального предела. $value-max определяет верхнюю границу,
+	// которую не может превышать возвращаемое значение.
+	@else if not is-number($value-max) {
+
+		// Если $value-max не является числом, возвращаем ошибку.
+		// Проверка выполняется только если $value и $value-min
+		// прошли валидацию.
+		@return log-invalid-type(
+			'number-clamp',
+			$value-max,
+			'$value-max',
+			'number'
+		);
+
+	}
+
+	// Все параметры прошли валидацию - выполняем ограничение диапазона.
+	@else {
+
+		// Формула ограничения значения в заданном диапазоне:
+		// Используем комбинацию встроенных функций math.max() и math.min().
+		//
+		// Логика работы:
+		// 1. math.max($value, $value-min) - гарантирует, что значение
+		//    не будет меньше минимального предела
+		// 2. math.min(..., $value-max) - гарантирует, что значение
+		//    не будет больше максимального предела
+		//
+		// Математическая формула:
+		// result = min(max(value, min-value), max-value)
+		//
+		// Ключевая особенность: функция гарантирует, что возвращаемое
+		// значение всегда будет находиться в диапазоне между $value-min
+		// и $value-max включительно.
+		@return math.min(math.max($value, $value-min), $value-max);
+
+	}
+
 }