@omnisass/library 0.2.0 → 0.3.0

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

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

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

@@ -1,4 +1,6 @@
 @use 'sass:list';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-number' as *;
 
 /// Генерирует последовательность чисел Фибоначчи.
 ///
@@ -216,20 +218,71 @@
 /// - Второй элемент: всегда 1 (если `$n > 1`)
 /// - Каждый последующий элемент: сумма двух предыдущих
 /// - Все элементы: целые положительные числа
+/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
+/// 	значение, не соответствующее типу `number`. Компиляция Sass
+/// 	будет остановлена с ошибкой.
 @function number-fibonacci($n) {
-	$-result: ();
-	$-a: 0;
-	$-b: 1;
 
-	@for $i from 1 through $n {
+	// Проверка типа входного параметра: ожидается числовое значение.
+	// Функция is-number() проверяет, является ли $n числом.
+	// $n определяет количество чисел Фибоначчи, которые нужно сгенерировать.
+	@if not is-number($n) {
 
-		$-result: list.append($-result, $-b);
-		$-temp: $-a + $-b;
-		$-a: $-b;
-		$-b: $-temp;
+		// Если $n не является числом, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные вычисления с нечисловыми данными.
+		@return log-invalid-type(
+			'number-fibonacci',
+			$n,
+			'$n',
+			'number'
+		);
 
 	}
 
-	@return $-result;
+	// Основная логика выполняется только если $n является
+	// корректным числом.
+	@else {
+
+		// Инициализация переменной для хранения результата.
+		// $-result будет содержать список чисел Фибоначчи.
+		$-result: ();
+
+		// Инициализация начальных значений последовательности Фибоначчи.
+		// $-a и $-b представляют два предыдущих числа в последовательности.
+		// Последовательность Фибоначчи начинается с: 0, 1, 1, 2, 3, 5, 8...
+		// Для генерации n чисел мы начинаем с $-a = 0, $-b = 1.
+		$-a: 0;
+		$-b: 1;
+
+		// Цикл генерации чисел Фибоначчи.
+		// Переменная $i принимает значения от 1 до $n включительно.
+		// На каждой итерации генерируется одно число Фибоначчи.
+		@for $i from 1 through $n {
+
+			// Добавление текущего числа Фибоначчи в список результата.
+			// На первой итерации $-b = 1 (первое число Фибоначчи).
+			// Функция list.append() добавляет число в конец списка.
+			$-result: list.append($-result, $-b);
+
+			// Вычисление следующего числа Фибоначчи.
+			// Алгоритм:
+			// 1. $-temp: временная переменная для хранения суммы двух предыдущих чисел
+			// 2. $-a: обновление для следующей итерации (становится предыдущим $-b)
+			// 3. $-b: обновление для следующей итерации (становится вычисленной суммой)
+			$-temp: $-a + $-b;
+			$-a: $-b;
+			$-b: $-temp;
+
+		}
+
+		// Возвращаем список сгенерированных чисел Фибоначчи.
+		// Список содержит $n чисел, начиная с 1 (первое число Фибоначчи).
+		// Классическая последовательность Фибоначчи начинается с 0, 1,
+		// но данная реализация начинает с 1 для более практического использования
+		// в дизайне (золотое сечение, пропорции и т.д.).
+		@return $-result;
+
+	}
 
 }

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