@omnisass/library 0.2.0

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

@@ -0,0 +1,236 @@
+@use 'sass:math';
+@use '../helpers/number/number-strip-unit' as *;
+@use '../loggers/log-invalid-type' as *;
+@use '../validators/type-of/is-number' as *;
+
+/// Конвертирует значения из пикселей (`px`) в относительные
+/// единицы (`em`).
+///
+/// Функция выполняет преобразование пиксельных значений в
+/// единицы `em` относительно заданного базового размера. Это
+/// особенно полезно для создания масштабируемых интерфейсов,
+/// которые корректно работают при изменении пользователем
+/// размера шрифта в браузере.
+///
+/// Важные особенности функции:
+/// - Преобразует пиксели в em с указанием единиц `em`
+/// - Поддерживает кастомный базовый размер (по умолчанию 16px)
+/// - Удаляет единицы измерения для корректного математического
+/// 	расчета
+/// - Использует `math.div()` для безопасного деления
+/// - Возвращает результат с единицами `em` для семантической
+/// 	ясности
+/// - Обрабатывает целые и дробные значения
+/// - Относится к размеру шрифта родительского элемента
+///
+/// > Единица `em` является относительной и зависит от размера
+/// > шрифта родительского элемента. Это важно учитывать при
+/// > вложенных структурах, так как `em` могут наследоваться
+/// > и множиться. Для независимых от контекста величин
+/// > рассмотрите использование единиц `rem`.
+/// ---
+/// @name convert-px2em
+/// @group utilities-converters
+/// @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#div См. также: Официальная документация Sass - Функция math.div()
+/// @link https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units См. также: MDN Web Docs - Значения и единицы измерения CSS
+/// @link https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Sizing_items_in_CSS См. также: MDN Web Docs - Размеры элементов в CSS
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/length См. также: MDN Web Docs - CSS-тип <length>
+/// @link https://css-tricks.com/snippets/sass/ См. также: CSS-Tricks - Коллекция сниппетов Sass
+/// @link https://css-tricks.com/snippets/css/guide-to-em-and-rem-units-in-css/ См. также: CSS-Tricks - Руководство по em и rem единицам в CSS
+/// @link https://sass-guidelin.es/ru/#section-41 См. также: Sass Guidelines - Раздел про математические операции
+/// @link https://www.w3schools.com/css/css_units.asp См. также: W3Schools - CSS единицы измерения
+/// @example scss - Стандартное преобразование (базовый размер 16px)
+/// 	@debug convert-px2em(16px);           // 1em
+/// 	@debug convert-px2em(8px);            // 0.5em
+/// 	@debug convert-px2em(24px);           // 1.5em
+/// 	@debug convert-px2em(32px);           // 2em
+/// 	@debug convert-px2em(48px);           // 3em
+/// 	@debug convert-px2em(4px);            // 0.25em
+/// 	@debug convert-px2em(1px);            // 0.0625em
+/// @example scss - Дробные значения
+/// 	@debug convert-px2em(12.5px);         // 0.78125em
+/// 	@debug convert-px2em(18.75px);        // 1.171875em
+/// 	@debug convert-px2em(0.5px);          // 0.03125em
+/// 	@debug convert-px2em(14.4px);         // 0.9em
+/// @example scss - Кастомный базовый размер
+/// 	@debug convert-px2em(16px, 10px);     // 1.6em (база 10px)
+/// 	@debug convert-px2em(20px, 10px);     // 2em (база 10px)
+/// 	@debug convert-px2em(8px, 10px);      // 0.8em (база 10px)
+/// 	@debug convert-px2em(16px, 20px);     // 0.8em (база 20px)
+/// 	@debug convert-px2em(24px, 20px);     // 1.2em (база 20px)
+/// 	@debug convert-px2em(10px, 20px);     // 0.5em (база 20px)
+/// @example scss - Граничные случаи
+/// 	@debug convert-px2em(0px);            // 0em
+/// 	@debug convert-px2em(0px, 16px);      // 0em
+/// 	@debug convert-px2em(160px);          // 10em
+/// 	@debug convert-px2em(1000px);         // 62.5em
+/// 	@debug convert-px2em(1px, 100px);     // 0.01em
+/// @example scss - Отрицательные значения
+/// 	@debug convert-px2em(-16px);          // -1em
+/// 	@debug convert-px2em(-8px);           // -0.5em
+/// 	@debug convert-px2em(-24px);          // -1.5em
+/// 	@debug convert-px2em(-16px, 8px);     // -2em
+/// @example scss - Безразмерные числа как аргументы
+/// 	@debug convert-px2em(16, 16);         // 1em (без единиц, но работает)
+/// 	@debug convert-px2em(8, 16);          // 0.5em
+/// 	@debug convert-px2em(24, 16);         // 1.5em
+/// @example scss - Сравнение em и rem
+/// 	// em - относительно родительского элемента
+/// 	.parent { font-size: 20px; }
+/// 	.child {
+/// 	  font-size: convert-px2em(16px); // 0.8em (относительно 20px родителя)
+/// 	}
+///
+/// 	// rem - относительно корневого элемента (html)
+/// 	html { font-size: 16px; }
+/// 	.element {
+/// 	  font-size: convert-px2em(16px); // 1em (но ведет себя как 1rem в контексте html)
+/// 	}
+/// @example css - Результат
+/// 	.parent {
+/// 		font-size: 20px;
+/// 	}
+///
+/// 	.child {
+/// 		font-size: 1em;
+/// 	}
+///
+/// 	html {
+/// 		font-size: 16px;
+/// 	}
+///
+/// 	.element {
+/// 		font-size: 1em;
+/// 	}
+/// @example scss - Использование в реальных сценариях
+/// 	$spacing-small: convert-px2em(8px);   // 0.5em
+/// 	$spacing-medium: convert-px2em(16px); // 1em
+/// 	$spacing-large: convert-px2em(24px);  // 1.5em
+///
+/// 	.element {
+/// 	  padding: convert-px2em(16px);
+/// 	  margin-bottom: convert-px2em(8px);
+/// 	  font-size: convert-px2em(18px, 16px); // 1.125em
+/// 	}
+///
+/// 	// Для кастомной типографической базы
+/// 	$base-font-size: 20px;
+/// 	.heading {
+/// 	  font-size: convert-px2em(24px, $base-font-size); // 1.2em
+/// 	  margin-bottom: convert-px2em(16px, $base-font-size); // 0.8em
+/// 	}
+/// @example css - Результат
+/// 	.element {
+/// 		padding: 1em;
+/// 		margin-bottom: 0.5em;
+/// 		font-size: 1.125em;
+/// 	}
+///
+/// 	.heading {
+/// 		font-size: 1.2em;
+/// 		margin-bottom: 0.8em;
+/// 	}
+/// @example scss - Комплексное использование с вложенностью
+/// 	.container {
+/// 	  font-size: 20px;
+///
+/// 	  .nested-element {
+/// 	    // Все em внутри будут относиться к font-size: 20px контейнера
+/// 	    padding: convert-px2em(10px, 20px); // 0.5em
+/// 	    margin: convert-px2em(20px, 20px);  // 1em
+/// 	    border-width: convert-px2em(2px, 20px); // 0.1em
+/// 	  }
+/// 	}
+/// @example css - Результат
+/// 	.container {
+/// 		font-size: 20px;
+/// 	}
+/// 	.container .nested-element {
+/// 		padding: 0.5em;
+/// 		margin: 1em;
+/// 		border-width: 0.1em;
+/// 	}
+/// @param {Number} $px - Значение в пикселях для конвертации.
+/// 	Может быть целым или дробным числом, положительным или
+/// 	отрицательным. Единицы измерения (`px`) удаляются для
+/// 	расчета, но ожидается, что значение изначально выражено
+/// 	в пикселях.
+/// @param {Number} $base [16px] - Базовый размер в пикселях
+/// 	для расчета. По умолчанию используется 16px, что
+/// 	соответствует стандартному размеру шрифта в большинстве
+/// 	браузеров. Может быть любым положительным числом (обычно
+/// 	в пикселях).
+/// @return {Number} - Значение в единицах `em`, рассчитанное
+/// 	по формуле: `($px / $base) * 1em`. Возвращает дробное
+/// 	или целое число с единицами измерения `em`.
+/// @throws {Error} - Может выбросить ошибку деления на ноль,
+/// 	если `$base` равен 0 после удаления единиц измерения.
+/// 	Также может выбросить ошибку при передаче нечисловых
+/// 	значений.
+@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;
+
+	}
+
+}

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

@@ -0,0 +1,180 @@
+@use 'sass:math';
+@use '../helpers/number/number-strip-unit' as *;
+@use '../loggers/log-invalid-type' as *;
+@use '../validators/type-of/is-number' as *;
+
+/// Конвертирует значения из пикселей (`px`) в относительные
+/// единицы (`rem`).
+///
+/// Функция выполняет преобразование пиксельных значений в
+/// единицы `rem` относительно заданного базового размера. Это
+/// особенно полезно для создания масштабируемых интерфейсов,
+/// которые корректно работают при изменении пользователем
+/// размера шрифта в браузере.
+///
+/// Важные особенности функции:
+/// - Преобразует пиксели в rem с указанием единиц `rem`
+/// - Поддерживает кастомный базовый размер (по умолчанию 16px)
+/// - Удаляет единицы измерения для корректного математического
+/// 	расчета
+/// - Использует `math.div()` для безопасного деления
+/// - Возвращает результат с единицами `rem` для семантической
+/// 	ясности
+/// - Обрабатывает целые и дробные значения
+/// ---
+/// @name convert-px2rem
+/// @group utilities-converters
+/// @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#div См. также: Официальная документация Sass - Функция math.div()
+/// @link https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units См. также: MDN Web Docs - Значения и единицы измерения CSS
+/// @link https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Sizing_itrems_in_CSS См. также: MDN Web Docs - Размеры элементов в CSS
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/length См. также: MDN Web Docs - CSS-тип <length>
+/// @link https://css-tricks.com/snippets/sass/ См. также: CSS-Tricks - Коллекция сниппетов Sass
+/// @link https://sass-guidelin.es/ru/#section-41 См. также: Sass Guidelines - Раздел про математические операции
+/// @link https://www.w3schools.com/css/css_units.asp См. также: W3Schools - CSS единицы измерения
+/// @example scss - Стандартное преобразование (базовый размер 16px)
+/// 	@debug convert-px2rem(16px);           // 1rem
+/// 	@debug convert-px2rem(8px);            // 0.5rem
+/// 	@debug convert-px2rem(24px);           // 1.5rem
+/// 	@debug convert-px2rem(32px);           // 2rem
+/// 	@debug convert-px2rem(48px);           // 3rem
+/// 	@debug convert-px2rem(4px);            // 0.25rem
+/// 	@debug convert-px2rem(1px);            // 0.0625rem
+/// @example scss - Дробные значения
+/// 	@debug convert-px2rem(12.5px);         // 0.78125rem
+/// 	@debug convert-px2rem(18.75px);        // 1.171875rem
+/// 	@debug convert-px2rem(0.5px);          // 0.03125rem
+/// 	@debug convert-px2rem(14.4px);         // 0.9rem
+/// @example scss - Кастомный базовый размер
+/// 	@debug convert-px2rem(16px, 10px);     // 1.6rem (база 10px)
+/// 	@debug convert-px2rem(20px, 10px);     // 2rem (база 10px)
+/// 	@debug convert-px2rem(8px, 10px);      // 0.8rem (база 10px)
+/// 	@debug convert-px2rem(16px, 20px);     // 0.8rem (база 20px)
+/// 	@debug convert-px2rem(24px, 20px);     // 1.2rem (база 20px)
+/// 	@debug convert-px2rem(10px, 20px);     // 0.5rem (база 20px)
+/// @example scss - Граничные случаи
+/// 	@debug convert-px2rem(0px);            // 0rem
+/// 	@debug convert-px2rem(0px, 16px);      // 0rem
+/// 	@debug convert-px2rem(160px);          // 10rem
+/// 	@debug convert-px2rem(1000px);         // 62.5rem
+/// 	@debug convert-px2rem(1px, 100px);     // 0.01rem
+/// @example scss - Отрицательные значения
+/// 	@debug convert-px2rem(-16px);          // -1rem
+/// 	@debug convert-px2rem(-8px);           // -0.5rem
+/// 	@debug convert-px2rem(-24px);          // -1.5rem
+/// 	@debug convert-px2rem(-16px, 8px);     // -2rem
+/// @example scss - Безразмерные числа как аргументы
+/// 	@debug convert-px2rem(16, 16);         // 1rem (без единиц, но работает)
+/// 	@debug convert-px2rem(8, 16);          // 0.5rem
+/// 	@debug convert-px2rem(24, 16);         // 1.5rem
+/// @example scss - Использование в реальных сценариях
+/// 	$spacing-small: convert-px2rem(8px);   // 0.5rem
+/// 	$spacing-medium: convert-px2rem(16px); // 1rem
+/// 	$spacing-large: convert-px2rem(24px);  // 1.5rem
+///
+/// 	.elrement {
+/// 		padding: convert-px2rem(16px);
+/// 		margin-bottom: convert-px2rem(8px);
+/// 		font-size: convert-px2rem(18px, 16px); // 1.125rem
+/// 	}
+///
+/// 	// Для кастомной типографической базы
+/// 	$base-font-size: 20px;
+/// 	.heading {
+/// 		font-size: convert-px2rem(24px, $base-font-size); // 1.2rem
+/// 		margin-bottom: convert-px2rem(16px, $base-font-size); // 0.8rem
+/// 	}
+/// @example css - Результат
+/// 	.elrement {
+/// 		padding: 1rem;
+/// 		margin-bottom: 0.5rem;
+/// 		font-size: 1.125rem;
+/// 	}
+///
+/// 	.heading {
+/// 		font-size: 1.2rem;
+/// 		margin-bottom: 0.8rem;
+/// 	}
+/// @param {Number} $px - Значение в пикселях для конвертации.
+/// 	Может быть целым или дробным числом, положительным или
+/// 	отрицательным. Единицы измерения (`px`) удаляются для
+/// 	расчета, но ожидается, что значение изначально выражено
+/// 	в пикселях.
+/// @param {Number} $base [16px] - Базовый размер в пикселях
+/// 	для расчета. По умолчанию используется `16px`, что
+/// 	соответствует стандартному размеру шрифта в большинстве
+/// 	браузеров. Может быть любым положительным числом (обычно
+/// 	в пикселях).
+/// @return {Number} - Значение в единицах `rem`, рассчитанное
+/// 	по формуле: `($px / $base) * 1rem`. Возвращает дробное
+/// 	или целое число с единицами измерения `rem`.
+/// @throws {Error} - Может выбросить ошибку деления на ноль,
+/// 	если `$base` равен 0 после удаления единиц измерения.
+/// 	Также может выбросить ошибку при передаче нечисловых
+/// 	значений.
+@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;
+
+	}
+
+}

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

@@ -0,0 +1,207 @@
+@use '../helpers/number/number-strip-unit' as *;
+@use '../loggers/log-invalid-type' as *;
+@use '../validators/type-of/is-number' as *;
+
+/// Конвертирует значения из относительных единиц (`rem`) в
+/// пиксели (`px`).
+///
+/// Функция выполняет преобразование значений в единицах `rem`
+/// в пиксели относительно заданного базового размера. Это
+/// особенно полезно для обратных расчетов, когда необходимо
+/// получить точное пиксельное значение из относительного, или
+/// для обеспечения обратной совместимости.
+///
+/// Важные особенности функции:
+/// - Преобразует rem в px с указанием единиц `px`
+/// - Поддерживает кастомный базовый размер (по умолчанию 16px)
+/// - Удаляет единицы измерения для корректного математического
+/// 	расчета
+/// - Возвращает результат с единицами `px` для семантической
+/// 	ясности
+/// - Обрабатывает целые и дробные значения
+/// - Полезен для расчета точных размеров из относительных величин
+/// - Обеспечивает обратное преобразование к `convert-px2rem`
+/// ---
+/// @name convert-rem2px
+/// @group utilities-converters
+/// @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://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units См. также: MDN Web Docs - Значения и единицы измерения CSS
+/// @link https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Sizing_items_in_CSS См. также: MDN Web Docs - Размеры элементов в CSS
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/length См. также: MDN Web Docs - CSS-тип <length>
+/// @link https://css-tricks.com/snippets/sass/ См. также: CSS-Tricks - Коллекция сниппетов Sass
+/// @link https://css-tricks.com/snippets/css/guide-to-em-and-rem-units-in-css/ См. также: CSS-Tricks - Руководство по em и rem единицам в CSS
+/// @link https://sass-guidelin.es/ru/#section-41 См. также: Sass Guidelines - Раздел про математические операции
+/// @link https://www.w3schools.com/css/css_units.asp См. также: W3Schools - CSS единицы измерения
+/// @example scss - Стандартное преобразование (базовый размер 16px)
+/// 	@debug convert-rem2px(1rem);           // 16px
+/// 	@debug convert-rem2px(0.5rem);         // 8px
+/// 	@debug convert-rem2px(1.5rem);         // 24px
+/// 	@debug convert-rem2px(2rem);           // 32px
+/// 	@debug convert-rem2px(3rem);           // 48px
+/// 	@debug convert-rem2px(0.25rem);        // 4px
+/// 	@debug convert-rem2px(0.0625rem);      // 1px
+/// @example scss - Дробные значения rem
+/// 	@debug convert-rem2px(0.78125rem);     // 12.5px
+/// 	@debug convert-rem2px(1.171875rem);    // 18.75px
+/// 	@debug convert-rem2px(0.03125rem);     // 0.5px
+/// 	@debug convert-rem2px(0.9rem);         // 14.4px
+/// 	@debug convert-rem2px(1.125rem);       // 18px
+/// 	@debug convert-rem2px(1.333rem);       // 21.328px
+/// @example scss - Кастомный базовый размер
+/// 	@debug convert-rem2px(1rem, 10px);     // 10px (база 10px)
+/// 	@debug convert-rem2px(2rem, 10px);     // 20px (база 10px)
+/// 	@debug convert-rem2px(0.8rem, 10px);   // 8px (база 10px)
+/// 	@debug convert-rem2px(0.8rem, 20px);   // 16px (база 20px)
+/// 	@debug convert-rem2px(1.2rem, 20px);   // 24px (база 20px)
+/// 	@debug convert-rem2px(0.5rem, 20px);   // 10px (база 20px)
+/// @example scss - Граничные случаи
+/// 	@debug convert-rem2px(0rem);           // 0px
+/// 	@debug convert-rem2px(0rem, 16px);     // 0px
+/// 	@debug convert-rem2px(10rem);          // 160px
+/// 	@debug convert-rem2px(62.5rem);        // 1000px
+/// 	@debug convert-rem2px(0.01rem, 100px); // 1px
+/// 	@debug convert-rem2px(100rem);         // 1600px
+/// @example scss - Отрицательные значения
+/// 	@debug convert-rem2px(-1rem);          // -16px
+/// 	@debug convert-rem2px(-0.5rem);        // -8px
+/// 	@debug convert-rem2px(-1.5rem);        // -24px
+/// 	@debug convert-rem2px(-2rem, 8px);     // -16px
+/// @example scss - Безразмерные числа как аргументы
+/// 	@debug convert-rem2px(1, 16);          // 16px (без единиц, но работает)
+/// 	@debug convert-rem2px(0.5, 16);        // 8px
+/// 	@debug convert-rem2px(1.5, 16);        // 24px
+/// @example scss - Обратное преобразование (round-trip)
+/// 	// Прямое и обратное преобразование должно давать исходное значение
+/// 	$original-px: 24px;
+/// 	$converted-rem: math.div($original-px, 16px); // 1.5rem
+/// 	$restored-px: convert-rem2px($converted-rem); // 24px
+/// 	@debug $original-px == $restored-px;          // true
+///
+/// 	// С кастомной базой
+/// 	$base: 20px;
+/// 	$original-px: 30px;
+/// 	$converted-rem: math.div($original-px, $base); // 1.5rem
+/// 	$restored-px: convert-rem2px($converted-rem, $base); // 30px
+/// @example scss - Использование в реальных сценариях
+/// 	// Расчет точных размеров для фиксированных элементов
+/// 	$spacing-small: convert-rem2px(0.5rem);   // 8px
+/// 	$spacing-medium: convert-rem2px(1rem);    // 16px
+/// 	$spacing-large: convert-rem2px(1.5rem);   // 24px
+///
+/// 	// Для обеспечения обратной совместимости
+/// 	.legacy-element {
+/// 		// Старый код использует px, новый использует rem
+/// 		padding: convert-rem2px(1rem); // 16px для обратной совместимости
+/// 		font-size: convert-rem2px(1.125rem); // 18px
+/// 	}
+///
+/// 	// Для медиа-запросов, где нужны точные пиксели
+/// 	$breakpoint: convert-rem2px(48rem); // 768px (если база 16px)
+/// 	@media (min-width: $breakpoint) {
+/// 		.container { max-width: convert-rem2px(75rem); } // 1200px
+/// 	}
+///
+/// 	// Для кастомной типографической базы
+/// 	$base-font-size: 20px;
+/// 	.heading {
+/// 		// Получаем точный размер в пикселях из относительного
+/// 		font-size: convert-rem2px(1.2rem, $base-font-size); // 24px
+/// 		line-height: convert-rem2px(1.8rem, $base-font-size); // 36px
+/// 	}
+/// @example css - Результат
+/// 	.legacy-element {
+/// 		padding: 16px;
+/// 		font-size: 18px;
+/// 	}
+///
+/// 	@media (min-width: 768px) {
+/// 		.container {
+/// 			max-width: 1200px;
+/// 		}
+/// 	}
+/// 	.heading {
+/// 		font-size: 24px;
+/// 		line-height: 36px;
+/// 	}
+/// @param {Number} $rem - Значение в единицах `rem` для
+/// 	конвертации. Может быть целым или дробным числом,
+/// 	положительным или отрицательным. Единицы измерения
+/// 	(`rem`) удаляются для расчета, но ожидается, что
+/// 	значение изначально выражено в rem.
+/// @param {Number} $base [16px] - Базовый размер в пикселях
+/// 	для расчета. По умолчанию используется 16px, что
+/// 	соответствует стандартному размеру шрифта в большинстве
+/// 	браузеров. Может быть любым положительным числом
+/// 	(обычно в пикселях).
+/// @return {Number} - Значение в единицах `px`, рассчитанное
+/// 	по формуле: `($rem * $base) * 1px`. Возвращает дробное
+/// 	или целое число с единицами измерения `px`.
+/// @throws {Error} - Может выбросить ошибку при передаче
+/// 	нечисловых значений. Для корректной работы оба аргумента
+/// 	должны быть числами.
+@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;
+
+	}
+
+}