@omnisass/library 0.2.0 → 2026.1.0-alpha.1

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

@@ -1,6 +1,4 @@
-@use '../../loggers/log-invalid-type' as *;
-@use '../../validators/type-of/is-number' as *;
-@use '../../validators/type-of/is-list' as *;
+@use '../../validators' as validators; // need type-of/is-number
 
 /// Находит минимальное числовое значение в списке.
 ///
@@ -23,7 +21,7 @@
 /// ---
 /// @name get-number-min
 /// @group utilities-getters
-/// @since 2025.12.27
+/// @since 0.0.1
 /// @access public
 /// @author Murad Rustamov (therteenten)
 /// @link https://sourcecraft.dev/users/therteenten/overview SourceCraft - therteenten
@@ -63,6 +61,7 @@
 /// @example scss - Поиск минимальной ширины контейнера
 /// 	$container-widths: 320px, 768px, 1024px, 1280px;
 /// 	@debug get-number-min($container-widths); // 320px
+/// @see get-number-min-safe
 /// @param {List} $list - Список значений, который может
 /// 	содержать элементы разных типов. Функция будет
 /// 	обрабатывать только числовые элементы.
@@ -73,90 +72,16 @@
 /// @throws {Error} - Может выбросить ошибку при попытке
 /// 	сравнить числа с несовместимыми единицами измерения.
 @function get-number-min($list) {
+	$-min: null;
 
-	// Инициализация переменной для хранения результата.
-	// Значение null используется для обозначения:
-	// - Пустого списка (возвращается null)
-	// - Отсутствия найденных чисел (в начале поиска)
-	$-result: null;
-
-	// Первичная проверка типа входного параметра.
-	// Функция ожидает получить список (list) или arglist.
-	@if not is-list($list) {
-
-		// Если $list не является списком или arglist,
-		// вызываем стандартизированную функцию логирования ошибок.
-		// Это обеспечивает единообразные сообщения об ошибках
-		// во всей кодовой базе.
-		@return log-invalid-type(
-			'get-number-min',
-			$list,
-			'$list',
-			('list', 'arglist')
-		);
-
-	}
-
-	// Основной блок обработки выполняется только если
-	// входной параметр прошел валидацию как корректный список.
-	@else {
-
-		// Итерация по всем элементам списка.
-		// Переменная $-item содержит текущий обрабатываемый элемент.
-		@each $-item in $list {
-
-			// Проверка типа текущего элемента.
-			// Функция is-number возвращает true для:
-			// - Целых и дробных чисел (42, 3.14)
-			// - Чисел с единицами измерения (10px, 2rem, 0.5em)
-			// Возвращает false для строк, булевых значений, null,
-			// карт и т.д.
-			@if is-number($-item) {
-
-				// Обновление текущего минимального значения.
-				// Условие выполняется в двух случаях:
-				// 1. $-result == null: это первое найденное число
-				//    в списке
-				// 2. $-item < $-result: текущее число меньше текущего
-				//    минимума
-				//
-				// Оператор < в Sass автоматически проверяет совместимость
-				// единиц измерения. Сравнение 10px < 2em вызовет ошибку
-				// выполнения Sass.
-				@if $-result == null or $-item < $-result {
-					$-result: $-item;
-				}
-
+	@each $-item in $list {
+		@if validators.is-number($-item) {
+			@if $-min == null or $-item < $-min {
+				$-min: $-item;
 			}
-
-			// Обработка случая, когда элемент не является числом.
-			@else {
-
-				// При обнаружении нечислового элемента функция немедленно
-				// прерывает выполнение. Это "fail-fast" подход, который
-				// предотвращает скрытые ошибки и неожиданное поведение.
-				@return log-invalid-type(
-					'get-number-min',
-					$-item,
-					'$-item',
-					'number'
-				);
-
-			}
-
 		}
-
 	}
 
-	// Возврат результата.
-	// Возможные возвращаемые значения:
-	// - null: если список был пустым или не содержал элементов
-	// - число: наименьшее значение из списка
-	//
-	// Если выполнение дошло до этой точки, значит:
-	// 1. $list был корректным списком
-	// 2. Все элементы списка были числами
-	// 3. Ни один элемент не вызвал ошибку
-	@return $-result;
+	@return $-min;
 
 }

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

@@ -1,6 +1,4 @@
 @use 'sass:math';
-@use '../../loggers/log-invalid-type' as *;
-@use '../../validators/type-of/is-number' as *;
 
 /// Вычисляет процентное отношение части к целому.
 ///
@@ -20,7 +18,7 @@
 /// ---
 /// @name get-number-percentage-of
 /// @group utilities-getters
-/// @since 2025.12.27
+/// @since 0.0.1
 /// @access public
 /// @author Murad Rustamov (therteenten)
 /// @link https://sourcecraft.dev/users/therteenten/overview SourceCraft - therteenten
@@ -91,59 +89,5 @@
 /// @throws {Error} - Может выбросить ошибку деления на ноль,
 /// 	если `$whole` равно 0, или если параметры не являются числами.
 @function get-number-percentage-of($part, $whole) {
-
-	@if not is-number($part) {
-
-		// Проверка типа параметра $part.
-		// Если $part не является числом, логируем ошибку и
-		// прерываем выполнение.
-		@return log-invalid-type(
-			'get-number-percentage-of',
-			$part,
-			'$part',
-			'number'
-		);
-
-	}
-
-	@else if not is-number($whole) {
-
-		// Проверка типа параметра $whole.
-		// Выполняется только если $part прошел проверку.
-		@return log-invalid-type(
-			'get-number-percentage-of',
-			$whole,
-			'$whole',
-			'number'
-		);
-
-	}
-
-	// Критическая проверка: предотвращение деления на ноль
-	//
-	// Математический контекст:
-	// - Деление любого числа на ноль не определено в математике
-	// - В вычислениях это приводит либо к бесконечности, либо к
-	// 	 ошибке
-	// - В Sass попытка деления на ноль вызывает ошибку компиляции
-	//
-	// Почему эта проверка важна:
-	// 1. Предотвращает падение компиляции Sass с неясной ошибкой
-	// 2. Дает разработчику понятное сообщение о проблеме
-	// 3. Сохраняет стабильность системы сборки
-	@else if $whole == 0 {
-		@error 'calc(infinity * 1%): You can\'t divide by zero!';
-	}
-
-	@else {
-
-		// Оба параметра являются числами.
-		// Вычисляем процентное отношение:
-		// 1. math.div($part, $whole) - безопасное деление
-		// 2. math.percentage() - преобразует десятичную дробь
-		//    в процент
-		@return math.percentage(math.div($part, $whole));
-
-	}
-
+	@return math.percentage(math.div($part, $whole));
 }

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

@@ -1,6 +1,4 @@
 @use 'sass:math';
-@use '../../loggers/log-invalid-type' as *;
-@use '../../validators/type-of/is-number' as *;
 
 /// Возвращает единицы измерения числа в виде строки.
 ///
@@ -19,7 +17,7 @@
 /// ---
 /// @name get-number-unit
 /// @group utilities-getters
-/// @since 2025.12.27
+/// @since 0.0.1
 /// @access public
 /// @author Murad Rustamov (therteenten)
 /// @link https://sourcecraft.dev/users/therteenten/overview SourceCraft - therteenten
@@ -57,8 +55,9 @@
 /// 	@debug get-number-unit(null);         // Ошибка, т.к. неподходящий тип
 /// 	@debug get-number-unit(auto);         // Ошибка, т.к. неподходящий тип
 /// 	@debug get-number-unit((16, "px"));   // Ошибка, т.к. неподходящий тип
-/// @param {Number} $value - Значение, единицы измерения
-/// 	которого нужно получить.
+/// @param {*} $value - Значение, единицы измерения которого
+/// 	нужно получить. Может быть любого типа, но для
+/// 	нечисловых значений функция вернет пустую строку.
 /// @return {String} - Строковое представление единиц
 /// 	измерения числа. Для чисел с единицами измерения
 /// 	возвращается строка с этими единицами. Для
@@ -67,45 +66,5 @@
 /// @throws {Error} - Не выбрасывает ошибок, только
 /// 	если значение является числом.
 @function get-number-unit($value) {
-
-	@if not is-number($value) {
-
-		// Проверка типа входного параметра.
-		// Функция ожидает получить числовое значение любого типа:
-		// - Целые числа (42)
-		// - Дробные числа (3.14)
-		// - Числа с единицами измерения (10px, 2rem, 0.5em, 50%)
-		//
-		// Если $value не является числом, вызываем стандартизированную
-		// функцию логирования ошибок для обеспечения единообразия
-		// сообщений об ошибках в проекте.
-		@return log-invalid-type(
-			'get-number-unit',
-			$value,
-			'$value',
-			'number'
-		);
-
-	} @else {
-
-		// Основная логика выполняется только если валидация
-		// типа прошла успешно.
-		//
-		// Используем встроенную функцию Sass math.unit():
-		// - Извлекает единицу измерения из числа как строку
-		// - Для безразмерных чисел возвращает пустую строку ("")
-		// - Сохраняет регистр единиц (px, PX, Px - все разные строки)
-		// - Не нормализует единицы (1cm и 10mm останутся разными строками)
-		//
-		// Примеры работы math.unit():
-		// - math.unit(10px)   → "px"
-		// - math.unit(2.5rem) → "rem"
-		// - math.unit(50%)    → "%"
-		// - math.unit(1cm)    → "cm"
-		// - math.unit(42)     → ""
-		// - math.unit(0)      → ""
-		@return math.unit($value);
-
-	}
-
+	@return math.unit($value);
 }

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

@@ -1,6 +1,4 @@
 @use 'sass:math';
-@use '../../loggers/log-invalid-type' as *;
-@use '../../validators/type-of/is-number' as *;
 
 /// Вычисляет ширину на основе высоты и соотношения сторон.
 ///
@@ -44,7 +42,7 @@
 /// ---
 /// @name get-number-width-by-ratio
 /// @group utilities-getters
-/// @since 2025.12.27
+/// @since 0.0.1
 /// @access public
 /// @author Murad Rustamov (therteenten)
 /// @link https://sourcecraft.dev/users/therteenten/overview SourceCraft - therteenten
@@ -156,64 +154,13 @@
 /// 	`width = height × ratio`. Сохраняет единицы измерения
 /// 	параметра `$height`.
 @function get-number-width-by-ratio($height, $ratio) {
-
-	@if not is-number($height) {
-
-		// Валидация первого параметра: высота.
-		// Функция ожидает числовое значение, которое может содержать
-		// единицы измерения (px, rem, em, %, и т.д.).
-		//
-		// Если $height не является числом (например, строка, булево
-		// значение), вызываем стандартизированную функцию
-		// логирования ошибок.
-		@return log-invalid-type(
-			'get-number-width-by-ratio',
-			$height,
-			'$height',
-			'number'
-		);
-
-	}
-
-	@else if not is-number($ratio) {
-
-		// Валидация второго параметра: соотношение сторон.
-		// Соотношение должно быть числом (чаще всего безразмерным).
-		//
-		// Проверка выполняется только если $height прошел валидацию.
-		// Это последовательный подход fail-fast (быстрая остановка
-		// при ошибке).
-		@return log-invalid-type(
-			'get-number-width-by-ratio',
-			$ratio,
-			'$ratio',
-			'number'
-		);
-
-	}
-
-	@else {
-
-		// Оба параметра валидны - выполняем вычисление.
-		//
-		// Формула: ширина = высота × соотношение.
-		//
-		// Важные аспекты:
-		// 1. Умножение $height (с единицами) на $ratio (безразмерное)
-		//    сохраняет единицы измерения из $height
-		// 2. Если $ratio также имеет единицы, Sass попытается их
-		//    перемножить, что может привести к неожиданным результатам
-		// 3. Рекомендуется передавать $ratio как безразмерное число
-		@return $height * $ratio;
-
-	}
-
+	@return $height * $ratio;
 }
 
 /// @name get-width-by-ratio
 /// @alias get-number-width-by-ratio
 /// @group utilities-aliases
-/// @since 2025.12.27
+/// @since 0.0.1
 /// @access public
 /// @author Murad Rustamov (therteenten)
 /// @link https://sourcecraft.dev/users/therteenten/overview SourceCraft - therteenten

package/modules/utilities/helpers/_index.scss

@@ -0,0 +1,44 @@
+////
+/// @group utilities-helpers
+////
+
+// Colors
+@forward 'color/color-blend';
+@forward 'color/color-blend-steps';
+@forward 'color/color-hue-shift';
+@forward 'color/color-scale';
+@forward 'color/color-shade';
+@forward 'color/color-tint';
+@forward 'color/color-triad';
+
+// List
+@forward 'list/list-dedupe';
+@forward 'list/list-insert-at';
+@forward 'list/list-merge';
+@forward 'list/list-sum-numbers';
+@forward 'list/list-sum-numbers-safe';
+@forward 'list/list-remove-at';
+
+// Number
+@forward 'number/number-ceil-to';
+@forward 'number/number-clamp';
+@forward 'number/number-clamp-max';
+@forward 'number/number-clamp-min';
+@forward 'number/number-denormalize';
+@forward 'number/number-fibonacci';
+@forward 'number/number-floor-to';
+@forward 'number/number-format-with-separator';
+@forward 'number/number-normalize';
+@forward 'number/number-random-between';
+@forward 'number/number-random-between-int';
+@forward 'number/number-range';
+@forward 'number/number-round-to';
+@forward 'number/number-round-to-nearest';
+@forward 'number/number-strip-unit';
+
+// String
+@forward 'string/string-capitalize';
+@forward 'string/string-replace';
+@forward 'string/string-trim';
+@forward 'string/string-trim-end';
+@forward 'string/string-trim-start';

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

@@ -1,9 +1,6 @@
 @use 'sass:math';
 @use 'sass:list';
 @use 'sass:color';
-@use '../../loggers/log-invalid-type' as *;
-@use '../../validators/type-of/is-color' as *;
-@use '../../validators/type-of/is-number' as *;
 
 /// Создает последовательность равномерно распределенных
 /// цветов между двумя точками.
@@ -25,7 +22,7 @@
 /// ---
 /// @name color-blend-steps
 /// @group utilities-helpers
-/// @since 2025.12.27
+/// @since 0.0.1
 /// @access public
 /// @author Murad Rustamov (therteenten)
 /// @link https://sourcecraft.dev/users/therteenten/overview SourceCraft - therteenten
@@ -118,93 +115,12 @@
 /// - Промежуточные элементы: равномерно распределенные смеси
 /// - Всего элементов: `$steps + 2`
 @function color-blend-steps($color-start, $color-end, $steps: 5) {
-
-	// Инициализация списка для хранения промежуточных цветов.
-	// Результатом функции будет список (массив) цветов,
-	// представляющих градиентный переход от начального цвета
-	// к конечному.
 	$-colors: ();
 
-	// Проверка типа первого параметра: ожидается начальный цвет.
-	// Функция is-color() проверяет, является ли $color-start
-	// валидным цветом CSS.
-	@if not is-color($color-start) {
-
-		// Если $color-start не является цветом, возвращаем ошибку через
-		// стандартную функцию логирования. Это предотвращает
-		// некорректные вычисления с нецветовыми данными.
-		@return log-invalid-type(
-			'color-blend-steps',
-			$color-start,
-			'$color-start',
-			'color'
-		);
-
-	}
-
-	// Проверка типа второго параметра: ожидается конечный цвет.
-	// Проверка выполняется только если $color-start прошел валидацию.
-	@else if not is-color($color-end) {
-
-		// Если $color-end не является цветом, возвращаем ошибку.
-		@return log-invalid-type(
-			'color-blend-steps',
-			$color-end,
-			'$color-end',
-			'color'
-		);
-
-	}
-
-	// Проверка типа третьего параметра: ожидается количество шагов.
-	// $steps определяет, сколько промежуточных цветов будет сгенерировано
-	// между начальным и конечным цветом.
-	@else if not is-number($steps) {
-
-		// Если $steps не является числом, возвращаем ошибку.
-		@return log-invalid-type(
-			'color-blend-steps',
-			$steps,
-			'$steps',
-			'number'
-		);
-
-	}
-
-	// Все параметры прошли валидацию - выполняем генерацию цветов.
-	@else {
-
-		// Цикл генерации промежуточных цветов.
-		// Переменная $i принимает значения от 0 до $steps включительно.
-		// Это создает $steps + 1 цвет в итоговом списке
-		// (включая начальный и конечный цвета).
-		@for $i from 0 through $steps {
-
-			// Вычисление процентного соотношения для текущего шага.
-			// Формула: (текущий шаг) × (100% / общее количество шагов)
-			// Пример для 5 шагов: шаги будут на 0%, 20%, 40%, 60%, 80%, 100%
-			$-percentage: $i * math.div(100, $steps);
-
-			// Создание промежуточного цвета с помощью функции color.mix()
-			// color.mix() смешивает два цвета в указанной пропорции.
-			// Параметры:
-			// - $color-end: первый цвет для смешивания
-			// - $color-start: второй цвет для смешивания
-			// - $-percentage * 1%: процентное соотношение
-			//   (сколько процентов $color-start в смеси)
-			//
-			// Примечание: порядок параметров в color.mix() важен:
-			// - При $-percentage = 0% → 100% $color-end, 0% $color-start
-			// - При $-percentage = 100% → 0% $color-end, 100% $color-start
-			$-colors: list.append($-colors, color.mix($color-end, $color-start, $-percentage * 1%));
-
-		}
-
-		// Возвращаем список сгенерированных цветов.
-		// Список содержит $steps + 1 элементов, равномерно распределенных
-		// между начальным и конечным цветом.
-		@return $-colors;
-
+	@for $-i from 0 through $steps {
+		$-percentage: $-i * math.div(100, $steps);
+		$-colors: list.append($-colors, color.mix($color-end, $color-start, $-percentage * 1%));
 	}
 
+	@return $-colors;
 }

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

@@ -1,7 +1,4 @@
 @use 'sass:color';
-@use '../../loggers/log-invalid-type' as *;
-@use '../../validators/type-of/is-color' as *;
-@use '../../validators/type-of/is-number' as *;
 
 /// Линейная интерполяция (смешивание) между двумя цветами.
 ///
@@ -27,7 +24,7 @@
 /// ---
 /// @name color-blend
 /// @group utilities-helpers
-/// @since 2025.12.27
+/// @since 0.0.1
 /// @access public
 /// @author Murad Rustamov (therteenten)
 /// @link https://sourcecraft.dev/users/therteenten/overview SourceCraft - therteenten
@@ -91,93 +88,22 @@
 /// 	$darkened: color-blend($base-color, black, 30);   // Затемнение на 30%
 /// @see color-shade
 /// @see color-tint
-/// @param {Color} $color-from - Исходный (начальный) цвет. Может
+/// @param {Color} $from - Исходный (начальный) цвет. Может
 /// 	быть в любом формате, поддерживаемом Sass (HEX, RGB,
 /// 	HSL и т.д.).
-/// @param {Color} $color-to - Целевой (конечный) цвет. Автоматически
+/// @param {Color} $to - Целевой (конечный) цвет. Автоматически
 /// 	приводится к тому же цветовому пространству, что и
-/// 	`$color-from`.
+/// 	`$from`.
 /// @param {Number} $percentage - Процент смешивания от
-/// 	`$color-from` к `$color-to` (0-100). Значение автоматически
+/// 	`$from` к `$to` (0-100). Значение автоматически
 /// 	конвертируется в проценты с помощью умножения на 1%.
-/// - 0: возвращает чистый цвет `$color-from`
-/// - 100: возвращает чистый цвет `$color-to`
-/// - 50: возвращает ровную смесь `50/50`
+/// 	- 0: возвращает чистый цвет `$from`
+/// 	- 100: возвращает чистый цвет `$to`
+/// 	- 50: возвращает ровную смесь `50/50`
 /// @return {Color} - Промежуточный цвет, полученный линейной
-/// 	интерполяцией между `$color-from` и `$color-to` в указанной пропорции.
+/// 	интерполяцией между `$from` и `$to` в указанной пропорции.
 /// 	Использует цветовое пространство по умолчанию для
 /// 	смешивания (обычно sRGB).
-@function color-blend($color-from, $color-to, $percentage) {
-
-	// Проверка типа первого параметра: ожидается начальный цвет.
-	// Функция is-color() проверяет, является ли $color-from
-	// валидным цветом CSS.
-	@if not is-color($color-from) {
-
-		// Если $color-from не является цветом, возвращаем ошибку через
-		// стандартную функцию логирования. Это предотвращает
-		// некорректные вычисления с нецветовыми данными.
-		@return log-invalid-type(
-			'color-blend',
-			$color-from,
-			'$color-from',
-			'color'
-		);
-
-	}
-
-	// Проверка типа второго параметра: ожидается конечный цвет.
-	// Проверка выполняется только если $color-from прошел валидацию.
-	@else if not is-color($color-to) {
-
-		// Если $color-to не является цветом, возвращаем ошибку.
-		@return log-invalid-type(
-			'color-blend',
-			$color-to,
-			'$color-to',
-			'color'
-		);
-
-	}
-
-	// Проверка типа третьего параметра: ожидается процент смешивания.
-	// $percentage определяет, сколько процентов начального цвета
-	// будет в итоговой смеси (от 0 до 100).
-	@else if not is-number($percentage) {
-
-		// Если $percentage не является числом, возвращаем ошибку.
-		@return log-invalid-type(
-			'color-blend',
-			$percentage,
-			'$percentage',
-			'number'
-		);
-
-	}
-
-	// Все параметры прошли валидацию - выполняем смешивание цветов.
-	@else {
-
-		// Формула смешивания: создаем промежуточный цвет между
-		// $color-from и $color-to с указанным процентным соотношением.
-		//
-		// Используем встроенную функцию color.mix():
-		// Параметры:
-		// - $color-to: первый цвет для смешивания
-		// - $color-from: второй цвет для смешивания
-		// - $percentage * 1%: процентное соотношение
-		//   (сколько процентов $color-from в смеси)
-		//
-		// Математика смешивания:
-		// - При $percentage = 0% → 100% $color-to, 0% $color-from
-		// - При $percentage = 50% → 50% $color-to, 50% $color-from
-		// - При $percentage = 100% → 0% $color-to, 100% $color-from
-		//
-		// Ключевая особенность: функция является оберткой над
-		// color.mix() с добавлением валидации параметров и
-		// преобразованием процентов в правильный формат.
-		@return color.mix($color-to, $color-from, $percentage * 1%);
-
-	}
-
+@function color-blend($from, $to, $percentage) {
+	@return color.mix($to, $from, $percentage * 1%);
 }