@omnisass/library 0.2.0

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

@@ -0,0 +1,97 @@
+@use 'sass:color';
+@use '../validators/type-of/is-color' as *;
+@use '../loggers/log-invalid-type' as *;
+
+/// Преобразует цвет из HEX формата в строку формата RGB.
+///
+/// Функция `convert-hex2rgb()` принимает цвет и возвращает его
+/// представление в виде строки RGB. Использует современные
+/// функции модуля `color` для точного извлечения каналов.
+///
+/// Полезно для CSS-переменных, создания динамических стилей.
+/// ---
+/// @name convert-hex2rgb
+/// @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/modules/color#channel См. также: Sass - Документация функции color.channel()
+/// @link https://sass-lang.com/documentation/values/colors#rgb-functions См. также: Sass - Цвета и RGB функции
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/rgb См. также: MDN - Функция rgb()
+/// @link https://www.w3schools.com/css/css_colors_rgb.asp См. также: W3Schools - CSS RGB цвета
+/// @link https://css-tricks.com/creating-color-themes-with-custom-properties-and-convert-hex2rgb/ См. также: CSS-Tricks - Темы с CSS-переменными и HEX-to-RGB
+/// @example scss - Пример использования
+/// 	$brand-blue: #3498db;
+///
+/// 	:root {
+/// 		--color-primary: #{$brand-blue};
+/// 		--color-primary-rgb: #{convert-hex2rgb($brand-blue)}; // "rgb(52, 152, 219)"
+/// 	}
+///
+/// 	.element {
+/// 		color: #{convert-hex2rgb(#ff0000)};
+/// 	}
+/// @example css - Результат
+/// 	:root {
+/// 		--color-primary: #3498db;
+/// 		--color-primary-rgb: rgb(52, 152, 219);
+/// 	}
+///
+/// 	.element {
+/// 		color: rgb(255, 0, 0);
+/// 	}
+/// @see convert-hex2rgba
+/// @param {Color} $color - Цвет для преобразования. Функция
+/// 	ожидает цвет в HEX формате, но может корректно
+/// 	обработать и другие форматы (rgb, hsl, имена цветов).
+/// 	Для прозрачных цветов (с альфа-каналом) возвращаемый
+/// 	RGB не будет содержать информации о прозрачности.
+/// @return {String} - Строка в формате `"rgb(r, g, b)"`,
+/// 	где `r`, `g`, `b` - числовые значения от 0 до 255.
+/// 	Если передан некорректный цвет, может вызвать ошибку
+/// 	Sass.
+@function convert-hex2rgb($color) {
+
+	// Проверка типа входного параметра: ожидается
+	// цветовое значение.
+	// Функция is-color() проверяет, является ли $color
+	// валидным цветом CSS.
+	@if not is-color($color) {
+
+		// Если $color не является цветом, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// выполнение операции конвертации с некорректными данными.
+		@return log-invalid-type(
+			'convert-hex2rgb',
+			$color,
+			'$color',
+			'color'
+		);
+
+	}
+
+	// Основная логика выполняется только если $value является
+	// корректной строкой.
+	@else {
+
+		// Формула преобразования: создаем строку формата rgb()
+		// из компонентов цвета.
+		//
+		// Алгоритм преобразования:
+		// 1. Извлекаем красный канал: color.channel($color, "red", $space: rgb)
+		// 	   Возвращает числовое значение от 0 до 255
+		// 2. Извлекаем зеленый канал: color.channel($color, "green", $space: rgb)
+		// 3. Извлекаем синий канал: color.channel($color, "blue", $space: rgb)
+		// 4. Формируем строку: rgb(красный, зеленый, синий)
+		//
+		// Ключевая особенность: функция возвращает строку, а не цветовой тип,
+		// из-за интерполяции #{} внутри строки.
+		// Это может быть полезно для генерации CSS переменных или
+		// вставки значений в CSS-функции.
+		@return 'rgb(#{color.channel($color, "red", $space: rgb)}, #{color.channel($color, "green", $space: rgb)}, #{color.channel($color, "blue", $space: rgb)})';
+
+	}
+
+}

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

@@ -0,0 +1,124 @@
+@use 'sass:color';
+@use '../validators/type-of/is-color' as *;
+@use '../validators/type-of/is-number' as *;
+@use '../loggers/log-invalid-type' as *;
+
+/// Преобразует цвет в строку формата RGBA с поддержкой
+/// прозрачности.
+///
+/// Функция `convert-hex2rgba()` принимает цвет и значение
+/// прозрачности (альфа-канал), возвращая строковое
+/// представление в формате RGBA. Используется для создания
+/// полупрозрачных версий цветов, например, для overlay,
+/// теней или градиентов. Работает с любыми цветовыми
+/// форматами, поддерживаемыми Sass.
+/// ---
+/// @name convert-hex2rgba
+/// @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/modules/color#channel См. также: Sass - Документация функции color.channel()
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/rgba См. также: MDN - Функция rgba()
+/// @link https://css-tricks.com/the-power-of-rgba/ См. также: CSS-Tricks - Возможности RGBA
+/// @link https://www.w3.org/TR/css-color-4/#rgba-functions См. также: W3C - Спецификация RGBA функций
+/// @link https://webaim.org/resources/contrastchecker/ См. также: WebAIM - Проверка контрастности цветов
+/// @example scss - Пример использования
+/// 	$primary-color: #3498db;
+///
+/// 	.overlay {
+/// 		// Полупрозрачный overlay основного цвета
+/// 		background-color: #{convert-hex2rgba($primary-color, 0.3)};
+/// 	}
+///
+/// 	.card {
+/// 		// Тень с использованием RGBA для плавного эффекта
+/// 		box-shadow: 0 4px 12px #{convert-hex2rgba(#000000, 0.08)};
+/// 	}
+///
+/// 	// Использование значения по умолчанию (альфа = 1)
+/// 	.solid-background {
+/// 		background-color: #{convert-hex2rgba($primary-color)}; // rgba(52, 152, 219, 1)
+/// 	}
+/// @example css - Результат
+/// 	.overlay {
+/// 		background-color: rgba(52, 152, 219, 0.3);
+/// 	}
+///
+/// 	.card {
+/// 		box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08);
+/// 	}
+///
+/// 	.solid-background {
+/// 		background-color: rgba(52, 152, 219, 1);
+/// 	}
+/// @see convert-hex2rgb
+/// @param {Color} $color - Исходный цвет для преобразования.
+/// 	Может быть в HEX, RGB, HSL, HSLA формате или
+/// 	именованный цвет. Альфа-канал исходного цвета
+/// 	игнорируется, используется значение параметра `$alpha`.
+/// @param {Number} $alpha [1] - Значение прозрачности от 0.0
+/// 	до 1.0. 0.0 - полностью прозрачный, 1.0 - полностью
+/// 	непрозрачный. Может быть дробным числом (например, 0.5
+/// 	для 50% прозрачности). Параметр имеет значение по
+/// 	умолчанию 1 (непрозрачный цвет).
+/// @return {String} - Строка в формате `"rgba(r, g, b, a)"`,
+/// 	где `r`, `g`, `b` - числовые значения от 0 до 255,
+/// 	`a` - значение прозрачности.
+@function convert-hex2rgba($color, $alpha: 1) {
+
+	// Проверка типа первого параметра: ожидается
+	// цветовое значение.
+	// Функция is-color() проверяет, является ли $color
+	// валидным цветом CSS.
+	@if not is-color($color) {
+
+		// Если $color не является цветом, логируем ошибку через
+		// отладочное сообщение.
+		@return log-invalid-type(
+			'convert-hex2rgba',
+			$color,
+			'$color',
+			'color'
+		);
+
+	}
+
+	// Проверка типа второго параметра: ожидается числовое значение
+	// для альфа-канала (прозрачности).
+	@else if not is-number($alpha) {
+
+		// Если $alpha не является числом, логируем ошибку через
+		// отладочное сообщение.
+		@return log-invalid-type(
+			'convert-hex2rgba',
+			$alpha,
+			'$alpha',
+			'number'
+		);
+
+	}
+
+	// Оба параметра прошли валидацию - выполняем конвертацию.
+	@else {
+
+		// Формула преобразования: создаем строку формата rgba()
+		// из компонентов цвета и значения альфа-канала.
+		//
+		// Алгоритм преобразования:
+		// 1. Извлекаем красный канал: color.channel($color, "red", $space: rgb)
+		// 	   Возвращает числовое значение от 0 до 255
+		// 2. Извлекаем зеленый канал: color.channel($color, "green", $space: rgb)
+		// 3. Извлекаем синий канал: color.channel($color, "blue", $space: rgb)
+		// 4. Используем переданное значение альфа-канала: $alpha
+		// 5. Формируем строку: rgba(красный, зеленый, синий, альфа)
+		//
+		// Ключевая особенность: функция возвращает строку, а не
+		// цветовой тип, из-за интерполяции #{} внутри строки.
+		@return 'rgba(#{color.channel($color, "red", $space: rgb)}, #{color.channel($color, "green", $space: rgb)}, #{color.channel($color, "blue", $space: rgb)}, #{$alpha})';
+
+	}
+
+}

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

@@ -0,0 +1,232 @@
+@use 'sass:string';
+@use '../loggers/log-invalid-type' as *;
+@use '../validators/type-of/is-string' as *;
+
+/// Конвертирует строку из `kebab-case` (кебаб-нотация) в
+/// `camelCase` (верблюжья нотация).
+///
+/// Функция проходит по каждому символу входной строки,
+/// игнорируя дефисы и преобразуя символы, следующие за
+/// дефисами, в верхний регистр. Это позволяет преобразовывать
+/// CSS-классы и HTML-атрибуты в формате kebab-case в имена
+/// переменных JavaScript/TypeScript в camelCase.
+///
+/// Важные особенности функции:
+/// - Сохраняет исходный регистр символов (кроме следующих за
+/// 	дефисами)
+/// - Игнорирует дефисы в исходной строке
+/// - Преобразует символы после дефисов в верхний регистр
+/// - Итеративно обрабатывает каждый символ строки
+/// - Возвращает строку в camelCase нотации
+/// - Полезно для преобразования CSS-селекторов в JS-свойства
+/// - Используется для консистентного именования в коде
+/// - Обрабатывает строки любой длины
+/// - Не изменяет цифры и специальные символы (кроме дефисов)
+/// - Учитывает граничные случаи (пустая строка, несколько
+/// 	дефисов подряд)
+/// - Обеспечивает обратное преобразование к `convert-camel2kebab`
+/// ---
+/// @name convert-kebab2camel
+/// @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/Learn/HTML/Howto/Use_data_attributes См. также: MDN Web Docs - Использование data-атрибутов
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_selectors См. также: MDN Web Docs - CSS селекторы
+/// @link https://css-tricks.com/snippets/sass/string-case-conversion-functions/ См. также: CSS-Tricks - Функции преобразования регистра строк в Sass
+/// @link https://css-tricks.com/whats-the-difference-between-kebab-case-camel-case-and-snake-case/ См. также: CSS-Tricks - Разница между kebab-case, camelCase и snake_case
+/// @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-kebab2camel('camel-case');      // 'camelCase'
+/// 	@debug convert-kebab2camel('background-color'); // 'backgroundColor'
+/// 	@debug convert-kebab2camel('font-size');       // 'fontSize'
+/// 	@debug convert-kebab2camel('border-radius');   // 'borderRadius'
+/// 	@debug convert-kebab2camel('padding-left');    // 'paddingLeft'
+/// 	@debug convert-kebab2camel('margin-bottom');   // 'marginBottom'
+/// @example scss - Множественные дефисы
+/// 	@debug convert-kebab2camel('border-top-left-radius');  // 'borderTopLeftRadius'
+/// 	@debug convert-kebab2camel('font-weight-bold');        // 'fontWeightBold'
+/// 	@debug convert-kebab2camel('text-decoration-line');    // 'textDecorationLine'
+/// 	@debug convert-kebab2camel('background-image-url');    // 'backgroundImageUrl'
+/// 	@debug convert-kebab2camel('grid-template-columns');   // 'gridTemplateColumns'
+/// 	@debug convert-kebab2camel('transition-property-all'); // 'transitionPropertyAll'
+/// @example scss - Преобразование CSS-классов в JS-свойства
+/// 	// Конвертация CSS-классов для использования в JavaScript
+/// 	$css-classes: 'modal-header', 'btn-primary', 'input-disabled';
+///
+/// 	@each $class in $css-classes {
+/// 		$js-property: convert-kebab2camel($class);
+/// 		@debug $js-property;
+/// 		// modal-header → modalHeader
+/// 		// btn-primary → btnPrimary
+/// 		// input-disabled → inputDisabled
+/// 	}
+/// @example scss - Интеграция с конфигурационными объектами
+/// 	// Конвертация CSS-свойств в имена JS-переменных
+/// 	$css-properties: (
+/// 		'primary-color': #3498db,
+/// 		'secondary-color': #2ecc71,
+/// 		'font-size-base': 16px,
+/// 		'border-radius-sm': 4px
+/// 	);
+///
+/// 	// Создание JS-объекта конфигурации
+/// 	$js-config: ();
+///
+/// 	@each $key, $value in $css-properties {
+/// 		$js-key: convert-kebab2camel($key);
+/// 		$js-config: map.merge($js-config, ($js-key: $value));
+/// 	}
+///
+/// 	@debug $js-config;
+/// 	// (primaryColor: #3498db, secondaryColor: #2ecc71,
+/// 	//  fontSizeBase: 16px, borderRadiusSm: 4px)
+/// @example css - Практическое применение в Sass/SCSS
+/// 	// Использование функции для генерации CSS-переменных
+/// 	$theme-colors: (
+/// 		primary-color: #3498db,
+/// 		secondary-color: #2ecc71,
+/// 		accent-color: #e74c3c
+/// 	);
+///
+/// 	:root {
+/// 		@each $name, $color in $theme-colors {
+/// 			--#{convert-kebab2camel($name)}: #{$color};
+/// 		}
+/// 	}
+/// @example css - Результат
+/// 	:root {
+/// 		--primaryColor: #3498db;
+/// 		--secondaryColor: #2ecc71;
+/// 		--accentColor: #e74c3c;
+/// 	}
+/// @example scss - Обратное преобразование данных из CSS
+/// 	// Получение данных из data-атрибутов и преобразование в camelCase
+/// 	$data-attributes: (
+/// 		'data-user-id': '12345',
+/// 		'data-is-active': 'true',
+/// 		'data-role-name': 'admin'
+/// 	);
+///
+/// 	@each $attr, $value in $data-attributes {
+/// 		// Убираем префикс 'data-' и преобразуем в camelCase
+/// 		$attr-name: string.slice($attr, 6); // 'user-id', 'is-active', 'role-name'
+/// 		$js-property: convert-kebab2camel($attr-name);
+/// 		@debug $js-property + ': ' + $value;
+/// 		// userId: 12345
+/// 		// isActive: true
+/// 		// roleName: admin
+/// 	}
+/// @example css - Применение для data-атрибутов
+/// 	// Генерация CSS для элементов с data-атрибутами
+/// 	.user-profile[data-user-id="12345"] {
+/// 		color: blue;
+/// 	}
+///
+/// 	.button[data-is-active="true"] {
+/// 		background-color: green;
+/// 	}
+///
+/// 	.admin-panel[data-role-name="admin"] {
+/// 		border: 2px solid red;
+/// 	}
+/// @param {String} $value - Строка в kebab-case нотации для
+/// 	конвертации. Может содержать буквы, цифры, дефисы и
+/// 	другие символы. Функция игнорирует дефисы и
+/// 	преобразует символы, следующие за дефисами, в верхний
+/// 	регистр.
+/// @return {String} - Строка в camelCase нотации, где все
+/// 	дефисы удалены, а символы, которые следовали за
+/// 	дефисами, преобразованы в верхний регистр. Первый
+/// 	символ остается в исходном регистре.
+/// @throws {Error} - Может выбросить ошибку при передаче
+/// 	нестроковых значений. Аргумент должен быть строкой
+/// 	для корректной работы строковых функций Sass.
+@function convert-kebab2camel($value) {
+
+	// Переменная для накопления результата преобразования.
+	$-result: "";
+
+	// Проверка типа входного параметра: ожидается строковое значение.
+	// Функция is-string() проверяет, является ли $value строкой
+	// (тип данных string).
+	@if not is-string($value) {
+
+		// Если $value не является строкой, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// выполнение операции замены с некорректными данными.
+		@return log-invalid-type(
+			'convert-kebab2camel',
+			$value,
+			'$value',
+			'string'
+		);
+
+	}
+
+	// Основная логика выполняется только если $value является
+	// корректной строкой.
+	@else {
+
+		// Флаг, указывающий, что следующий символ должен быть
+		// преобразован в верхний регистр. Устанавливается в true,
+		// когда встречается дефис "-" в исходной строке.
+		$-capitalize-next: false;
+
+		// Определение длины входной строки для организации цикла.
+		// Функция string.length() возвращает количество символов
+		// в строке.
+		$-length: string.length($value);
+
+		// Цикл по всем символам строки от первого до последнего.
+		// Индекс $i последовательно принимает значения от 1 до $-length.
+		@for $i from 1 through $-length {
+
+			// Извлечение текущего символа строки по индексу $i.
+			// Функция string.slice() возвращает подстроку,
+			// в данном случае - один символ.
+			$-char: string.slice($value, $i, $i);
+
+			// Проверка: является ли текущий символ дефисом "-".
+			@if $-char == "-" {
+
+				// Если символ - дефис, устанавливаем флаг, что
+				// следующий символ должен быть заглавным.
+				// Сам дефис не добавляется к результату.
+				$-capitalize-next: true;
+
+			}
+
+			// Проверка: установлен ли флаг заглавного регистра
+			// для текущего символа.
+			@else if $-capitalize-next {
+
+				// Если флаг установлен, добавляем символ в верхнем
+				// регистре к результату и сбрасываем флаг.
+				$-result: $-result + string.to-upper-case($-char);
+				$-capitalize-next: false;
+
+			} @else {
+
+				// Если символ не дефис и флаг не установлен,
+				// добавляем символ как есть (в исходном регистре).
+				$-result: $-result + $-char;
+
+			}
+
+		}
+
+		// Возвращаем итоговую строку после преобразования всех
+		// символов.
+		@return $-result;
+
+	}
+
+}

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

@@ -0,0 +1,118 @@
+@use '../helpers/string/string-replace' as *;
+@use '../loggers/log-invalid-type' as *;
+@use '../validators/type-of/is-string' as *;
+
+/// Преобразует строку из `kebab-case` (кебаб-нотация) в
+/// `snake_case` (змеиная нотация).
+///
+/// Функция заменяет все дефисы (`-`) на символы нижнего
+/// подчеркивания (`_`) в переданной строке. Это преобразование
+/// позволяет конвертировать CSS-классы и имена переменных из
+/// frontend-разработки в формат, используемый в backend-языках
+/// программирования, таких как Python, Ruby и PHP.
+///
+/// Важные особенности функции:
+/// - Заменяет все вхождения дефисов на нижние подчеркивания
+/// - Сохраняет все остальные символы без изменений
+/// - Не изменяет регистр символов
+/// - Работает с любыми строками, содержащими дефисы
+/// - Простая и эффективная реализация через замену символов
+/// - Полезно для конвертации имен из frontend в backend
+/// - Используется для унификации именования в full-stack проектах
+/// - Поддерживает строки любой длины и сложности
+/// - Обрабатывает множественные дефисы подряд
+/// - Учитывает граничные случаи (пустая строка, отсутствие
+/// 	дефисов)
+/// ---
+/// @name convert-kebab2snake
+/// @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/Global_Objects/String/replace См. также: MDN Web Docs - Метод String.replace()
+/// @link https://developer.mozilla.org/en-US/docs/Glossary/Snake_case См. также: MDN Web Docs - Глоссарий: Snake_case
+/// @link https://developer.mozilla.org/en-US/docs/Glossary/Kebab-case См. также: MDN Web Docs - Глоссарий: Kebab-case
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_selectors См. также: MDN Web Docs - CSS селекторы
+/// @link https://css-tricks.com/snippets/sass/string-replace-function/ См. также: CSS-Tricks - Функция замены строк в Sass
+/// @link https://css-tricks.com/whats-the-difference-between-kebab-case-camel-case-and-snake-case/ См. также: CSS-Tricks - Разница между kebab-case, camelCase и snake_case
+/// @link https://sass-guidelin.es/ru/#section-42 См. также: Sass Guidelines - Раздел про строки
+/// @link https://www.python.org/dev/peps/pep-0008/ См. также: PEP 8 - Style Guide for Python Code
+/// @link https://rubystyle.guide/#naming См. также: Ruby Style Guide - Именование
+/// @example scss - Базовые преобразования
+/// 	@debug convert-kebab2snake('kebab-case');       // 'kebab_case'
+/// 	@debug convert-kebab2snake('background-color'); // 'background_color'
+/// 	@debug convert-kebab2snake('font-size');        // 'font_size'
+/// 	@debug convert-kebab2snake('border-radius');    // 'border_radius'
+/// 	@debug convert-kebab2snake('padding-left');     // 'padding_left'
+/// 	@debug convert-kebab2snake('margin-bottom');    // 'margin_bottom'
+/// @example scss - Множественные дефисы
+/// 	@debug convert-kebab2snake('border-top-left-radius');    // 'border_top_left_radius'
+/// 	@debug convert-kebab2snake('font-weight-bold');          // 'font_weight_bold'
+/// 	@debug convert-kebab2snake('text-decoration-line');      // 'text_decoration_line'
+/// 	@debug convert-kebab2snake('background-image-url');      // 'background_image_url'
+/// 	@debug convert-kebab2snake('grid-template-columns');     // 'grid_template_columns'
+/// 	@debug convert-kebab2snake('transition-property-all');   // 'transition_property_all'
+/// @example scss - Сложные случаи с цифрами и аббревиатурами
+/// 	@debug convert-kebab2snake('xml-http-request');          // 'xml_http_request'
+/// 	@debug convert-kebab2snake('css-animation');             // 'css_animation'
+/// 	@debug convert-kebab2snake('html5-canvas');              // 'html5_canvas'
+/// 	@debug convert-kebab2snake('ui-component');              // 'ui_component'
+/// 	@debug convert-kebab2snake('api-endpoint');              // 'api_endpoint'
+/// 	@debug convert-kebab2snake('user-id');                   // 'user_id'
+/// @example scss - Граничные случаи
+/// 	@debug convert-kebab2snake('single');                   // 'single'
+/// 	@debug convert-kebab2snake('');                         // '' (пустая строка)
+/// 	@debug convert-kebab2snake('already_snake');           // 'already_snake' (без изменений)
+/// 	@debug convert-kebab2snake('multiple---hyphens');      // 'multiple___hyphens'
+/// 	@debug convert-kebab2snake('-leading-hyphen');         // '_leading_hyphen'
+/// 	@debug convert-kebab2snake('trailing-hyphen-');        // 'trailing_hyphen_'
+/// @param {String} $value - Строка в kebab-case нотации для
+/// 	конвертации. Может содержать буквы, цифры, дефисы и
+/// 	другие символы. Функция заменяет все вхождения `-` на
+/// 	`_`, сохраняя остальные символы без изменений.
+/// @return {String} - Строка в snake_case нотации, где все
+/// 	дефисы заменены на символы нижнего подчеркивания.
+/// 	Результат подходит для использования в backend-языках
+/// 	программирования, конфигурационных файлах и API-запросах.
+/// @throws {Error} - Может выбросить ошибку при передаче
+/// 	нестроковых значений или если функция `string-replace`
+/// 	не определена. Требуется наличие функции `string-replace`
+/// 	в модуле `helpers` для корректной работы.
+/// @requires {function} string-replace - Вспомогательная
+/// 	функция замены подстрок в строке.
+/// 	Должна быть определена и доступна для корректной работы
+/// 	данной функции.
+@function convert-kebab2snake($value) {
+
+	// Проверка типа входного параметра: ожидается строковое значение.
+	// Функция is-string() проверяет, является ли $value строкой
+	// (тип данных string).
+	@if not is-string($value) {
+
+		// Если $value не является строкой, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// выполнение операции замены с некорректными данными.
+		@return log-invalid-type(
+			'convert-kebab2snake',
+			$value,
+			'$value',
+			'string'
+		);
+
+	}
+
+	// Основная логика выполняется только если $value является
+	// корректной строкой.
+	@else {
+
+		// Формула преобразования: заменяем все дефисы "-" на
+		// нижние подчеркивания "_".
+		@return string-replace($value, "-", "_");
+
+	}
+
+}