@omnisass/library 0.2.0 → 0.3.0

package/modules/utilities/helpers/number/_number-random-between-int.scss

@@ -1,23 +1,25 @@
 @use 'sass:math';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-number' as *;
 
 /// Генерирует случайное целое число в заданном диапазоне.
 ///
 /// Функция принимает минимальное и максимальное целые значения
 /// и возвращает случайное целое число, равномерно распределенное
-/// в диапазоне [`$min`, `$max`] включительно.
+/// в диапазоне [`$value-min`, `$value-max`] включительно.
 ///
 /// Формула генерации:
-/// `math.floor($min + math.random() * ($max - $min + 1))`
+/// `math.floor($value-min + math.random() * ($value-max - $value-min + 1))`
 ///
 /// Визуализация работы:
 /// - Генерирует базовое случайное число от 0 до 1 (исключая 1)
 /// - Масштабирует его на длину диапазона плюс 1
-/// - Сдвигает на минимальное значение (`$min`)
+/// - Сдвигает на минимальное значение (`$value-min`)
 /// - Округляет вниз до ближайшего целого числа
 ///
 /// Важные особенности функции:
 /// - Работает только с целыми числами (без единиц измерения)
-/// - Диапазон включает оба конца: `$min` и `$max`
+/// - Диапазон включает оба конца: `$value-min` и `$value-max`
 /// - Равномерное распределение в заданном диапазоне
 /// - Каждый вызов функции возвращает новое случайное значение
 /// - Результат компилируется в CSS как фиксированное целое число
@@ -67,18 +69,77 @@
 /// 	$columns: number-random-between-int(2, 6);   // например: 4
 /// 	$repeat-count: number-random-between-int(3, 8); // например: 5
 /// 	$z-index: number-random-between-int(1, 10);  // например: 7
-/// @param {Number} $min - Минимальное целое значение диапазона (включительно).
+/// @param {Number} $value-min - Минимальное целое значение диапазона (включительно).
 ///   Должно быть целым числом без единиц измерения.
 ///   Определяет нижнюю границу генерации.
-/// @param {Number} $max - Максимальное целое значение диапазона (включительно).
+/// @param {Number} $value-max - Максимальное целое значение диапазона (включительно).
 ///   Должно быть целым числом без единиц измерения.
 ///   Определяет верхнюю границу генерации.
-///   Должно быть больше или равно `$min` для корректных результатов.
-/// @return {Number} - Случайное целое число в диапазоне [`$min`, `$max`].
+///   Должно быть больше или равно `$value-min` для корректных результатов.
+/// @return {Number} - Случайное целое число в диапазоне [`$value-min`, `$value-max`].
 ///   Всегда возвращает целое число без единиц измерения.
-/// @throws {Error} - Может выбросить ошибку при передаче
-///   нецелых чисел или чисел с единицами измерения.
-///   При `$max < $min` результат может быть неожиданным.
-@function number-random-between-int($min, $max) {
-  @return math.floor($min + math.random() * ($max - $min + 1));
+/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
+/// 	значение, не соответствующее типу `number`. Компиляция Sass
+/// 	будет остановлена с ошибкой.
+/// @throws {Warning} - При `$value-max < $value-min` результат
+/// 	может быть неожиданным.
+@function number-random-between-int($value-min, $value-max) {
+
+	// Проверка типа первого параметра: ожидается числовое значение
+	// минимальной границы диапазона. $value-min определяет нижнюю
+	// границу (включительно) для генерации случайного целого числа.
+	@if not is-number($value-min) {
+
+		// Если $value-min не является числом, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные вычисления с нечисловыми данными.
+		@return log-invalid-type(
+			'number-random-between-int',
+			$value-min,
+			'$value-min',
+			'number'
+		);
+
+	}
+
+	// Проверка типа второго параметра: ожидается числовое значение
+	// максимальной границы диапазона. $value-max определяет верхнюю
+	// границу (включительно) для генерации случайного целого числа.
+	@else if not is-number($value-max) {
+
+		// Если $value-max не является числом, возвращаем ошибку.
+		// Проверка выполняется только если $value-min прошел валидацию.
+		@return log-invalid-type(
+			'number-random-between-int',
+			$value-max,
+			'$value-max',
+			'number'
+		);
+
+	}
+
+	// Все параметры прошли валидацию - генерируем случайное целое число.
+	@else {
+
+		// Формула генерации случайного целого числа в диапазоне
+		// [$value-min, $value-max] включительно:
+		//
+		// Алгоритм вычислений:
+		// 1. math.random() - генерирует случайное число от 0 (включительно)
+		//    до 1 (исключительно)
+		// 2. $value-max - $value-min + 1 - вычисляем ширину диапазона
+		//    с добавлением 1 для включения верхней границы
+		// 3. math.random() * ... - масштабируем случайное число в диапазон
+		// 4. $value-min + ... - смещаем результат в нужный диапазон
+		// 5. math.floor() - округляем вниз до целого числа
+		//
+		// Математическая формула:
+		// result = floor(value-min + random() × (value-max - value-min + 1))
+		//
+		// Ключевая особенность: функция возвращает случайное ЦЕЛОЕ число
+		// в указанном диапазоне включительно (обе границы могут быть результатом).
+		@return math.floor($value-min + math.random() * ($value-max - $value-min + 1));
+
+	}
+
 }

package/modules/utilities/helpers/number/_number-random-between.scss

@@ -1,19 +1,21 @@
 @use 'sass:math';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-number' as *;
 
 /// Генерирует случайное число в заданном диапазоне.
 ///
 /// Функция принимает минимальное и максимальное значения
 /// и возвращает случайное число, равномерно распределенное
-/// в диапазоне [`$min`, `$max`] (включительно для `$min`,
-/// исключительно для `$max` для дробных чисел).
+/// в диапазоне [`$value-min`, `$value-max`] (включительно для `$value-min`,
+/// исключительно для `$value-max` для дробных чисел).
 ///
 /// Формула генерации:
-/// `$min + math.random() * ($max - $min)`
+/// `$value-min + math.random() * ($value-max - $value-min)`
 ///
 /// Визуализация работы:
 /// - Генерирует базовое случайное число от 0 до 1 (исключая 1)
-/// - Масштабирует его на длину диапазона (`$max - $min`)
-/// - Сдвигает на минимальное значение (`$min`)
+/// - Масштабирует его на длину диапазона (`$value-max - $value-min`)
+/// - Сдвигает на минимальное значение (`$value-min`)
 ///
 /// Важные особенности функции:
 /// - Работает с любыми числовыми значениями (целые, дробные,
@@ -98,23 +100,82 @@
 /// 	.decorative {
 /// 		transform: rotate(2.1312623254deg);
 /// 	}
-/// @param {Number} $min - Минимальное значение диапазона (включительно).
+/// @param {Number} $value-min - Минимальное значение диапазона (включительно).
 ///   Может быть любым числом: целым, дробным, положительным,
 ///   отрицательным, с единицами измерения или без.
 ///   Определяет нижнюю границу генерации.
-/// @param {Number} $max - Максимальное значение диапазона (исключительно
+/// @param {Number} $value-max - Максимальное значение диапазона (исключительно
 ///   для дробных чисел, но практически достижимо).
 ///   Может быть любым числом: целым, дробным, положительным,
 ///   отрицательным, с единицами измерения или без.
 ///   Определяет верхнюю границу генерации.
-///   Должно быть больше или равно `$min` для корректных результатов.
-/// @return {Number} - Случайное число в диапазоне [`$min`, `$max`).
+///   Должно быть больше или равно `$value-min` для корректных результатов.
+/// @return {Number} - Случайное число в диапазоне [`$value-min`, `$value-max`).
 ///   Если параметры имеют единицы измерения, результат будет
 ///   иметь те же единицы. Всегда возвращает дробное число.
-/// @throws {Error} - Не выбрасывает ошибок явно, но при
-///   `$max < $min` результат может быть неожиданным (возможны
-///   отрицательные значения длины диапазона). Рекомендуется
-///   всегда передавать `$min ≤ $max`.
-@function number-random-between($min, $max) {
-	@return $min + math.random() * ($max - $min);
+/// @throws {Warning} - При `$value-max < $value-min` результат может
+/// 	быть неожиданным (возможны отрицательные значения длины
+/// 	диапазона). Рекомендуется всегда передавать
+/// 	`$value-min ≤ $value-max`.
+/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
+/// 	значение, не соответствующее типу `number`. Компиляция Sass
+/// 	будет остановлена с ошибкой.
+@function number-random-between($value-min, $value-max) {
+
+	// Проверка типа первого параметра: ожидается числовое значение
+	// минимальной границы диапазона. $value-min определяет нижнюю
+	// границу для генерации случайного числа.
+	@if not is-number($value-min) {
+
+		// Если $value-min не является числом, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные вычисления с нечисловыми данными.
+		@return log-invalid-type(
+			'number-random-between',
+			$value-min,
+			'$value-min',
+			'number'
+		);
+
+	}
+
+	// Проверка типа второго параметра: ожидается числовое значение
+	// максимальной границы диапазона. $value-max определяет верхнюю
+	// границу для генерации случайного числа.
+	@else if not is-number($value-max) {
+
+		// Если $value-max не является числом, возвращаем ошибку.
+		// Проверка выполняется только если $value-min прошел валидацию.
+		@return log-invalid-type(
+			'number-random-between',
+			$value-max,
+			'$value-max',
+			'number'
+		);
+
+	}
+
+	// Все параметры прошли валидацию - генерируем случайное число.
+	@else {
+
+		// Формула генерации случайного числа в диапазоне
+		// [$value-min, $value-max):
+		//
+		// Алгоритм вычислений:
+		// 1. math.random() - генерирует случайное число от 0 (включительно)
+		//    до 1 (исключительно)
+		// 2. $value-max - $value-min - вычисляем ширину диапазона
+		// 3. math.random() * ... - масштабируем случайное число в диапазон
+		// 4. $value-min + ... - смещаем результат в нужный диапазон
+		//
+		// Математическая формула:
+		// result = value-min + random() × (value-max - value-min)
+		//
+		// Ключевая особенность: функция возвращает случайное число
+		// в указанном диапазоне, где $value-min включительно,
+		// а $value-max исключительно.
+		@return $value-min + math.random() * ($value-max - $value-min);
+
+	}
+
 }

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

@@ -1,4 +1,6 @@
 @use 'sass:list';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-number' as *;
 
 /// Генерирует последовательность чисел в заданном диапазоне
 /// с определенным шагом.
@@ -242,27 +244,118 @@
 ///   - Последний элемент: ближайшее к `$end` значение, кратное шагу
 ///   - Все элементы: равномерно распределены с шагом `$step`
 ///   - Направление: соответствует соотношению `$start` и `$end`
+/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
+/// 	значение, не соответствующее типу `number`. Компиляция Sass
+/// 	будет остановлена с ошибкой.
 @function number-range($from, $to, $step: 1) {
-	$-result: ();
 
-	@if $from < $to {
-		@for $i from $from through $to {
-			@if ($i - $from) % $step == 0 {
+	// Проверка типа первого параметра: ожидается числовое значение
+	// начальной точки диапазона. $from определяет начальное значение
+	// для генерации последовательности чисел.
+	@if not is-number($from) {
 
-				$-result: list.append($-result, $i);
+		// Если $from не является числом, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные вычисления с нечисловыми данными.
+		@return log-invalid-type(
+			'number-range',
+			$from,
+			'$from',
+			'number'
+		);
+
+	}
+
+	// Проверка типа второго параметра: ожидается числовое значение
+	// конечной точки диапазона. $to определяет конечное значение
+	// для генерации последовательности чисел.
+	@else if not is-number($to) {
+
+		// Если $to не является числом, возвращаем ошибку.
+		// Проверка выполняется только если $from прошел валидацию.
+		@return log-invalid-type(
+			'number-range',
+			$to,
+			'$to',
+			'number'
+		);
+
+	}
+
+	// Проверка типа третьего параметра: ожидается числовое значение
+	// шага последовательности. $step определяет интервал между
+	// числами в генерируемой последовательности.
+	@else if not is-number($step) {
+
+		// Если $step не является числом, возвращаем ошибку.
+		// Проверка выполняется только если $from и $to
+		// прошли валидацию.
+		@return log-invalid-type(
+			'number-range',
+			$step,
+			'$step',
+			'number'
+		);
+
+	}
+
+	// Все параметры прошли валидацию - генерируем числовую последовательность.
+	@else {
+
+		// Инициализация переменной для хранения результата.
+		// $-result будет содержать список чисел в указанном диапазоне
+		// с заданным шагом.
+		$-result: ();
+
+		// Проверка направления диапазона: восходящая последовательность.
+		// Если начальное значение меньше конечного, генерируем числа
+		// от меньшего к большему.
+		@if $from < $to {
+
+			// Цикл по всем числам от $from до $to включительно.
+			// Переменная $i принимает значения от $from до $to.
+			@for $i from $from through $to {
+
+				// Проверка: соответствует ли текущее число шагу последовательности.
+				// Условие ($i - $from) % $step == 0 проверяет, что разница
+				// между текущим числом и начальным значением кратна шагу.
+				@if ($i - $from) % $step == 0 {
+
+					// Если число соответствует шагу, добавляем его в результат.
+					// Функция list.append() добавляет число в конец списка.
+					$-result: list.append($-result, $i);
+
+				}
 
 			}
-		}
-	} @else {
-		@for $i from $from through $to {
-			@if ($from - $i) % $step == 0 {
 
-				$-result: list.append($-result, $i);
+		} @else {
+
+			// Нисходящая последовательность.
+			// Если начальное значение больше или равно конечному,
+			// генерируем числа от большего к меньшему.
+			@for $i from $from through $to {
+
+				// Проверка: соответствует ли текущее число шагу последовательности
+				// для нисходящего направления.
+				// Условие ($from - $i) % $step == 0 проверяет, что разница
+				// между начальным значением и текущим числом кратна шагу.
+				@if ($from - $i) % $step == 0 {
+
+					// Если число соответствует шагу, добавляем его в результат.
+					$-result: list.append($-result, $i);
+
+				}
 
 			}
+
 		}
-	}
 
-	@return $-result;
+		// Возвращаем список чисел в указанном диапазоне с заданным шагом.
+		// Последовательность включает начальное и конечное значения,
+		// если они соответствуют шагу.
+		@return $-result;
+
+	}
 
 }

package/modules/utilities/helpers/number/_number-round-to-nearest.scss

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

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

@@ -1,4 +1,6 @@
 @use 'sass:math';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-number' as *;
 
 /// Округляет число до указанного количества знаков после
 /// запятой.
@@ -109,10 +111,71 @@
 /// @throws {Error} - Может выбросить ошибку если `$precision`
 /// 	не является целым неотрицательным числом или если
 /// 	`$value` не является числом.
+/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
+/// 	значение, не соответствующее типу `number`. Компиляция Sass
+/// 	будет остановлена с ошибкой.
 @function number-round-to($value, $precision: 2) {
 
-	$-multiplier: math.pow(10, $precision);
+	// Проверка типа первого параметра: ожидается числовое значение.
+	// Функция is-number() проверяет, является ли $value числом.
+	// Это может быть целое число, дробное число или число с единицами измерения.
+	@if not is-number($value) {
 
-	@return math.div(math.round($value * $-multiplier), $-multiplier);
+		// Если $value не является числом, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные вычисления с нечисловыми данными.
+		@return log-invalid-type(
+			'number-round-to',
+			$value,
+			'$value',
+			'number'
+		);
+
+	}
+
+	// Проверка типа второго параметра: ожидается числовое значение
+	// для точности округления. $precision определяет количество
+	// знаков после запятой в результате округления.
+	@else if not is-number($precision) {
+
+		// Если $precision не является числом, возвращаем ошибку.
+		// Проверка выполняется только если $value прошел валидацию.
+		@return log-invalid-type(
+			'number-round-to',
+			$precision,
+			'$precision',
+			'number'
+		);
+
+	}
+
+	// Все параметры прошли валидацию - выполняем округление с заданной точностью.
+	@else {
+
+		// Вычисление множителя для округления.
+		// math.pow(10, $precision) возводит 10 в степень $precision,
+		// создавая множитель для перемещения нужного количества
+		// знаков после запятой в целую часть числа.
+		// Пример: при $precision = 2 → множитель = 100
+		$-multiplier: math.pow(10, $precision);
+
+		// Формула округления с заданной точностью:
+		// 1. $value * $-multiplier - умножаем значение на множитель,
+		//    чтобы переместить нужное количество знаков после запятой
+		//    в целую часть (например, 3.14159 × 100 = 314.159)
+		// 2. math.round(...) - округляем результат к ближайшему целому
+		//    (314.159 → 314)
+		// 3. math.div(..., $-multiplier) - делим обратно на множитель,
+		//    чтобы вернуть десятичную точку на исходное место (314 → 3.14)
+		//
+		// Математическая формула:
+		// result = round(value × 10^precision) ÷ 10^precision
+		//
+		// Ключевая особенность: функция округляет значение до указанного
+		// количества знаков после запятой с использованием математического
+		// округления, где .5 всегда округляется вверх.
+		@return math.div(math.round($value * $-multiplier), $-multiplier);
+
+	}
 
 }

package/modules/utilities/helpers/number/_number-strip-unit.scss

@@ -79,19 +79,53 @@
 /// @return {Number} - Безразмерное числовое значение, равное
 /// 	числовой части входного значения. Если входное значение
 /// 	уже было безразмерным, возвращается то же самое значение.
-/// @throws {Error} - Может выбросить ошибку, если передано
-/// 	нечисловое значение, так как математические операции
-/// 	Sass требуют числовых операндов.
+/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
+/// 	значение, не соответствующее типу `number`. Компиляция Sass
+/// 	будет остановлена с ошибкой.
 @function number-strip-unit($value) {
 
-	$-result: 'null';
+	// Проверка типа входного параметра: ожидается числовое значение.
+	// Функция is-number() проверяет, является ли $value числом.
+	// Это может быть целое число, дробное число или число с единицами измерения.
+	@if not is-number($value) {
+
+		// Если $value не является числом, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные вычисления с нечисловыми данными.
+		@return log-invalid-type(
+			'number-strip-unit',
+			$value,
+			'$value',
+			'number'
+		);
 
-	@if is-number($value) {
-		$-result: math.div($value, $value * 0 + 1);
-	} @else {
-		@debug log-invalid-type('number-strip-unit', $value, '$value', 'number');
 	}
 
-	@return $-result;
+	// Основная логика выполняется только если $value является
+	// корректным числом.
+	@else {
+
+		// Формула удаления единиц измерения из числа:
+		// Используем математический трюк для конвертации числа
+		// в безразмерное значение.
+		//
+		// Алгоритм вычислений:
+		// 1. $value * 0 + 1 - создаем безразмерное число 1:
+		//    - $value * 0 = 0 с теми же единицами измерения, что и $value
+		//    - 0 + 1 = 1 без единиц измерения (единицы теряются при сложении
+		//      с безразмерным числом)
+		// 2. math.div($value, ...) - делим исходное значение на безразмерную 1
+		//    Деление числа с единицами измерения на безразмерное число
+		//    удаляет единицы измерения, сохраняя числовое значение.
+		//
+		// Математическая формула:
+		// result = value ÷ (value × 0 + 1)
+		//
+		// Ключевая особенность: этот метод корректно работает с любыми
+		// единицами измерения (px, rem, em, %, и т.д.) и всегда возвращает
+		// безразмерное числовое значение.
+		@return math.div($value, $value * 0 + 1);
+
+	}
 
 }