@omnisass/library 0.2.0 → 2026.1.0-alpha.1

package/modules/utilities/helpers/misc/_url-encode.scss

@@ -1,148 +0,0 @@
-@forward 'url-encode.configs';
-
-@use 'url-encode.configs' as configs;
-@use '../string/string-replace' as *;
-@use '../../loggers/log-invalid-type' as *;
-@use '../../validators/type-of/is-map' as *;
-@use '../../validators/type-of/is-string' as *;
-
-/// Кодирует строку для безопасного использования в URL.
-///
-/// Функция заменяет зарезервированные и небезопасные символы в
-/// строке на их процентное представление в соответствии с
-/// RFC 3986. Это позволяет безопасно включать пользовательские
-/// данные, параметры и динамические значения в URL-адреса без
-/// риска нарушения структуры URL или возникновения ошибок.
-///
-/// Важные особенности функции:
-/// - Заменяет зарезервированные символы URL на процентное кодирование
-/// - Использует настраиваемую карту замены символов
-/// - Поддерживает кастомные наборы символов для кодирования
-/// - Обрабатывает строки любой длины и сложности
-/// - Сохраняет безопасные символы без изменений
-/// - Полезно для динамической генерации URL с параметрами
-/// - Используется для создания безопасных ссылок и маршрутов
-/// - Обеспечивает корректную работу с международными символами
-/// - Предотвращает инъекции и нарушения структуры URL
-/// - Совместима со стандартами кодирования URL
-/// ---
-/// @name url-encode
-/// @group utilities-helpers
-/// @since 2026.01.13
-/// @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/string См. также: Официальная документация Sass - Модуль String
-/// @link https://sass-lang.com/documentation/values/strings См. также: Официальная документация Sass - Тип данных "Строки"
-/// @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent См. также: MDN Web Docs - Функция encodeURIComponent()
-/// @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURI См. также: MDN Web Docs - Функция encodeURI()
-/// @link https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding См. также: MDN Web Docs - Глоссарий: Percent-encoding
-/// @link https://developer.mozilla.org/en-US/docs/Web/API/URL_API См. также: MDN Web Docs - URL API
-/// @link https://datatracker.ietf.org/doc/html/rfc3986 См. также: RFC 3986 - Uniform Resource Identifier (URI): Generic Syntax
-/// @link https://en.wikipedia.org/wiki/Percent-encoding См. также: Wikipedia - Percent-encoding
-/// @link https://css-tricks.com/snippets/sass/string-replace-function/ См. также: CSS-Tricks - Функция замены строк в Sass
-/// @link https://css-tricks.com/snippets/jquery/get-query-params-object-from-url/ См. также: CSS-Tricks - Получение параметров запроса из URL
-/// @link https://sass-guidelin.es/ru/#section-42 См. также: Sass Guidelines - Раздел про строки
-/// @link https://www.urlencoder.io/learn/ См. также: URL Encoder - Обучение кодированию URL
-/// @example scss - Базовое кодирование строк
-/// 	@debug url-encode('Hello World!');        // 'Hello%20World%21'
-/// 	@debug url-encode('query=test&sort=asc'); // 'query%3Dtest%26sort%3Dasc'
-/// 	@debug url-encode('price=$100');          // 'price%3D%24100'
-/// 	@debug url-encode('user@example.com');    // 'user%40example.com'
-/// 	@debug url-encode('path/to/file.js');     // 'path%2Fto%2Ffile.js'
-/// 	@debug url-encode('name=John Doe');       // 'name%3DJohn%20Doe'
-/// @param {String} $value - Строка для кодирования в URL.
-/// 	Может содержать любые символы, включая зарезервированные
-/// 	символы URL. Функция заменит все символы из карты замены
-/// 	на их процентное представление.
-/// @param {Map} $chars-map [configs.$set-url-reserved-chars] -
-/// 	Карта замены символов для кодирования. По умолчанию
-/// 	используется глобальная конфигурация из
-/// 	`configs.$set-url-reserved-chars`. Карта должна содержать
-/// 	пары ключ-значение, где ключ - символ для замены,
-/// 	значение - процентное представление символа.
-/// @return {String} - Закодированная строка, где все символы
-/// 	из карты замены преобразованы в их процентное
-/// 	представление. Строка безопасна для использования в
-/// 	любой части URL (path, query, fragment).
-/// @throws {Error} - Может выбросить ошибку при передаче
-/// 	нестрокового значения или если функция `string-replace`
-/// 	не определена. Требуется наличие функции `string-replace`
-/// 	в доступном scope.
-/// @require {function} string-replace - Вспомогательная
-/// 	функция замены подстрок в строке. Должна быть определена
-/// 	и доступна для корректной работы данной функции.
-/// @require {variable} configs.$set-url-reserved-chars -
-/// 	Глобальная переменная с картой зарезервированных символов
-/// 	URL. Содержит маппинг символов на их процентное
-/// 	кодирование по умолчанию.
-@function url-encode(
-	$value,
-	$chars-map: configs.$set-url-reserved-chars) {
-
-	// Проверка типа первого параметра: ожидается строковое значение.
-	// Функция is-string() проверяет, является ли $value строкой
-	// (тип данных string).
-	@if not is-string($value) {
-
-		// Если $value не является строкой, возвращаем ошибку через
-		// стандартную функцию логирования. Это предотвращает
-		// некорректные операции кодирования с нестроковыми данными.
-		@return log-invalid-type(
-			'url-encode',
-			$value,
-			'$value',
-			'string'
-		);
-
-	}
-
-	// Проверка типа второго параметра: ожидается карта (map) символов.
-	// $chars-map содержит сопоставление символов, которые нужно заменить,
-	// с их URL-закодированными представлениями. По умолчанию используется
-	// значение из конфигурации configs.$set-url-reserved-chars.
-	@else if not is-map($chars-map) {
-
-		// Если $chars-map не является картой, возвращаем ошибку.
-		// Проверка выполняется только если $value прошел валидацию.
-		@return log-invalid-type(
-			'url-encode',
-			$chars-map,
-			'$chars-map',
-			'map'
-		);
-
-	}
-
-	// Все параметры прошли валидацию - выполняем кодирование строки.
-	@else {
-
-		// Инициализация переменной для хранения результата.
-		// Начинаем с исходного значения, которое будет постепенно
-		// преобразовываться путем замены символов.
-		$-result: $value;
-
-		// Итерация по всем парам ключ-значение в карте символов.
-		// - $string: символ или последовательность символов для замены.
-		// - $replacement: закодированное представление символа для URL.
-		@each $string, $replacement in $chars-map {
-
-			// Замена каждого вхождения $string на $replacement в строке.
-			// Функция string-replace() выполняет глобальную замену
-			// всех вхождений искомой подстроки.
-			$-result: string-replace($-result, $string, $replacement);
-
-		}
-
-		// Возвращаем закодированную строку, безопасную для использования в URL.
-		// Все символы, указанные в $chars-map, будут заменены на их
-		// URL-закодированные эквиваленты (обычно в формате %XX,
-		// где XX - шестнадцатеричный код символа).
-		@return $-result;
-
-	}
-
-}

package/modules/utilities/loggers/_log-invalid-type.scss

@@ -1,151 +0,0 @@
-@use '../../../configs' as libconfigs;
-@use '../validators/type-of/is-type' as *;
-
-/// Логирует ошибку или предупреждение о несоответствии типа
-/// параметра ожидаемым типам.
-///
-/// Функция генерирует детализированное сообщение об ошибке или
-/// предупреждение, когда переданный параметр имеет тип, не
-/// соответствующий ожидаемым типам. Поддерживает два режима
-/// работы: строгий (выбрасывает ошибку) и нестрогий (выводит
-/// предупреждение). Сообщения локализованы на русский и
-/// английский языки и включают название функции для лучшей
-/// идентификации источника проблемы.
-///
-/// Важные особенности функции:
-/// - Поддерживает строгий и нестрогий режимы работы
-/// - Предоставляет локализованные сообщения (русский/английский)
-/// - Включает название функции в сообщение об ошибке
-/// - Выводит детальную информацию об ожидаемых и полученных типах
-/// - Генерирует структурированные отладочные сообщения
-/// - Позволяет гибко настраивать поведение через конфигурацию
-/// - Сохраняет целостность типов в библиотеках и фреймворках
-/// - Упрощает отладку неправильного использования функций
-/// - Обеспечивает единообразную обработку ошибок типов
-/// - Интегрируется с системой конфигурации проекта
-/// - Возвращает `null` для совместимости с другими функциями
-/// ---
-/// @name log-invalid-type
-/// @group utilities-loggers
-/// @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/values См. также: Официальная документация Sass - Типы данных
-/// @link https://sass-lang.com/documentation/style-rules/error См. также: Официальная документация Sass - Директива @error
-/// @link https://sass-lang.com/documentation/at-rules/warn См. также: Официальная документация Sass - Директива @warn
-/// @link https://sass-lang.com/documentation/at-rules/debug См. также: Официальная документация Sass - Директива @debug
-/// @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/typeof См. также: MDN Web Docs - Оператор typeof
-/// @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError См. также: MDN Web Docs - Ошибка TypeError
-/// @link https://developer.mozilla.org/en-US/docs/Learn/JavaScript/First_steps/Useful_string_methods См. также: MDN Web Docs - Методы работы со строками
-/// @link https://css-tricks.com/sass-techniques-from-the-trenches/ См. также: CSS-Tricks - Sass техники из практики
-/// @link https://css-tricks.com/debugging-sass/ См. также: CSS-Tricks - Отладка Sass
-/// @link https://sass-guidelin.es/ru/#section-7 См. также: Sass Guidelines - Раздел про обработку ошибок
-/// @link https://www.w3schools.com/js/js_typeof.asp См. также: W3Schools - JavaScript Typeof
-/// @example scss - Интеграция с системой конфигурации
-/// 	// Настройка поведения через глобальные конфигурации
-/// 	// $set-strict-mode: true;  // Строгий режим
-/// 	// $set-strict-mode: false; // Нестрогий режим
-/// 	// $set-loglang: 'en';      // Английский язык
-/// 	// $set-loglang: 'ru';      // Русский язык
-///
-/// 	@function calculate-margin($base, $multiplier) {
-/// 	  @if is-type($base) != 'number' {
-/// 	    @return log-invalid-type(
-/// 	      'calculate-margin',
-/// 	      $base,
-/// 	      '$base',
-/// 	      ('number')
-/// 	    );
-/// 	  }
-/// 	  @return $base * $multiplier;
-/// 	}
-///
-/// 	// Поведение зависит от глобальных настроек
-/// 	@debug calculate-margin(10px, 2);  // 20px
-/// 	@debug calculate-margin('10px', 2); // ⛔ Error или ⚠️ Warning (с указанием функции «calculate-margin»)
-/// @param {String} $function-name - Название функции, в которой
-/// 	произошла ошибка типа. Используется для идентификации
-/// 	источника ошибки в стеке вызовов. Должно быть строковым
-/// 	значением. Включается в сообщение об ошибке для лучшей
-/// 	идентификации.
-/// @param {*} $parameter - Фактическое значение параметра,
-/// 	тип которого проверяется. Может быть любого типа,
-/// 	функция определит его тип с помощью `is-type()`.
-/// @param {String} $parameter-name - Имя параметра в виде
-/// 	строки (например, '$value', '$options'). Используется
-/// 	в сообщении об ошибке для идентификации проблемного
-/// 	параметра.
-/// @param {List | String} $expected-types - Список ожидаемых типов
-/// 	параметра. Может содержать один или несколько типов
-/// 	в виде строк (например, `'map', `('number')` или
-/// 	`('string', 'list', 'map')`). Отображается в
-/// 	сообщении об ошибке.
-/// @return {Null} - Всегда возвращает `null`. Это позволяет
-/// 	использовать функцию в выражениях возврата, не нарушая
-/// 	сигнатуры других функций.
-/// @throws {Error} - Выбрасывает ошибку в строгом режиме
-/// 	(`$set-strict-mode: true`). Ошибка содержит
-/// 	локализованное сообщение о несоответствии типа с
-/// 	указанием названия функции.
-/// @throws {Warning} - Выводит предупреждение в нестрогом
-/// 	режиме (`$set-strict-mode: false`).
-/// 	Дополнительно выводит отладочные сообщения с помощью
-/// 	`@debug` для детальной диагностики.
-/// @require {function} is-type - Вспомогательная функция
-/// 	определения типа значения. Должна быть определена
-/// 	и доступна для корректной работы данной функции.
-/// @require {variable} $set-strict-mode - Глобальная переменная,
-/// 	определяющая режим работы. Если `true` - выбрасывает
-/// 	ошибку, если `false` - выводит предупреждение.
-/// @require {variable} $set-loglang - Глобальная переменная,
-/// 	определяющая язык сообщений. Поддерживает значения `'ru'`
-/// 	(русский) и другие (английский).
-@function log-invalid-type(
-	$function-name,
-	$parameter,
-	$parameter-name,
-	$expected-types) {
-
-	// Получаем глобальные настройки из конфигурации
-	$-strict-mode: libconfigs.$set-strict-mode; // Режим работы: true = ошибки (строгий), false = предупреждения
-	$-loglang: libconfigs.$set-loglang;         // Язык вывода сообщений
-	$-log-message: '';                          // Текст сообщения об ошибке
-
-	// Определяем язык на основе глобальной настройки
-	@if $-loglang != 'ru' {
-		// Английская версия сообщения
-		// is-type($parameter) - вспомогательная функция,
-		// возвращающая тип значения
-		$-log-message: 'The parameter «#{$parameter-name}» of the function «#{$function-name}» received an unexpected type «#{is-type($parameter)}», although «#{$expected-types}» is expected';
-	} @else {
-		// Русская версия сообщения
-		$-log-message: 'Параметр «#{$parameter-name}» функции «#{$function-name}» получил неожиданный тип «#{is-type($parameter)}», хотя ожидается «#{$expected-types}»';
-	}
-
-	// Если строгий режим отключен
-	@if $-strict-mode == false {
-		// Выводим предупреждение (не останавливает компиляцию)
-		@warn '⚠️ ' + $-log-message;
-
-		// Детальная отладочная информация:
-		@debug '🟦 ┌ #{$parameter-name}';      // Имя параметра
-		@debug '🟥 └⤬ #{is-type($parameter)}'; // Фактический тип параметра (с ошибкой)
-
-		// Выводим список ожидаемых типов
-		@each $type in $expected-types {
-			@debug '✅ └─ #{$type}'; // Каждый ожидаемый тип
-		}
-
-	} @else {
-		// Строгий режим - выводим ошибку
-		// (останавливает компиляцию)
-		@error '⛔ ' + $-log-message;
-	}
-
-	// Всегда возвращаем null для использования
-	// в качестве заглушки
-	@return null;
-
-}

package/modules/utilities/loggers/_log-invalid-value.scss

@@ -1,151 +0,0 @@
-@use '../../../configs' as libconfigs;
-
-/// Логирует ошибку или предупреждение о недопустимом значении
-/// параметра, когда передано значение, не входящее в список
-/// разрешенных.
-///
-/// Функция генерирует детализированное сообщение об ошибке или
-/// предупреждение, когда переданный параметр имеет значение,
-/// не соответствующее ожидаемому набору допустимых значений.
-/// Поддерживает два режима работы: строгий (выбрасывает ошибку)
-/// и нестрогий (выводит предупреждение). Сообщения локализованы
-/// на русский и английский языки и включают название функции
-/// для лучшей идентификации источника проблемы.
-///
-/// Важные особенности функции:
-/// - Поддерживает строгий и нестрогий режимы работы
-/// - Предоставляет локализованные сообщения (русский/английский)
-/// - Включает название функции в сообщение об ошибке
-/// - Выводит детальную информацию о допустимых и полученных значениях
-/// - Генерирует структурированные отладочные сообщения
-/// - Позволяет гибко настраивать поведение через конфигурацию
-/// - Сохраняет целостность данных в библиотеках и фреймворках
-/// - Упрощает отладку неправильного использования функций
-/// - Обеспечивает единообразную обработку ошибок значений
-/// - Интегрируется с системой конфигурации проекта
-/// - Возвращает `null` для совместимости с другими функциями
-/// ---
-/// @name log-invalid-value
-/// @group utilities-loggers
-/// @since 2026.01.14
-/// @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 См. также: Официальная документация Sass - Типы данных
-/// @link https://sass-lang.com/documentation/style-rules/error См. также: Официальная документация Sass - Директива @error
-/// @link https://sass-lang.com/documentation/at-rules/warn См. также: Официальная документация Sass - Директива @warn
-/// @link https://sass-lang.com/documentation/at-rules/debug См. также: Официальная документация Sass - Директива @debug
-/// @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError См. также: MDN Web Docs - Ошибка RangeError
-/// @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError См. также: MDN Web Docs - Ошибка TypeError
-/// @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/switch См. также: MDN Web Docs - Оператор switch
-/// @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/throw См. также: MDN Web Docs - Оператор throw
-/// @link https://css-tricks.com/sass-techniques-from-the-trenches/ См. также: CSS-Tricks - Sass техники из практики
-/// @link https://css-tricks.com/debugging-sass/ См. также: CSS-Tricks - Отладка Sass
-/// @link https://sass-guidelin.es/ru/#section-7 См. также: Sass Guidelines - Раздел про обработку ошибок
-/// @link https://www.w3schools.com/js/js_errors.asp См. также: W3Schools - JavaScript Ошибки
-/// @example scss - Строгий режим (выбрасывает ошибку)
-/// 	// В строгом режиме функция выбрасывает ошибку
-/// 	// libconfigs.$set-strict-mode: true;
-/// 	// libconfigs.$set-loglang: 'en';
-///
-/// 	@function get-color($theme) {
-/// 	  @if not index(('light', 'dark', 'auto'), $theme) {
-/// 	    @return log-invalid-value(
-/// 	      'get-color',
-/// 	      $theme,
-/// 	      '$theme',
-/// 	      ('light', 'dark', 'auto')
-/// 	    );
-/// 	  }
-/// 	  @if $theme == 'light' { @return #ffffff; }
-/// 	  @if $theme == 'dark' { @return #000000; }
-/// 	  @if $theme == 'auto' { @return #888888; }
-/// 	}
-///
-/// 	@debug get-color('light');    // #ffffff
-/// 	@debug get-color('dark');     // #000000
-/// 	@debug get-color('blue');     // ⛔ Error: An incorrect value was passed to the parameter «$theme» of the function «get-color». The parameter takes specific values: «light, dark, auto».
-/// @param {String} $function-name - Название функции, в которой
-/// 	произошла ошибка значения. Используется для идентификации
-/// 	источника ошибки в стеке вызовов. Должно быть строковым
-/// 	значением. Включается в сообщение об ошибке для лучшей
-/// 	идентификации.
-/// @param {*} $parameter - Фактическое значение параметра,
-/// 	которое проверяется на соответствие допустимым значениям.
-/// 	Может быть любого типа (строка, число, список и т.д.).
-/// @param {String} $parameter-name - Имя параметра в виде
-/// 	строки (например, '$variant', '$size'). Используется
-/// 	в сообщении об ошибке для идентификации проблемного
-/// 	параметра.
-/// @param {List} $expected-values - Список допустимых значений
-/// 	параметра. Может содержать одно или несколько значений
-/// 	в виде списка (например, `('light', 'dark')` или
-/// 	`(1, 2, 3, 4)`). Отображается в сообщении об ошибке.
-/// @return {Null} - Всегда возвращает `null`. Это позволяет
-/// 	использовать функцию в выражениях возврата, не нарушая
-/// 	сигнатуры других функций.
-/// @throws {Error} - Выбрасывает ошибку в строгом режиме
-/// 	(`$set-strict-mode: true`). Ошибка содержит
-/// 	локализованное сообщение о недопустимом значении с
-/// 	указанием названия функции и списка допустимых значений.
-/// @throws {Warning} - Выводит предупреждение в нестрогом
-/// 	режиме (`$set-strict-mode: false`).
-/// 	Дополнительно выводит отладочные сообщения с помощью
-/// 	`@debug` для детальной диагностики.
-/// @require {variable} $set-strict-mode - Глобальная переменная,
-/// 	определяющая режим работы. Если `true` - выбрасывает
-/// 	ошибку, если `false` - выводит предупреждение.
-/// @require {variable} $set-loglang - Глобальная переменная,
-/// 	определяющая язык сообщений. Поддерживает значения `'ru'`
-/// 	(русский) и другие (английский).
-@function log-invalid-value(
-	$function-name,
-	$parameter,
-	$parameter-name,
-	$expected-values) {
-
-	// Получаем глобальные настройки из конфигурационного
-	// файла:
-	$-strict-mode: libconfigs.$set-strict-mode; // true = строгий режим (ошибки), false = режим предупреждений
-	$-loglang: libconfigs.$set-loglang;         // язык сообщений ('ru' = русский, любое другое = английский)
-	$-log-message: '';                          // переменная для хранения текста сообщения
-
-	// Если язык НЕ русский, используем английский текст
-	@if $-loglang != 'ru' {
-		// Английская версия: сообщает о неверном значении и
-		// показывает ожидаемые варианты:
-		$-log-message: 'An incorrect value was passed to the parameter «#{$parameter-name}» of the function «#{$function-name}». The parameter takes specific values: «#{$expected-values}».';
-	} @else {
-		// Русская версия: то же сообщение на русском языке:
-		$-log-message: 'В параметр «#{$parameter-name}» функции «#{$function-name}» передано неверное значение. Параметр принимает конкретные значения: «#{$expected-values}».';
-	}
-
-	// Если строгий режим ВЫКЛЮЧЕН (false)
-	@if $-strict-mode == false {
-
-		// Выводим предупреждение в консоль (не останавливает
-		// компиляцию):
-		@warn '⚠️  ' + $-log-message;
-
-		// Дополнительная отладочная информация для разработчика:
-		@debug '🟦 ┌ #{$parameter-name}'; // Синяя строка: показывает имя проблемного параметра
-		@debug '🟥 └⤬ #{$parameter}';     // Красная строка с крестиком: показывает переданное неверное значение
-
-		// Перебираем все ожидаемые значения и выводим их:
-		@each $value in $expected-values {
-			@debug '✅ └─ #{$value}'; // Зеленая строка с галочкой: каждое допустимое значение
-		}
-
-	} @else {
-		// СТРОГИЙ РЕЖИМ ВКЛЮЧЕН (true)
-		// Выводим ошибку, которая ПРЕРЫВАЕТ компиляцию:
-		@error '⛔ ' + $-log-message;
-	}
-
-	// Функция всегда возвращает `null`. Это удобно, чтобы
-	// использовать вызов этой функции как "заглушку".
-	// Например: `@return log-invalid-value(...);`
-	@return null;
-
-}

package/test.md

@@ -1,168 +0,0 @@
-Напиши мне комментарии SassDoc для этой функции:
-
-```scss
-@function convert-camel2kebab($value) {
-
-	$-result: '';
-	$-length: string.length($value);
-
-	@for $i from 1 through $-length {
-
-		$-char: string.slice($value, $i, $i);
-
-		@if $-char == string.to-upper-case($-char) and $i > 1 {
-			$-result: $-result + '-' + string.to-lower-case($-char);
-		} @else {
-			$-result: $-result + string.to-lower-case($-char);
-		}
-
-	}
-
-	@return $-result;
-
-}
-```
-но, так, как это сделано на примере этой функции:
-
-```scss
-/// Конвертирует значения из относительных единиц (`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 - Контекст вложенности em
-/// 	// em зависят оass-lang.com/documentation/values/numbers#unitsт контекста родительского элемента
-/// 	.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;
-/// 	}
-/// @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) {
-	@return helpers.number-strip-unit($em) * helpers.number-strip-unit($base) * 1px;
-}
-```
-
-но, учти несколько моментов:
-
-1. Старайся описания укладывать такую же ширину строки
-2. В строке `/// @since` нужно указать текущую дату в формате `YYYY.MM.DD`
-3. Строку `/// @author Murad Rustamov (therteenten)` менять не нужно, как и строку `/// @group`
-4. Первые две ссылки также необходимо не трогать:
-```scss
-/// @link https://sourcecraft.dev/users/therteenten/overview SourceCraft - therteenten
-/// @link https://sourcecraft.dev/omnisass/library SourceCraft - OmniSass
-```
-5. Ссылки должны быть по теме, к которой относится смысл функции и ссылки должны быть в виде `/// @link https://some.com См. также: Название сайта - Название старницы` (данное правило не относится к первым двум ссылкам из пункта 4)
-6. Количество ссылок не меньше 8
-7. Примеры `/// @example` должны быть достоверны и без ошибок