@omnisass/library 0.2.0

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

@@ -0,0 +1,109 @@
+@use 'sass:list';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-list' as *;
+
+/// Возвращает первый элемент списка.
+///
+/// Функция извлекает первый элемент из переданного списка.
+/// Работает с любыми типами списков: разделенными запятыми,
+/// пробелами или скобками.
+///
+/// > Функция является оберткой над встроенной функцией `nth()`.
+/// > Используйте `get-list-item-start()` для лучшей читаемости кода.
+/// ---
+/// @name get-list-item-start
+/// @group utilities-getters
+/// @since 2025.12.27
+/// @access public
+/// @author Sindre Sorhus
+/// @author Murad Rustamov (therteenten) [адаптация]
+/// @link https://github.com/sindresorhus GitHub - Sindre Sorhus
+/// @link https://sourcecraft.dev/users/therteenten/overview SourceCraft - therteenten
+/// @link https://sourcecraft.dev/omnisass/library SourceCraft - OmniSass
+/// @link https://sass-lang.com/documentation/modules/list#nth См. также: Официальная документация Sass - Функция `list.nth()`
+/// @link https://sass-lang.com/documentation/values/lists См. также: Официальная документация Sass - Тип данных "Списки" (Lists)
+/// @link https://sass-lang.com/documentation/modules/list См. также: Официальная документация Sass - Модуль list
+/// @link https://sass-lang.com/documentation/at-rules/function См. также: Официальная документация Sass - Правило `@function`
+/// @link https://sass-lang.com/documentation/style-rules/declarations#custom-properties См. также: См. также: Документация Sass - Пользовательские функции
+/// @link https://developer.mozilla.org/ru/docs/Web/CSS/list-style-type См. также: MDN Web Docs - CSS свойство `list-style-type`
+/// @link https://developer.mozilla.org/ru/docs/Web/CSS/CSS_lists См. также: MDN Web Docs - Работа со списками в CSS
+/// @link https://www.w3schools.com/sass/sass_functions_list.php См. также: W3Schools - Функции для работы со списками в Sass
+/// @link https://www.sass.hk/docs/ См. также: Китайская документация Sass - Полное руководство
+/// @link https://sass-guidelin.es/ru/#section-39 См. также: Sass Guidelines - Раздел про пользовательские функции
+/// @link https://github.com/sass/sass/blob/main/accepted/module-system.md См. также: GitHub - Документация по модульной системе Sass
+/// @link https://stackoverflow.com/questions/36885966/sass-get-first-item-from-a-list См. также: Stack Overflow - Как получить первый элемент списка в Sass
+/// @link https://stackoverflow.com/questions/16444456/sass-get-nth-child-using-variable См. также: Stack Overflow - Использование `nth()` с переменными
+/// @link https://css-tricks.com/snippets/sass/ См. также: CSS-Tricks - Коллекция сниппетов Sass
+/// @link https://web.dev/learn/css/lists/ См. также: web.dev - Изучение CSS списков
+/// @link https://frontender.info/sass-lists/ См. также: Frontender Magazine - Работа со списками в Sass
+/// @link https://habr.com/ru/post/156549/ См. также: Habr - Статья "Sass для верстальщика: списки и циклы"
+/// @link https://www.sitepoint.com/using-sass-maps/ См. также: SitePoint - Использование карт (`maps`) в Sass
+/// @link https://www.freecodecamp.org/news/how-to-use-lists-in-sass/ См. также: freeCodeCamp - Как использовать списки в Sass
+/// @link https://code.tutsplus.com/tutorials/understanding-sass-lists--cms-22020 См. также: Envato Tuts+ - Понимание списков в Sass
+/// @link https://dev.to/kathryngrayson/using-sass-list-functions-4lp См. также: Dev.to - Использование функций для работы со списками в Sass
+/// @link https://css-live.ru/vecssti-i-sovety/vse-o-spiskax-v-sass.html См. также: CSS-Live - Все о списках в Sass
+/// @link https://itchief.ru/sass/cycles-and-lists См. также: itchief - Циклы и списки в Sass
+/// @link https://htmlacademy.ru/blog/boost/tools/sass-3 См. также: HTML Academy - Sass: списки, циклы, условия
+/// @link https://metanit.com/web/html5/13.6.php См. также: Metanit - Списки и циклы в Sass
+/// @link https://ru.hexlet.io/courses/sass-basics/lessons/conditionals/theory_unit См. также: Hexlet - Условные операторы и списки в Sass
+/// @link https://www.youtube.com/watch?v=roywYSEPSvc См. также: YouTube - Sass Tutorial #10 - Lists (The Net Ninja)
+/// @link https://www.youtube.com/watch?v=BIz02qY5BRA См. также: YouTube - Sass списки и циклы (на русском)
+/// @link https://codelabs.developers.google.com/codelabs/cloud-sass-cli#5 См. также: Google Codelabs - Создание пользовательских функций в Sass
+/// @link https://www.npmjs.com/package/sass См. также: npm - Документация пакета Dart Sass
+/// @link https://marketplace.visualstudio.com/items?itemName=Syler.sass-indented См. также: VS Code Marketplace - Поддержка синтаксиса Sass
+/// @link https://stylelint.io/user-guide/rules/list/ См. также: Stylelint - Правила для работы со списками
+/// @link https://sass-lang.com/documentation/js-api См. также: JavaScript API - Работа с Sass через JavaScript
+/// @link https://sass-lang.com/documentation/cli/dart-sass См. также: CLI - Командная строка Dart Sass
+/// @link https://sass-lang.com/documentation/breaking-changes/module-system См. также: Breaking Changes - Изменения в модульной системе
+/// @link https://sass-lang.com/documentation/values/numbers#units См. также: Документация Sass - Числа и единицы измерения
+/// @link https://sass-lang.com/documentation/values/strings См. также: Документация Sass - Строки
+/// @link https://sass-lang.com/documentation/values/booleans См. также: Документация Sass - Логические значения
+/// @link https://sass-lang.com/documentation/values/null См. также: Документация Sass - Значение `null`
+/// @link https://sass-lang.com/documentation/values/maps См. также: Документация Sass - Карты (`maps`)
+/// @link https://sass-lang.com/documentation/interpolation См. также: Документация Sass - Интерполяция
+/// @example scss - Извлечение первого элемента
+/// 	@debug get-list-item-start(apple banana cherry);     // apple
+/// 	@debug get-list-item-start((1, 2, 3, 4));            // 1
+/// 	@debug get-list-item-start(red blue green);          // red
+/// 	@debug get-list-item-start(("one", "two", "three")); // "one"
+/// @example scss - Использование в условных конструкциях
+/// 	$colors: red, blue, green;
+/// 	$primary: get-list-item-start($colors); // $primary: red
+/// @example scss - Обработка пустого списка
+/// 	@debug get-list-item-start(());    // error
+/// 	@debug get-list-item-start(none);  // null
+/// @see get-list-item-end
+/// @param {List} $list - Список, из которого нужно извлечь
+/// 	первый элемент.
+/// @return {*} - Первый элемент списка. Возвращает `null`,
+/// 	если список пустой.
+/// @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);
+
+	}
+
+}

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

@@ -0,0 +1,179 @@
+@use 'sass:list';
+@use 'sass:map';
+@use './get-list-item-start' as *;
+@use './get-list-item-end' as *;
+@use '../../loggers/log-invalid-value' as *;
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-string' as *;
+
+/// Возвращает первый или последний элемент списка.
+///
+/// Функция предоставляет удобный способ получения крайних
+/// элементов списка с явным указанием, какой именно элемент
+/// нужен - первый (начальный) или последний (конечный).
+/// Это упрощает код и делает его более читаемым по
+/// сравнению с прямым использованием `list.nth()` с
+/// индексами `1` или `-1`.
+///
+/// Важные особенности функции:
+/// - Поддерживает получение как первого, так и последнего
+/// 	элемента
+/// - Возвращает `null` для некорректных значений параметра
+/// 	`$direction`
+/// - Обрабатывает пустые списки (возвращает `null`)
+/// - Использует встроенные функции модуля `list` для
+/// 	надежности
+/// - Имеет понятный интерфейс с именованными параметрами
+/// - Сохраняет тип и значение исходного элемента
+/// ---
+/// @name get-list-item
+/// @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/lists См. также: Официальная документация Sass - Списки
+/// @link https://sass-lang.com/documentation/modules/list См. также: Официальная документация Sass - Модуль list
+/// @link https://sass-lang.com/documentation/modules/list#nth См. также: Официальная документация Sass - Функция list.nth()
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Lists_and_Counters/Using_CSS_counters См. также: MDN Web Docs - CSS списки и счетчики
+/// @link https://css-tricks.com/snippets/sass/ См. также: CSS-Tricks - Коллекция сниппетов Sass
+/// @link https://sass-guidelin.es/ru/#section-43 См. также: Sass Guidelines - Раздел про списки
+/// @link https://www.w3schools.com/sass/sass_lists.php См. также: W3Schools - Списки в Sass
+/// @example scss - Получение первого элемента (по умолчанию)
+/// 	@debug get-list-item((a, b, c, d, e));           // "a"
+/// 	@debug get-list-item((a, b, c, d, e), "start");  // "a"
+/// 	@debug get-list-item(("first", "second", "third")); // "first"
+/// 	@debug get-list-item((1px, 2px, 3px, 4px));      // 1px
+/// 	@debug get-list-item(((1, 2), (3, 4), (5, 6)));  // (1, 2)
+/// @example scss - Получение последнего элемента
+/// 	@debug get-list-item((a, b, c, d, e), "end");    // "e"
+/// 	@debug get-list-item(("first", "second", "third"), "end"); // "third"
+/// 	@debug get-list-item((1px, 2px, 3px, 4px), "end"); // 4px
+/// 	@debug get-list-item(((1, 2), (3, 4), (5, 6)), "end"); // (5, 6)
+/// @example scss - Списки из одного элемента
+/// 	@debug get-list-item((only-item,));              // "only-item"
+/// 	@debug get-list-item((only-item,), "start");     // "only-item"
+/// 	@debug get-list-item((only-item,), "end");       // "only-item"
+/// 	@debug get-list-item((42,));                     // 42
+/// @example scss - Пустые списки
+/// 	@debug get-list-item(());          // Error: список не должен быть пустым
+/// 	@debug get-list-item((), "start"); // Error: список не должен быть пустым
+/// 	@debug get-list-item((), "end");   // Error: список не должен быть пустым
+/// @example scss - Некорректные значения направления
+/// 	@debug get-list-item((a, b, c), "middle"); // null
+/// 	@debug get-list-item((a, b, c), "center"); // null
+/// 	@debug get-list-item((a, b, c), "");       // null
+/// 	@debug get-list-item((a, b, c), null);     // null
+/// 	@debug get-list-item((a, b, c), 1);        // null
+/// 	@debug get-list-item((a, b, c), true);     // null
+/// @example scss - Списки с разделителями
+/// 	@debug get-list-item([a, b, c, d, e]);           // Error: квадратные скобки
+/// 	@debug get-list-item([a, b, c, d, e], "end");    // Error: квадратные скобки
+/// 	@debug get-list-item((a b c d e));               // "a" (разделитель пробел)
+/// 	@debug get-list-item((a b c d e), "end");        // "e"
+/// @see get-list-item-start
+/// @see get-list-item-end
+/// @param {List} $list - Список, из которого нужно получить
+/// 	элемент. Может быть списком любого типа элементов,
+/// 	включая вложенные списки. Для пустых списков функция
+/// 	возвращает `null`.
+/// @param {String} $direction ["start"] - Направление,
+/// 	указывающее какой элемент нужно получить. Допустимые
+/// 	значения:
+///   - `"start"` (по умолчанию) - получить первый элемент списка
+///   - `"end"` - получить последний элемент списка
+/// 	Для любых других значений функция возвращает `null`.
+/// @return {*} - Элемент списка в указанной позиции. Для
+/// 	`$direction: "start"` возвращает первый элемент, для
+/// 	`$direction: "end"` - последний элемент. Возвращает
+/// 	`null` для пустых списков, некорректных значений
+/// 	`$direction` или если список не содержит элементов
+/// 	в указанной позиции.
+/// @throws Не выбрасывает ошибок, безопасно обрабатывает
+/// 	некорректные входные данные. Для пустых списков и
+/// 	некорректных значений `$direction` возвращает `null`.
+@function get-list-item($list, $direction: 'start') {
+
+	// Переменная для хранения результата функции
+	// Инициализируем пустой строкой, но тип может
+	// измениться в зависимости от функций get-list-item-start/end
+	$-result: '';
+
+	// ВАЛИДАЦИЯ ПАРАМЕТРА $direction
+
+	// 1. Проверка типа: параметр `$direction` должен быть строкой.
+	// Используем вспомогательную функцию is-string. Если тип не
+	// `string`, выводим отладочное сообщение через
+	// `log-invalid-type`:
+	@if not is-string($direction) {
+		@debug log-invalid-type(
+			'get-list-item',
+			$direction,
+			'$direction',
+			'string'
+		);
+	}
+
+	// 2. Проверка значения: `$direction` должен быть `'start'`
+	// или `'end'`.
+	// Используем функцию `list.index` для поиска значения в списке.
+	// Если `direction` не найден в списке `('start' 'end')`, выводим
+	// сообщение об ошибке значения. Важно: эта проверка выполняется
+	// только если первая проверка прошла (или пропущена).
+	@if not list.index('start' 'end', $direction) {
+		@debug log-invalid-value(
+			'get-list-item',
+			$direction,
+			'$direction',
+			('start', 'end')
+		);
+	} @else {
+
+		// Если обе проверки пройдены (или не выполнялись из-за
+		// логики условия), переходим к основной логике функции.
+
+		// СОЗДАНИЕ КАРТЫ (MAP) ДЛЯ ВЫБОРА НУЖНОЙ ФУНКЦИИ
+		// Карта связывает строковые ключи с результатами
+		// соответствующих функций. Это элегантная альтернатива
+		// конструкции if-else.
+		$-directions: (
+			'start': get-list-item-start($list),  // Вызываем функцию для получения первого элемента
+			'end': get-list-item-end($list)       // Вызываем функцию для получения последнего элемента
+		);
+
+		// ПОЛУЧЕНИЕ РЕЗУЛЬТАТА ИЗ КАРТЫ
+		// Используем функцию `map.get` для получения значения по
+		// ключу `$direction`:
+		// - Если `$direction = 'start'`, получим результат `get-list-item-start($list)`
+		// - Если `$direction = 'end'`, получим результат `get-list-item-end($list)`
+
+		// Альтернативный подход: использовать прямое условие:
+		// `if(sass($direction == "start"): get-list-item-start($list); else: get-list-item-end($list))`
+		// Но карта более масштабируема для добавления новых
+		// направлений.
+		$-result: map.get($-directions, $direction);
+
+		// Примечание: если бы у нас было больше вариантов, можно
+		// было бы добавить их в карту:
+		// - `'middle': get-list-item-middle($list),`
+		// - `'second': get-list-item-second($list),`
+		// и т.д.
+
+	}
+
+	// (!) Важно: мы не проводим проверку на тип `arglist` и/или
+	// `list`, поскольку эти операции уже реализованы в функциях
+	// `get-list-item-start` и `get-list-item-end`.
+
+	// ВОЗВРАТ РЕЗУЛЬТАТА
+	// - Если были ошибки валидации, вернется пустая строка
+	// 	  (инициализированное значение)
+	// - Если валидация прошла, вернется результат соответствующей
+	// 	  функции
+	// (!) Важно: функция `log-invalid-type` и `log-invalid-value`
+	// возвращают `null`, но здесь мы его не используем, поэтому
+	// ошибки только логируются, но не влияют на поток выполнения.
+	@return $-result;
+
+}

package/modules/utilities/getters/number/_get-number-from-percent.scss

@@ -0,0 +1,139 @@
+@use 'sass:math';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-number' as *;
+
+/// Вычисляет абсолютное значение по проценту от целого.
+///
+/// Функция выполняет обратную операцию процентного расчета:
+/// находит абсолютное числовое значение, которое составляет
+/// указанный процент от заданного целого числа.
+///
+/// Важные особенности функции:
+/// - Преобразует процентное значение в абсолютное число
+/// - Корректно работает с процентными единицами измерения
+/// - Использует безопасное деление через `math.div()`
+/// - Возвращает значение в тех же единицах измерения, что и
+/// 	`$whole`
+/// - Идеально подходит для обратных расчетов от процентов к
+/// 	числам
+/// ---
+/// @name get-number-from-percent
+/// @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#div См. также: Официальная документация Sass - Функция math.div()
+/// @link https://sass-lang.com/documentation/values/numbers#units См. также: Официальная документация Sass - Единицы измерения чисел
+/// @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-from-percent(50%, 200);    // 100
+/// 	@debug get-number-from-percent(25%, 1000);   // 250
+/// 	@debug get-number-from-percent(75%, 80);     // 60
+/// 	@debug get-number-from-percent(100%, 150);   // 150
+/// @example scss - Расчет с десятичными процентами
+/// 	@debug get-number-from-percent(33.33%, 300); // 99.99
+/// 	@debug get-number-from-percent(12.5%, 800);  // 100
+/// 	@debug get-number-from-percent(0.1%, 1000);  // 1
+/// 	@debug get-number-from-percent(150%, 200);   // 300
+/// @example scss - Расчет с единицами измерения
+/// 	@debug get-number-from-percent(50%, 200px);  // 100px
+/// 	@debug get-number-from-percent(25%, 4rem);   // 1rem
+/// 	@debug get-number-from-percent(10%, 2em);    // 0.2em
+/// 	@debug get-number-from-percent(33%, 150%);   // 49.5%
+/// @example scss - Практическое использование для адаптивных отступов
+/// 	$container-width: 1200px;
+/// 	$gutter-percentage: 5%;
+/// 	$gutter-width: get-number-from-percent($gutter-percentage, $container-width);
+/// 	// $gutter-width: 60px
+/// 	.container {
+/// 		width: $container-width;
+/// 		padding-left: $gutter-width;
+/// 		padding-right: $gutter-width;
+/// 	}
+/// @example css - Результат
+/// 	.container {
+/// 		width: 1200px;
+/// 		padding-left: 60px;
+/// 		padding-right: 60px;
+/// 	}
+/// @example scss - Практическое использование для типографики
+/// 	$base-font-size: 16px;
+/// 	$line-height-percentage: 150%;
+/// 	$line-height: get-number-from-percent($line-height-percentage, $base-font-size);
+/// 	// $line-height: 24px
+/// 	body {
+/// 		font-size: $base-font-size;
+/// 		line-height: $line-height;
+/// 	}
+/// @example css - Результат
+/// 	body {
+/// 		font-size: 16px;
+/// 		line-height: 24px;
+/// 	}
+/// @example scss - Практическое использование для скидок
+/// 	$original-price: 5000;
+/// 	$discount-percent: 20%;
+/// 	$discount-amount: get-number-from-percent($discount-percent, $original-price);
+/// 	// $discount-amount: 1000
+/// 	$final-price: $original-price - $discount-amount;
+/// 	// $final-price: 4000
+/// 	.price::after {
+/// 		content: "#{$final-price} руб.";
+/// 	}
+/// @example css - Результат
+/// 	.price::after {
+/// 		content: "4000 руб.";
+/// 	}
+/// @param {Number} $percentage - Процентное значение, которое
+/// 	нужно преобразовать в абсолютное число. Должно содержать
+/// 	единицу измерения '%' (например, "50%", "25.5%", "100%").
+/// @param {Number} $whole - Целое число, от которого вычисляется
+/// 	процент. Может быть любым числом (целым, дробным, с единицами
+/// 	измерения или без).
+/// @return {Number} - Абсолютное числовое значение, представляющее
+/// 	указанный процент от целого. Возвращает значение в тех же
+/// 	единицах измерения, что и параметр `$whole`.
+/// @throws {Error} - Может выбросить ошибку если `$percentage`
+/// 	не содержит единицы измерения '%' или если параметры
+/// 	не являются числами.
+@function get-number-from-percent($percentage, $whole) {
+
+	// ВАЛИДАЦИЯ ВХОДНЫХ ПАРАМЕТРОВ
+	// Проверяем, что `$percentage` является числом. Используем
+	// вспомогательную функцию `is-number` для проверки типа
+	@if not is-number($percentage) {
+
+		// Если `$percentage` не число, логируем ошибку типа.
+		// `log-invalid-type` выводит информативное сообщение об ошибке
+		@return log-invalid-type(
+			'get-number-from-percent',
+			$percentage,
+			'$percentage',
+			'number'
+		);
+
+	} @else if not is-number($whole) {
+
+		// Проверяем, что `$whole` является числом.
+		// Эта проверка выполняется только если первая проверка
+		// пройдена. Если `$percentage` не число, мы сюда не
+		// попадем из-за `@else if`
+		@return log-invalid-type(
+			'get-number-from-percent',
+			$whole,
+			'$whole',
+			'number'
+		);
+
+	} @else {
+
+		// ОСНОВНАЯ ЛОГИКА ФУНКЦИИ
+		// Оба параметра прошли валидацию
+		// Вычисляем результат: (процент / 100%) * целое
+		@return math.div($percentage, 100%) * $whole;
+
+	}
+
+}

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

@@ -0,0 +1,199 @@
+@use 'sass:math';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-number' as *;
+
+/// Вычисляет высоту на основе ширины и соотношения сторон.
+///
+/// Функция рассчитывает высоту элемента по заданной ширине
+/// и соотношению сторон (aspect ratio). Соотношение сторон
+/// определяется как `ширина / высота`. Это фундаментальная
+/// операция в веб-дизайне, используемая для создания
+/// адаптивных медиа-элементов, изображений, видео-контейнеров
+/// и поддержания пропорций элементов.
+///
+/// Математическая формула:
+/// - `height = width / ratio` (где `ratio = width / height`)
+///
+/// Свойства результата:
+/// - При `ratio = 1` (квадрат) → высота равна ширине
+/// - При `ratio > 1` (альбомная ориентация) → высота меньше
+/// 	ширины
+/// - При `ratio < 1` (портретная ориентация) → высота больше
+/// 	ширины
+/// - Результат имеет те же единицы измерения, что и `$width`
+/// - Функция сохраняет пропорции исходного соотношения сторон
+///
+/// Важные особенности функции:
+/// - Вычисляет высоту по ширине и соотношению сторон
+/// - Использует `math.div()` для безопасного деления
+/// - Сохраняет единицы измерения ширины (`px`, `rem`, `em`,
+/// 	`%`, и т.д.)
+/// - Поддерживает дробные значения соотношения сторон
+/// - Идеально подходит для адаптивных вычислений в CSS
+/// - Является основой для поддержания пропорций в веб-дизайне
+///
+/// > Вычисление высоты по соотношению сторон является ключевой
+/// > техникой в адаптивном веб-дизайне. Этот подход позволяет
+/// > создавать элементы с фиксированными пропорциями, которые
+/// > корректно масштабируются на различных устройствах и размерах
+/// > экрана. Особенно полезно для видео-контейнеров, изображений
+/// > и адаптивных iframe.
+/// >
+/// > Пример: для отображения видео 16:9 с шириной 800px,
+/// > высота будет вычислена как 800 / (16/9) = 450px.
+/// ---
+/// @name get-number-height-by-ratio
+/// @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/modules/math См. также: Официальная документация Sass - Модуль math
+/// @link https://sass-lang.com/documentation/modules/math#div См. также: Официальная документация Sass - Функция math.div()
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio См. также: MDN Web Docs - CSS свойство aspect-ratio
+/// @link https://css-tricks.com/aspect-ratio-boxes/ См. также: CSS-Tricks - Блоки с фиксированным соотношением сторон
+/// @link https://www.w3schools.com/howto/howto_css_aspect_ratio.asp См. также: W3Schools - Как создавать блоки с фиксированным соотношением сторон
+/// @example scss - Стандартные соотношения сторон видео
+/// 	@debug get-number-height-by-ratio(800px, math.div(16, 9));  // 450px
+/// 	@debug get-number-height-by-ratio(800px, 1.7777777778);    // 449.999999994375px
+/// 	@debug get-number-height-by-ratio(800px, math.div(4, 3));   // 600px
+/// 	@debug get-number-height-by-ratio(800px, 1.3333333333);    // 600.0000000150001px
+/// 	@debug get-number-height-by-ratio(800px, math.div(21, 9));  // 342.85714285714283px
+/// 	@debug get-number-height-by-ratio(800px, 2.3333333333);    // 342.8571428620408px
+/// @example scss - Квадратные и прямоугольные элементы
+/// 	@debug get-number-height-by-ratio(400px, 1);                // 400px (квадрат)
+/// 	@debug get-number-height-by-ratio(600px, 2);                // 300px (горизонтальный прямоугольник 2:1)
+/// 	@debug get-number-height-by-ratio(600px, 0.5);              // 1200px (вертикальный прямоугольник 1:2)
+/// 	@debug get-number-height-by-ratio(300px, math.div(3, 2));   // 200px (3:2)
+/// 	@debug get-number-height-by-ratio(300px, math.div(2, 3));   // 450px (2:3)
+/// @example scss - Разные единицы измерения
+/// 	@debug get-number-height-by-ratio(100%, math.div(16, 9));   // 56.25%
+/// 	@debug get-number-height-by-ratio(50rem, math.div(16, 9));  // 28.125rem
+/// 	@debug get-number-height-by-ratio(80vw, math.div(16, 9));   // 45vw
+/// 	@debug get-number-height-by-ratio(1200px, math.div(16, 9)); // 675px
+/// 	@debug get-number-height-by-ratio(64em, math.div(4, 3));    // 48em
+/// @example scss - Дробные значения ширины
+/// 	@debug get-number-height-by-ratio(750.5px, math.div(16, 9)); // 422.15625px
+/// 	@debug get-number-height-by-ratio(1024.75px, 1.5);          // 683.1666666666666px
+/// 	@debug get-number-height-by-ratio(256.25rem, math.div(5, 4)); // 205rem
+/// 	@debug get-number-height-by-ratio(99.9%, 1.618);            // 61.74289245982695%
+/// @example scss - Популярные соотношения сторон
+/// 	// 1:1 - Квадрат, Instagram фото
+/// 	@debug get-number-height-by-ratio(500px, 1);                // 500px
+///
+/// 	// 4:3 - Стандартный монитор, некоторые планшеты
+/// 	@debug get-number-height-by-ratio(1024px, math.div(4, 3));  // 768px
+///
+/// 	// 16:9 - Современное видео, Full HD
+/// 	@debug get-number-height-by-ratio(1920px, math.div(16, 9)); // 1080px
+///
+/// 	// 21:9 - Ультраширокий монитор, кинематографичный формат
+/// 	@debug get-number-height-by-ratio(2560px, math.div(21, 9)); // 1097.142857142857px
+///
+/// 	// 3:2 - Некоторые фотоаппараты, MacBook
+/// 	@debug get-number-height-by-ratio(1800px, math.div(3, 2));  // 1200px
+///
+/// 	// 1.618:1 - Золотое сечение
+/// 	@debug get-number-height-by-ratio(1000px, 1.618);           // 618.0469715698392px
+/// @example scss - Для адаптивных контейнеров
+/// 	.video-container {
+/// 		width: 100%;
+/// 		height: get-number-height-by-ratio(100%, math.div(16, 9));
+/// 	}
+///
+/// 	.square-image {
+/// 		width: 300px;
+/// 		height: get-number-height-by-ratio(300px, 1);
+/// 	}
+///
+/// 	.portrait-card {
+/// 		width: 250px;
+/// 		height: get-number-height-by-ratio(250px, math.div(3, 4));
+/// 	}
+/// @example css - Результат
+/// 	.video-container {
+/// 		width: 100%;
+/// 		height: 56.25%;
+/// 	}
+///
+/// 	.square-image {
+/// 		width: 300px;
+/// 		height: 300px;
+/// 	}
+///
+/// 	.portrait-card {
+/// 		width: 250px;
+/// 		height: 333.3333333333px;
+/// 	}
+/// @example scss - Проверка граничных значений
+/// 	@debug get-number-height-by-ratio(0px, math.div(16, 9));    // 0px
+/// 	@debug get-number-height-by-ratio(1000px, math.div(1, 0));  // 0px
+/// 	@debug get-number-height-by-ratio(1000px, 0);               // Ошибка: деление на ноль (calc(infinity * 1px))
+/// 	@debug get-number-height-by-ratio(1000px, math.div(0, 1));  // Ошибка: деление на ноль (calc(infinity * 1px))
+/// @example scss - Очень большие соотношения
+/// 	@debug get-number-height-by-ratio(1000px, 10);              // 100px (очень широкий)
+/// 	@debug get-number-height-by-ratio(1000px, 0.1);             // 10000px (очень узкий)
+/// 	@debug get-number-height-by-ratio(500px, 100);              // 5px
+/// 	@debug get-number-height-by-ratio(500px, 0.01);             // 50000px
+/// @param {Number} $width - Ширина элемента. Может быть
+/// 	любым числом с единицами измерения (`px`, `rem`, `em`,
+/// 	`%`, `vw`, и т.д.) или без них.
+/// @param {Number} $ratio - Соотношение сторон, вычисляемое
+///   как `ширина / высота`. Например:
+///   - 1.7777777778 для 16:9
+///   - 1.3333333333 для 4:3
+///   - 1 для квадрата
+///   - 0.75 для портретного формата 3:4
+/// @return {Number} - Высота элемента, рассчитанная по формуле
+/// 	`height = width / ratio`. Сохраняет единицы измерения
+/// 	параметра `$width`.
+/// @throws {Error} - Выбрасывает ошибку деления на ноль, если
+/// 	`$ratio = 0`. Это соответствует математически невозможной
+/// 	ситуации, когда высота была бы бесконечной.
+@function get-number-height-by-ratio($width, $ratio) {
+
+	@if not is-number($width) {
+
+		// Логируем ошибку: неверный тип параметра $width
+		@return log-invalid-type(
+			'get-number-height-by-ratio',
+			$width,
+			'$width',
+			'number'
+		);
+
+	} @else if not is-number($ratio) {
+
+		// Логируем ошибку: неверный тип параметра $ratio
+		@return log-invalid-type(
+			'get-number-height-by-ratio',
+			$ratio,
+			'$ratio',
+			'number'
+		);
+
+	} @else {
+
+		// Оба параметра корректны, вычисляем высоту
+		// Используется функция math.div для деления ширины
+		// на соотношение (более безопасная альтернатива
+		// обычному оператору / в Sass)
+		@return math.div($width, $ratio);
+
+	}
+
+}
+
+/// @name get-height-by-ratio
+/// @alias get-number-height-by-ratio
+/// @group utilities-aliases
+/// @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
+@function get-height-by-ratio($width, $ratio) {
+	@return get-number-height-by-ratio($width, $ratio);
+}