@omnisass/library 0.2.0 → 2026.1.0-alpha.1

package/modules/utilities/converters/_convert-hex2rgba.scss

@@ -1,7 +1,4 @@
 @use 'sass:color';
-@use '../validators/type-of/is-color' as *;
-@use '../validators/type-of/is-number' as *;
-@use '../loggers/log-invalid-type' as *;
 
 /// Преобразует цвет в строку формата RGBA с поддержкой
 /// прозрачности.
@@ -15,7 +12,7 @@
 /// ---
 /// @name convert-hex2rgba
 /// @group utilities-converters
-/// @since 2025.12.27
+/// @since 0.0.1
 /// @access public
 /// @author Murad Rustamov (therteenten)
 /// @link https://sourcecraft.dev/users/therteenten/overview SourceCraft - therteenten
@@ -68,57 +65,5 @@
 /// 	где `r`, `g`, `b` - числовые значения от 0 до 255,
 /// 	`a` - значение прозрачности.
 @function convert-hex2rgba($color, $alpha: 1) {
-
-	// Проверка типа первого параметра: ожидается
-	// цветовое значение.
-	// Функция is-color() проверяет, является ли $color
-	// валидным цветом CSS.
-	@if not is-color($color) {
-
-		// Если $color не является цветом, логируем ошибку через
-		// отладочное сообщение.
-		@return log-invalid-type(
-			'convert-hex2rgba',
-			$color,
-			'$color',
-			'color'
-		);
-
-	}
-
-	// Проверка типа второго параметра: ожидается числовое значение
-	// для альфа-канала (прозрачности).
-	@else if not is-number($alpha) {
-
-		// Если $alpha не является числом, логируем ошибку через
-		// отладочное сообщение.
-		@return log-invalid-type(
-			'convert-hex2rgba',
-			$alpha,
-			'$alpha',
-			'number'
-		);
-
-	}
-
-	// Оба параметра прошли валидацию - выполняем конвертацию.
-	@else {
-
-		// Формула преобразования: создаем строку формата rgba()
-		// из компонентов цвета и значения альфа-канала.
-		//
-		// Алгоритм преобразования:
-		// 1. Извлекаем красный канал: color.channel($color, "red", $space: rgb)
-		// 	   Возвращает числовое значение от 0 до 255
-		// 2. Извлекаем зеленый канал: color.channel($color, "green", $space: rgb)
-		// 3. Извлекаем синий канал: color.channel($color, "blue", $space: rgb)
-		// 4. Используем переданное значение альфа-канала: $alpha
-		// 5. Формируем строку: rgba(красный, зеленый, синий, альфа)
-		//
-		// Ключевая особенность: функция возвращает строку, а не
-		// цветовой тип, из-за интерполяции #{} внутри строки.
-		@return 'rgba(#{color.channel($color, "red", $space: rgb)}, #{color.channel($color, "green", $space: rgb)}, #{color.channel($color, "blue", $space: rgb)}, #{$alpha})';
-
-	}
-
+	@return "rgba(#{color.channel($color, "red", $space: rgb)}, #{color.channel($color, "green", $space: rgb)}, #{color.channel($color, "blue", $space: rgb)}, #{$alpha})";
 }

package/modules/utilities/converters/_convert-px2em.scss

@@ -1,7 +1,5 @@
 @use 'sass:math';
-@use '../helpers/number/number-strip-unit' as *;
-@use '../loggers/log-invalid-type' as *;
-@use '../validators/type-of/is-number' as *;
+@use '../helpers' as helpers; // need number/number-strip-unit
 
 /// Конвертирует значения из пикселей (`px`) в относительные
 /// единицы (`em`).
@@ -31,7 +29,7 @@
 /// ---
 /// @name convert-px2em
 /// @group utilities-converters
-/// @since 2025.12.27
+/// @since 0.0.1
 /// @access public
 /// @author Murad Rustamov (therteenten)
 /// @link https://sourcecraft.dev/users/therteenten/overview SourceCraft - therteenten
@@ -175,62 +173,5 @@
 /// 	Также может выбросить ошибку при передаче нечисловых
 /// 	значений.
 @function convert-px2em($px, $base: 16px) {
-
-	// Проверка типа первого параметра: ожидается числовое
-	// значение в пикселях.
-	@if not is-number($px) {
-
-		// Если $px не является числом, возвращаем ошибку через
-		// стандартную функцию логирования. Это предотвращает
-		// некорректные вычисления с нечисловыми данными.
-		@return log-invalid-type(
-			'convert-px2em',
-			$px,
-			'$px',
-			'number'
-		);
-
-	}
-
-	// Проверка типа второго параметра: ожидается числовое
-	// значение базового размера.
-	@else if not is-number($base) {
-
-		// Если $base не является числом, возвращаем ошибку.
-		// Проверка выполняется только если $px прошел валидацию.
-		@return log-invalid-type(
-			'convert-px2em',
-			$base,
-			'$base',
-			'number'
-		);
-
-	}
-
-	// Оба параметра прошли валидацию - выполняем конвертацию.
-	@else {
-
-		// Формула конвертации: em = px ÷ базовый_размер_шрифта.
-		//
-		// Алгоритм вычислений:
-		// 1. number-strip-unit($px) - удаляем единицу измерения
-		// 	   'px' из первого значения
-		// 	   Пример: 24px → 24 (число без единиц)
-		// 2. number-strip-unit($base) - удаляем единицу измерения
-		// 	   из базового размера
-		// 	   Пример: 16px → 16 (число без единиц)
-		// 3. Делим безразмерные числа: (число px) ÷ (базовый размер)
-		// 	   Используем math.div() для безопасного деления
-		// 	   Пример: math.div(24, 16) = 1.5
-		// 4. Умножаем результат на 1em для добавления единицы
-		// 	   измерения em
-		// 	   Пример: 1.5 × 1em = 1.5em
-		//
-		// Ключевая особенность: результат в em зависит от размера
-		// шрифта родительского элемента. Если размер шрифта родителя
-		// изменяется, em значения адаптируются относительно него.
-		@return math.div(number-strip-unit($px), number-strip-unit($base)) * 1em;
-
-	}
-
+	@return math.div(helpers.number-strip-unit($px), helpers.number-strip-unit($base)) * 1em;
 }

package/modules/utilities/converters/_convert-px2rem.scss

@@ -1,7 +1,5 @@
 @use 'sass:math';
-@use '../helpers/number/number-strip-unit' as *;
-@use '../loggers/log-invalid-type' as *;
-@use '../validators/type-of/is-number' as *;
+@use '../helpers' as helpers; // need number/number-strip-unit
 
 /// Конвертирует значения из пикселей (`px`) в относительные
 /// единицы (`rem`).
@@ -24,7 +22,7 @@
 /// ---
 /// @name convert-px2rem
 /// @group utilities-converters
-/// @since 2025.12.27
+/// @since 0.0.1
 /// @access public
 /// @author Murad Rustamov (therteenten)
 /// @link https://sourcecraft.dev/users/therteenten/overview SourceCraft - therteenten
@@ -119,62 +117,5 @@
 /// 	Также может выбросить ошибку при передаче нечисловых
 /// 	значений.
 @function convert-px2rem($px, $base: 16px) {
-
-	// Проверка типа первого параметра: ожидается числовое
-	// значение в пикселях.
-	@if not is-number($px) {
-
-		// Если $px не является числом, возвращаем ошибку через
-		// стандартную функцию логирования. Это предотвращает
-		// некорректные вычисления с нечисловыми данными.
-		@return log-invalid-type(
-			'convert-px2rem',
-			$px,
-			'$px',
-			'number'
-		);
-
-	}
-
-	// Проверка типа второго параметра: ожидается числовое
-	// значение базового размера.
-	@else if not is-number($base) {
-
-		// Если $base не является числом, возвращаем ошибку.
-		// Проверка выполняется только если $px прошел валидацию.
-		@return log-invalid-type(
-			'convert-px2rem',
-			$base,
-			'$base',
-			'number'
-		);
-
-	}
-
-	// Оба параметра прошли валидацию - выполняем конвертацию.
-	@else {
-
-		// Формула конвертации: rem = px ÷ базовый_размер_шрифта.
-		//
-		// Алгоритм вычислений:
-		// 1. number-strip-unit($px) - удаляем единицу измерения
-		// 	   'px' из первого значения
-		// 	   Пример: 24px → 24 (число без единиц)
-		// 2. number-strip-unit($base) - удаляем единицу измерения
-		// 	   из базового размера
-		// 	   Пример: 16px → 16 (число без единиц)
-		// 3. Делим безразмерные числа: (число px) ÷ (базовый размер)
-		// 	   Используем math.div() для безопасного деления
-		// 	   Пример: math.div(24, 16) = 1.5
-		// 4. Умножаем результат на 1rem для добавления единицы
-		// 	   измерения rem
-		// 	   Пример: 1.5 × 1rem = 1.5rem
-		//
-		// Ключевая особенность: результат в rem зависит от базового
-		// размера шрифта. Если пользователь изменит размер шрифта
-		// в браузере, rem значения адаптируются.
-		@return math.div(number-strip-unit($px), number-strip-unit($base)) * 1rem;
-
-	}
-
+	@return math.div(helpers.number-strip-unit($px), helpers.number-strip-unit($base)) * 1rem;
 }

package/modules/utilities/converters/_convert-rem2px.scss

@@ -1,6 +1,4 @@
-@use '../helpers/number/number-strip-unit' as *;
-@use '../loggers/log-invalid-type' as *;
-@use '../validators/type-of/is-number' as *;
+@use '../helpers' as helpers; // need number/number-strip-unit
 
 /// Конвертирует значения из относительных единиц (`rem`) в
 /// пиксели (`px`).
@@ -24,7 +22,7 @@
 /// ---
 /// @name convert-rem2px
 /// @group utilities-converters
-/// @since 2025.12.27
+/// @since 0.0.1
 /// @access public
 /// @author Murad Rustamov (therteenten)
 /// @link https://sourcecraft.dev/users/therteenten/overview SourceCraft - therteenten
@@ -146,62 +144,5 @@
 /// 	нечисловых значений. Для корректной работы оба аргумента
 /// 	должны быть числами.
 @function convert-rem2px($rem, $base: 16px) {
-
-	// Проверка типа первого параметра: ожидается числовое
-	// значение в rem.
-	@if not is-number($rem) {
-
-    // Если $rem не является числом, возвращаем ошибку через
-		// стандартную функцию логирования. Это предотвращает
-		// некорректные вычисления с нечисловыми данными.
-    @return log-invalid-type(
-        'convert-rem2px',
-        $rem,
-        '$rem',
-        'number'
-    );
-
-	}
-
-	// Проверка типа второго параметра: ожидается числовое
-	// значение базового размера.
-	@else if not is-number($base) {
-
-    // Если $base не является числом, возвращаем ошибку.
-    // Проверка выполняется только если $rem прошел валидацию.
-    @return log-invalid-type(
-        'convert-rem2px',
-        $base,
-        '$base',
-        'number'
-    );
-
-	}
-
-	// Оба параметра прошли валидацию - выполняем конвертацию.
-	@else {
-
-    // Формула конвертации: px = rem × базовый_размер_шрифта.
-    //
-    // Алгоритм вычислений:
-    // 1. number-strip-unit($rem) - удаляем единицу измерения
-		// 	   'rem' из первого значения
-    // 	   Пример: 1.5rem → 1.5 (число без единиц)
-    // 2. number-strip-unit($base) - удаляем единицу измерения
-		// 	   из базового размера
-    // 	   Пример: 16px → 16 (число без единиц)
-    // 3. Умножаем оба безразмерных числа: (число rem) × (базовый
-		// 	   размер)
-    // 	   Пример: 1.5 × 16 = 24
-    // 4. Умножаем результат на 1px для добавления единицы
-		// 	   измерения пикселей
-    // 	   Пример: 24 × 1px = 24px
-    //
-    // Важно: функция предполагает, что $base передается в
-		// пикселях. Если $base будет в других единицах, результат
-		// будет неожиданным.
-    @return number-strip-unit($rem) * number-strip-unit($base) * 1px;
-
-	}
-
+  @return helpers.number-strip-unit($rem) * helpers.number-strip-unit($base) * 1px;
 }

package/modules/utilities/converters/_index.scss

@@ -0,0 +1,10 @@
+////
+/// @group utilities-converters
+////
+
+@forward 'convert-em2px';
+@forward 'convert-hex2rgb';
+@forward 'convert-hex2rgba';
+@forward 'convert-px2em';
+@forward 'convert-px2rem';
+@forward 'convert-rem2px';

package/modules/utilities/getters/_index.scss

@@ -0,0 +1,23 @@
+////
+/// @group utilities-getters
+////
+
+// Color
+@forward 'color/get-color-brightness';
+@forward 'color/get-color-darkest';
+
+// List
+@forward 'list/get-list-item';
+@forward 'list/get-list-item-end';
+@forward 'list/get-list-item-start';
+
+// Number
+@forward 'number/get-number-from-percent';
+@forward 'number/get-number-height-by-ratio';
+@forward 'number/get-number-width-by-ratio';
+@forward 'number/get-number-max';
+@forward 'number/get-number-max-safe';
+@forward 'number/get-number-min';
+@forward 'number/get-number-min-safe';
+@forward 'number/get-number-percentage-of';
+@forward 'number/get-number-unit';

package/modules/utilities/getters/color/_get-color-brightness.scss

@@ -1,6 +1,4 @@
 @use 'sass:color';
-@use '../../loggers/log-invalid-type' as *;
-@use '../../validators/type-of/is-color' as *;
 
 /// Рассчитывает яркость (светлоту) цвета.
 ///
@@ -17,7 +15,7 @@
 /// ---
 /// @name get-color-brightness
 /// @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
@@ -90,49 +88,5 @@
 /// 	серые тона - промежуточные значения в зависимости от
 /// 	их светлоты.
 @function get-color-brightness($color) {
-
-	// Проверка типа входного параметра: ожидается
-	// цветовое значение.
-	//
-	// Функция is-color() проверяет, является ли $color
-	// валидным цветом CSS.
-	// Поддерживаемые форматы: hex, rgb, rgba, hsl,
-	// hsla, названия цветов.
-	@if not is-color($color) {
-
-		// Если $color не является цветом, логируем ошибку
-		// через отладочное сообщение:
-		@return log-invalid-type(
-			'get-color-brightness',
-			$color,
-			'$color',
-			'color'
-		);
-
-	} @else {
-
-		// Основная логика выполняется только если $color
-		// является валидным цветом.
-		//
-		// Используем функцию color.channel() для извлечения
-		// компонента яркости:
-		// - Первый параметр: $color - исходный цвет
-		// - Второй параметр: "lightness" - извлекаем компонент
-		// 	  яркости
-		// - Третий параметр: $space: hsl - указываем цветовое
-		// 	  пространство HSL
-		//
-		// HSL (Hue, Saturation, Lightness) - цветовая модель:
-		// - Hue (оттенок): угол на цветовом круге (0-360deg)
-		// - Saturation (насыщенность): процент (0%-100%)
-		// - Lightness (яркость): процент (0%-100%)
-		//
-		// Возвращаемое значение: процент от 0% до 100%, где:
-		// - 0% = абсолютно черный
-		// - 100% = абсолютно белый
-		// - 50% = чистый цвет (без добавления черного или белого)
-		@return color.channel($color, "lightness", $space: hsl);
-
-	}
-
+	@return color.channel($color, "lightness", $space: hsl);
 }

package/modules/utilities/getters/color/_get-color-darkest.scss

@@ -1,6 +1,4 @@
 @use 'sass:color';
-@use '../../loggers/log-invalid-type' as *;
-@use '../../validators/type-of/is-list' as *;
 
 /// Находит самый темный цвет в списке по значению lightness
 /// в HSL-пространстве.
@@ -26,7 +24,7 @@
 /// ---
 /// @name get-color-darkest
 /// @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
@@ -93,7 +91,7 @@
 ///
 /// 	// Важно: функция не валидирует типы элементов!
 /// 	@debug get-color-darkest((#ff0000, 10px, #0000ff)); // Ошибка при вычислении lightness
-/// @param {List} $color-list - Список цветов для анализа.
+/// @param {List} $colorsList - Список цветов для анализа.
 /// 	Ожидается, что все элементы списка являются валидными
 /// 	цветами в любом формате (hex, rgb, hsl, названия и т.д.).
 /// @return {Color | Null} - Самый темный цвет из списка по
@@ -104,75 +102,22 @@
 /// @throws {Error} - Может выбросить ошибку, если в списке
 /// 	встречаются элементы, не являющиеся цветами, при
 /// 	попытке вызова `color.channel()`.
-@function get-color-darkest($color-list) {
+@function get-color-darkest($colorsList) {
 
-	// Инициализация переменных для хранения результата поиска.
-	// - $-result: будет содержать самый темный цвет из списка
-	// - $-min-lightness: будет содержать минимальное значение
-	// 	  яркости (наименьшая яркость = самый темный)
-	$-result: '';
-	$-min-lightness: null;
+  $-darkest: null;
+  $-min-lightness: null;
 
-	// Проверка типа входного параметра: ожидается список
-	// (list) или arglist цветов.
-	// Функция предназначена для работы со списком цветовых
-	// значений.
-	@if not is-list($color-list) {
+  @each $-color in $colorsList {
 
-		// Если $color-list не является списком, возвращаем
-		// ошибку через стандартную функцию логирования. Это
-		// предотвращает дальнейшее выполнение с некорректными
-		// данными.
-		@return log-invalid-type(
-			'get-color-darkest',
-			$color-list,
-			'$color-list',
-			('list', 'arglist')
-		);
+    $-lightness: color.channel($-color, "lightness", $space: hsl);
 
-	}
+    @if $-min-lightness == null or $-lightness < $-min-lightness {
+      $-min-lightness: $-lightness;
+      $-darkest: $-color;
+    }
 
-	// Основная логика выполняется только если входной параметр
-	// прошел валидацию.
-	@else {
+  }
 
-		// Итерация по всем цветам в списке.
-		@each $-color in $color-list {
-
-			// Для каждого цвета вычисляем его яркость (lightness) в
-			// пространстве HSL.
-			// - color.channel() извлекает компонент яркости из цвета.
-			// - $space: hsl указывает использовать HSL цветовое
-			// 	  пространство
-			// Результат: процентное значение от 0% до 100%.
-			// 0% = абсолютно черный, 100% = абсолютно белый.
-			$-lightness: color.channel($-color, "lightness", $space: hsl);
-
-			// Поиск цвета с минимальной яркостью (самого темного).
-			// Условие выполняется в двух случаях:
-			// 1. $-min-lightness == null: это первый обрабатываемый
-			// 	   цвет в списке
-			// 2. $-lightness < $-min-lightness: текущий цвет темнее
-			// 	   предыдущего найденного
-			@if $-min-lightness == null or $-lightness < $-min-lightness {
-
-				// Обновляем значения:
-				// - $-min-lightness: запоминаем новое минимальное значение
-				// 	  яркости
-				// - $-result: сохраняем ссылку на самый темный цвет на
-				// 	  данный момент
-				$-min-lightness: $-lightness;
-				$-result: $-color;
-
-			}
-
-		}
-
-		// Возвращаем самый темный цвет из списка.
-		// Если список был пустым, вернется начальное
-		// значение '' (пустая строка).
-		@return $-result;
-
-	}
+  @return $-darkest;
 
 }

package/modules/utilities/getters/list/_get-list-item-end.scss

@@ -1,6 +1,4 @@
 @use 'sass:list';
-@use '../../loggers/log-invalid-type' as *;
-@use '../../validators/type-of/is-list' as *;
 
 /// Возвращает последний элемент списка.
 ///
@@ -12,7 +10,7 @@
 /// ---
 /// @name get-list-item-end
 /// @group utilities-getters
-/// @since 2025.12.27
+/// @since 0.0.1
 /// @access public
 /// @author Sindre Sorhus
 /// @author Murad Rustamov (therteenten)
@@ -85,30 +83,5 @@
 /// @throws Не выбрасывает ошибок, возвращает
 /// 	`null` для пустых списков
 @function get-list-item-end($list) {
-
-	@if not is-list($list) {
-
-		// Валидация типа входного параметра.
-    // Функция ожидает получить список (list) или arglist.
-		@return log-invalid-type(
-			'get-list-item-end',
-			$list,
-			'$list',
-			('list', 'arglist')
-		);
-
-	} @else {
-
-		// Основная логика выполняется только если $list является
-		// корректным списком.
-    //
-    // Используем встроенную функцию Sass list.nth():
-    // - Извлекает элемент по указанному индексу (в данном
-		// 	  случае -1 - последний)
-    // - Для пустого списка возвращает null
-    // - Сохраняет тип и значение элемента без изменений
-		@return list.nth($list, -1);
-
-	}
-
+	@return list.nth($list, -1);
 }

package/modules/utilities/getters/list/_get-list-item-start.scss

@@ -1,6 +1,4 @@
 @use 'sass:list';
-@use '../../loggers/log-invalid-type' as *;
-@use '../../validators/type-of/is-list' as *;
 
 /// Возвращает первый элемент списка.
 ///
@@ -13,7 +11,7 @@
 /// ---
 /// @name get-list-item-start
 /// @group utilities-getters
-/// @since 2025.12.27
+/// @since 0.0.1
 /// @access public
 /// @author Sindre Sorhus
 /// @author Murad Rustamov (therteenten) [адаптация]
@@ -80,30 +78,5 @@
 /// @throws Не выбрасывает ошибки, но возвращает
 /// 	`null` для пустых списков.
 @function get-list-item-start($list) {
-
-	@if not is-list($list) {
-
-		// Валидация типа входного параметра.
-    // Функция ожидает получить список (list) или arglist.
-		@return log-invalid-type(
-			'get-list-item-start',
-			$list,
-			'$list',
-			('list', 'arglist')
-		);
-
-	} @else {
-
-		// Основная логика выполняется только если $list является
-		// корректным списком.
-    //
-    // Используем встроенную функцию Sass list.nth():
-    // - Извлекает элемент по указанному индексу (в данном
-		// 	  случае 1 - первый)
-    // - Для пустого списка возвращает null
-    // - Сохраняет тип и значение элемента без изменений
-		@return list.nth($list, 1);
-
-	}
-
+	@return list.nth($list, 1);
 }