@omnisass/library 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# История изменений OmniSass
+Обратите внимание, что данный текст представляет собой краткое изложение истории разработки проекта по версиям. Для более детального ознакомления с изменениями рекомендуется обратиться к соответствующему [разделу](https://sourcecraft.dev/therteenten/omnisass/commits/?rev=master) в SourceCraft.
+
+## 0.0.1 - Alpha Public Preview
+...

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025, Murad Rustamov (therteenten) <therteenten@ya.ru>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,2 @@
+# OmniSass
+Библиотека функций и миксинов, написанная на языке CSS-препроцессора Sass. Она предназначена для того, чтобы упростить, ускорить и улучшить процесс создания стилей для веб-сайтов.

package/_configs.scss

@@ -0,0 +1,68 @@
+////
+/// Настоятельно рекомендуется обратить внимание на тот факт,
+/// что конфигурационные параметры, представленные в данном файле,
+/// регламентируют глобальные настройки библиотеки. В то же время,
+/// специализированные параметры, относящиеся к конкретным миксинам
+/// и функциям, локализованы в соответствующих директориях,
+/// предназначенных для этих сущностей. Это архитектурное решение
+/// обеспечивает модульность и гибкость конфигурации, позволяя
+/// осуществлять тонкую настройку отдельных модулей.
+///
+/// При использовании этого модуля пространство имён для этих
+/// конфигов рекомендуется указывать как `libconfigs`.
+/// ---
+/// @group libconfigs
+////
+
+/// Включает или выключает строгий режим компиляции OmniSass.
+///
+/// Когда строгий режим включен (`true`), компилятор будет
+/// выбрасывать ошибки при использовании устаревших функций,
+/// нерекомендуемых практик или потенциально проблемных
+/// конструкций. Это помогает писать более чистый и совместимый
+/// код.
+/// ---
+/// @name set-strict-mode
+/// @access public
+/// @example scss Отключение режима
+/// 	@use 'omnisass' as libomnisass with (
+/// 		$set-strict-mode: false
+/// 	);
+/// @type Boolean
+$set-strict-mode: true !default;
+
+/// RUSSIAN:
+/// Устанавливает язык для системных сообщений и логов
+/// компилятора.
+///
+/// Определяет язык, на котором будут выводиться предупреждения,
+/// ошибки и другие системные сообщения во время компиляции
+/// Sass-кода. Поддерживаемые значения: 'ru' (русский), 'en'
+/// (английский).
+///
+/// > Наличие новых языков можно проверить в документации.
+///
+/// ENGLISH:
+/// Sets the language for system messages and compiler logs.
+///
+/// Defines the language in which warnings, errors, and other
+/// system messages will be displayed during compilation of
+/// the Sass code. Supported values: 'ru' (Russian), 'en'
+/// (English).
+///
+/// > The availability of new languages can be checked in the
+/// > documentation.
+/// ---
+/// @name set-loglang
+/// @access public
+/// @example scss Отключение режима
+/// 	@use 'omnisass' as libomnisass with (
+/// 		$set-loglang: 'en'
+/// 	);
+/// @type String
+$set-loglang: 'ru' !default;
+
+/// @name set-fingerprint
+/// @access public
+/// @type Boolean
+$set-fingerprint: true !default;

package/index.scss

@@ -0,0 +1,95 @@
+@charset "UTF-8";
+
+@forward 'configs';
+@forward 'package';
+
+/// Converters
+@forward 'modules/utilities/converters/convert-camel2kebab';
+@forward 'modules/utilities/converters/convert-em2px';
+@forward 'modules/utilities/converters/convert-hex2rgb';
+@forward 'modules/utilities/converters/convert-hex2rgba';
+@forward 'modules/utilities/converters/convert-kebab2camel';
+@forward 'modules/utilities/converters/convert-kebab2snake';
+@forward 'modules/utilities/converters/convert-px2em';
+@forward 'modules/utilities/converters/convert-px2rem';
+@forward 'modules/utilities/converters/convert-rem2px';
+@forward 'modules/utilities/converters/convert-snake2kebab';
+
+// Getters
+@forward 'modules/utilities/getters/color/get-color-brightness';
+@forward 'modules/utilities/getters/color/get-color-darkest';
+@forward 'modules/utilities/getters/list/get-list-item';
+@forward 'modules/utilities/getters/list/get-list-item-end';
+@forward 'modules/utilities/getters/list/get-list-item-start';
+@forward 'modules/utilities/getters/number/get-number-from-percent';
+@forward 'modules/utilities/getters/number/get-number-height-by-ratio';
+@forward 'modules/utilities/getters/number/get-number-max';
+@forward 'modules/utilities/getters/number/get-number-min';
+@forward 'modules/utilities/getters/number/get-number-percentage-of';
+@forward 'modules/utilities/getters/number/get-number-unit';
+@forward 'modules/utilities/getters/number/get-number-width-by-ratio';
+
+// Helpers
+@forward 'modules/utilities/helpers/color/color-blend';
+@forward 'modules/utilities/helpers/color/color-blend-steps';
+@forward 'modules/utilities/helpers/color/color-hue-shift';
+@forward 'modules/utilities/helpers/color/color-scale';
+@forward 'modules/utilities/helpers/color/color-shade';
+@forward 'modules/utilities/helpers/color/color-tint';
+@forward 'modules/utilities/helpers/color/color-triad';
+@forward 'modules/utilities/helpers/list/list-dedupe';
+@forward 'modules/utilities/helpers/list/list-insert-at';
+@forward 'modules/utilities/helpers/list/list-merge';
+@forward 'modules/utilities/helpers/list/list-remove-at';
+@forward 'modules/utilities/helpers/list/list-sum-numbers';
+@forward 'modules/utilities/helpers/list/list-sum-numbers-safe';
+@forward 'modules/utilities/helpers/misc/url-encode';
+@forward 'modules/utilities/helpers/number/number-ceil-to';
+@forward 'modules/utilities/helpers/number/number-clamp';
+@forward 'modules/utilities/helpers/number/number-clamp-max';
+@forward 'modules/utilities/helpers/number/number-clamp-min';
+@forward 'modules/utilities/helpers/number/number-denormalize';
+@forward 'modules/utilities/helpers/number/number-fibonacci';
+@forward 'modules/utilities/helpers/number/number-floor-to';
+@forward 'modules/utilities/helpers/number/number-format-with-separator';
+@forward 'modules/utilities/helpers/number/number-normalize';
+@forward 'modules/utilities/helpers/number/number-random-between';
+@forward 'modules/utilities/helpers/number/number-random-between-int';
+@forward 'modules/utilities/helpers/number/number-range';
+@forward 'modules/utilities/helpers/number/number-round-to';
+@forward 'modules/utilities/helpers/number/number-round-to-nearest';
+@forward 'modules/utilities/helpers/number/number-strip-unit';
+@forward 'modules/utilities/helpers/string/string-capitalize';
+@forward 'modules/utilities/helpers/string/string-replace';
+@forward 'modules/utilities/helpers/string/string-trim';
+@forward 'modules/utilities/helpers/string/string-trim-end';
+@forward 'modules/utilities/helpers/string/string-trim-start';
+
+// Loggers
+@forward 'modules/utilities/loggers/log-invalid-type';
+@forward 'modules/utilities/loggers/log-invalid-value';
+
+// Validators
+@forward 'modules/utilities/validators/color/is-color-light';
+@forward 'modules/utilities/validators/color/is-color-list';
+@forward 'modules/utilities/validators/list/is-list-contained';
+@forward 'modules/utilities/validators/misc/is-time';
+@forward 'modules/utilities/validators/number/is-int';
+@forward 'modules/utilities/validators/number/is-int-even';
+@forward 'modules/utilities/validators/number/is-int-odd';
+@forward 'modules/utilities/validators/number/is-number-has-unit';
+@forward 'modules/utilities/validators/number/is-number-negative';
+@forward 'modules/utilities/validators/number/is-number-positive';
+@forward 'modules/utilities/validators/number/is-number-unitless';
+@forward 'modules/utilities/validators/number/is-number-zero';
+@forward 'modules/utilities/validators/string/is-string-contained';
+@forward 'modules/utilities/validators/string/is-string-empty';
+@forward 'modules/utilities/validators/string/is-string-ending-with';
+@forward 'modules/utilities/validators/string/is-string-starting-with';
+@forward 'modules/utilities/validators/type-of/is-boolean';
+@forward 'modules/utilities/validators/type-of/is-color';
+@forward 'modules/utilities/validators/type-of/is-list';
+@forward 'modules/utilities/validators/type-of/is-map';
+@forward 'modules/utilities/validators/type-of/is-number';
+@forward 'modules/utilities/validators/type-of/is-string';
+@forward 'modules/utilities/validators/type-of/is-type';

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

@@ -0,0 +1,186 @@
+@use 'sass:string';
+@use '../loggers/log-invalid-type' as *;
+@use '../validators/type-of/is-string' as *;
+
+/// Конвертирует строку из `camelCase` (верблюжья нотация) в
+/// `kebab-case` (кебаб-нотация или дефисная нотация).
+///
+/// Функция проходит по каждому символу входной строки и
+/// преобразует заглавные буквы в строчные с добавлением дефиса
+/// перед ними (кроме первого символа). Это позволяет
+/// преобразовывать имена переменных JavaScript/TypeScript или
+/// названия классов в формате, совместимом с CSS-нотацией.
+///
+/// Важные особенности функции:
+/// - Сохраняет регистр исходных символов (преобразует к нижнему)
+/// - Добавляет дефис перед заглавными буквами (кроме первой)
+/// - Итеративно обрабатывает каждый символ строки
+/// - Возвращает строку в нижнем регистре с дефисами
+/// - Полезно для генерации CSS-классов из JS-объектов
+/// - Используется для консистентного именования стилей
+/// - Обрабатывает строки любой длины
+/// - Не изменяет цифры и специальные символы в строке
+/// - Учитывает граничные случаи (пустая строка, одиночный символ)
+/// - Обеспечивает двустороннюю совместимость naming convention
+/// ---
+/// @name convert-camel2kebab
+/// @group utilities-converters
+/// @since 2026.01.13
+/// @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/string См. также: Официальная документация Sass - Модуль String
+/// @link https://sass-lang.com/documentation/values/strings См. также: Официальная документация Sass - Тип данных "Строки"
+/// @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer См. также: MDN Web Docs - Object initializer
+/// @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#variable_names См. также: MDN Web Docs - Имена переменных в JavaScript
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_nesting/Using_CSS_nesting См. также: MDN Web Docs - Использование CSS Nesting
+/// @link https://developer.mozilla.org/en-US/docs/Learn/Getting_started_with_the_web/JavaScript_basics См. также: MDN Web Docs - Основы JavaScript
+/// @link https://css-tricks.com/snippets/sass/string-case-conversion-functions/ См. также: CSS-Tricks - Функции преобразования регистра строк в Sass
+/// @link https://css-tricks.com/sass-techniques-from-the-trenches/ См. также: CSS-Tricks - Sass техники из практики
+/// @link https://sass-guidelin.es/ru/#section-42 См. также: Sass Guidelines - Раздел про строки
+/// @link https://www.w3schools.com/js/js_conventions.asp См. также: W3Schools - Соглашения по коду JavaScript
+/// @example scss - Базовые преобразования
+/// 	@debug convert-camel2kebab('camelCase');      // 'camel-case'
+/// 	@debug convert-camel2kebab('backgroundColor'); // 'background-color'
+/// 	@debug convert-camel2kebab('fontSize');       // 'font-size'
+/// 	@debug convert-camel2kebab('borderRadius');   // 'border-radius'
+/// 	@debug convert-camel2kebab('paddingLeft');    // 'padding-left'
+/// 	@debug convert-camel2kebab('marginBottom');   // 'margin-bottom'
+/// @example scss - Граничные случаи
+/// 	@debug convert-camel2kebab('single');         // 'single'
+/// 	@debug convert-camel2kebab('');               // '' (пустая строка)
+/// 	@debug convert-camel2kebab('A');              // 'a'
+/// 	@debug convert-camel2kebab('AB');             // 'a-b'
+/// 	@debug convert-camel2kebab('AlreadyKebab');   // 'already-kebab'
+/// 	@debug convert-camel2kebab('lowercase');      // 'lowercase'
+/// @example scss - Компоненты и классы
+/// 	@debug convert-camel2kebab('ButtonPrimary');  // 'button-primary'
+/// 	@debug convert-camel2kebab('ModalHeader');    // 'modal-header'
+/// 	@debug convert-camel2kebab('CardContent');    // 'card-content'
+/// 	@debug convert-camel2kebab('InputGroup');     // 'input-group'
+/// 	@debug convert-camel2kebab('NavBar');         // 'nav-bar'
+/// 	@debug convert-camel2kebab('SideMenu');       // 'side-menu'
+/// @example scss - Интеграция с JavaScript объектами
+/// 	// Преобразование ключей объекта JS в CSS-классы
+/// 	$js-config: (
+/// 	  primaryColor: 'blue',
+/// 	  secondaryColor: 'gray',
+/// 	  fontSizeSmall: 12px,
+/// 	  borderRadiusLarge: 8px
+/// 	);
+///
+/// 	@each $key, $value in $js-config {
+/// 	  .#{convert-camel2kebab($key)} {
+/// 	    content: $value;
+/// 	  }
+/// 	}
+/// @example css - Результат
+/// 	.primary-color {
+/// 	  content: "blue";
+/// 	}
+///
+/// 	.secondary-color {
+/// 	  content: "gray";
+/// 	}
+///
+/// 	.font-size-small {
+/// 	  content: 12px;
+/// 	}
+///
+/// 	.border-radius-large {
+/// 	  content: 8px;
+/// 	}
+/// @param {String} $value - Строка в `camelCase` нотации для
+/// 	конвертации. Может содержать буквы (верхний и нижний
+/// 	регистр), цифры и специальные символы. Функция
+/// 	преобразует заглавные буквы в строчные и добавляет
+/// 	дефисы перед ними.
+/// @return {String} - Строка в kebab-case нотации, где все
+/// 	символы преобразованы к нижнему регистру, а перед
+/// 	заглавными буквами (кроме первой) добавлены дефисы.
+/// 	Результат готов к использованию как CSS-класс или
+/// 	часть селектора.
+/// @throws {Error} - Может выбросить ошибку при передаче
+/// 	нестроковых значений. Аргумент должен быть строкой
+/// 	для корректной работы строковых функций Sass.
+@function convert-camel2kebab($value) {
+
+	// Переменная для накопления результата преобразования.
+	// Инициализируется пустой строкой.
+	$-result: '';
+
+	// Проверка типа входного параметра: ожидается строковое значение.
+	// Функция is-string() проверяет, является ли $value строкой
+	// (тип данных string).
+	@if not is-string($value) {
+
+		// Если $value не является строкой, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// выполнение операции преобразования с некорректными данными.
+		@return log-invalid-type(
+			'convert-camel2kebab',
+			$value,
+			'$value',
+			'string'
+		);
+
+	}
+
+	// Основная логика выполняется только если $value является
+	// корректной строкой.
+	@else {
+
+		// Определение длины входной строки для организации цикла.
+		// Функция string.length() возвращает количество символов
+		// в строке.
+		$-length: string.length($value);
+
+		// Цикл по всем символам строки от первого до последнего.
+		// Индекс $i последовательно принимает значения от 1 до $-length.
+		@for $i from 1 through $-length {
+
+			// Извлечение текущего символа строки по индексу $i.
+			// Функция string.slice() возвращает подстроку,
+			// в данном случае - один символ.
+			$-char: string.slice($value, $i, $i);
+
+			// Проверка: является ли текущий символ заглавной буквой
+			// и не является ли он первым символом в строке.
+			// Условие $-char == string.to-upper-case($-char) проверяет,
+			// что символ в верхнем регистре (сравнивая его с его же
+			// версией в верхнем регистре).
+			// Условие $i > 1 гарантирует, что мы не добавляем дефис
+			// перед первым символом (даже если он заглавный).
+			@if $-char == string.to-upper-case($-char) and $i > 1 {
+
+				// Если символ - заглавная буква и не первый в строке:
+				// 1. Добавляем дефис "-" к результату
+				// 2. Добавляем символ, преобразованный в нижний регистр
+				//
+				// Это преобразует camelCase в kebab-case:
+				// Пример: "camelCase" → "camel-case"
+				//         "C" (на позиции 6) → "-c"
+				$-result: $-result + '-' + string.to-lower-case($-char);
+
+			} @else {
+
+				// Если символ не является заглавной буквой ИЛИ
+				// это первый символ в строке:
+				// Добавляем символ, преобразованный в нижний регистр.
+				//
+				// Это гарантирует, что вся строка будет в нижнем регистре
+				// и первый символ никогда не получит дефис перед собой.
+				$-result: $-result + string.to-lower-case($-char);
+
+			}
+
+		}
+
+		// Возвращаем итоговую строку после преобразования
+		// всех символов.
+		@return $-result;
+
+	}
+
+}

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

@@ -0,0 +1,239 @@
+@use '../helpers/number/number-strip-unit' as *;
+@use '../loggers/log-invalid-type' as *;
+@use '../validators/type-of/is-number' as *;
+
+/// Конвертирует значения из относительных единиц (`em`) в
+/// пиксели (`px`).
+///
+/// Функция выполняет преобразование значений в единицах `em`
+/// в пиксели относительно заданного базового размера. Это
+/// особенно полезно для обратных расчетов, когда необходимо
+/// получить точное пиксельное значение из относительного,
+/// учитывая контекст родительского элемента.
+///
+/// Важные особенности функции:
+/// - Преобразует `em` в `px` с указанием единиц `px`
+/// - Поддерживает кастомный базовый размер (по умолчанию 16px)
+/// - Удаляет единицы измерения для корректного математического
+/// 	расчета
+/// - Возвращает результат с единицами `px` для семантической
+/// 	ясности
+/// - Обрабатывает целые и дробные значения
+/// - Полезен для расчета точных размеров из относительных
+/// 	величин
+/// - Обеспечивает обратное преобразование к `convert-px2em`
+/// - Учитывает относительную природу `em` единиц
+/// ---
+/// @name convert-em2px
+/// @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-em2px(1em);            // 16px
+/// 	@debug convert-em2px(0.5em);          // 8px
+/// 	@debug convert-em2px(1.5em);          // 24px
+/// 	@debug convert-em2px(2em);            // 32px
+/// 	@debug convert-em2px(3em);            // 48px
+/// 	@debug convert-em2px(0.25em);         // 4px
+/// 	@debug convert-em2px(0.0625em);       // 1px
+/// @example scss - Дробные значения em
+/// 	@debug convert-em2px(0.78125em);      // 12.5px
+/// 	@debug convert-em2px(1.171875em);     // 18.75px
+/// 	@debug convert-em2px(0.03125em);      // 0.5px
+/// 	@debug convert-em2px(0.9em);          // 14.4px
+/// 	@debug convert-em2px(1.125em);        // 18px
+/// 	@debug convert-em2px(1.333em);        // 21.328px
+/// @example scss - Кастомный базовый размер
+/// 	@debug convert-em2px(1em, 10px);      // 10px (база 10px)
+/// 	@debug convert-em2px(2em, 10px);      // 20px (база 10px)
+/// 	@debug convert-em2px(0.8em, 10px);    // 8px (база 10px)
+/// 	@debug convert-em2px(0.8em, 20px);    // 16px (база 20px)
+/// 	@debug convert-em2px(1.2em, 20px);    // 24px (база 20px)
+/// 	@debug convert-em2px(0.5em, 20px);    // 10px (база 20px)
+/// @example scss - Граничные случаи
+/// 	@debug convert-em2px(0em);            // 0px
+/// 	@debug convert-em2px(0em, 16px);      // 0px
+/// 	@debug convert-em2px(10em);           // 160px
+/// 	@debug convert-em2px(62.5em);         // 1000px
+/// 	@debug convert-em2px(0.01em, 100px);  // 1px
+/// 	@debug convert-em2px(100em);          // 1600px
+/// @example scss - Отрицательные значения
+/// 	@debug convert-em2px(-1em);           // -16px
+/// 	@debug convert-em2px(-0.5em);         // -8px
+/// 	@debug convert-em2px(-1.5em);         // -24px
+/// 	@debug convert-em2px(-2em, 8px);      // -16px
+/// @example scss - Безразмерные числа как аргументы
+/// 	@debug convert-em2px(1, 16);          // 16px (без единиц, но работает)
+/// 	@debug convert-em2px(0.5, 16);        // 8px
+/// 	@debug convert-em2px(1.5, 16);        // 24px
+/// @example scss - Обратное преобразование (round-trip)
+/// 	// Прямое и обратное преобразование должно давать исходное значение
+/// 	$original-px: 24px;
+/// 	$converted-em: math.div($original-px, 16px); // 1.5em
+/// 	$restored-px: convert-em2px($converted-em); // 24px
+/// 	@debug $original-px == $restored-px;        // true
+///
+/// 	// С кастомной базой
+/// 	$base: 20px;
+/// 	$original-px: 30px;
+/// 	$converted-em: math.div($original-px, $base); // 1.5em
+/// 	$restored-px: convert-em2px($converted-em, $base); // 30px
+/// @example scss - Контекст вложенности em
+/// 	// em зависят от контекста родительского элемента
+/// 	.parent { font-size: 20px; }
+/// 	.child {
+/// 	  // 1em внутри .parent равно 20px
+/// 	  $px-value: convert-em2px(1em, 20px); // 20px
+/// 	  // 0.5em внутри .parent равно 10px
+/// 	  $px-value: convert-em2px(0.5em, 20px); // 10px
+/// 	}
+///
+/// 	// Вложенные em множатся
+/// 	.grandparent { font-size: 16px; }
+/// 	.parent { font-size: 1.5em; } // 24px
+/// 	.child {
+/// 	  // 1em внутри .parent равно 24px, а не 16px!
+/// 	  $px-value: convert-em2px(1em, 24px); // 24px
+/// 	}
+/// @example css - Результат
+/// 	.parent {
+/// 		font-size: 20px;
+/// 	}
+///
+/// 	.grandparent {
+/// 		font-size: 16px;
+/// 	}
+///
+/// 	.parent {
+/// 		font-size: 1.5em;
+/// 	}
+/// @example scss - Использование в реальных сценариях
+/// 	// Расчет точных размеров для фиксированных элементов
+/// 	$spacing-small: convert-em2px(0.5em);   // 8px
+/// 	$spacing-medium: convert-em2px(1em);    // 16px
+/// 	$spacing-large: convert-em2px(1.5em);   // 24px
+///
+/// 	// Для обеспечения обратной совместимости
+/// 	.legacy-element {
+/// 	  // Старый код использует px, новый использует em
+/// 	  padding: convert-em2px(1em); // 16px для обратной совместимости
+/// 	  font-size: convert-em2px(1.125em); // 18px
+/// 	}
+///
+/// 	// Для сложных вложенных структур
+/// 	.container {
+/// 	  font-size: 18px;
+///
+/// 	  .nested-element {
+/// 	    // Все em внутри относятся к font-size: 18px контейнера
+/// 	    padding: convert-em2px(0.5em, 18px); // 9px
+/// 	    margin: convert-em2px(1em, 18px);    // 18px
+/// 	    border-width: convert-em2px(0.111em, 18px); // 2px
+/// 	  }
+/// 	}
+///
+/// 	// Для медиа-запросов с учетом контекста
+/// 	$parent-font-size: 14px;
+/// 	@media (min-width: 768px) {
+/// 	  .responsive-element {
+/// 	    // Em рассчитываются относительно текущего контекста
+/// 	    font-size: convert-em2px(1.2em, $parent-font-size); // 16.8px
+/// 	  }
+/// 	}
+/// @example css - Результат
+/// 	.legacy-element {
+/// 		padding: 16px;
+/// 		font-size: 18px;
+/// 	}
+///
+/// 	.container {
+/// 		font-size: 18px;
+/// 	}
+/// 	.container .nested-element {
+/// 		padding: 9px;
+/// 		margin: 18px;
+/// 		border-width: 1.998px;
+/// 	}
+///
+/// 	@media (min-width: 768px) {
+/// 		.responsive-element {
+/// 			font-size: 16.8px;
+/// 		}
+/// 	}
+/// @param {Number} $em - Значение в единицах `em` для
+/// 	конвертации. Может быть целым или дробным числом,
+/// 	положительным или отрицательным. Единицы измерения (`em`)
+/// 	удаляются для расчета, но ожидается, что значение
+/// 	изначально выражено в `em`.
+/// @param {Number} $base [16px] - Базовый размер в пикселях
+/// 	для расчета. По умолчанию используется `16px`, что
+/// 	соответствует стандартному размеру шрифта в большинстве
+/// 	браузеров. Может быть любым положительным числом (обычно
+/// 	в пикселях). Важно, что параметр представляет размер
+/// 	шрифта родительского элемента, относительно которого
+/// 	рассчитываются `em`.
+/// @return {Number} - Значение в единицах `px`, рассчитанное
+/// 	по формуле: `($em * $base) * 1px`. Возвращает дробное
+/// 	или целое число с единицами измерения `px`.
+/// @throws {Error} - Может выбросить ошибку при передаче
+/// 	нечисловых значений. Для корректной работы оба
+/// 	аргумента должны быть числами.
+@function convert-em2px($em, $base: 16px) {
+
+	// Проверка типа первого параметра: ожидается числовое
+	// значение в единицах em. Единица em является относительной
+	// и рассчитывается относительно размера шрифта родительского
+	// элемента.
+	@if not is-number($em) {
+
+		// Если $em не является числом, логируем ошибку через
+		// отладочное сообщение.
+		@return log-invalid-type(
+			'convert-em2px',
+			$em,
+			'$em',
+			'number'
+		);
+
+	}
+
+	// Основная логика выполняется только если $value является
+	// корректной строкой.
+	@else {
+
+		// Формула конвертации: px = em × базовый_размер_шрифта.
+		//
+		// Алгоритм вычислений:
+		// 1. number-strip-unit($em) - удаляем единицу измерения
+		// 	   'em' из первого значения
+		// 	   Пример: 1.5em → 1.5 (число без единиц)
+		// 2. number-strip-unit($base) - удаляем единицу измерения
+		// 	   из базового размера
+		// 	   Пример: 16px → 16 (число без единиц)
+		// 3. Умножаем безразмерные числа: (число em) × (базовый размер)
+		// 	   Пример: 1.5 × 16 = 24
+		// 4. Умножаем результат на 1px для добавления единицы
+		// 	   измерения пикселей
+		// 	   Пример: 24 × 1px = 24px
+		//
+		// Ключевая особенность: результат в пикселях зависит от
+		// базового размера шрифта. В отличие от rem, который зависит
+		// от корневого элемента, em зависит от размера шрифта
+		// непосредственного родителя.
+		@return number-strip-unit($em) * number-strip-unit($base) * 1px;
+
+	}
+
+}