@omnisass/library 0.2.0

package/modules/utilities/helpers/color/_color-hue-shift.scss

@@ -0,0 +1,148 @@
+@use 'sass:color';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-color' as *;
+@use '../../validators/type-of/is-number' as *;
+
+/// Поворачивает цветовой тон (hue) цвета на заданное
+/// количество градусов.
+///
+/// Функция `color-hue-shift()` изменяет цветовой тон цвета
+/// в HSL-пространстве, сохраняя при этом его насыщенность и
+/// светлоту. Это позволяет создавать вариации цвета,
+/// которые гармонично сочетаются с исходным, сохраняя
+/// одинаковую насыщенность и яркость. Полезно для создания
+/// цветовых палитр, акцентных цветов или динамического
+/// изменения цвета при взаимодействии.
+///
+/// > Функция возвращает цвет в формате HSL, даже если
+/// > исходный цвет был в другом формате. Используйте
+/// > функцию `meta.inspect()` если нужен HEX формат.
+///
+/// > Для больших значений $degrees (>360 или <-360)
+/// > результат будет нормализован в диапазон 0-360°.
+/// ---
+/// @name color-hue-shift
+/// @group utilities-helpers
+/// @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://en.wikipedia.org/wiki/Hue См. также: Wikipedia - Цветовой тон (Hue)
+/// @link https://color.adobe.com/create/color-wheel См. также: Adobe Color - Цветовой круг
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/hsl См. также: MDN - Функция HSL
+/// @link https://css-tricks.com/hsl-hsla-is-great-for-programmatic-color-control/ См. также: CSS-Tricks - HSL отлично подходит для программного управления цветом
+/// @example scss - Поворот на 180 градусов (дополнительный цвет)
+/// 	$color: #3498db;
+/// 	$complementary: color-hue-shift($color, 180);
+/// 	.element {
+/// 		color: $color;
+/// 		background-color: $complementary;
+/// 	}
+/// @example css - Результат
+/// 	.element {
+/// 		color: #3498db;
+/// 		background-color: hsl(24.0718562874, 69.8744769874%, 53.137254902%);
+/// 	}
+/// @example scss - Создание гармоничных акцентов (±30 градусов)
+/// 	$primary: #2ecc71;
+/// 	$accent-1: color-hue-shift($primary, 30);
+/// 	$accent-2: color-hue-shift($primary, -30);
+/// @example scss - Динамическое изменение цвета при наведении
+/// 	.button {
+/// 		background-color: #e74c3c;
+///
+/// 		&:hover {
+/// 			// Легкое смещение тона для визуальной обратной связи
+/// 			background-color: color-hue-shift(#e74c3c, 15);
+/// 		}
+/// 	}
+/// @example css - Результат
+/// 	.button {
+/// 		background-color: #e74c3c;
+/// 	}
+/// 	.button:hover {
+/// 		background-color: hsl(20.6140350877, 78.0821917808%, 57.0588235294%);
+/// 	}
+/// @example scss - Создание монохромной палитры с вариациями тона
+/// 	$base-color: #9b59b6;
+/// 	$palette: (
+/// 		color-hue-shift($base-color, -20),
+/// 		$base-color,
+/// 		color-hue-shift($base-color, 20),
+/// 		color-hue-shift($base-color, 40)
+/// 	);
+/// @param {Color} $color - Исходный цвет, тон которого нужно
+/// 	изменить. Может быть в любом формате, поддерживаемом
+/// 	Sass (HEX, RGB, HSL, имя цвета).
+/// @param {Number} $degrees - Количество градусов для
+/// 	поворота тона. Положительные значения вращают по часовой
+/// 	стрелке, отрицательные - против. Значение автоматически
+/// 	нормализуется в диапазон 0-360° с помощью оператора %
+/// 	(прописывать вручную оператор % не нужно).
+/// @return {Color} - Новый цвет в формате HSL с измененным
+/// 	цветовым тоном, но с сохранением исходных значений
+/// 	насыщенности и светлоты.
+@function color-hue-shift($color, $degrees) {
+
+	// Проверка типа первого параметра: ожидается цветовое значение.
+	// Функция is-color() проверяет, является ли $color валидным цветом CSS.
+	@if not is-color($color) {
+
+		// Если $color не является цветом, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные вычисления с нецветовыми данными.
+		@return log-invalid-type(
+			'color-hue-shift',
+			$color,
+			'$color',
+			'color'
+		);
+
+	}
+
+	// Проверка типа второго параметра: ожидается числовое значение
+	// угла поворота в градусах. Положительные значения вращают цвет
+	// по часовой стрелке на цветовом круге, отрицательные - против.
+	@else if not is-number($degrees) {
+
+		// Если $degrees не является числом, возвращаем ошибку.
+		@return log-invalid-type(
+			'color-hue-shift',
+			$degrees,
+			'$degrees',
+			'number'
+		);
+
+	}
+
+	// Все параметры прошли валидацию - выполняем изменение оттенка.
+	@else {
+
+		// Вычисление нового значения оттенка (hue).
+		// Формула: (текущий оттенок + угол поворота) по модулю 360.
+		// Оператор % 360 гарантирует, что результат всегда будет
+		// в диапазоне от 0 до 359 градусов (цветовой круг).
+		// color.channel() извлекает компонент оттенка из цвета
+		// в пространстве HSL.
+		$-new-hue: (color.channel($color, "hue", $space: hsl) + $degrees) % 360;
+
+		// Создание нового цвета с измененным оттенком.
+		// Используем функцию hsl() для создания цвета в формате HSL.
+		// Компоненты:
+		// - $-new-hue: новый оттенок после поворота
+		// - saturation: насыщенность исходного цвета (сохраняется)
+		// - lightness: яркость исходного цвета (сохраняется)
+		//
+		// Таким образом, меняется только положение цвета на
+		// цветовом круге, сохраняя его насыщенность и яркость.
+		@return hsl(
+			$-new-hue,
+			color.channel($color, "saturation", $space: hsl),
+			color.channel($color, "lightness", $space: hsl)
+		);
+
+	}
+
+}

package/modules/utilities/helpers/color/_color-scale.scss

@@ -0,0 +1,208 @@
+@use 'sass:color';
+@use 'sass:list';
+@use 'sass:math';
+@use './color-shade' as *;
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-color' as *;
+@use '../../validators/type-of/is-number' as *;
+
+/// Генерирует монохромную шкалу оттенков путем затемнения
+/// базового цвета.
+///
+/// Функция `color-scale()` создает последовательность
+/// оттенков от исходного цвета до почти черного, равномерно
+/// распределяя шаги затемнения.
+///
+/// Идеально подходит для создания вариаций одного цвета для
+/// состояний hover/active, типографических иерархий или
+/// систем теней.
+/// ---
+/// @name color-scale
+/// @group utilities-helpers
+/// @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/lists См. также: Sass - Работа со списками (lists)
+/// @link https://www.smashingmagazine.com/2017/04/developer-guide-color-palettes/ См. также: Smashing Magazine - Гид по созданию цветовых палитр
+/// @link https://refactoringui.com/previews/building-your-color-palette См. также: Refactoring UI - Построение цветовых палитр
+/// @link https://medium.com/@erikdkennedy/color-in-ui-design-a-practical-framework-e18cacd97f9e См. также: Medium - Практический подход к цвету в дизайне
+/// @link https://m2.material.io/design/color/the-color-system.html См. также: Material Design - Система цвета
+/// @example scss - Примеры использования
+/// 	@use 'sass:list';
+///
+/// 	// Миксин, который генерирует CSS-комментарии для каждого шага шкалы
+/// 	@mixin debug-color-steps($scale) {
+/// 		@each $-color, $-index in $scale {
+/// 			/* step #{$-index}: #{$-color} */
+/// 		}
+/// 	}
+///
+/// 	// Использование миксина с шкалой из 3 шагов
+/// 	$blue-scale: color-scale(#3498db, 3);
+/// 	@include debug-color-steps($blue-scale);
+///
+/// 	// Миксин для генерации CSS-переменных
+/// 	@mixin generate-color-vars($scale, $name: 'color') {
+/// 		@for $i from 1 through list.length($scale) {
+/// 			--#{$name}-#{$i}: #{list.nth($scale, $i)};
+/// 		}
+/// 	}
+///
+/// 	// Создание переменных для серой шкалы
+/// 	$gray-scale: color-scale(#ccc, 4);
+/// 	:root {
+/// 		@include generate-color-vars($gray-scale, 'gray');
+/// 	}
+///
+/// 	// Миксин для компонента с состояними и комментариями
+/// 	@mixin color-stepped-element($base-color, $steps: 3) {
+/// 		$scale: color-scale($base-color, $steps);
+///
+/// 		background-color: list.nth($scale, 1);
+///
+/// 		&:hover {
+/// 			background-color: list.nth($scale, 2);
+/// 		}
+///
+/// 		&:active {
+/// 			background-color: list.nth($scale, 3);
+/// 		}
+/// 	}
+///
+/// 	// Применение миксина для alert-компонента
+/// 	.alert {
+/// 		@include color-stepped-element(#e74c3c, 2);
+/// 	}
+///
+/// 	// Миксин для отладки с нумерацией от 0
+/// 	@mixin debug-scale-steps($scale) {
+/// 		@for $i from 0 to list.length($scale) {
+/// 			/* step #{$i}: #{list.nth($scale, $i + 1)} */
+/// 		}
+/// 	}
+///
+/// 	// Пример использования debug-миксина
+/// 	$test-scale: color-scale(#ff0000, 5);
+/// 	@include debug-scale-steps($test-scale);
+/// @example css - Результат
+/// 	/* step : #3498db */
+/// 	/* step : rgb(34.6666666667, 101.3333333333, 146) */
+/// 	/* step : rgb(17.3333333333, 50.6666666667, 73) */
+/// 	/* step : black */
+///
+/// 	:root {
+/// 		--gray-1: #cccccc;
+/// 		--gray-2: #999999;
+/// 		--gray-3: #666666;
+/// 		--gray-4: #333333;
+/// 		--gray-5: black;
+/// 	}
+///
+/// 	.alert {
+/// 		background-color: #e74c3c;
+/// 	}
+/// 	.alert:hover {
+/// 		background-color: rgb(115.5, 38, 30);
+/// 	}
+/// 	.alert:active {
+/// 		background-color: black;
+/// 	}
+///
+/// 	/* step 0: red */
+/// 	/* step 1: #cc0000 */
+/// 	/* step 2: #990000 */
+/// 	/* step 3: #660000 */
+/// 	/* step 4: #330000 */
+/// 	/* step 5: black */
+/// @param {Color} $color - Исходный цвет, от которого
+/// 	строится шкала затемнения. Может быть в любом формате,
+/// 	который поддерживает Sass (HEX, RGB, HSL и т.д.).
+/// @param {Number} $steps [5] - Количество шагов затемнения.
+/// 	Определяет, сколько промежуточных оттенков будет
+/// 	создано между исходным цветом и максимально затемненным
+/// 	вариантом. При `$steps: 5` будет создано 6 цветов
+/// 	(исходный + 5 затемненных оттенков).
+/// @return {List} - Упорядоченный список (list) цветов, где:
+/// - Первый элемент: исходный цвет (`$color`)
+/// - Последний элемент: `color-shade($color, 100%)`
+/// - Промежуточные элементы: равномерно распределенные оттенки
+/// - Длина списка = `$steps + 1`
+@function color-scale($color, $steps: 5) {
+
+	// Проверка типа первого параметра: ожидается базовый цвет.
+	// Функция is-color() проверяет, является ли $color валидным цветом CSS.
+	@if not is-color($color) {
+
+		// Если $color не является цветом, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные вычисления с нецветовыми данными.
+		@return log-invalid-type(
+			'color-scale',
+			$color,
+			'$color',
+			'color'
+		);
+
+	}
+
+	// Проверка типа второго параметра: ожидается количество шагов
+	// (уровней) в цветовой шкале. Определяет, сколько оттенков
+	// будет сгенерировано на основе базового цвета.
+	@else if not is-number($steps) {
+
+		// Если $steps не является числом, возвращаем ошибку.
+		@return log-invalid-type(
+			'color-scale',
+			$steps,
+			'$steps',
+			'number'
+		);
+
+	}
+
+	// Все параметры прошли валидацию - выполняем генерацию шкалы.
+	@else {
+
+		// Инициализация списка для хранения цветовой палитры.
+		// Результатом функции будет список (массив) цветов,
+		// представляющих шкалу оттенков базового цвета.
+		$-palette: ();
+
+		// Цикл генерации цветов шкалы.
+		// Переменная $i принимает значения от 0 до $steps включительно.
+		// Это создает $steps + 1 цвет в итоговом списке.
+		@for $i from 0 through $steps {
+
+			// Вычисление процентного значения для текущего шага.
+			// Формула: (текущий шаг) × (100 / общее количество шагов)
+			// Пример для 5 шагов: значения будут 0%, 20%, 40%, 60%,
+			// 80%, 100%.
+			$-percentage: math.div($i * 100, $steps);
+
+			// Генерация оттенка с помощью вспомогательной функции
+			// color-shade().
+			// Предполагается, что color-shade($color, $percentage)
+			// создает оттенок базового цвета с указанной интенсивностью.
+			// - При $percentage = 0% → самый светлый оттенок (близкий
+			//   к белому)
+			// - При $percentage = 100% → самый темный оттенок (близкий
+			//   к черному)
+			$-shade: color-shade($color, $-percentage);
+
+			// Добавление сгенерированного оттенка в палитру.
+			// Функция list.append() добавляет новый элемент в
+			// конец списка.
+			$-palette: list.append($-palette, $-shade);
+
+		}
+
+		// Возвращаем список сгенерированных оттенков.
+		// Список содержит $steps + 1 элементов, равномерно распределенных
+		// по шкале от самого светлого к самому темному оттенку.
+		@return $-palette;
+
+	}
+
+}

package/modules/utilities/helpers/color/_color-shade.scss

@@ -0,0 +1,113 @@
+@use 'sass:color';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-color' as *;
+@use '../../validators/type-of/is-number' as *;
+
+/// Создает затемненную версию цвета, добавляя к нему
+/// черный цвет.
+///
+/// Функция `color-shade()` затемняет исходный цвет, смешивая
+/// его с черным. Процент затемнения определяет, сколько
+/// черного цвета будет добавлено к исходному.
+///
+/// Это полезно для создания вариаций цветов для состояний
+/// наведения, теней или для построения цветовых палитр с
+/// различными уровнями насыщенности.
+/// ---
+/// @name color-shade
+/// @group utilities-helpers
+/// @since 2025.12.27
+/// @access public
+/// @author Kitty Giraudel
+/// @author Murad Rustamov (therteenten) [адаптация]
+/// @link https://github.com/KittyGiraudel GitHub - Kitty Giraudel
+/// @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#mix См. также: Sass — Официальная документация по модулю color
+/// @link https://sass-guidelin.es/ru/ См. также: Sass Guidelines — Руководство по написанию разумного Sass
+/// @link https://www.w3schools.com/sass/sass_functions_color.asp См. также: W3Schools — Справочник по цветовым функциям Sass
+/// @link https://developer.mozilla.org/ru/docs/Web/CSS/color_value См. также: MDN — Значения цвета CSS
+/// @example scss - Пример использования
+/// 	.button {
+/// 		background-color: #3498db;
+///
+/// 		&:hover {
+/// 			// Затемняет цвет на 20% для состояния наведения
+/// 			background-color: color-shade(#3498db, 20);
+/// 		}
+///
+/// 	}
+/// @example css - Результат
+/// 	.button {
+/// 		background-color: #3498db;
+/// 	}
+/// 	.button:hover {
+/// 		background-color: rgb(41.6, 121.6, 175.2);
+/// 	}
+/// @param {Color} $color - Исходный цвет для затемнения.
+/// 	Может быть в любом формате, который поддерживает Sass
+/// 	(hex, rgb, rgba, hsl, hsla, имя цвета).
+/// @param {Number} $percentage - Процент затемнения (от 0
+/// 	до 100). Определяет долю черного цвета в итоговой
+/// 	смеси. 0 вернет исходный цвет, 100 вернет чистый
+/// 	черный.
+/// @return {Color} - Затемненный цвет в том же формате,
+/// 	что и исходный.
+@function color-shade($color, $percentage) {
+
+	// Проверка типа первого параметра: ожидается базовый цвет.
+	// Функция is-color() проверяет, является ли $color валидным цветом CSS.
+	@if not is-color($color) {
+
+		// Если $color не является цветом, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные вычисления с нецветовыми данными.
+		@return log-invalid-type(
+			'color-shade',
+			$color,
+			'$color',
+			'color'
+		);
+
+	}
+
+	// Проверка типа второго параметра: ожидается процентное значение
+	// интенсивности затемнения. Определяет, насколько темным будет
+	// итоговый цвет относительно базового.
+	@else if not is-number($percentage) {
+
+		// Если $percentage не является числом, возвращаем ошибку.
+		@return log-invalid-type(
+			'color-shade',
+			$percentage,
+			'$percentage',
+			'number'
+		);
+
+	}
+
+	// Все параметры прошли валидацию - выполняем затемнение цвета.
+	@else {
+
+		// Формула затемнения: смешивание базового цвета с черным
+		// в указанной пропорции.
+		//
+		// Используем встроенную функцию color.mix():
+		// Параметры:
+		// - black: первый цвет для смешивания (черный)
+		// - $color: второй цвет для смешивания (базовый цвет)
+		// - $percentage * 1%: процентное соотношение
+		//   (сколько процентов черного цвета в смеси)
+		//
+		// Математика смешивания:
+		// - При $percentage = 0% → 100% $color, 0% black (исходный цвет)
+		// - При $percentage = 50% → 50% $color, 50% black (среднее затемнение)
+		// - При $percentage = 100% → 0% $color, 100% black (полностью черный)
+		//
+		// Результат: цвет, который является затемненной версией
+		// исходного цвета, где процент определяет степень затемнения.
+		@return color.mix(black, $color, $percentage * 1%);
+
+	}
+
+}

package/modules/utilities/helpers/color/_color-tint.scss

@@ -0,0 +1,118 @@
+@use 'sass:color';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-color' as *;
+@use '../../validators/type-of/is-number' as *;
+
+/// Осветляет исходный цвет, смешивая его с белым.
+///
+/// Функция `color-tint()` создает более светлые оттенки
+/// цвета путем добавления белого. Это удобно для генерации
+/// цветовых палитр, оформления состояний интерфейса
+/// (например, disabled), градиентов или оттенков фона.
+/// ---
+/// @name color-tint
+/// @group utilities-helpers
+/// @since 2025.12.27
+/// @access public
+/// @author Kitty Giraudel
+/// @author Murad Rustamov (therteenten) [адаптация]
+/// @link https://github.com/KittyGiraudel GitHub - Kitty Giraudel
+/// @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#mix См. также: Sass — Официальная документация по модулю color
+/// @link https://sass-guidelin.es/ru/#_2 См. также: Sass Guidelines — Вложенность
+/// @link https://www.w3schools.com/sass/sass_functions_color.php См. также: W3Schools — Справочник по цветовым функциям Sass
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/color_value См. также: MDN — CSS Color Values
+/// @link https://css-tricks.com/snippets/sass/tint-shade-functions/ См. также: CSS-Tricks — Функции tint() и shade() на Sass
+/// @example scss - Пример использования
+/// 	$primary-color: #3498db;
+///
+/// 	.card {
+/// 		background-color: $primary-color;
+///
+/// 		&--light {
+/// 			// Осветлить основной цвет на 40%
+/// 			background-color: color-tint($primary-color, 40);
+/// 		}
+///
+/// 		&--highlight {
+/// 			// Очень светлый акцентный фон
+/// 			background-color: color-tint($primary-color, 85);
+/// 		}
+/// 	}
+/// @example css - Результат
+/// 	.card {
+/// 		background-color: #3498db;
+/// 	}
+/// 	.card--light {
+/// 		background-color: rgb(133.2, 193.2, 233.4);
+/// 	}
+/// 	.card--highlight {
+/// 		background-color: rgb(224.55, 239.55, 249.6);
+/// 	}
+/// @param {Color} $color - Исходный цвет для осветления.
+/// 	Допустимы все форматы Sass (hex, rgb, hsl, имя цвета
+/// 	и т.д.).
+/// @param {Number} $percentage - Интенсивность осветления
+/// 	(0 - 100). Указывает долю белого в итоговой смеси.
+/// 	При 0 вернется исходный цвет, при 100 — чистый белый.
+/// @return {Color} - Осветленный цвет в том же формате,
+/// 	что и входной.
+@function color-tint($color, $percentage) {
+
+	// Проверка типа первого параметра: ожидается базовый цвет.
+	// Функция is-color() проверяет, является ли $color валидным цветом CSS.
+	@if not is-color($color) {
+
+		// Если $color не является цветом, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные вычисления с нецветовыми данными.
+		@return log-invalid-type(
+			'color-tint',
+			$color,
+			'$color',
+			'color'
+		);
+
+	}
+
+	// Проверка типа второго параметра: ожидается процентное значение
+	// интенсивности осветления. Определяет, насколько светлым будет
+	// итоговый цвет относительно базового.
+	@else if not is-number($percentage) {
+
+		// Если $percentage не является числом, возвращаем ошибку.
+		@return log-invalid-type(
+			'color-tint',
+			$percentage,
+			'$percentage',
+			'number'
+		);
+
+	}
+
+	// Все параметры прошли валидацию - выполняем осветление цвета.
+	@else {
+
+		// Формула осветления: смешивание базового цвета с белым
+		// в указанной пропорции.
+		//
+		// Используем встроенную функцию color.mix():
+		// Параметры:
+		// - white: первый цвет для смешивания (белый)
+		// - $color: второй цвет для смешивания (базовый цвет)
+		// - $percentage * 1%: процентное соотношение
+		//   (сколько процентов белого цвета в смеси)
+		//
+		// Математика смешивания:
+		// - При $percentage = 0% → 100% $color, 0% white (исходный цвет)
+		// - При $percentage = 50% → 50% $color, 50% white (среднее осветление)
+		// - При $percentage = 100% → 0% $color, 100% white (полностью белый)
+		//
+		// Результат: цвет, который является осветленной версией
+		// исходного цвета, где процент определяет степень осветления.
+		@return color.mix(white, $color, $percentage * 1%);
+
+	}
+
+}