@omnisass/library 0.2.1 → 0.4.0

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

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

package/modules/utilities/helpers/number/_number-format-with-separator.scss

@@ -1,6 +1,9 @@
 @use 'sass:math';
 @use 'sass:meta';
 @use 'sass:string';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-number' as *;
+@use '../../validators/type-of/is-string' as *;
 
 /// Форматирует число, добавляя разделители тысяч для улучшения
 /// читаемости больших чисел.
@@ -93,30 +96,110 @@
 /// 	часть исходного числа игнорируется.
 /// @throws {Error} - Может выбросить ошибку если `$value`
 /// 	не является числом или если `$separator` не является строкой.
+/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
+/// 	значение, не соответствующее типу `number (`$value`) или
+/// 	`string` (`$separator`). Компиляция Sass будет остановлена
+/// 	с ошибкой.
 @function number-format-with-separator($value, $separator: ",") {
 
-	$-result: "";
-	$-str: meta.inspect(math.abs($value));
-	$-length: string.length($-str);
-	$-counter: 0;
+	// Проверка типа первого параметра: ожидается числовое значение.
+	// Функция is-number() проверяет, является ли $value числом.
+	// Это может быть целое число или дробное число.
+	@if not is-number($value) {
 
-	@for $i from $-length through 1 {
+		// Если $value не является числом, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные вычисления с нечисловыми данными.
+		@return log-invalid-type(
+			'number-format-with-separator',
+			$value,
+			'$value',
+			'number'
+		);
 
-		$char: string.slice($-str, $i, $i);
-		$-result: $char + $-result;
-		$-counter: $-counter + 1;
+	}
 
-		@if $-counter == 3 and $i > 1 {
-			$-result: $separator + $-result;
-			$-counter: 0;
-		}
+	// Проверка типа второго параметра: ожидается строковое значение
+	// разделителя тысяч. $separator определяет символ, который будет
+	// использоваться для разделения групп разрядов (по умолчанию запятая).
+	@else if not is-string($separator) {
 
-	}
+		// Если $separator не является строкой, возвращаем ошибку.
+		// Проверка выполняется только если $value прошел валидацию.
+		@return log-invalid-type(
+			'number-format-with-separator',
+			$separator,
+			'$separator',
+			'string'
+		);
 
-	@if $value < 0 {
-		$-result: "-" + $-result;
 	}
 
-	@return $-result;
+	// Все параметры прошли валидацию - выполняем форматирование числа.
+	@else {
+
+		// Инициализация переменной для хранения отформатированной строки.
+		// $-result будет содержать число с разделителями тысяч.
+		$-result: null;
+
+		// Преобразование абсолютного значения числа в строку.
+		// math.abs() возвращает абсолютное значение (без знака минус).
+		// meta.inspect() преобразует число в строковое представление.
+		$-str: meta.inspect(math.abs($value));
+
+		// Определение длины строкового представления числа.
+		// string.length() возвращает количество символов в строке.
+		$-length: string.length($-str);
+
+		// Счетчик для отслеживания количества обработанных цифр.
+		// Используется для вставки разделителя каждые 3 цифры.
+		$-counter: 0;
+
+		// Обратный цикл по символам строкового представления числа.
+		// Переменная $i принимает значения от $-length до 1 включительно.
+		// Цикл идет справа налево (от младших разрядов к старшим).
+		@for $i from $-length through 1 {
+
+			// Извлечение текущего символа (цифры) из строки.
+			// string.slice() возвращает подстроку, в данном случае один символ.
+			$char: string.slice($-str, $i, $i);
+
+			// Добавление символа в начало результата.
+			// Поскольку цикл идет справа налево, каждый новый символ
+			// добавляется в начало строки для сохранения правильного порядка.
+			$-result: $char + $-result;
+
+			// Увеличение счетчика обработанных цифр.
+			$-counter: $-counter + 1;
+
+			// Проверка: нужно ли вставить разделитель тысяч.
+			// Условие выполняется, если:
+			// 1. Обработано 3 цифры ($-counter == 3)
+			// 2. Есть еще цифры слева для обработки ($i > 1)
+			@if $-counter == 3 and $i > 1 {
+
+				// Вставка разделителя тысяч в начало результата.
+				// Разделитель добавляется перед текущей группой из 3 цифр.
+				$-result: $separator + $-result;
+
+				// Сброс счетчика для начала новой группы.
+				$-counter: 0;
+
+			}
+
+		}
+
+		// Обработка отрицательных чисел.
+		// Если исходное значение было отрицательным, добавляем знак минус
+		// в начало отформатированной строки.
+		@if $value < 0 {
+			$-result: "-" + $-result;
+		}
+
+		// Возвращаем отформатированную строку с разделителями тысяч.
+		// Число разбито на группы по 3 цифры, начиная справа.
+		@return $-result;
+
+	}
 
 }

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

@@ -1,9 +1,11 @@
 @use 'sass:math';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-number' as *;
 
 /// Нормализует число к единичному интервалу [0, 1].
 ///
 /// Функция выполняет линейное преобразование числа из
-/// исходного диапазона `[$min, $max]` в нормализованный
+/// исходного диапазона `[$value-min, $value-max]` в нормализованный
 /// диапазон `[0, 1]`. Это фундаментальная математическая
 /// операция, используемая в статистике, компьютерной графике,
 /// анимациях и алгоритмах интерполяции.
@@ -33,7 +35,7 @@
 /// > создания прогресс-баров, цветовых градиентов и других
 /// > алгоритмов, требующих значений в единичном интервале.
 /// >
-/// > Для значений вне диапазона `[$min, $max]` результат будет
+/// > Для значений вне диапазона `[$value-min, $value-max]` результат будет
 /// > выходить за пределы [0, 1], что может быть полезно для
 /// > экстраполяции или обнаружения выбросов.
 /// ---
@@ -143,18 +145,94 @@
 /// @param {Number} $value - Число для нормализации.
 /// 	Может быть любым числом: целым, дробным, положительным,
 /// 	отрицательным, с единицами измерения или без.
-/// @param {Number} $min - Нижняя граница исходного диапазона.
+/// @param {Number} $value-min - Нижняя граница исходного диапазона.
 /// 	Значение, соответствующее `0` в нормализованном диапазоне.
-/// @param {Number} $max - Верхняя граница исходного диапазона.
+/// @param {Number} $value-max - Верхняя граница исходного диапазона.
 /// 	Значение, соответствующее `1` в нормализованном диапазоне.
 /// @return {Number} - Нормализованное значение в диапазоне [0, 1].
 /// 	Возвращает дробное безразмерное число. Если `$value` находится
-/// 	между `$min` и `$max`, результат будет в диапазоне [0, 1].
-/// 	Если `$value` меньше `$min`, результат будет отрицательным.
-/// 	Если `$value` больше `$max`, результат будет больше 1.
+/// 	между `$value-min` и `$value-max`, результат будет в диапазоне [0, 1].
+/// 	Если `$value` меньше `$value-min`, результат будет отрицательным.
+/// 	Если `$value` больше `$value-max`, результат будет больше 1.
 /// @throws {Error} - Может выбросить ошибку деления на ноль, если
-/// 	`$min == $max`. В этом случае знаменатель формулы становится
+/// 	`$value-min == $value-max`. В этом случае знаменатель формулы становится
 /// 	нулем, что приводит к математической неопределенности.
-@function number-normalize($value, $min, $max) {
-	@return math.div($value - $min, $max - $min);
+/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
+/// 	значение, не соответствующее типу `number`. Компиляция Sass
+/// 	будет остановлена с ошибкой.
+@function number-normalize($value, $value-min, $value-max) {
+
+	// Проверка типа первого параметра: ожидается числовое значение.
+	// Функция is-number() проверяет, является ли $value числом.
+	// $value будет нормализовано в диапазон от 0 до 1.
+	@if not is-number($value) {
+
+		// Если $value не является числом, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные вычисления с нечисловыми данными.
+		@return log-invalid-type(
+			'number-normalize',
+			$value,
+			'$value',
+			'number'
+		);
+
+	}
+
+	// Проверка типа второго параметра: ожидается числовое значение
+	// минимальной границы исходного диапазона. $value-min определяет
+	// нижнюю границу диапазона, из которого будет нормализовано число.
+	@else if not is-number($value-min) {
+
+		// Если $value-min не является числом, возвращаем ошибку.
+		// Проверка выполняется только если $value прошел валидацию.
+		@return log-invalid-type(
+			'number-normalize',
+			$value-min,
+			'$value-min',
+			'number'
+		);
+
+	}
+
+	// Проверка типа третьего параметра: ожидается числовое значение
+	// максимальной границы исходного диапазона. $value-max определяет
+	// верхнюю границу диапазона, из которого будет нормализовано число.
+	@else if not is-number($value-max) {
+
+		// Если $value-max не является числом, возвращаем ошибку.
+		// Проверка выполняется только если $value и $value-min
+		// прошли валидацию.
+		@return log-invalid-type(
+			'number-normalize',
+			$value-max,
+			'$value-max',
+			'number'
+		);
+
+	}
+
+	// Все параметры прошли валидацию - выполняем нормализацию.
+	@else {
+
+		// Формула нормализации числа из произвольного диапазона
+		// [$value-min, $value-max] в диапазон [0, 1]:
+		//
+		// Алгоритм вычислений:
+		// 1. $value - $value-min - смещаем значение так, чтобы минимальное
+		//    значение диапазона стало 0
+		// 2. $value-max - $value-min - вычисляем ширину исходного диапазона
+		// 3. math.div(...) - делим смещенное значение на ширину диапазона
+		//    для получения нормализованного значения от 0 до 1
+		//
+		// Математическая формула:
+		// result = (value - value-min) ÷ (value-max - value-min)
+		//
+		// Ключевая особенность: функция преобразует значение из произвольного
+		// диапазона в нормализованное значение от 0 до 1, где 0 соответствует
+		// $value-min, а 1 соответствует $value-max.
+		@return math.div($value - $value-min, $value-max - $value-min);
+
+	}
+
 }

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);
+
+	}
+
 }