@omnisass/library 0.2.0

package/modules/utilities/helpers/string/_string-trim-start.scss

@@ -0,0 +1,62 @@
+@use 'sass:string';
+
+/// Удаляет пробелы с начала строки (слева).
+///
+/// Функция последовательно проверяет и удаляет пробелы с начала
+/// строки, пока не встретит непробельный символ.
+///
+/// Возвращает строку без начальных пробелов.
+///
+/// Важные особенности функции:
+/// - Использует цикл `@while` для последовательного удаления начальных пробелов
+/// - Проверяет первый символ строки на равенство пробелу
+/// - Использует `string.slice()` для создания подстрок без начальных пробелов
+/// - Удаляет только пробелы (символ " "), не удаляет другие whitespace-символы
+/// - Сохраняет все пробелы в конце строки и между словами
+/// - Полезен для обработки выровненных текстов или значений с отступами
+/// ---
+/// @name string-trim-start
+/// @group utilities-helpers
+/// @since 2026.01.03
+/// @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/strings См. также: Официальная документация Sass - Тип данных "Строки"
+/// @link https://sass-lang.com/documentation/modules/string#slice См. также: Официальная документация Sass - Функция string.slice()
+/// @link https://sass-lang.com/documentation/at-rules/control См. также: Официальная документация Sass - Управляющие директивы
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/string_value См. также: MDN Web Docs - CSS-тип <string>
+/// @link https://sass-lang.com/documentation/values/strings#interpolation См. также: Официальная документация Sass - Интерполяция строк
+/// @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/trimStart См. также: MDN Web Docs - JavaScript метод trimStart()
+/// @example scss - Удаление начальных пробелов
+/// 	@debug string-trim-start('  hello');      // "hello"
+/// 	@debug string-trim-start('   world');     // "world"
+/// 	@debug string-trim-start('  test  ');     // "test  " (конечные пробелы сохраняются)
+/// @example scss - Строки без начальных пробелов
+/// 	@debug string-trim-start('hello');        // "hello"
+/// 	@debug string-trim-start('hello  ');      // "hello  "
+/// 	@debug string-trim-start('');             // ""
+/// @example scss - Граничные случаи
+/// 	@debug string-trim-start('   ');          // "" (только пробелы)
+/// 	@debug string-trim-start(' a b ');        // "a b " (сохраняет внутренние и конечные пробелы)
+/// 	@debug string-trim-start('  hello world'); // "hello world"
+/// @example scss - Сравнение с полным trim
+/// 	@debug string-trim-start('  text  ');     // "text  "
+/// 	@debug string-trim('  text  ');           // "text" (удаляет и конечные пробелы)
+/// @param {String} $string - Строка, из которой нужно удалить
+/// 	начальные пробелы.
+/// @return {String} - Возвращает новую строку, в которой удалены
+/// 	все пробелы с начала оригинальной строки.
+/// 	Если строка состоит только из пробелов, возвращается пустая строка.
+/// @throws {Error} - Не выбрасывает ошибок. Если передано нестроковое
+/// 	значение, функция может вернуть неожиданный результат или вызвать
+/// 	ошибку выполнения.
+@function string-trim-start($string) {
+
+	@while string.slice($string, 1, 1) == " " {
+		$string: string.slice($string, 2);
+	}
+
+	@return $string;
+
+}

package/modules/utilities/helpers/string/_string-trim.scss

@@ -0,0 +1,69 @@
+@use 'sass:string';
+
+/// Удаляет пробелы с начала и конца строки.
+///
+/// Функция последовательно проверяет и удаляет пробелы с начала
+/// строки, затем с конца строки, пока не встретит непробельный
+/// символ.
+///
+/// Возвращает строку без начальных и конечных пробелов.
+///
+/// Важные особенности функции:
+/// - Использует циклы `@while` для последовательного удаления пробелов
+/// - Проверяет первый и последний символы строки на равенство пробелу
+/// - Использует `string.slice()` для создания подстрок без пробелов
+/// - Удаляет только пробелы (символ " "), не удаляет другие whitespace-символы
+/// - Сохраняет оригинальные пробелы внутри строки
+/// ---
+/// @name string-trim
+/// @group utilities-helpers
+/// @since 2026.01.03
+/// @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/strings См. также: Официальная документация Sass - Тип данных "Строки"
+/// @link https://sass-lang.com/documentation/modules/string#slice См. также: Официальная документация Sass - Функция string.slice()
+/// @link https://sass-lang.com/documentation/at-rules/control См. также: Официальная документация Sass - Управляющие директивы
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/string_value См. также: MDN Web Docs - CSS-тип <string>
+/// @link https://sass-lang.com/documentation/values/strings#interpolation См. также: Официальная документация Sass - Интерполяция строк
+/// @link https://sass-lang.com/documentation/values/strings#quotes См. также: Официальная документация Sass - Кавычки в строках
+/// @example scss - Удаление пробелов с обеих сторон
+/// 	@debug string-trim('  hello  ');      // "hello"
+/// 	@debug string-trim('   test   ');     // "test"
+/// 	@debug string-trim('  multiple words  '); // "multiple words"
+/// @example scss - Только начальные или конечные пробелы
+/// 	@debug string-trim('  leading');      // "leading"
+/// 	@debug string-trim('trailing  ');     // "trailing"
+/// 	@debug string-trim('  both  ');       // "both"
+/// @example scss - Строки без внешних пробелов
+/// 	@debug string-trim('hello');          // "hello"
+/// 	@debug string-trim('');               // ""
+/// 	@debug string-trim('inner space');    // "inner space"
+/// @example scss - Граничные случаи
+/// 	@debug string-trim('   ');            // "" (только пробелы)
+/// 	@debug string-trim(' a ');            // "a" (один символ с пробелами)
+/// 	@debug string-trim('  a b  ');        // "a b" (внутренние пробелы сохраняются)
+/// @param {String} $string - Строка, из которой нужно удалить
+/// 	начальные и конечные пробелы.
+/// @return {String} - Возвращает новую строку, в которой удалены
+/// 	все пробелы с начала и конца оригинальной строки.
+/// 	Если строка состоит только из пробелов, возвращается пустая строка.
+/// @throws {Error} - Не выбрасывает ошибок. Если передано нестроковое
+/// 	значение, функция может вернуть неожиданный результат или вызвать
+/// 	ошибку выполнения.
+@function string-trim($string) {
+
+	// Убираем пробелы в начале
+	@while string.slice($string, 1, 1) == " " {
+		$string: string.slice($string, 2);
+	}
+
+	// Убираем пробелы в конце
+	@while string.slice($string, -1) == " " {
+		$string: string.slice($string, 1, -2);
+	}
+
+	@return $string;
+
+}

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

@@ -0,0 +1,151 @@
+@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

@@ -0,0 +1,151 @@
+@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/modules/utilities/setters/_index.scss

@@ -0,0 +1,3 @@
+////
+/// @group utilities-setters
+////

package/modules/utilities/validators/color/_is-color-light.scss

@@ -0,0 +1,132 @@
+@use 'sass:color';
+
+/// Определяет, является ли цвет светлым (по пороговому
+/// значению светлоты).
+///
+/// Функция `is-color-light()` анализирует цвет и возвращает
+/// `true`, если его светлота (lightness в HSL) превышает
+/// заданный порог. Это особенно полезно для автоматического
+/// выбора контрастного цвета текста, создания доступных
+/// интерфейсов или применения стилей в зависимости от тона
+/// фонового цвета.
+/// ---
+/// @name is-color-light
+/// @group utilities-validators
+/// @since 2026.01.03
+/// @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/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 - Смена цвета текста для разных фонов
+/// @link https://css-tricks.com/8-digit-hex-codes/ См. также: CSS-Tricks - Цвета с альфа-каналом в HEX
+/// @example scss - Пример использования
+/// 	$primary: #3498db;
+/// 	$dark-bg: #2c3e50;
+/// 	$light-bg: #ecf0f1;
+///
+/// 	// Автоматический выбор цвета текста
+/// 	.card {
+/// 		&--dark {
+/// 			background-color: $dark-bg;
+/// 			color: if(is-color-light($dark-bg), #000, #fff); // белый текст
+/// 		}
+///
+/// 		&--light {
+/// 			background-color: $light-bg;
+/// 			color: if(is-color-light($light-bg), #000, #fff); // черный текст
+/// 		}
+/// 	}
+///
+/// 	// Динамическое изменение стиля с порогом по умолчанию (50%)
+/// 	.badge {
+/// 		background-color: $primary;
+///
+/// 		@if is-color-light($primary) {
+/// 			border: 1px solid color.scale($primary, $lightness: -20%)
+/// 		} @else {
+/// 			border: 1px solid color.adjust($primary, $lightness: -20%)
+/// 		}
+/// 	}
+///
+/// 	// Использование кастомного порога
+/// 	.notification {
+/// 		background-color: #777; // средне-серый
+///
+/// 		@if is-color-light(#777, 60%) {
+/// 			// Этот код не выполнится, т.к. светлота #777 около 46%
+/// 			color: #222;
+/// 		} @else {
+/// 			color: #eee;
+/// 		}
+/// 	}
+/// @example css - Результат
+/// 	.card--dark {
+/// 		background-color: #2c3e50;
+/// 		color: #fff;
+/// 	}
+/// 	.card--light {
+/// 		background-color: #ecf0f1;
+/// 		color: #000;
+/// 	}
+///
+/// 	.badge {
+/// 		background-color: #4d4d4d;
+/// 		border: 1px solid #1a1a1a;
+/// 	}
+///
+/// 	.notification {
+/// 		background-color: #777;
+/// 		color: #eee;
+/// 	}
+/// @example scss - Пример использования (`@debug`)
+/// 	// Основные цвета
+/// 	@debug is-color-light(#ffffff); // true (100% lightness)
+/// 	@debug is-color-light(#000000); // false (0% lightness)
+///
+/// 	// Серые оттенки - lightness равна примерно процентному значению в HEX
+/// 	@debug is-color-light(#f8f9fa); // true (~98% lightness)
+/// 	@debug is-color-light(#cccccc); // true (~80% lightness)
+/// 	@debug is-color-light(#888888); // true (~53% lightness) - это ключевая ошибка!
+/// 	@debug is-color-light(#808080); // true (ровно 50% lightness) - не false!
+/// 	@debug is-color-light(#777777); // false (~47% lightness)
+/// 	@debug is-color-light(#333333); // false (~20% lightness)
+///
+/// 	// Именованные цвета - реальные значения lightnes
+/// 	@debug is-color-light(white);    // true (100%)
+/// 	@debug is-color-light(black);    // false (0%)
+/// 	@debug is-color-light(red);      // true (50%) - по умолчанию true!
+/// 	@debug is-color-light(lime);     // true (100%)
+/// 	@debug is-color-light(yellow);   // true (97%)
+/// 	@debug is-color-light(blue);     // false (50%) - по умолчанию false!
+/// 	@debug is-color-light(green);    // false (50%) - по умолчанию false!
+/// 	@debug is-color-light(purple);   // false (50%) - по умолчанию false!
+///
+/// 	// Цвета с использованием различных форматов
+/// 	@debug is-color-light(rgb(128, 128, 128)); // true (50% lightness)
+/// 	@debug is-color-light(rgba(127, 127, 127, 0.5)); // false (49.8% lightness)
+/// 	@debug is-color-light(hsl(0, 100%, 50%));  // true (50% lightness - красный)
+/// 	@debug is-color-light(hsl(240, 100%, 50%)); // false (50% lightness - синий)
+///
+/// 	// С кастомным порогом
+/// 	@debug is-color-light(#aaaaaa, 60%); // true (67% lightness)
+/// 	@debug is-color-light(#aaaaaa, 70%); // false (67% lightness < 70%)
+/// 	@debug is-color-light(#444444, 40%); // false (27% lightness)
+/// 	@debug is-color-light(#444444, 20%); // true (27% lightness > 20%)
+/// @param {Color} $color - Цвет для проверки. Может быть в
+/// 	любом формате, который поддерживает Sass (HEX, RGB,
+/// 	HSL, имя цвета).
+/// @param {Number} $threshold [50] - Пороговое значение
+/// 	светлоты в процентах (0% - 100%). По умолчанию
+/// 	используется значение 50%, которое является
+/// 	общепринятым разделением между светлыми и темными
+/// 	тонами. Можно изменить для тонкой настройки.
+/// @return {Boolean} - Возвращает `true`, если светлота
+/// 	цвета больше порогового значения, и `false` в противном
+/// 	случае.
+@function is-color-light($color, $threshold: 50) {
+	@return color.channel($color, "lightness", $space: hsl) > $threshold;
+}