@omnisass/library 0.4.0 → 0.5.0

package/modules/utilities/helpers/number/_number-fibonacci.scss

@@ -218,9 +218,10 @@
 /// - Второй элемент: всегда 1 (если `$n > 1`)
 /// - Каждый последующий элемент: сумма двух предыдущих
 /// - Все элементы: целые положительные числа
-/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
-/// 	значение, не соответствующее типу `number`. Компиляция Sass
-/// 	будет остановлена с ошибкой.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$n` → `number`
 @function number-fibonacci($n) {
 
 	// Проверка типа входного параметра: ожидается числовое значение.

package/modules/utilities/helpers/number/_number-floor-to.scss

@@ -110,9 +110,11 @@
 /// 	измерения исходного числа `$value`.
 /// @throws {Error} - Может выбросить ошибку если происходит
 /// 	деление на ноль.
-/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
-/// 	значение, не соответствующее типу `number`. Компиляция Sass
-/// 	будет остановлена с ошибкой.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$value` → `number`
+/// - `$nearest` → `number`
 @function number-floor-to($value, $nearest) {
 
 	// Проверка типа первого параметра: ожидается числовое значение.

package/modules/utilities/helpers/number/_number-format-with-separator.scss

@@ -96,10 +96,11 @@
 /// 	часть исходного числа игнорируется.
 /// @throws {Error} - Может выбросить ошибку если `$value`
 /// 	не является числом или если `$separator` не является строкой.
-/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
-/// 	значение, не соответствующее типу `number (`$value`) или
-/// 	`string` (`$separator`). Компиляция Sass будет остановлена
-/// 	с ошибкой.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$value` → `number`
+/// - `$separator` → `string`
 @function number-format-with-separator($value, $separator: ",") {
 
 	// Проверка типа первого параметра: ожидается числовое значение.

package/modules/utilities/helpers/number/_number-normalize.scss

@@ -157,9 +157,12 @@
 /// @throws {Error} - Может выбросить ошибку деления на ноль, если
 /// 	`$value-min == $value-max`. В этом случае знаменатель формулы становится
 /// 	нулем, что приводит к математической неопределенности.
-/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
-/// 	значение, не соответствующее типу `number`. Компиляция Sass
-/// 	будет остановлена с ошибкой.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$value` → `number`
+/// - `$value-min` → `number`
+/// - `$value-max` → `number`
 @function number-normalize($value, $value-min, $value-max) {
 
 	// Проверка типа первого параметра: ожидается числовое значение.

package/modules/utilities/helpers/number/_number-random-between-int.scss

@@ -78,9 +78,11 @@
 ///   Должно быть больше или равно `$value-min` для корректных результатов.
 /// @return {Number} - Случайное целое число в диапазоне [`$value-min`, `$value-max`].
 ///   Всегда возвращает целое число без единиц измерения.
-/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
-/// 	значение, не соответствующее типу `number`. Компиляция Sass
-/// 	будет остановлена с ошибкой.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$value-min` → `number`
+/// - `$value-max` → `number`
 /// @throws {Warning} - При `$value-max < $value-min` результат
 /// 	может быть неожиданным.
 @function number-random-between-int($value-min, $value-max) {

package/modules/utilities/helpers/number/_number-random-between.scss

@@ -117,9 +117,11 @@
 /// 	быть неожиданным (возможны отрицательные значения длины
 /// 	диапазона). Рекомендуется всегда передавать
 /// 	`$value-min ≤ $value-max`.
-/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
-/// 	значение, не соответствующее типу `number`. Компиляция Sass
-/// 	будет остановлена с ошибкой.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$value-min` → `number`
+/// - `$value-max` → `number`
 @function number-random-between($value-min, $value-max) {
 
 	// Проверка типа первого параметра: ожидается числовое значение

package/modules/utilities/helpers/number/_number-range.scss

@@ -244,9 +244,12 @@
 ///   - Последний элемент: ближайшее к `$end` значение, кратное шагу
 ///   - Все элементы: равномерно распределены с шагом `$step`
 ///   - Направление: соответствует соотношению `$start` и `$end`
-/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
-/// 	значение, не соответствующее типу `number`. Компиляция Sass
-/// 	будет остановлена с ошибкой.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$from` → `number`
+/// - `$to` → `number`
+/// - `$step` → `number`
 @function number-range($from, $to, $step: 1) {
 
 	// Проверка типа первого параметра: ожидается числовое значение

package/modules/utilities/helpers/number/_number-round-to-nearest.scss

@@ -128,9 +128,11 @@
 /// @throws {Error} - Может выбросить ошибку если `$value` или
 /// 	`$nearest` не являются числами, или если происходит
 /// 	деление на ноль.
-/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
-/// 	значение, не соответствующее типу `number`. Компиляция Sass
-/// 	будет остановлена с ошибкой.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$value` → `number`
+/// - `$nearest` → `number`
 @function number-round-to-nearest($value, $nearest) {
 
 	// Проверка типа первого параметра: ожидается числовое значение.

package/modules/utilities/helpers/number/_number-round-to.scss

@@ -111,9 +111,11 @@
 /// @throws {Error} - Может выбросить ошибку если `$precision`
 /// 	не является целым неотрицательным числом или если
 /// 	`$value` не является числом.
-/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
-/// 	значение, не соответствующее типу `number`. Компиляция Sass
-/// 	будет остановлена с ошибкой.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$value` → `number`
+/// - `$precision` → `number`
 @function number-round-to($value, $precision: 2) {
 
 	// Проверка типа первого параметра: ожидается числовое значение.

package/modules/utilities/helpers/number/_number-strip-unit.scss

@@ -79,9 +79,10 @@
 /// @return {Number} - Безразмерное числовое значение, равное
 /// 	числовой части входного значения. Если входное значение
 /// 	уже было безразмерным, возвращается то же самое значение.
-/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
-/// 	значение, не соответствующее типу `number`. Компиляция Sass
-/// 	будет остановлена с ошибкой.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$value` → `number`
 @function number-strip-unit($value) {
 
 	// Проверка типа входного параметра: ожидается числовое значение.

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

@@ -74,9 +74,10 @@
 /// 	первый символ преобразован в верхний регистр, а все
 /// 	остальные символы остаются без изменений. Для пустой
 /// 	строки возвращает пустую строку.
-/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
-/// 	значение, не соответствующее типу `string`. Компиляция Sass
-/// 	будет остановлена с ошибкой.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$string` → `string`
 @function string-capitalize($string) {
 
 	// Проверка типа входного параметра: ожидается строковое значение.

package/modules/utilities/helpers/string/_string-lorips.config.scss

@@ -39,8 +39,6 @@
 /// @link https://loremipsum.io/generator/ См. также: Lorem Ipsum - Генератор с настройками
 /// @link https://www.lipsum.com/feed/html См. также: Lipsum.com - Генератор HTML Lorem Ipsum
 /// @link https://github.com/sass/sass/issues/2871 См. также: GitHub - Обсуждение текстовых утилит в Sass
-/// @see string-lorips - Функция для генерации текста-
-///   заполнителя на основе этого набора слов.
 /// @type List
 $set-lorem-ipsum-words: "lorem"
                         "ipsum"

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

@@ -58,9 +58,12 @@
 /// 	`$replaceable` не найдена, возвращается оригинальная строка.
 /// @throws {Error} - Может вызвать ошибку глубины рекурсии при очень
 /// 	длинных строках с множественными заменами.
-/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
-/// 	значение, не соответствующее типу `string`. Компиляция Sass
-/// 	будет остановлена с ошибкой.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$string` → `string`
+/// - `$replaceable` → `string`
+/// - `$replacement` → `string`
 @function string-replace($string, $replaceable, $replacement: '') {
 
 	// Проверка типа первого параметра: ожидается исходная строка.

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

@@ -50,9 +50,10 @@
 /// @return {String} - Возвращает новую строку, в которой удалены
 /// 	все пробелы с конца оригинальной строки.
 /// 	Если строка состоит только из пробелов, возвращается пустая строка.
-/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
-/// 	значение, не соответствующее типу `string`. Компиляция Sass
-/// 	будет остановлена с ошибкой.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$string` → `string`
 @function string-trim-end($string) {
 
 	// Проверка типа входного параметра: ожидается строковое значение.

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

@@ -50,9 +50,10 @@
 /// @return {String} - Возвращает новую строку, в которой удалены
 /// 	все пробелы с начала оригинальной строки.
 /// 	Если строка состоит только из пробелов, возвращается пустая строка.
-/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
-/// 	значение, не соответствующее типу `string`. Компиляция Sass
-/// 	будет остановлена с ошибкой.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$string` → `string`
 @function string-trim-start($string) {
 
 	// Проверка типа входного параметра: ожидается строковое значение.

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

@@ -51,9 +51,10 @@
 /// @return {String} - Возвращает новую строку, в которой удалены
 /// 	все пробелы с начала и конца оригинальной строки.
 /// 	Если строка состоит только из пробелов, возвращается пустая строка.
-/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
-/// 	значение, не соответствующее типу `string`. Компиляция Sass
-/// 	будет остановлена с ошибкой.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$string` → `string`
 @function string-trim($string) {
 
 	// Проверка типа входного параметра: ожидается строковое значение.

package/modules/utilities/loggers/_log.scss

@@ -0,0 +1,219 @@
+@use 'sass:map';
+@use '../../../package' as package;
+@use '../../../configs' as libconfigs;
+@use './log-invalid-value' as *;
+
+/// Универсальная функция логирования с поддержкой
+/// локализации и трёх уровней важности.
+///
+/// Функция предоставляет единый интерфейс для вывода
+/// отладочной информации, предупреждений и ошибок в
+/// процессе компиляции Sass-кода.
+///
+/// Поддерживает два языка (русский и английский), что
+/// делает её неплохим решением для многоязычных
+/// проектов и библиотек, распространяемых среди
+/// разработчиков из разных стран (если они у проекта
+/// будут вообще).
+///
+/// Сообщения для логирования передаются в виде карты
+/// с ключами 'ru' и 'en', что позволяет гибко
+/// управлять контентом без изменения кода функции.
+///
+/// Функция автоматически определяет язык сообщения на 4
+/// основе глобальной конфигурации проекта
+/// (`$set-loglang`). Если язык установлен как
+/// 'en' — используется англоязычное сообщение, во
+/// всех остальных случаях  — русскоязычное. Это
+/// обеспечивает обратную совместимость и
+/// предсказуемое поведение.
+///
+/// В зависимости от переданного типа логирования (`$type`)
+/// функция использует разные директивы Sass:
+/// - `debug` — выводит сообщение синим цветом через `@debug`
+/// - `warn` — выводит предупреждение жёлтым цветом через `@warn`
+/// - `error` — выбрасывает критическую ошибку красным цветом
+/// 	через `@error`, которая останавливает компиляцию
+///
+/// Если передан неподдерживаемый тип логирования, функция
+/// делегирует обработку ошибки вспомогательной функции
+/// `log-invalid-value`, которая сгенерирует соответствующее
+/// сообщение о недопустимом значении параметра.
+///
+/// Функция всегда возвращает `null`, что позволяет использовать
+/// её в выражениях, не влияя на возвращаемые значения других
+/// функций, но при этом гарантируя выполнение побочного эффекта
+/// (вывод сообщения в консоль).
+/// ---
+/// @name log
+/// @group utilities-loggers
+/// @since 2026.03.18
+/// @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/at-rules/debug См. также: Официальная документация Sass - Директива @debug
+/// @link https://sass-lang.com/documentation/at-rules/warn См. также: Официальная документация Sass - Директива @warn
+/// @link https://sass-lang.com/documentation/at-rules/error См. также: Официальная документация Sass - Директива @error
+/// @link https://sass-lang.com/documentation/values/maps См. также: Официальная документация Sass - Тип данных "Карты" (`maps`)
+/// @link https://sass-lang.com/documentation/modules/map#get См. также: Официальная документация Sass - Функция `map.get()`
+/// @link https://developer.mozilla.org/en-US/docs/Web/API/console См. также: MDN Web Docs - Консоль браузера (console)
+/// @link https://developer.mozilla.org/en-US/docs/Web/API/console/debug См. также: MDN Web Docs - console.debug()
+/// @link https://developer.mozilla.org/en-US/docs/Web/API/console/warn См. также: MDN Web Docs - console.warn()
+/// @link https://developer.mozilla.org/en-US/docs/Web/API/console/error См. также: MDN Web Docs - console.error()
+/// @link https://sass-guidelin.es/ru/#debugging См. также: Sass Guidelines - Отладка и логирование
+/// @link https://css-tricks.com/debugging-sass/ См. также: CSS-Tricks - Отладка Sass
+/// @link https://www.sitepoint.com/sass-basics-debug-warn-error/ См. также: SitePoint - Основы Sass: @debug, @warn и @error
+/// @link https://dev.to/kennethlum/using-sass-s-map-for-logging-2c1d См. также: Dev.to - Использование карт Sass для логирования
+/// @link https://stackoverflow.com/questions/20333659/sass-debug-warnings-and-errors См. также: Stack Overflow - Отладка, предупреждения и ошибки в Sass
+/// @link https://habr.com/ru/post/449342/ См. также: Habr - Sass: @debug, @warn, @error для отладки
+/// @link https://www.youtube.com/watch?v=9G2TlF1j6sM См. также: YouTube - Отладка Sass с помощью @debug и @warn
+/// @link https://www.npmjs.com/package/sass См. также: npm - Документация пакета Dart Sass
+/// @link https://github.com/sass/sass/tree/main/spec См. также: GitHub - Спецификация языка Sass
+/// @link https://en.wikipedia.org/wiki/Log_level См. также: Wikipedia - Уровни логирования
+/// @link https://www.atatus.com/blog/log-levels-explained/ См. также: Atatus Blog - Объяснение уровней логирования
+/// @link https://www.marshall.edu/at/wp-content/uploads/AT-Logging-Levels-Explained.pdf См. также: Marshall University - Уровни логирования (PDF)
+/// @link https://www.w3.org/TR/css3-color/ См. также: W3C - Спецификация CSS Color Module
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/color См. также: MDN Web Docs - CSS свойство color
+/// @example scss - Базовая отладка на разных языках
+///   // Конфигурация: libconfigs.$set-loglang: 'ru'
+///   $message-ru: (
+///     ru: 'Начало компиляции темы',
+///     en: 'Theme compilation started'
+///   );
+///   @debug log($message-ru); // 🟦 Начало компиляции темы
+///
+///   // Конфигурация: libconfigs.$set-loglang: 'en'
+///   @debug log($message-ru); // 🟦 Theme compilation started
+///
+/// @example scss - Использование в миксине с предупреждением
+///   @mixin deprecated($old-name, $new-name) {
+///     $warning: (
+///       ru: 'Миксин #{$old-name} устарел. Используйте #{$new-name}',
+///       en: 'Mixin #{$old-name} is deprecated. Use #{$new-name} instead'
+///     );
+///     @debug log($warning, 'warn');
+///     @content;
+///   }
+///
+///   @include deprecated('border-radius-old', 'border-radius') {
+///     border-radius: 4px;
+///   }
+///
+/// @example scss - Сложное сообщение с динамическими данными
+///   @function validate-color($color, $context) {
+///     @if type-of($color) != 'color' {
+///       $message: (
+///         ru: 'В контексте "#{$context}" передано невалидное значение цвета: #{$color}',
+///         en: 'Invalid color value "#{$color}" passed in context: #{$context}'
+///       );
+///       @return log($message, 'error');
+///     }
+///     @return $color;
+///   }
+///
+///   $primary: validate-color(#ff0000, 'theme'); // нормально
+///   $primary: validate-color('red', 'theme');   // 🟥 Invalid color value...
+///
+/// @example scss - Неподдерживаемый тип логирования
+///   $message: (
+///     ru: 'Тестовое сообщение',
+///     en: 'Test message'
+///   );
+///   @debug log($message, 'invalid-type'); // вызовет log-invalid-value
+///
+/// @param {Map} $message-map - Карта с сообщениями для разных языков.
+///   Должна содержать ключи 'ru' и 'en' со строковыми значениями.
+///   Пример: `(ru: 'Привет', en: 'Hello')`.
+/// @param {String} $type ['debug'] - Тип логирования.
+///   Поддерживаемые значения: 'debug', 'warn', 'error'.
+///   По умолчанию используется 'debug'.
+/// @return {Null} - Всегда возвращает `null`. Это позволяет
+///   использовать функцию в выражениях, где ожидается возврат
+///   значения, но при этом необходим побочный эффект в виде
+///   вывода сообщения в консоль.
+/// @throws {Error} - Выбрасывает ошибку через директиву `@error`,
+///   если передан тип `'error'`. Ошибка содержит локализованное
+///   сообщение из карты с префиксом в виде красного квадрата.
+/// @throws {Warning} - Выводит предупреждение через директиву
+///   `@warn`, если передан тип `'warn'`. Предупреждение содержит
+///   локализованное сообщение с префиксом в виде жёлтого квадрата.
+/// @require {variable} $set-loglang - Глобальная переменная,
+/// 	определяющая язык сообщений. Поддерживает значения `'ru'`
+/// 	(русский) и другие (английский).
+@function log(
+	$message-map,
+	$type: 'debug') {
+
+	// Получаем язык сообщений из глобальной конфигурации.
+	// Поддерживаются два режима: 'ru' (русский) и
+	// 'en' — английский.
+	$-loglang: libconfigs.$set-loglang;
+
+	// Переменная для хранения финального сообщения
+	// после выбора языка.
+	$-log-message: null;
+
+	// Выбираем сообщение в зависимости от языка.
+	// Если язык 'en' — используем английский текст из карты,
+	// для всех остальных случаев — русский.
+	@if $-loglang == 'en' {
+
+		// Извлекаем английскую версию сообщения из карты.
+		// Ключ 'en' должен присутствовать в карте обязательно.
+		$-log-message: map.get($message-map, en);
+
+	} @else {
+
+		// Извлекаем русскую версию сообщения из карты.
+		// Ключ 'ru' должен присутствовать в карте обязательно.
+		$-log-message: map.get($message-map, ru);
+
+	}
+
+	// Отображаем в консоли название и версию библиотеки.
+	@debug '⬛ #{package.$title} v#{package.$version} (#{package.$package})';
+
+	// Обрабатываем тип логирования и выводим сообщение
+	// соответствующим способом.
+	@if $type == 'debug' {
+
+		// Отладочное сообщение — не останавливает компиляцию,
+		// выводится только при включённом режиме отладки.
+		// Синий квадрат используется для визуального отличия.
+		@debug '🟦 #{$-log-message}';
+
+	} @else if $type == 'warn' {
+
+		// Предупреждение — не останавливает компиляцию,
+		// но выводится всегда, показывая потенциальные проблемы.
+		// Жёлтый квадрат привлекает внимание к предупреждению.
+		@warn '🟨 #{$-log-message}';
+
+	} @else if $type == 'error' {
+
+		// Критическая ошибка — ПОЛНОСТЬЮ ОСТАНАВЛИВАЕТ компиляцию.
+		// Красный квадрат сигнализирует о серьёзной проблеме.
+		@error '🟥 #{$-log-message}';
+
+	} @else {
+
+		// Если передан неподдерживаемый тип логирования,
+		// делегируем обработку ошибки вспомогательной функции.
+		// log-invalid-value сгенерирует сообщение о том,
+		// какие типы логирования допустимы.
+		@return log-invalid-value(
+			'log',
+			$type,
+			'$type',
+			('debug', 'warn', 'error')
+		);
+
+	}
+
+	// Функция всегда возвращает null, чтобы не влиять
+	// на возвращаемые значения вызывающих функций,
+	// но при этом гарантировать выполнение побочного эффекта.
+	@return null;
+
+}