@omnisass/library 0.2.1 → 0.3.0

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

@@ -1,4 +1,6 @@
 @use 'sass:string';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-string' as *;
 
 /// Преобразует первый символ строки в верхний регистр, остальные
 /// оставляет без изменений.
@@ -72,13 +74,52 @@
 /// 	первый символ преобразован в верхний регистр, а все
 /// 	остальные символы остаются без изменений. Для пустой
 /// 	строки возвращает пустую строку.
-/// @throws Не выбрасывает ошибок, корректно обрабатывает строки
-/// 	любой длины и содержания.
+/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
+/// 	значение, не соответствующее типу `string`. Компиляция Sass
+/// 	будет остановлена с ошибкой.
 @function string-capitalize($string) {
 
-	$-first: string.to-upper-case(string.slice($string, 1, 1));
-	$-rest: string.slice($string, 2);
+	// Проверка типа входного параметра: ожидается строковое значение.
+	// Функция is-string() проверяет, является ли $string строкой
+	// (тип данных string). Строка будет преобразована в формат,
+	// где первый символ становится заглавным.
+	@if not is-string($string) {
 
-	@return $-first + $-rest;
+		// Если $string не является строкой, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные операции преобразования с нестроковыми данными.
+		@return log-invalid-type(
+			'string-capitalize',
+			$string,
+			'$string',
+			'string'
+		);
+
+	}
+
+	// Основная логика выполняется только если $string является
+	// корректной строкой.
+	@else {
+
+		// Извлечение первого символа строки и преобразование его
+		// в верхний регистр.
+		// Алгоритм:
+		// 1. string.slice($string, 1, 1) - извлекает первый символ строки
+		//    (позиции с 1 по 1 включительно)
+		// 2. string.to-upper-case(...) - преобразует символ в верхний регистр
+		$-first: string.to-upper-case(string.slice($string, 1, 1));
+
+		// Извлечение оставшейся части строки (все символы после первого).
+		// string.slice($string, 2) возвращает подстроку, начиная со второго символа
+		// и до конца строки. Если строка состоит из одного символа,
+		// возвращается пустая строка.
+		$-rest: string.slice($string, 2);
+
+		// Соединение заглавного первого символа с оставшейся частью строки.
+		// Результат - строка, где первый символ заглавный, а остальные
+		// символы сохраняют свой исходный регистр.
+		@return $-first + $-rest;
+
+	}
 
 }

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

@@ -1,4 +1,6 @@
 @use 'sass:string';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-string' as *;
 
 /// Заменяет все вхождения подстроки в строке на другую подстроку.
 ///
@@ -56,14 +58,90 @@
 /// 	`$replaceable` не найдена, возвращается оригинальная строка.
 /// @throws {Error} - Может вызвать ошибку глубины рекурсии при очень
 /// 	длинных строках с множественными заменами.
+/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
+/// 	значение, не соответствующее типу `string`. Компиляция Sass
+/// 	будет остановлена с ошибкой.
 @function string-replace($string, $replaceable, $replacement: '') {
 
-	$-index: string.index($string, $replaceable);
+	// Проверка типа первого параметра: ожидается исходная строка.
+	// Функция is-string() проверяет, является ли $string строкой.
+	// В этой строке будут заменяться все вхождения подстроки.
+	@if not is-string($string) {
+
+		// Если $string не является строкой, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные операции замены с нестроковыми данными.
+		@return log-invalid-type(
+			'string-replace',
+			$string,
+			'$string',
+			'string'
+		);
+
+	}
+
+	// Проверка типа второго параметра: ожидается строка для поиска.
+	// $replaceable определяет подстроку, которую нужно найти и заменить.
+	@else if not is-string($replaceable) {
+
+		// Если $replaceable не является строкой, возвращаем ошибку.
+		// Проверка выполняется только если $string прошел валидацию.
+		@return log-invalid-type(
+			'string-replace',
+			$replaceable,
+			'$replaceable',
+			'string'
+		);
+
+	}
+
+	// Проверка типа третьего параметра: ожидается строка-замена.
+	// $replacement определяет подстроку, на которую будет заменено
+	// каждое вхождение $replaceable. По умолчанию - пустая строка.
+	@else if not is-string($replacement) {
+
+		// Если $replacement не является строкой, возвращаем ошибку.
+		// Проверка выполняется только если $string и $replaceable
+		// прошли валидацию.
+		@return log-invalid-type(
+			'string-replace',
+			$replacement,
+			'$replacement',
+			'string'
+		);
 
-	@if $-index {
-		@return string.slice($string, 1, $-index - 1) + $replacement + string-replace(string.slice($string, $-index + string.length($replaceable)), $replaceable, $replacement);
 	}
 
-	@return $string;
+	// Все параметры прошли валидацию - выполняем замену подстрок.
+	@else {
+
+		// Поиск первого вхождения искомой подстроки в исходной строке.
+		// string.index() возвращает позицию первого вхождения $replaceable
+		// в $string или null, если подстрока не найдена.
+		$-index: string.index($string, $replaceable);
+
+		// Проверка: найдено ли хотя бы одно вхождение подстроки.
+		@if $-index {
+
+			// Рекурсивная замена всех вхождений подстроки.
+			// Алгоритм:
+			// 1. string.slice($string, 1, $-index - 1) - часть строки
+			//    до первого вхождения заменяемой подстроки
+			// 2. + $replacement - добавляем строку-замену
+			// 3. + string-replace(string.slice($string, $-index + string.length($replaceable)), ...)
+			//    - рекурсивный вызов функции для оставшейся части строки
+			//      (после первого вхождения заменяемой подстроки)
+			//
+			// Рекурсия продолжается до тех пор, пока в строке
+			// не останется вхождений заменяемой подстроки.
+			@return string.slice($string, 1, $-index - 1) + $replacement + string-replace(string.slice($string, $-index + string.length($replaceable)), $replaceable, $replacement);
+
+		}
+
+		// Если подстрока не найдена, возвращаем исходную строку без изменений.
+		// Это базовый случай рекурсии.
+		@return $string;
+
+	}
 
 }

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

@@ -1,4 +1,6 @@
 @use 'sass:string';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-string' as *;
 
 /// Удаляет пробелы с конца строки (справа).
 ///
@@ -48,15 +50,56 @@
 /// @return {String} - Возвращает новую строку, в которой удалены
 /// 	все пробелы с конца оригинальной строки.
 /// 	Если строка состоит только из пробелов, возвращается пустая строка.
-/// @throws {Error} - Не выбрасывает ошибок. Если передано нестроковое
-/// 	значение, функция может вернуть неожиданный результат или вызвать
-/// 	ошибку выполнения.
+/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
+/// 	значение, не соответствующее типу `string`. Компиляция Sass
+/// 	будет остановлена с ошибкой.
 @function string-trim-end($string) {
 
-	@while string.slice($string, -1) == " " {
-		$string: string.slice($string, 1, -2);
+	// Проверка типа входного параметра: ожидается строковое значение.
+	// Функция is-string() проверяет, является ли $string строкой
+	// (тип данных string). Строка будет обработана для удаления
+	// пробельных символов в конце.
+	@if not is-string($string) {
+
+		// Если $string не является строкой, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные операции обрезки с нестроковыми данными.
+		@return log-invalid-type(
+			'string-trim-end',
+			$string,
+			'$string',
+			'string'
+		);
+
 	}
 
-	@return $string;
+	// Основная логика выполняется только если $string является
+	// корректной строкой.
+	@else {
+
+		// Цикл удаления пробельных символов с конца строки.
+		// Цикл продолжается до тех пор, пока последний символ строки
+		// является пробелом.
+		@while string.slice($string, -1) == " " {
+
+			// Удаление последнего символа из строки.
+			// Алгоритм:
+			// 1. string.slice($string, 1, -2) - создает новую строку,
+			//    которая содержит все символы исходной строки,
+			//    кроме последнего.
+			//    - 1: начальный индекс (первый символ)
+			//    - -2: конечный индекс (предпоследний символ, считая с конца)
+			// 2. Присваивание результата обратно переменной $string
+			//    для следующей итерации цикла.
+			$string: string.slice($string, 1, -2);
+
+		}
+
+		// Возвращаем строку без пробельных символов в конце.
+		// Если в исходной строке не было пробелов в конце,
+		// возвращается оригинальная строка без изменений.
+		@return $string;
+
+	}
 
 }

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

@@ -1,4 +1,6 @@
 @use 'sass:string';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-string' as *;
 
 /// Удаляет пробелы с начала строки (слева).
 ///
@@ -48,15 +50,56 @@
 /// @return {String} - Возвращает новую строку, в которой удалены
 /// 	все пробелы с начала оригинальной строки.
 /// 	Если строка состоит только из пробелов, возвращается пустая строка.
-/// @throws {Error} - Не выбрасывает ошибок. Если передано нестроковое
-/// 	значение, функция может вернуть неожиданный результат или вызвать
-/// 	ошибку выполнения.
+/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
+/// 	значение, не соответствующее типу `string`. Компиляция Sass
+/// 	будет остановлена с ошибкой.
 @function string-trim-start($string) {
 
-	@while string.slice($string, 1, 1) == " " {
-		$string: string.slice($string, 2);
+	// Проверка типа входного параметра: ожидается строковое значение.
+	// Функция is-string() проверяет, является ли $string строкой
+	// (тип данных string). Строка будет обработана для удаления
+	// пробельных символов в начале.
+	@if not is-string($string) {
+
+		// Если $string не является строкой, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные операции обрезки с нестроковыми данными.
+		@return log-invalid-type(
+			'string-trim-start',
+			$string,
+			'$string',
+			'string'
+		);
+
 	}
 
-	@return $string;
+	// Основная логика выполняется только если $string является
+	// корректной строкой.
+	@else {
+
+		// Цикл удаления пробельных символов с начала строки.
+		// Цикл продолжается до тех пор, пока первый символ строки
+		// является пробелом.
+		@while string.slice($string, 1, 1) == " " {
+
+			// Удаление первого символа из строки.
+			// Алгоритм:
+			// 1. string.slice($string, 2) - создает новую строку,
+			//    которая содержит все символы исходной строки,
+			//    начиная со второго символа.
+			//    - 2: начальный индекс (второй символ)
+			//    - Если не указан конечный индекс, берется до конца строки
+			// 2. Присваивание результата обратно переменной $string
+			//    для следующей итерации цикла.
+			$string: string.slice($string, 2);
+
+		}
+
+		// Возвращаем строку без пробельных символов в начале.
+		// Если в исходной строке не было пробелов в начале,
+		// возвращается оригинальная строка без изменений.
+		@return $string;
+
+	}
 
 }

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

@@ -1,4 +1,6 @@
 @use 'sass:string';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-string' as *;
 
 /// Удаляет пробелы с начала и конца строки.
 ///
@@ -49,21 +51,64 @@
 /// @return {String} - Возвращает новую строку, в которой удалены
 /// 	все пробелы с начала и конца оригинальной строки.
 /// 	Если строка состоит только из пробелов, возвращается пустая строка.
-/// @throws {Error} - Не выбрасывает ошибок. Если передано нестроковое
-/// 	значение, функция может вернуть неожиданный результат или вызвать
-/// 	ошибку выполнения.
+/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
+/// 	значение, не соответствующее типу `string`. Компиляция Sass
+/// 	будет остановлена с ошибкой.
 @function string-trim($string) {
 
-	// Убираем пробелы в начале
-	@while string.slice($string, 1, 1) == " " {
-		$string: string.slice($string, 2);
-	}
+	// Проверка типа входного параметра: ожидается строковое значение.
+	// Функция is-string() проверяет, является ли $string строкой
+	// (тип данных string). Строка будет обработана для удаления
+	// пробельных символов с обоих концов.
+	@if not is-string($string) {
+
+		// Если $string не является строкой, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные операции обрезки с нестроковыми данными.
+		@return log-invalid-type(
+			'string-trim',
+			$string,
+			'$string',
+			'string'
+		);
 
-	// Убираем пробелы в конце
-	@while string.slice($string, -1) == " " {
-		$string: string.slice($string, 1, -2);
 	}
 
-	@return $string;
+	// Основная логика выполняется только если $string является
+	// корректной строкой.
+	@else {
+
+		// Удаление пробельных символов с начала строки.
+		// Цикл продолжается до тех пор, пока первый символ строки
+		// является пробелом.
+		@while string.slice($string, 1, 1) == " " {
+
+			// Удаление первого символа из строки.
+			// string.slice($string, 2) создает новую строку,
+			// которая содержит все символы исходной строки,
+			// начиная со второго символа.
+			$string: string.slice($string, 2);
+
+		}
+
+		// Удаление пробельных символов с конца строки.
+		// Цикл продолжается до тех пор, пока последний символ строки
+		// является пробелом.
+		@while string.slice($string, -1) == " " {
+
+			// Удаление последнего символа из строки.
+			// string.slice($string, 1, -2) создает новую строку,
+			// которая содержит все символы исходной строки,
+			// кроме последнего.
+			$string: string.slice($string, 1, -2);
+
+		}
+
+		// Возвращаем строку без пробельных символов в начале и конце.
+		// Если в исходной строке не было пробелов на краях,
+		// возвращается оригинальная строка без изменений.
+		@return $string;
+
+	}
 
 }

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

@@ -111,7 +111,7 @@
 	// Получаем глобальные настройки из конфигурации
 	$-strict-mode: libconfigs.$set-strict-mode; // Режим работы: true = ошибки (строгий), false = предупреждения
 	$-loglang: libconfigs.$set-loglang;         // Язык вывода сообщений
-	$-log-message: '';                          // Текст сообщения об ошибке
+	$-log-message: null;                          // Текст сообщения об ошибке
 
 	// Определяем язык на основе глобальной настройки
 	@if $-loglang != 'ru' {

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

@@ -109,7 +109,7 @@
 	// файла:
 	$-strict-mode: libconfigs.$set-strict-mode; // true = строгий режим (ошибки), false = режим предупреждений
 	$-loglang: libconfigs.$set-loglang;         // язык сообщений ('ru' = русский, любое другое = английский)
-	$-log-message: '';                          // переменная для хранения текста сообщения
+	$-log-message: null;                          // переменная для хранения текста сообщения
 
 	// Если язык НЕ русский, используем английский текст
 	@if $-loglang != 'ru' {

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

@@ -1,4 +1,7 @@
 @use 'sass:color';
+@use '../../loggers/log-invalid-type' as *;
+@use '../type-of/is-color' as *;
+@use '../type-of/is-number' as *;
 
 /// Определяет, является ли цвет светлым (по пороговому
 /// значению светлоты).
@@ -124,9 +127,63 @@
 /// 	используется значение 50%, которое является
 /// 	общепринятым разделением между светлыми и темными
 /// 	тонами. Можно изменить для тонкой настройки.
-/// @return {Boolean} - Возвращает `true`, если светлота
-/// 	цвета больше порогового значения, и `false` в противном
-/// 	случае.
+/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
+/// 	значение, не соответствующее типу `color` ($color) или
+/// 	`number` (`$threshold`). Компиляция Sass будет остановлена
+/// 	с ошибкой.
 @function is-color-light($color, $threshold: 50) {
-	@return color.channel($color, "lightness", $space: hsl) > $threshold;
+
+	// Проверка типа первого параметра: ожидается цветовое значение.
+	// Функция is-color() проверяет, является ли $color валидным цветом CSS.
+	// Цвет будет проанализирован для определения его яркости.
+	@if not is-color($color) {
+
+		// Если $color не является цветом, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные вычисления с нецветовыми данными.
+		@return log-invalid-type(
+			'is-color-light',
+			$color,
+			'$color',
+			'color'
+		);
+
+	}
+
+	// Проверка типа второго параметра: ожидается числовое значение
+	// порога яркости. $threshold определяет граничное значение
+	// яркости (в процентах), выше которой цвет считается светлым.
+	// По умолчанию используется 50%.
+	@else if not is-number($threshold) {
+
+		// Если $threshold не является числом, возвращаем ошибку.
+		// Проверка выполняется только если $color прошел валидацию.
+		@return log-invalid-type(
+			'is-color-light',
+			$threshold,
+			'$threshold',
+			'number'
+		);
+
+	}
+
+	// Все параметры прошли валидацию - определяем, является ли цвет светлым.
+	@else {
+
+		// Логика определения светлоты цвета:
+		// 1. color.channel($color, "lightness", $space: hsl) - извлекает
+		//    значение яркости цвета в пространстве HSL (от 0% до 100%)
+		// 2. ... > $threshold - сравнивает яркость цвета с пороговым значением
+		//
+		// Возвращаемое значение:
+		// - true: если яркость цвета больше порогового значения (цвет светлый)
+		// - false: если яркость цвета меньше или равна пороговому значению
+		//          (цвет темный или нейтральный)
+		//
+		// Ключевая особенность: функция возвращает булево значение (true/false),
+		// которое можно использовать в условных конструкциях @if/@else.
+		@return color.channel($color, "lightness", $space: hsl) > $threshold;
+
+	}
+
 }

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

@@ -1,4 +1,6 @@
-@use '../type-of/is-color' as type-of;
+@use '../../loggers/log-invalid-type' as *;
+@use '../type-of/is-color' as *;
+@use '../type-of/is-list' as *;
 
 /// Проверяет, что все элементы в списке являются цветами.
 ///
@@ -101,24 +103,54 @@
 /// 	в списке являются цветами. Возвращает `false`, если
 /// 	хотя бы один элемент не является цветом. Для пустого
 /// 	списка возвращает `true`.
-/// @throws {Error} - Не выбрасывает ошибок, безопасно
-/// 	обрабатывает любые типы данных.
+/// @throws {Error} - Выбрасывает ошибку, если параметру `$list` передано
+/// 	значение, не соответствующее типу `list`. Компиляция Sass
+/// 	будет остановлена с ошибкой.
 @function is-color-list($list) {
 
-	@each $-item in $list {
+	// Проверка типа входного параметра: ожидается список или arglist.
+	// Функция is-list() проверяет, является ли $list валидным списком
+	// или arglist (специальный тип для переменного числа аргументов).
+	@if not is-list($list) {
 
-		@if not type-of.is-color($-item) {
-			@return false;
-		}
+		// Если $list не является списком, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные проверки с некорректными данными.
+		@return log-invalid-type(
+			'is-color-list',
+			$list,
+			'$list',
+			('list', 'arglist')
+		);
 
 	}
 
-	@return true;
+	// Основная логика выполняется только если $list является
+	// корректным списком или arglist.
+	@else {
 
-}
+		// Итерация по всем элементам списка.
+		// Переменная $-item содержит текущий проверяемый элемент.
+		@each $-item in $list {
+
+			// Проверка: является ли текущий элемент цветом.
+			// Функция is-color() возвращает true для валидных цветов CSS.
+			@if not is-color($-item) {
 
+				// Если хотя бы один элемент не является цветом,
+				// немедленно возвращаем false. Это ранний выход из функции,
+				// который оптимизирует производительность для больших списков.
+				@return false;
 
+			}
 
+		}
 
+		// Если все элементы прошли проверку и являются цветами,
+		// возвращаем true. Эта точка достигается только если цикл
+		// завершился без преждевременного возврата.
+		@return true;
 
+	}
 
+}

package/modules/utilities/validators/list/_is-list-contained.scss

@@ -1,4 +1,6 @@
 @use 'sass:list';
+@use '../../loggers/log-invalid-type' as *;
+@use '../type-of/is-list' as *;
 
 /// Проверяет, содержится ли значение в указанном списке.
 ///
@@ -58,8 +60,45 @@
 /// @param {List} $list - Список, в котором выполняется поиск
 /// @return {Boolean} - Возвращает `true`, если значение
 /// 	найдено в списке, иначе возвращает `false`.
-/// @throws Не выбрасывает ошибок, безопасно работает с
-/// 	любыми списками
+/// @throws {Error} - Выбрасывает ошибку, если параметру `$list` передано
+/// 	значение, не соответствующее типу `list`. Компиляция Sass
+/// 	будет остановлена с ошибкой.
 @function is-list-contained($list, $value) {
-	@return (null != list.index($list, $value));
+
+	// Проверка типа первого параметра: ожидается список или arglist.
+	// Функция is-list() проверяет, является ли $list валидным списком
+	// или arglist (специальный тип для переменного числа аргументов).
+	@if not is-list($list) {
+
+		// Если $list не является списком, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные проверки с некорректными данными.
+		@return log-invalid-type(
+			'is-list-contained',
+			$list,
+			'$list',
+			('list', 'arglist')
+		);
+
+	}
+
+	// Основная логика выполняется только если $list является
+	// корректным списком или arglist.
+	@else {
+
+		// Проверка наличия значения в списке.
+		// Алгоритм:
+		// 1. list.index($list, $value) - ищет первое вхождение значения
+		//    в списке и возвращает его индекс (начиная с 1)
+		//    Если значение не найдено, возвращает null
+		// 2. null != ... - сравниваем результат с null
+		//    - Если результат не равен null → значение найдено → true
+		//    - Если результат равен null → значение не найдено → false
+		//
+		// Ключевая особенность: функция возвращает булево значение (true/false),
+		// указывающее, содержится ли значение хотя бы один раз в списке.
+		@return (null != list.index($list, $value));
+
+	}
+
 }