@omnisass/library 0.2.0

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

@@ -0,0 +1,168 @@
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-number' as *;
+@use '../../validators/type-of/is-list' as *;
+
+/// Находит максимальное числовое значение в списке.
+///
+/// Функция проходит по всем элементам списка и находит
+/// наибольшее числовое значение. Нечисловые элементы (строки,
+/// цвета, списки, карты и т.д.) игнорируются без вывода
+/// ошибок. Если в списке нет числовых элементов, функция
+/// возвращает `null`.
+///
+/// Важные особенности функции:
+/// - Игнорирует все нечисловые элементы без предупреждений
+/// - Возвращает `null` для пустых списков или списков без чисел
+/// - Сравнивает только числа с совместимыми единицами измерения
+/// - Использует локальные переменные с префиксом `$-` для
+/// 	избежания конфликтов
+/// - Не является прямой заменой `math.max()`, которая принимает
+/// 	аргументы, а не список
+/// - Сохраняет единицы измерения найденного максимального
+/// 	значения
+/// ---
+/// @name get-number-max
+/// @group utilities-getters
+/// @since 2025.12.27
+/// @access public
+/// @author Murad Rustamov (therteenten)
+/// @link https://sourcecraft.dev/users/therteenten/overview SourceCraft - therteenten
+/// @link https://sourcecraft.dev/omnisass/library SourceCraft - OmniSass
+/// @link https://sass-lang.com/documentation/modules/math#max См. также: Официальная документация Sass - Функция math.max()
+/// @link https://sass-lang.com/documentation/values/numbers#units См. также: Официальная документация Sass - Числа и единицы измерения
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/max MDN Web Docs - CSS функция max()
+/// @link https://stackoverflow.com/questions/19088270/find-the-highest-number-in-a-list-with-sass Stack Overflow - Поиск наибольшего числа в списке Sass
+/// @link https://css-tricks.com/snippets/sass/ См. также: CSS-Tricks - Коллекция сниппетов Sass
+/// @link https://sass-guidelin.es/ru/#list-functions См. также: Sass Guidelines - Функции для работы со списками
+/// @link https://frontender.info/sass-lists/ См. также: Frontender Magazine - Работа со списками в Sass
+/// @link https://www.w3schools.com/sass/sass_functions_numeric.php См. также: W3Schools - Числовые функции в Sass
+/// @link https://habr.com/ru/post/247887/ См. также: Habr - Статья "Sass для верстальщика: числа и математика"
+/// @example scss - Поиск максимального числа
+/// 	@debug get-number-max((10, 20, 30, 40));          // 40
+/// 	@debug get-number-max((1, 5, 3, 9, 2));          // 9
+/// 	@debug get-number-max((0.1, 0.5, 0.3));          // 0.5
+/// @example scss - Поиск максимального значения с единицами измерения
+/// 	@debug get-number-max((10px, 20px, 30px));       // 30px
+/// 	@debug get-number-max((1rem, 2.5rem, 0.5rem));   // 2.5rem
+/// 	@debug get-number-max((50%, 30%, 80%));          // 80%
+/// @example scss - Обработка смешанных типов данных
+/// 	@debug get-number-max((10, "text", 30, #fff, 20)); // 30
+/// 	@debug get-number-max((true, false, null, 5));     // 5
+/// 	@debug get-number-max(("a", "b", "c"));            // null
+/// @example scss - Обработка чисел с разными единицами измерения
+/// 	// Сравнение работает только для чисел с совместимыми единицами
+/// 	// @debug get-number-max((10px, 20px, 2em));  // Error: 2em and 20px have incompatible units.
+/// 	@debug get-number-max((1cm, 20mm, 0.5in)); // 20mm (если единицы совместимы)
+/// @example scss - Пустые списки и крайние случаи
+/// 	@debug get-number-max(());                        // null
+/// 	@debug get-number-max(none);                      // null
+/// 	@debug get-number-max((10px));                    // 10px
+/// 	@debug get-number-max((-10, -20, -5));            // -5
+/// @example scss - Практическое использование
+/// 	$font-sizes: 12px, 14px, 16px, 18px, 20px;
+/// 	@debug get-number-max($font-sizes); // $largest-font: 20px
+/// @example scss - Поиск максимальной ширины контейнера
+/// 	$container-widths: 320px, 768px, 1024px, 1280px;
+/// 	@debug get-number-max($container-widths); // $max-width: 1280px
+/// @param {List} $list - Список значений, который может
+/// 	содержать элементы разных типов. Функция будет
+/// 	обрабатывать только числовые элементы.
+/// @return {Number | Null} - Максимальное числовое значение
+/// 	из списка или `null`, если в списке нет числовых элементов.
+/// 	Сохраняет единицы измерения найденного максимального
+/// 	значения.
+/// @throws {Error} - Может выбросить ошибку при попытке
+/// 	сравнить числа с несовместимыми единицами измерения.
+@function get-number-max($list) {
+
+	// Переменная для хранения текущего максимального значения.
+	// Инициализируется как null, чтобы отслеживать:
+	// 1. Пустые списки (результат останется null)
+	// 2. Первое найденное число (будет присвоено $-result)
+	$-result: null;
+
+	// Первичная валидация входных данных.
+	// Убеждаемся, что переданный аргумент является
+	// списком или arglist.
+	@if not is-list($list) {
+
+		// Если $list не является списком, логируем
+		// ошибку и прерываем выполнение.
+		@return log-invalid-type(
+			'get-number-max',
+			$list,
+			'$list',
+			('list', 'arglist')
+		);
+
+	}
+
+	// Основная логика выполняется только если валидация прошла
+	// успешно.
+	// Блок @else гарантирует, что код ниже выполняется только
+	// для корректных списков.
+	@else {
+
+		// Итерация по всем элементам списка.
+		@each $-item in $list {
+
+			// Проверка типа текущего элемента.
+			// Функция is-number возвращает true только для:
+			// - Целых чисел (42)
+			// - Дробных чисел (3.14)
+			// - Чисел с единицами измерения (10px, 2rem, 1.5em)
+			@if is-number($-item) {
+
+				// Обновление значения максимума.
+				// Условие проверяет два случая:
+				// 1. $-result == null: это первое найденное число
+				// 2. $-item > $-result: текущее число больше текущего
+				// 	   максимума
+				// Оператор > в Sass работает с учетом единиц измерения,
+				// но требует их совместимости (например, нельзя
+				// сравнить 10px и 2em).
+				@if $-result == null or $-item > $-result {
+					$-result: $-item;
+				}
+
+			}
+
+			// Обработка нечисловых элементов.
+			// Если is-number($-item) вернул false, элемент имеет
+			// неподдерживаемый тип (строка, булево значение, null,
+			// карта и т.д.).
+			@else {
+
+				// Ветка обработки ошибок: элемент не является числом.
+				// Прерываем выполнение функции при первом же нечисловом
+				// элементе. Это "безопасный" подход - лучше явная
+				// ошибка, чем неявное некорректное поведение.
+				//
+				// (!) Важно: функция не пытается пропустить нечисловые
+				// элементы или преобразовать их - она строго требует
+				// числового ввода.
+				@return log-invalid-type(
+					'get-number-max',
+					$-item,
+					'$-item',
+					'number'
+				);
+
+			}
+
+		}
+
+	}
+
+	// Возвращаем результат.
+	// Возможные значения:
+	// - null: если список был пустой (не содержал элементов)
+	// - число: максимальное значение из списка
+	//
+	// Если функция дошла до этой точки, значит:
+	// 1. $list был корректным списком
+	// 2. Все элементы списка были числами
+	// 3. Не было вызвано ни одной ошибки через log-invalid-type
+	@return $-result;
+
+}

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

@@ -0,0 +1,162 @@
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-number' as *;
+@use '../../validators/type-of/is-list' as *;
+
+/// Находит минимальное числовое значение в списке.
+///
+/// Функция проходит по всем элементам списка и находит
+/// наименьшее числовое значение. Нечисловые элементы (строки,
+/// цвета, списки, карты и т.д.) игнорируются без вывода
+/// ошибок. Если в списке нет числовых элементов, функция
+/// возвращает `null`.
+///
+/// Важные особенности функции:
+/// - Игнорирует все нечисловые элементы без предупреждений
+/// - Возвращает `null` для пустых списков или списков без чисел
+/// - Сравнивает только числа с совместимыми единицами измерения
+/// - Использует локальные переменные с префиксом `$-` для
+/// 	избежания конфликтов
+/// - Не является прямой заменой `math.min()`, которая принимает
+/// 	аргументы, а не список
+/// - Сохраняет единицы измерения найденного минимального
+/// 	значения
+/// ---
+/// @name get-number-min
+/// @group utilities-getters
+/// @since 2025.12.27
+/// @access public
+/// @author Murad Rustamov (therteenten)
+/// @link https://sourcecraft.dev/users/therteenten/overview SourceCraft - therteenten
+/// @link https://sourcecraft.dev/omnisass/library SourceCraft - OmniSass
+/// @link https://sass-lang.com/documentation/modules/math#min См. также: Официальная документация Sass - Функция math.min()
+/// @link https://sass-lang.com/documentation/values/numbers#units См. также: Официальная документация Sass - Числа и единицы измерения
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/min MDN Web Docs - CSS функция min()
+/// @link https://css-tricks.com/snippets/sass/ См. также: CSS-Tricks - Коллекция сниппетов Sass
+/// @link https://sass-guidelin.es/ru/#list-functions См. также: Sass Guidelines - Функции для работы со списками
+/// @link https://frontender.info/sass-lists/ См. также: Frontender Magazine - Работа со списками в Sass
+/// @link https://www.w3schools.com/sass/sass_functions_numeric.php См. также: W3Schools - Числовые функции в Sass
+/// @link https://habr.com/ru/post/247887/ См. также: Habr - Статья "Sass для верстальщика: числа и математика"
+/// @example scss - Поиск минимального числа
+/// 	@debug get-number-min((10, 20, 30, 40));  // 10
+/// 	@debug get-number-min((5, 1, 9, 3, 2));   // 1
+/// 	@debug get-number-min((0.5, 0.1, 0.3));   // 0.1
+/// @example scss - Поиск минимального значения с единицами измерения
+/// 	@debug get-number-min((10px, 20px, 30px));     // 10px
+/// 	@debug get-number-min((2.5rem, 1rem, 0.5rem)); // 0.5rem
+/// 	@debug get-number-min((80%, 50%, 30%));        // 30%
+/// @example scss - Обработка смешанных типов данных
+/// 	@debug get-number-min((10, "текст", 30, #fff, 20)); // 10
+/// 	@debug get-number-min((true, false, null, 5));      // 5
+/// 	@debug get-number-min(("a", "b", "c"));             // null
+/// @example scss - Обработка чисел с разными единицами измерения
+/// 	// Сравнение работает только для чисел с совместимыми единицами
+/// 	@debug get-number-min((10px, 20px, 2em));  // Error: 2em and 10px have incompatible units.
+/// 	@debug get-number-min((1cm, 20mm, 0.5in)); // 1cm
+/// @example scss - Пустые списки и крайние случаи
+/// 	@debug get-number-min(());             // null
+/// 	@debug get-number-min(none);           // null
+/// 	@debug get-number-min((10px));         // 10px
+/// 	@debug get-number-min((-5, -10, -20)); // -20
+/// @example scss - Практическое использование
+/// 	$font-sizes: 12px, 14px, 16px, 18px, 20px;
+/// 	@debug get-number-min($font-sizes); // 12px
+/// @example scss - Поиск минимальной ширины контейнера
+/// 	$container-widths: 320px, 768px, 1024px, 1280px;
+/// 	@debug get-number-min($container-widths); // 320px
+/// @param {List} $list - Список значений, который может
+/// 	содержать элементы разных типов. Функция будет
+/// 	обрабатывать только числовые элементы.
+/// @return {Number | Null} - Минимальное числовое значение из
+/// 	списка или `null`, если в списке нет числовых элементов.
+/// 	Сохраняет единицы измерения найденного минимального
+/// 	значения.
+/// @throws {Error} - Может выбросить ошибку при попытке
+/// 	сравнить числа с несовместимыми единицами измерения.
+@function get-number-min($list) {
+
+	// Инициализация переменной для хранения результата.
+	// Значение 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;
+				}
+
+			}
+
+			// Обработка случая, когда элемент не является числом.
+			@else {
+
+				// При обнаружении нечислового элемента функция немедленно
+				// прерывает выполнение. Это "fail-fast" подход, который
+				// предотвращает скрытые ошибки и неожиданное поведение.
+				@return log-invalid-type(
+					'get-number-min',
+					$-item,
+					'$-item',
+					'number'
+				);
+
+			}
+
+		}
+
+	}
+
+	// Возврат результата.
+	// Возможные возвращаемые значения:
+	// - null: если список был пустым или не содержал элементов
+	// - число: наименьшее значение из списка
+	//
+	// Если выполнение дошло до этой точки, значит:
+	// 1. $list был корректным списком
+	// 2. Все элементы списка были числами
+	// 3. Ни один элемент не вызвал ошибку
+	@return $-result;
+
+}

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

@@ -0,0 +1,149 @@
+@use 'sass:math';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-number' as *;
+
+/// Вычисляет процентное отношение части к целому.
+///
+/// Функция рассчитывает, какой процент от целого числа
+/// составляет указанная часть. Возвращает процентное значение
+/// с символом '%', которое можно использовать непосредственно
+/// в CSS-свойствах.
+///
+/// Важные особенности функции:
+/// - Использует безопасное деление через `math.div()`
+/// - Преобразует десятичную дробь в процент через
+/// 	`math.percentage()`
+/// - Возвращает значение с символом процента (например, "50%")
+/// - Работает с любыми числовыми значениями (с единицами
+/// 	измерения и без)
+/// - Поддерживает вычисление любых пропорций и отношений
+/// ---
+/// @name get-number-percentage-of
+/// @group utilities-getters
+/// @since 2025.12.27
+/// @access public
+/// @author Murad Rustamov (therteenten)
+/// @link https://sourcecraft.dev/users/therteenten/overview SourceCraft - therteenten
+/// @link https://sourcecraft.dev/omnisass/library SourceCraft - OmniSass
+/// @link https://sass-lang.com/documentation/modules/math#percentage См. также: Официальная документация Sass - Функция math.percentage()
+/// @link https://sass-lang.com/documentation/modules/math#div См. также: Официальная документация Sass - Функция math.div()
+/// @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toFixed MDN Web Docs - Number.toFixed()
+/// @example scss - Базовое вычисление процентов
+/// 	@debug get-number-percentage-of(50, 100);    // 50%
+/// 	@debug get-number-percentage-of(25, 200);    // 12.5%
+/// 	@debug get-number-percentage-of(3, 4);       // 75%
+/// 	@debug get-number-percentage-of(1, 3);       // 33.33333333333333%
+/// @example scss - Вычисление процентного соотношения
+/// 	@debug get-number-percentage-of(16, 9);      // 177.77777777777777% (соотношение 16:9)
+/// 	@debug get-number-percentage-of(4, 3);       // 133.33333333333331%(соотношение 4:3)
+/// 	@debug get-number-percentage-of(1, 2);       // 50% (соотношение 1:2)
+/// 	@debug get-number-percentage-of(2, 1);       // 200% (соотношение 2:1)
+/// @example scss - Вычисление доли от целого
+/// 	@debug get-number-percentage-of(30, 150);    // 20% (30 составляет 20% от 150)
+/// 	@debug get-number-percentage-of(75, 300);    // 25% (75 составляет 25% от 300)
+/// 	@debug get-number-percentage-of(120, 80);    // 150% (120 составляет 150% от 80)
+/// 	@debug get-number-percentage-of(0, 100);     // 0% (0 составляет 0% от 100)
+/// @example scss - Практическое использование для прогресс-бара
+/// 	$completed-tasks: 7;
+/// 	$total-tasks: 10;
+/// 	$progress: get-number-percentage-of($completed-tasks, $total-tasks);
+/// 	// $progress: 70%
+/// 	.progress-bar {
+/// 		width: $progress;
+/// 	}
+/// @example css - Результат
+/// 	.progress-bar {
+/// 		width: 70%;
+/// 	}
+/// @example scss - Практическое использование для соотношения сторон
+/// 	$width: 1920;
+/// 	$height: 1080;
+/// 	$aspect-ratio: get-number-percentage-of($height, $width);
+/// 	// $aspect-ratio: 56.25%
+/// 	.video-container {
+/// 		padding-bottom: $aspect-ratio;
+/// 	}
+/// @example css - Результат
+/// 	.video-container {
+/// 		padding-bottom: 56.25%;
+/// 	}
+/// @example scss - Практическое использование для скидок и расчетов
+/// 	$discount-amount: 25;
+/// 	$original-price: 100;
+/// 	$discount-percentage: get-number-percentage-of($discount-amount, $original-price);
+/// 	// $discount-percentage: 25%
+/// 	.discount-badge::after {
+/// 		content: "-#{$discount-percentage}";
+/// 	}
+/// @example css - Результат
+/// 	.discount-badge::after {
+/// 		content: "-25%";
+/// 	}
+/// @param {Number} $part - Числовое значение, представляющее часть
+/// 	целого. Может быть любым числом (целым, дробным, с единицами
+/// 	измерения или без).
+/// @param {Number} $whole - Числовое значение, представляющее целое.
+/// 	Может быть любым числом (целым, дробным, с единицами измерения
+/// 	или без). Не должно быть равно нулю.
+/// @return {Number} - Процентное значение с символом '%',
+/// 	представляющее отношение части к целому. Возвращаемое значение
+/// 	можно использовать напрямую в CSS-свойствах.
+/// @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));
+
+	}
+
+}

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

@@ -0,0 +1,111 @@
+@use 'sass:math';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-number' as *;
+
+/// Возвращает единицы измерения числа в виде строки.
+///
+/// Функция является оберткой над встроенной функцией
+/// `math.unit()` и возвращает строковое представление
+/// единиц измерения переданного числа. Если число не имеет
+/// единиц измерения (является безразмерным), возвращается
+/// пустая строка (`''`).
+///
+/// Важные особенности функции:
+/// - Возвращает строку с единицами измерения числа
+/// - Для безразмерных чисел возвращает пустую строку (`''`)
+/// - Работает с любыми типами единиц измерения CSS
+/// - Является чистой оберткой над встроенной функцией `math.unit()`
+/// - Не изменяет исходное значение, только возвращает его единицы
+/// ---
+/// @name get-number-unit
+/// @group utilities-getters
+/// @since 2025.12.27
+/// @access public
+/// @author Murad Rustamov (therteenten)
+/// @link https://sourcecraft.dev/users/therteenten/overview SourceCraft - therteenten
+/// @link https://sourcecraft.dev/omnisass/library SourceCraft - OmniSass
+/// @link https://sass-lang.com/documentation/values/numbers См. также: Официальная документация Sass - Тип данных "Числа"
+/// @link https://sass-lang.com/documentation/values/numbers#units См. также: Официальная документация Sass - Единицы измерения в числах
+/// @link https://sass-lang.com/documentation/modules/math#unit См. также: Официальная документация Sass - Функция math.unit()
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Values_and_Units См. также: MDN Web Docs - CSS значения и единицы измерения
+/// @link https://css-tricks.com/snippets/sass/ См. также: CSS-Tricks - Коллекция сниппетов Sass
+/// @link https://sass-guidelin.es/ru/#section-39 См. также: Sass Guidelines - Раздел про проверку типов
+/// @link https://www.w3schools.com/sass/sass_functions_numeric.php См. также: W3Schools - Числовые функции в Sass
+/// @example scss - Простые единицы измерения
+/// 	@debug get-number-unit(16px);         // "px"
+/// 	@debug get-number-unit(2.5rem);       // "rem"
+/// 	@debug get-number-unit(100%);         // "%"
+/// 	@debug get-number-unit(90deg);        // "deg"
+/// 	@debug get-number-unit(1s);           // "s"
+/// 	@debug get-number-unit(10vw);         // "vw"
+/// 	@debug get-number-unit(96dpi);        // "dpi"
+/// @example scss - Безразмерные числа
+/// 	@debug get-number-unit(16);           // ""
+/// 	@debug get-number-unit(0);            // ""
+/// 	@debug get-number-unit(3.14);         // ""
+/// 	@debug get-number-unit(-5);           // ""
+/// 	@debug get-number-unit(0.5);          // ""
+/// 	@debug get-number-unit(1e-10);        // ""
+/// @example scss - Граничные случаи с нулем
+/// 	@debug get-number-unit(0px);          // "px"
+/// 	@debug get-number-unit(0%);           // "%"
+/// 	@debug get-number-unit(0rem);         // "rem"
+/// @example scss - Нечисловые значения
+/// 	@debug get-number-unit("16px");       // Ошибка, т.к. неподходящий тип
+/// 	@debug get-number-unit(#ff0000);      // Ошибка, т.к. неподходящий тип
+/// 	@debug get-number-unit(true);         // Ошибка, т.к. неподходящий тип
+/// 	@debug get-number-unit(null);         // Ошибка, т.к. неподходящий тип
+/// 	@debug get-number-unit(auto);         // Ошибка, т.к. неподходящий тип
+/// 	@debug get-number-unit((16, "px"));   // Ошибка, т.к. неподходящий тип
+/// @param {Number} $value - Значение, единицы измерения
+/// 	которого нужно получить.
+/// @return {String} - Строковое представление единиц
+/// 	измерения числа. Для чисел с единицами измерения
+/// 	возвращается строка с этими единицами. Для
+/// 	безразмерных чисел и нечисловых значений
+/// 	возвращается пустая строка (`''`).
+/// @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);
+
+	}
+
+}