@omnisass/library 0.2.0

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

@@ -0,0 +1,173 @@
+@use '../helpers/string/string-replace' as *;
+@use '../loggers/log-invalid-type' as *;
+@use '../validators/type-of/is-string' as *;
+
+/// Преобразует строку из `snake_case` (змеиная нотация) в
+/// `kebab-case` (кебаб-нотация).
+///
+/// Функция заменяет все символы нижнего подчеркивания (`_`)
+/// на дефисы (`-`) в переданной строке. Это простое
+/// преобразование позволяет конвертировать имена переменных
+/// из языков программирования, использующих snake_case
+/// (Python, Ruby, PHP) в CSS-совместимый kebab-case формат.
+///
+/// Важные особенности функции:
+/// - Заменяет все вхождения нижнего подчеркивания на дефисы
+/// - Сохраняет все остальные символы без изменений
+/// - Не изменяет регистр символов
+/// - Работает с любыми строками, содержащими подчеркивания
+/// - Простая и эффективная реализация через замену символов
+/// - Полезно для конвертации имен из backend в frontend
+/// - Используется для унификации именования в full-stack проектах
+/// - Поддерживает строки любой длины и сложности
+/// - Обрабатывает множественные подчеркивания подряд
+/// - Учитывает граничные случаи (пустая строка, отсутствие
+/// 	подчеркиваний)
+/// ---
+/// @name convert-snake2kebab
+/// @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/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-snake2kebab('snake_case');           // 'snake-case'
+/// 	@debug convert-snake2kebab('background_color');     // 'background-color'
+/// 	@debug convert-snake2kebab('font_size');           // 'font-size'
+/// 	@debug convert-snake2kebab('border_radius');       // 'border-radius'
+/// 	@debug convert-snake2kebab('padding_left');        // 'padding-left'
+/// 	@debug convert-snake2kebab('margin_bottom');       // 'margin-bottom'
+/// @example scss - Множественные подчеркивания
+/// 	@debug convert-snake2kebab('border_top_left_radius');    // 'border-top-left-radius'
+/// 	@debug convert-snake2kebab('font_weight_bold');          // 'font-weight-bold'
+/// 	@debug convert-snake2kebab('text_decoration_line');      // 'text-decoration-line'
+/// 	@debug convert-snake2kebab('background_image_url');      // 'background-image-url'
+/// 	@debug convert-snake2kebab('grid_template_columns');     // 'grid-template-columns'
+/// 	@debug convert-snake2kebab('transition_property_all');   // 'transition-property-all'
+/// @example scss - Сложные случаи с цифрами и аббревиатурами
+/// 	@debug convert-snake2kebab('xml_http_request');          // 'xml-http-request'
+/// 	@debug convert-snake2kebab('css_animation');             // 'css-animation'
+/// 	@debug convert-snake2kebab('html5_canvas');              // 'html5-canvas'
+/// 	@debug convert-snake2kebab('ui_component');              // 'ui-component'
+/// 	@debug convert-snake2kebab('api_endpoint');              // 'api-endpoint'
+/// 	@debug convert-snake2kebab('user_id');                   // 'user-id'
+/// @example scss - Граничные случаи
+/// 	@debug convert-snake2kebab('single');                   // 'single'
+/// 	@debug convert-snake2kebab('');                         // '' (пустая строка)
+/// 	@debug convert-snake2kebab('already-kebab');           // 'already-kebab' (без изменений)
+/// 	@debug convert-snake2kebab('multiple___underscores');  // 'multiple---hyphens'
+/// 	@debug convert-snake2kebab('_leading_underscore');     // '-leading-underscore'
+/// 	@debug convert-snake2kebab('trailing_underscore_');    // 'trailing-underscore-'
+/// @example scss - Интеграция с Python/Ruby конфигурациями
+/// 	// Конвертация переменных из backend (Python/Ruby) в CSS
+/// 	$backend-variables: (
+/// 	  'primary_color': #3498db,
+/// 	  'secondary_color': #2ecc71,
+/// 	  'font_size_base': 16px,
+/// 	  'border_radius_small': 4px,
+/// 	  'max_width_container': 1200px
+/// 	);
+///
+/// 	:root {
+/// 	  @each $name, $value in $backend-variables {
+/// 	    --#{convert-snake2kebab($name)}: #{$value};
+/// 	  }
+/// 	}
+/// @example css - Результат интеграции с backend
+/// 	:root {
+/// 	  --primary-color: #3498db;
+/// 	  --secondary-color: #2ecc71;
+/// 	  --font-size-base: 16px;
+/// 	  --border-radius-small: 4px;
+/// 	  --max-width-container: 1200px;
+/// 	}
+/// @example scss - Работа с API-ответами
+/// 	// Преобразование ключей JSON из snake_case в kebab-case
+/// 	$api-response: (
+/// 	  'user_name': 'John Doe',
+/// 	  'email_address': 'john@example.com',
+/// 	  'is_active': true,
+/// 	  'created_at': '2023-01-15',
+/// 	  'updated_at': '2023-12-28'
+/// 	);
+///
+/// 	.user-data {
+/// 	  @each $key, $value in $api-response {
+/// 	    data-#{convert-snake2kebab($key)}: "#{$value}";
+/// 	  }
+/// 	}
+/// @example css - Результат для data-атрибутов
+/// 	.user-data {
+/// 	  data-user-name: "John Doe";
+/// 	  data-email-address: "john@example.com";
+/// 	  data-is-active: true;
+/// 	  data-created-at: "2023-01-15";
+/// 	  data-updated-at: "2023-12-28";
+/// 	}
+/// @param {String} $value - Строка в snake_case нотации для
+/// 	конвертации. Может содержать буквы, цифры, символы
+/// 	нижнего подчеркивания и другие символы. Функция заменяет
+/// 	все вхождения `_` на `-`, сохраняя остальные символы
+/// 	без изменений.
+/// @return {String} - Строка в kebab-case нотации, где все
+/// 	символы нижнего подчеркивания заменены на дефисы.
+/// 	Результат готов к использованию как CSS-класс, часть
+/// 	селектора или имя CSS-переменной.
+/// @throws {Error} - Может выбросить ошибку при передаче
+/// 	нестроковых значений или если функция `string-replace`
+/// 	не определена. Требуется наличие функции `string-replace`
+/// 	в доступном scope.
+/// @require {function} string-replace - Вспомогательная
+/// 	функция замены подстрок в строке из модуля `helpers`.
+/// 	Должна быть определена и доступна для корректной работы
+/// 	данной функции.
+@function convert-snake2kebab($value) {
+
+	// Проверка типа входного параметра: ожидается
+	// строковое значение.
+	// Функция is-string() проверяет, является ли $value
+	// строкой (тип данных string).
+	@if not is-string($value) {
+
+		// Если $value не является строкой, возвращаем ошибку
+		// через стандартную функцию логирования.
+		// Это предотвращает выполнение операции замены с
+		// некорректными данными.
+		@return log-invalid-type(
+			'convert-snake2kebab',
+			$value,
+			'$value',
+			'string'
+		);
+
+	} @else {
+
+		// Основная логика выполняется только если $value
+		// является корректной строкой.
+		//
+		// Используем вспомогательную функцию string-replace()
+		// для замены символов:
+		// - Первый параметр: $value - исходная строка для
+		// 	  преобразования
+		// - Второй параметр: "_" - искомый символ (нижнее
+		// 	  подчеркивание, snake_case разделитель)
+		// - Третий параметр: "-" - заменяющий символ (дефис,
+		// 	  kebab-case разделитель)
+		//
+		// Результат: строка, в которой все символы "_" заменены на "-".
+		@return string-replace($value, "_", "-");
+
+	}
+
+}

package/modules/utilities/getters/color/_get-color-brightness.scss

@@ -0,0 +1,138 @@
+@use 'sass:color';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-color' as *;
+
+/// Рассчитывает яркость (светлоту) цвета.
+///
+/// Функция `get-color-brightness()` возвращает значение
+/// светлоты цвета в соответствии с моделью HSL.
+///
+/// Это упрощенный интерфейс к стандартной функции
+/// `lightness()`. Значение яркости варьируется от 0%
+/// (абсолютно черный) до 100% (абсолютно белый).
+///
+/// Полезно для динамического определения контрастности
+/// текста, автоматической корректировки цветов или создания
+/// доступных цветовых схем.
+/// ---
+/// @name get-color-brightness
+/// @group utilities-getters
+/// @since 2025.12.27
+/// @access public
+/// @author Murad Rustamov (therteenten)
+/// @link https://sourcecraft.dev/users/therteenten/overview SourceCraft - therteenten
+/// @link https://sourcecraft.dev/omnisass/library SourceCraft - OmniSass
+/// @link https://sass-lang.com/documentation/modules/color#lightness См. также: Sass - Документация функции lightness()
+/// @link https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast См. также: MDN - Понимание WCAG: Контрастность цветов
+/// @link https://webaim.org/resources/contrastchecker/ См. также: WebAIM - Проверка контрастности цветов
+/// @link https://www.w3.org/TR/WCAG21/#contrast-minimum См. также: W3C - Рекомендации по минимальному контрасту
+/// @link https://css-tricks.com/switch-font-color-for-different-backgrounds-with-css/ См. также: CSS-Tricks - Смена цвета текста для разных фонов
+/// @example scss - Пример использования
+/// 	$primary: #3498db;
+/// 	$brightness: get-color-brightness($primary); // Пример: ~53%
+///
+/// 	// Автоматический выбор цвета текста в зависимости от фона
+/// 	.element {
+/// 		background-color: $primary;
+/// 		color: color: if($brightness > 50%, #000, #fff);
+/// 	}
+/// @example css - Результат
+/// 	.element {
+/// 		background-color: #3498db;
+/// 		color: #000;
+/// 	}
+/// @example scss - Стандартные цвета
+/// 	@debug get-color-brightness(#ffffff);      // 100%
+/// 	@debug get-color-brightness(#000000);      // 0%
+/// 	@debug get-color-brightness(#ff0000);      // 50%
+/// 	@debug get-color-brightness(#00ff00);      // 50%
+/// 	@debug get-color-brightness(#0000ff);      // 50%
+/// 	@debug get-color-brightness(#ffff00);      // 50%
+/// 	@debug get-color-brightness(#ff00ff);      // 50%
+/// 	@debug get-color-brightness(#00ffff);      // 50%
+/// 	@debug get-color-brightness(#808080);      // 50.196078431372555%
+/// 	@debug get-color-brightness(#c0c0c0);      // 75.29411764705883%
+/// @example scss - Цвета в разных форматах
+/// 	@debug get-color-brightness(rgb(255, 0, 0));          // 50%
+/// 	@debug get-color-brightness(rgba(255, 0, 0, 0.5));    // 50%
+/// 	@debug get-color-brightness(hsl(0, 100%, 50%));       // 50%
+/// 	@debug get-color-brightness(hsla(0, 100%, 50%, 0.5)); // 50%
+/// 	@debug get-color-brightness(hsl(120, 100%, 50%));     // 50%
+/// 	@debug get-color-brightness(hsl(240, 100%, 50%));     // 50%
+/// @example scss - Градации серого
+/// 	@debug get-color-brightness(#000000);      // 0%
+/// 	@debug get-color-brightness(#333333);      // 20%
+/// 	@debug get-color-brightness(#666666);      // 40%
+/// 	@debug get-color-brightness(#999999);      // 60%
+/// 	@debug get-color-brightness(#cccccc);      // 80%
+/// 	@debug get-color-brightness(#ffffff);      // 100%
+/// @example scss - Пастельные цвета
+/// 	@debug get-color-brightness(#ffcccc);      // 90%
+/// 	@debug get-color-brightness(#ccffcc);      // 90%
+/// 	@debug get-color-brightness(#ccccff);      // 90%
+/// 	@debug get-color-brightness(#ffe6cc);      // 90%
+/// 	@debug get-color-brightness(#e6ccff);      // 90%
+/// @example scss - Яркие и темные цвета
+/// 	@debug get-color-brightness(#ff9900);      // 50%
+/// 	@debug get-color-brightness(#00cc99);      // 40%
+/// 	@debug get-color-brightness(#663399);      // 40%
+/// 	@debug get-color-brightness(#330066);      // 20%
+/// 	@debug get-color-brightness(#003366);      // 20%
+/// @example scss - Полупрозрачные цвета
+/// 	@debug get-color-brightness(rgba(0, 0, 0, 0.5));     // 0% (яркость не зависит от альфа-канала)
+/// 	@debug get-color-brightness(rgba(255, 255, 255, 0.3)); // 100%
+/// 	@debug get-color-brightness(rgba(128, 128, 128, 0.8)); // 50.196078431372555%
+/// @param {Color} $color - Цвет для анализа яркости. Может
+/// 	быть в любом формате, который поддерживает Sass (HEX,
+/// 	RGB, HSL, имя цвета).
+/// @return {Number} - Значение светлоты в процентах (0% - 100%).
+/// 	Черный цвет вернет значение около 0%, белый - 100%,
+/// 	серые тона - промежуточные значения в зависимости от
+/// 	их светлоты.
+@function get-color-brightness($color) {
+
+	// Проверка типа входного параметра: ожидается
+	// цветовое значение.
+	//
+	// Функция is-color() проверяет, является ли $color
+	// валидным цветом CSS.
+	// Поддерживаемые форматы: hex, rgb, rgba, hsl,
+	// hsla, названия цветов.
+	@if not is-color($color) {
+
+		// Если $color не является цветом, логируем ошибку
+		// через отладочное сообщение:
+		@return log-invalid-type(
+			'get-color-brightness',
+			$color,
+			'$color',
+			'color'
+		);
+
+	} @else {
+
+		// Основная логика выполняется только если $color
+		// является валидным цветом.
+		//
+		// Используем функцию color.channel() для извлечения
+		// компонента яркости:
+		// - Первый параметр: $color - исходный цвет
+		// - Второй параметр: "lightness" - извлекаем компонент
+		// 	  яркости
+		// - Третий параметр: $space: hsl - указываем цветовое
+		// 	  пространство HSL
+		//
+		// HSL (Hue, Saturation, Lightness) - цветовая модель:
+		// - Hue (оттенок): угол на цветовом круге (0-360deg)
+		// - Saturation (насыщенность): процент (0%-100%)
+		// - Lightness (яркость): процент (0%-100%)
+		//
+		// Возвращаемое значение: процент от 0% до 100%, где:
+		// - 0% = абсолютно черный
+		// - 100% = абсолютно белый
+		// - 50% = чистый цвет (без добавления черного или белого)
+		@return color.channel($color, "lightness", $space: hsl);
+
+	}
+
+}

package/modules/utilities/getters/color/_get-color-darkest.scss

@@ -0,0 +1,178 @@
+@use 'sass:color';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-list' as *;
+
+/// Находит самый темный цвет в списке по значению lightness
+/// в HSL-пространстве.
+///
+/// Функция проходит по всем цветам в списке, вычисляет
+/// lightness каждого цвета в HSL-пространстве и возвращает
+/// цвет с наименьшим значением `lightness`.
+///
+/// Если несколько цветов имеют одинаковое минимальное
+/// значение `lightness`, возвращается первый найденный
+/// такой цвет.
+///
+/// Важные особенности функции:
+/// - Использует HSL-пространство для вычисления lightness
+/// - Значение `lightness` измеряется в процентах (0% - черный,
+/// 	100% - белый)
+/// - Возвращает `null` для пустого списка
+/// - Ожидает, что все элементы списка являются цветами
+/// - Не проверяет тип элементов (используйте is-color-list()
+/// 	для валидации)
+/// - Использует локальные переменные с префиксом `$-` для
+/// 	избежания конфликтов
+/// ---
+/// @name get-color-darkest
+/// @group utilities-getters
+/// @since 2025.12.27
+/// @access public
+/// @author Murad Rustamov (therteenten)
+/// @link https://sourcecraft.dev/users/therteenten/overview SourceCraft - therteenten
+/// @link https://sourcecraft.dev/omnisass/library SourceCraft - OmniSass
+/// @link https://sass-lang.com/documentation/modules/color#channel См. также: Официальная документация Sass - Функция color.channel()
+/// @link https://sass-lang.com/documentation/values/colors#hsl См. также: Официальная документация Sass - HSL цвета
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/hsl MDN Web Docs - CSS функция hsl()
+/// @link https://css-tricks.com/snippets/sass/ См. также: CSS-Tricks - Коллекция сниппетов Sass
+/// @link https://sass-guidelin.es/ru/#color-functions См. также: Sass Guidelines - Функции для работы с цветами
+/// @link https://frontender.info/sass-colors/ См. также: Frontender Magazine - Работа с цветами в Sass
+/// @link https://www.w3schools.com/sass/sass_functions_color.php См. также: W3Schools - Функции для работы с цветами в Sass
+/// @link https://habr.com/ru/post/247881/ См. также: Habr - Статья "Sass для верстальщика: цвета"
+/// @example scss - Поиск самого темного цвета
+/// 	@debug get-color-darkest((#000000, #333333, #666666));            // #000000
+/// 	@debug get-color-darkest((#ff0000, #00ff00, #0000ff));            // #ff000000
+/// 	@debug get-color-darkest((hsl(0, 100%, 20%), hsl(0, 100%, 50%))); // hsl(0, 100%, 20%)
+/// @example scss - Градации серого
+/// 	@debug get-color-darkest((#ffffff, #cccccc, #999999, #666666, #333333, #000000)); // #000000
+/// 	@debug get-color-darkest((#f8f9fa, #e9ecef, #dee2e6, #ced4da, #adb5bd));          // #adb5bd
+/// @example scss - Разные цветовые пространства (конвертируются в HSL)
+/// 	@debug get-color-darkest((rgb(0, 0, 0), rgb(100, 100, 100)));       // rgb(0, 0, 0)
+/// 	@debug get-color-darkest((#f00, #0f0, #00f));                       // #f00
+/// 	@debug get-color-darkest((hsl(0, 100%, 30%), hsl(120, 100%, 30%))); // hsl(0, 100%, 30%)
+/// @example scss - Практическое использование для определения акцентного цвета
+/// 	$brand-colors: (#3498db, #2ecc71, #e74c3c, #f1c40f);
+/// 	$darkest-brand: get-color-darkest($brand-colors);
+/// 	// $darkest-brand: #3498db (синий самый темный в HSL)
+///
+/// 	.dark-element {
+/// 		background-color: $darkest-brand;
+/// 		color: white;
+/// 	}
+/// @example css - Результат
+/// 	.dark-element {
+/// 		background-color: #2ecc71;
+/// 		color: white;
+/// 	}
+/// @example scss - Создание градиента от самого темного
+/// 	$palette: (#ff6b6b, #4ecdc4, #45b7d1, #96ceb4, #ffeaa7);
+/// 	$base-color: get-color-darkest($palette);
+/// 	.gradient-box {
+/// 		background: linear-gradient(135deg, $base-color, color.adjust($base-color, $lightness: 30%));
+/// 	}
+/// @example css - Результат
+/// 	.gradient-box {
+/// 		background: linear-gradient(135deg, #45b7d1, rgb(191.6637931034, 230.4827586207, 239.3362068966));
+/// 	}
+/// @example scss - Выбор цвета текста на темном фоне
+/// 	$background-options: (#2c3e50, #34495e, #7f8c8d);
+/// 	$darkest-bg: get-color-darkest($background-options);
+///
+/// 	.card {
+/// 		background: $darkest-bg;
+/// 		color: if(color.channel($darkest-bg, "lightness", $space: hsl) < 50%, white, black);
+/// 	}
+/// @example css - Результат
+/// 	.card {
+/// 		background: #2c3e50;
+/// 		color: white;
+/// 	}
+/// @example scss - Обработка пустых и некорректных списков
+/// 	@debug get-color-darkest(());        // null
+/// 	@debug get-color-darkest((#ff0000)); // #ff0000
+///
+/// 	// Важно: функция не валидирует типы элементов!
+/// 	@debug get-color-darkest((#ff0000, 10px, #0000ff)); // Ошибка при вычислении lightness
+/// @param {List} $color-list - Список цветов для анализа.
+/// 	Ожидается, что все элементы списка являются валидными
+/// 	цветами в любом формате (hex, rgb, hsl, названия и т.д.).
+/// @return {Color | Null} - Самый темный цвет из списка по
+/// 	значению lightness в HSL-пространстве. Возвращает
+/// 	`null`, если список пустой. Если несколько цветов
+/// 	имеют одинаковую минимальную lightness, возвращает
+/// 	первый из них.
+/// @throws {Error} - Может выбросить ошибку, если в списке
+/// 	встречаются элементы, не являющиеся цветами, при
+/// 	попытке вызова `color.channel()`.
+@function get-color-darkest($color-list) {
+
+	// Инициализация переменных для хранения результата поиска.
+	// - $-result: будет содержать самый темный цвет из списка
+	// - $-min-lightness: будет содержать минимальное значение
+	// 	  яркости (наименьшая яркость = самый темный)
+	$-result: '';
+	$-min-lightness: null;
+
+	// Проверка типа входного параметра: ожидается список
+	// (list) или arglist цветов.
+	// Функция предназначена для работы со списком цветовых
+	// значений.
+	@if not is-list($color-list) {
+
+		// Если $color-list не является списком, возвращаем
+		// ошибку через стандартную функцию логирования. Это
+		// предотвращает дальнейшее выполнение с некорректными
+		// данными.
+		@return log-invalid-type(
+			'get-color-darkest',
+			$color-list,
+			'$color-list',
+			('list', 'arglist')
+		);
+
+	}
+
+	// Основная логика выполняется только если входной параметр
+	// прошел валидацию.
+	@else {
+
+		// Итерация по всем цветам в списке.
+		@each $-color in $color-list {
+
+			// Для каждого цвета вычисляем его яркость (lightness) в
+			// пространстве HSL.
+			// - color.channel() извлекает компонент яркости из цвета.
+			// - $space: hsl указывает использовать HSL цветовое
+			// 	  пространство
+			// Результат: процентное значение от 0% до 100%.
+			// 0% = абсолютно черный, 100% = абсолютно белый.
+			$-lightness: color.channel($-color, "lightness", $space: hsl);
+
+			// Поиск цвета с минимальной яркостью (самого темного).
+			// Условие выполняется в двух случаях:
+			// 1. $-min-lightness == null: это первый обрабатываемый
+			// 	   цвет в списке
+			// 2. $-lightness < $-min-lightness: текущий цвет темнее
+			// 	   предыдущего найденного
+			@if $-min-lightness == null or $-lightness < $-min-lightness {
+
+				// Обновляем значения:
+				// - $-min-lightness: запоминаем новое минимальное значение
+				// 	  яркости
+				// - $-result: сохраняем ссылку на самый темный цвет на
+				// 	  данный момент
+				$-min-lightness: $-lightness;
+				$-result: $-color;
+
+			}
+
+		}
+
+		// Возвращаем самый темный цвет из списка.
+		// Если список был пустым, вернется начальное
+		// значение '' (пустая строка).
+		@return $-result;
+
+	}
+
+}

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

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