@omnisass/library 0.2.1 → 0.4.0

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

@@ -1,4 +1,6 @@
 @use 'sass:list';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-number' as *;
 
 /// Генерирует последовательность чисел в заданном диапазоне
 /// с определенным шагом.
@@ -242,27 +244,118 @@
 ///   - Последний элемент: ближайшее к `$end` значение, кратное шагу
 ///   - Все элементы: равномерно распределены с шагом `$step`
 ///   - Направление: соответствует соотношению `$start` и `$end`
+/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
+/// 	значение, не соответствующее типу `number`. Компиляция Sass
+/// 	будет остановлена с ошибкой.
 @function number-range($from, $to, $step: 1) {
-	$-result: ();
 
-	@if $from < $to {
-		@for $i from $from through $to {
-			@if ($i - $from) % $step == 0 {
+	// Проверка типа первого параметра: ожидается числовое значение
+	// начальной точки диапазона. $from определяет начальное значение
+	// для генерации последовательности чисел.
+	@if not is-number($from) {
 
-				$-result: list.append($-result, $i);
+		// Если $from не является числом, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные вычисления с нечисловыми данными.
+		@return log-invalid-type(
+			'number-range',
+			$from,
+			'$from',
+			'number'
+		);
+
+	}
+
+	// Проверка типа второго параметра: ожидается числовое значение
+	// конечной точки диапазона. $to определяет конечное значение
+	// для генерации последовательности чисел.
+	@else if not is-number($to) {
+
+		// Если $to не является числом, возвращаем ошибку.
+		// Проверка выполняется только если $from прошел валидацию.
+		@return log-invalid-type(
+			'number-range',
+			$to,
+			'$to',
+			'number'
+		);
+
+	}
+
+	// Проверка типа третьего параметра: ожидается числовое значение
+	// шага последовательности. $step определяет интервал между
+	// числами в генерируемой последовательности.
+	@else if not is-number($step) {
+
+		// Если $step не является числом, возвращаем ошибку.
+		// Проверка выполняется только если $from и $to
+		// прошли валидацию.
+		@return log-invalid-type(
+			'number-range',
+			$step,
+			'$step',
+			'number'
+		);
+
+	}
+
+	// Все параметры прошли валидацию - генерируем числовую последовательность.
+	@else {
+
+		// Инициализация переменной для хранения результата.
+		// $-result будет содержать список чисел в указанном диапазоне
+		// с заданным шагом.
+		$-result: ();
+
+		// Проверка направления диапазона: восходящая последовательность.
+		// Если начальное значение меньше конечного, генерируем числа
+		// от меньшего к большему.
+		@if $from < $to {
+
+			// Цикл по всем числам от $from до $to включительно.
+			// Переменная $i принимает значения от $from до $to.
+			@for $i from $from through $to {
+
+				// Проверка: соответствует ли текущее число шагу последовательности.
+				// Условие ($i - $from) % $step == 0 проверяет, что разница
+				// между текущим числом и начальным значением кратна шагу.
+				@if ($i - $from) % $step == 0 {
+
+					// Если число соответствует шагу, добавляем его в результат.
+					// Функция list.append() добавляет число в конец списка.
+					$-result: list.append($-result, $i);
+
+				}
 
 			}
-		}
-	} @else {
-		@for $i from $from through $to {
-			@if ($from - $i) % $step == 0 {
 
-				$-result: list.append($-result, $i);
+		} @else {
+
+			// Нисходящая последовательность.
+			// Если начальное значение больше или равно конечному,
+			// генерируем числа от большего к меньшему.
+			@for $i from $from through $to {
+
+				// Проверка: соответствует ли текущее число шагу последовательности
+				// для нисходящего направления.
+				// Условие ($from - $i) % $step == 0 проверяет, что разница
+				// между начальным значением и текущим числом кратна шагу.
+				@if ($from - $i) % $step == 0 {
+
+					// Если число соответствует шагу, добавляем его в результат.
+					$-result: list.append($-result, $i);
+
+				}
 
 			}
+
 		}
-	}
 
-	@return $-result;
+		// Возвращаем список чисел в указанном диапазоне с заданным шагом.
+		// Последовательность включает начальное и конечное значения,
+		// если они соответствуют шагу.
+		@return $-result;
+
+	}
 
 }

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

@@ -1,4 +1,6 @@
 @use 'sass:math';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-number' as *;
 
 /// Округляет число до ближайшего кратного значения с
 /// использованием стандартного математического округления
@@ -126,6 +128,61 @@
 /// @throws {Error} - Может выбросить ошибку если `$value` или
 /// 	`$nearest` не являются числами, или если происходит
 /// 	деление на ноль.
+/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
+/// 	значение, не соответствующее типу `number`. Компиляция Sass
+/// 	будет остановлена с ошибкой.
 @function number-round-to-nearest($value, $nearest) {
-	@return math.round(math.div($value, $nearest)) * $nearest;
+
+	// Проверка типа первого параметра: ожидается числовое значение.
+	// Функция is-number() проверяет, является ли $value числом.
+	// Это может быть целое число, дробное число или число с единицами измерения.
+	@if not is-number($value) {
+
+		// Если $value не является числом, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные вычисления с нечисловыми данными.
+		@return log-invalid-type(
+			'number-round-to-nearest',
+			$value,
+			'$value',
+			'number'
+		);
+
+	}
+
+	// Проверка типа второго параметра: ожидается числовое значение
+	// для шага округления. $nearest определяет, до какого ближайшего
+	// кратного значения нужно округлить исходное число.
+	@else if not is-number($nearest) {
+
+		// Если $nearest не является числом, возвращаем ошибку.
+		// Проверка выполняется только если $value прошел валидацию.
+		@return log-invalid-type(
+			'number-round-to-nearest',
+			$nearest,
+			'$nearest',
+			'number'
+		);
+
+	}
+
+	// Все параметры прошли валидацию - выполняем округление к ближайшему.
+	@else {
+
+		// Формула округления к ближайшему кратному значению:
+		// 1. math.div($value, $nearest) - делим исходное значение на шаг округления
+		// 2. math.round() - округляем результат деления к ближайшему целому
+		//    (использует математическое округление: .5 округляется вверх)
+		// 3. * $nearest - умножаем округленное целое на шаг округления
+		//
+		// Математическая формула:
+		// result = round(value / nearest) × nearest
+		//
+		// Ключевая особенность: функция округляет значение к ближайшему
+		// кратному с использованием математического округления,
+		// где .5 всегда округляется вверх.
+		@return math.round(math.div($value, $nearest)) * $nearest;
+
+	}
+
 }

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

@@ -1,4 +1,6 @@
 @use 'sass:math';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-number' as *;
 
 /// Округляет число до указанного количества знаков после
 /// запятой.
@@ -109,10 +111,71 @@
 /// @throws {Error} - Может выбросить ошибку если `$precision`
 /// 	не является целым неотрицательным числом или если
 /// 	`$value` не является числом.
+/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
+/// 	значение, не соответствующее типу `number`. Компиляция Sass
+/// 	будет остановлена с ошибкой.
 @function number-round-to($value, $precision: 2) {
 
-	$-multiplier: math.pow(10, $precision);
+	// Проверка типа первого параметра: ожидается числовое значение.
+	// Функция is-number() проверяет, является ли $value числом.
+	// Это может быть целое число, дробное число или число с единицами измерения.
+	@if not is-number($value) {
 
-	@return math.div(math.round($value * $-multiplier), $-multiplier);
+		// Если $value не является числом, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные вычисления с нечисловыми данными.
+		@return log-invalid-type(
+			'number-round-to',
+			$value,
+			'$value',
+			'number'
+		);
+
+	}
+
+	// Проверка типа второго параметра: ожидается числовое значение
+	// для точности округления. $precision определяет количество
+	// знаков после запятой в результате округления.
+	@else if not is-number($precision) {
+
+		// Если $precision не является числом, возвращаем ошибку.
+		// Проверка выполняется только если $value прошел валидацию.
+		@return log-invalid-type(
+			'number-round-to',
+			$precision,
+			'$precision',
+			'number'
+		);
+
+	}
+
+	// Все параметры прошли валидацию - выполняем округление с заданной точностью.
+	@else {
+
+		// Вычисление множителя для округления.
+		// math.pow(10, $precision) возводит 10 в степень $precision,
+		// создавая множитель для перемещения нужного количества
+		// знаков после запятой в целую часть числа.
+		// Пример: при $precision = 2 → множитель = 100
+		$-multiplier: math.pow(10, $precision);
+
+		// Формула округления с заданной точностью:
+		// 1. $value * $-multiplier - умножаем значение на множитель,
+		//    чтобы переместить нужное количество знаков после запятой
+		//    в целую часть (например, 3.14159 × 100 = 314.159)
+		// 2. math.round(...) - округляем результат к ближайшему целому
+		//    (314.159 → 314)
+		// 3. math.div(..., $-multiplier) - делим обратно на множитель,
+		//    чтобы вернуть десятичную точку на исходное место (314 → 3.14)
+		//
+		// Математическая формула:
+		// result = round(value × 10^precision) ÷ 10^precision
+		//
+		// Ключевая особенность: функция округляет значение до указанного
+		// количества знаков после запятой с использованием математического
+		// округления, где .5 всегда округляется вверх.
+		@return math.div(math.round($value * $-multiplier), $-multiplier);
+
+	}
 
 }

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

@@ -79,19 +79,53 @@
 /// @return {Number} - Безразмерное числовое значение, равное
 /// 	числовой части входного значения. Если входное значение
 /// 	уже было безразмерным, возвращается то же самое значение.
-/// @throws {Error} - Может выбросить ошибку, если передано
-/// 	нечисловое значение, так как математические операции
-/// 	Sass требуют числовых операндов.
+/// @throws {Error} - Выбрасывает ошибку, если в параметры передано
+/// 	значение, не соответствующее типу `number`. Компиляция Sass
+/// 	будет остановлена с ошибкой.
 @function number-strip-unit($value) {
 
-	$-result: 'null';
+	// Проверка типа входного параметра: ожидается числовое значение.
+	// Функция is-number() проверяет, является ли $value числом.
+	// Это может быть целое число, дробное число или число с единицами измерения.
+	@if not is-number($value) {
+
+		// Если $value не является числом, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные вычисления с нечисловыми данными.
+		@return log-invalid-type(
+			'number-strip-unit',
+			$value,
+			'$value',
+			'number'
+		);
 
-	@if is-number($value) {
-		$-result: math.div($value, $value * 0 + 1);
-	} @else {
-		@debug log-invalid-type('number-strip-unit', $value, '$value', 'number');
 	}
 
-	@return $-result;
+	// Основная логика выполняется только если $value является
+	// корректным числом.
+	@else {
+
+		// Формула удаления единиц измерения из числа:
+		// Используем математический трюк для конвертации числа
+		// в безразмерное значение.
+		//
+		// Алгоритм вычислений:
+		// 1. $value * 0 + 1 - создаем безразмерное число 1:
+		//    - $value * 0 = 0 с теми же единицами измерения, что и $value
+		//    - 0 + 1 = 1 без единиц измерения (единицы теряются при сложении
+		//      с безразмерным числом)
+		// 2. math.div($value, ...) - делим исходное значение на безразмерную 1
+		//    Деление числа с единицами измерения на безразмерное число
+		//    удаляет единицы измерения, сохраняя числовое значение.
+		//
+		// Математическая формула:
+		// result = value ÷ (value × 0 + 1)
+		//
+		// Ключевая особенность: этот метод корректно работает с любыми
+		// единицами измерения (px, rem, em, %, и т.д.) и всегда возвращает
+		// безразмерное числовое значение.
+		@return math.div($value, $value * 0 + 1);
+
+	}
 
 }

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-count.scss

@@ -0,0 +1,173 @@
+@use 'sass:string';
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-string' as *;
+
+/// Подсчитывает количество вхождений подстроки в строку.
+///
+/// Функция принимает строку и подстроку, затем возвращает
+/// количество непересекающихся вхождений подстроки в строку.
+/// Поиск чувствителен к регистру и выполняется слева направо.
+/// Это полезно для анализа текста, подсчета символов или слов,
+/// проверки частоты встречаемости определенных паттернов в
+/// строковых данных.
+///
+/// Важные особенности функции:
+/// - Выполняет регистрозависимый поиск подстроки
+/// - Подсчитывает только непересекающиеся вхождения
+/// - Выполняет строгую проверку типов обоих параметров
+/// - Использует цикл while для последовательного поиска
+/// - Возвращает 0, если подстрока не найдена ни разу
+/// - Работает с любыми строками, включая пустые
+/// - Обрабатывает Unicode-символы и многосимвольные подстроки
+/// - Полезна для текстового анализа и статистики
+/// - Может использоваться для подсчета слов или символов
+/// - Подходит для валидации форматов строк
+/// - Эффективна для строк средней длины
+/// - Для пустой подстроки всегда возвращает 0 (поскольку
+///   поиск пустой строки в Sass возвращает null)
+/// - Функция использует алгоритм последовательного поиска
+///   через `string.index()` и усечение строки после каждого
+///   найденного вхождения
+/// - Для длинных строк и часто встречающихся подстрок
+///   производительность может снижаться из-за многократного
+///   вызова `string.slice()`
+/// - Поиск чувствителен к регистру: "Hello" и "hello"
+///   считаются разными подстроками
+/// - Функция корректно обрабатывает многосимвольные
+///   подстроки и Unicode-последовательности
+/// ---
+/// @name string-count
+/// @group utilities-helpers
+/// @since 2026.01.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/modules/string См. также: Официальная документация Sass - Модуль String
+/// @link https://sass-lang.com/documentation/values/strings См. также: Официальная документация Sass - Тип данных "Строки"
+/// @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String См. также: MDN Web Docs - Объект String
+/// @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/includes См. также: MDN Web Docs - Метод String.includes()
+/// @link https://en.wikipedia.org/wiki/String_(computer_science) См. также: Wikipedia - Строка (информатика)
+/// @link https://en.wikipedia.org/wiki/Substring См. также: Wikipedia - Подстрока
+/// @link https://css-tricks.com/snippets/sass/string-count-function/ См. также: CSS-Tricks - Функция подсчета подстрок в Sass
+/// @link https://css-tricks.com/sass-string-manipulation-functions/ См. также: CSS-Tricks - Функции для работы со строками в Sass
+/// @link https://sass-guidelin.es/ru/#section-44 См. также: Sass Guidelines - Раздел про функции
+/// @link https://github.com/sass/sass/issues/1402 См. также: GitHub - Обсуждение строковых операций в Sass
+/// @link https://www.30secondsofcode.org/sass/p/1/string-count См. также: 30 seconds of code - Функция string-count
+/// @example scss - Подсчет одиночных символов
+/// 	@debug string-count("hello", "l");      // 2
+/// 	@debug string-count("banana", "a");     // 3
+/// 	@debug string-count("test", "t");       // 2
+/// 	@debug string-count("abc", "z");        // 0
+/// 	@debug string-count("", "a");           // 0
+/// 	@debug string-count("aaa", "aa");       // 1 (непересекающиеся)
+/// @example scss - Подсчет многосимвольных подстрок
+/// 	@debug string-count("hello world", "lo");      // 1
+/// 	@debug string-count("test test test", "test"); // 3
+/// 	@debug string-count("ababab", "ab");           // 3
+/// 	@debug string-count("one two one", "one");     // 2
+/// 	@debug string-count("hello hello", "hello");   // 2
+/// @example scss - Регистрозависимый поиск
+/// 	@debug string-count("Hello World", "hello");   // 0
+/// 	@debug string-count("Hello World", "Hello");   // 1
+/// 	@debug string-count("ABC abc ABC", "ABC");     // 2
+/// 	@debug string-count("Test test", "test");      // 1
+/// @example scss - Граничные случаи
+/// 	@debug string-count("aaaa", "aa");       // 2
+/// 	@debug string-count("aaaaa", "aa");      // 2
+/// 	@debug string-count("a", "a");           // 1
+/// 	@debug string-count("abc", "");          // 0
+/// 	@debug string-count("", "");             // 0
+/// @param {String} $string - Исходная строка, в которой
+///   выполняется поиск. Может быть любой строкой: пустой,
+///   односимвольной, содержащей пробелы, Unicode-символы
+///   или специальные символы.
+/// @param {String} $substring - Подстрока, количество
+///   вхождений которой нужно подсчитать. Может быть любой
+///   строкой, включая пустую, односимвольную или
+///   многосимвольную. Поиск регистрозависимый.
+/// @return {Number} - Целое неотрицательное число,
+///   представляющее количество непересекающихся вхождений
+///   подстроки `$substring` в строку `$string`.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр
+///   передано значение, не соответствующее необходимому типу:
+///
+///   - `$string` → `string`
+///   - `$substring` → `string`
+@function string-count($string, $substring) {
+
+	// Проверка типа первого параметра: ожидается строковое значение.
+	// Исходная строка должна быть строкой для выполнения поиска
+	// подстроки с помощью функции string.index().
+	@if not is-string($string) or $string == '' {
+
+		// Если $string не является строкой, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные операции с нестроковыми типами данных.
+		@return log-invalid-type(
+			'string-count',
+			$string,
+			'$string',
+			'string'
+		);
+
+	}
+
+	// Проверка типа второго параметра: ожидается строковое значение.
+	// Подстрока также должна быть строкой, так как string.index()
+	// работает только со строковыми аргументами.
+	@else if not is-string($substring) or $substring == '' {
+
+		// Если $substring не является строкой, возвращаем ошибку.
+		// Проверка выполняется только если $string прошел валидацию.
+		@return log-invalid-type(
+			'string-count',
+			$substring,
+			'$substring',
+			'string'
+		);
+
+	}
+
+	// Все параметры прошли валидацию - подсчитываем вхождения.
+	@else {
+
+		// Инициализация счетчика вхождений.
+		// Начальное значение 0 соответствует случаю, когда подстрока
+		// не найдена ни разу.
+		$-count: 0;
+
+		// Поиск первого вхождения подстроки в строку.
+		// string.index() возвращает позицию первого вхождения
+		// подстроки или null, если подстрока не найдена.
+		$-index: string.index($string, $substring);
+
+		// Цикл поиска всех вхождений подстроки.
+		// Цикл продолжается, пока находятся новые вхождения
+		// подстроки ($-index != null).
+		@while $-index != null {
+
+			// Увеличение счетчика найденных вхождений.
+			// Каждое найденное вхождение увеличивает счетчик на 1.
+			$-count: $-count + 1;
+
+			// Усечение строки после найденного вхождения.
+			// Новая строка начинается с символа, следующего за
+			// концом найденной подстроки, чтобы исключить
+			// пересекающиеся вхождения.
+			$string: string.slice($string, $-index + string.length($substring));
+
+			// Поиск следующего вхождения подстроки в усеченной строке.
+			// Если подстрока найдена снова, цикл продолжится,
+			// иначе $-index станет null, и цикл завершится.
+			$-index: string.index($string, $substring);
+
+		}
+
+		// Возвращаем общее количество найденных вхождений.
+		// Если подстрока не была найдена ни разу, $-count останется 0.
+		@return $-count;
+
+	}
+
+}