@omnisass/library 0.3.0 → 0.4.1

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-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;
+
+	}
+
+}

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

@@ -0,0 +1,81 @@
+/// Глобальная переменная с набором слов Lorem Ipsum.
+///
+/// Список содержит 35 стандартных слов классического текста-
+/// заполнителя Lorem Ipsum в нижнем регистре. Переменная
+/// используется функциями для генерации текста-заполнителя
+/// и может быть переопределена для использования кастомного
+/// набора слов или другого языка.
+///
+/// - Переменная объявлена с флагом `!default`, что
+///   позволяет переопределить ее в проекте перед импортом
+///   библиотеки. Это полезно для локализации или
+///   использования кастомного набора слов.
+/// - Для генерации корректного текста-заполнителя
+///   рекомендуется использовать функции, которые учитывают
+///   капитализацию первого слова и добавление пунктуации.
+/// - Многострочное форматирование списка улучшает
+///   читаемость кода, но не влияет на содержимое переменной.
+///   Каждое слово находится на отдельной строке для удобства
+///   просмотра и редактирования.
+/// - Все слова приведены к нижнему регистру.
+///   Функции, использующие эту переменную, должны сами
+///   заботиться о капитализации при необходимости.
+/// ---
+/// @name set-lorem-ipsum-words
+/// @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/values/lists См. также: Официальная документация Sass - Тип данных "Списки"
+/// @link https://sass-lang.com/documentation/values/strings См. также: Официальная документация Sass - Тип данных "Строки"
+/// @link https://en.wikipedia.org/wiki/Lorem_ipsum См. также: Wikipedia - Lorem ipsum
+/// @link https://en.wikipedia.org/wiki/Latin См. также: Wikipedia - Латинский язык
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/content См. также: MDN Web Docs - CSS свойство content
+/// @link https://css-tricks.com/snippets/sass/lorem-ipsum-generator/ См. также: CSS-Tricks - Генератор Lorem Ipsum на Sass
+/// @link https://css-tricks.com/design-systems-with-sass-placeholders/ См. также: CSS-Tricks - Дизайн-системы с заполнителями
+/// @link https://sass-guidelin.es/ru/#section-23 См. также: Sass Guidelines - Раздел про переменные
+/// @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"
+                        "dolor"
+                        "sit"
+                        "amet"
+                        "consectetur"
+                        "adipiscing"
+                        "elit"
+                        "sed"
+                        "do"
+                        "eiusmod"
+                        "tempor"
+                        "incididunt"
+                        "ut"
+                        "labore"
+                        "et"
+                        "dolore"
+                        "magna"
+                        "aliqua"
+                        "ut"
+                        "enim"
+                        "ad"
+                        "minim"
+                        "veniam"
+                        "quis"
+                        "nostrud"
+                        "exercitation"
+                        "ullamco"
+                        "laboris"
+                        "nisi"
+                        "ut"
+                        "aliquip"
+                        "ex"
+                        "ea"
+                        "commodo"
+                        "consequat"
+                        !default;

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

@@ -0,0 +1,198 @@
+@forward './string-lorips.config';
+
+@use 'sass:list';
+@use './string-capitalize' as *;
+@use './string-lorips.config' as configs;
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-list' as *;
+@use '../../validators/type-of/is-number' as *;
+
+/// Генерирует текст-заполнитель на основе указанного списка слов.
+///
+/// Функция создает текст-заполнитель указанной длины (в словах)
+/// путем циклического повторения слов из предоставленного списка.
+/// По умолчанию используется классический набор слов Lorem Ipsum.
+/// Результат автоматически капитализируется (первая буква становится
+/// заглавной) и завершается точкой для грамматической корректности.
+///
+/// Важные особенности функции:
+/// - Поддерживает кастомные списки слов через параметр `$words-list`
+/// - Использует классический набор слов Lorem Ipsum по умолчанию
+/// - Поддерживает указание произвольного количества слов
+/// - Автоматически циклически повторяет слова при превышении длины списка
+/// - Капитализирует первую букву результата
+/// - Добавляет завершающую точку для грамматической правильности
+/// - Разделяет слова одиночными пробелами
+/// - Выполняет строгую проверку типов входных параметров
+/// - Возвращает строку, готовую к использованию как текст-заполнитель
+/// - Полезна для создания макетов, прототипов и тестирования типографики
+/// - Обеспечивает единообразный заполнитель во всем проекте
+/// - Позволяет легко локализовать текст-заполнитель
+/// - Сохраняет детерминированность результата
+/// - Функция использует циклический доступ к словам.
+///   При запросе количества слов, превышающего длину списка,
+///   последовательность начинается заново с первого слова.
+///   Это реализовано через операцию модуля (%).
+/// - Все слова в списке должны быть в нижнем регистре
+///   для корректной работы функции `string-capitalize()`.
+///   Капитализация применяется только к первой букве
+///   итоговой строки.
+/// - При передаче пустого списка и ненулевого значения
+///   `$word-count` произойдет ошибка при попытке обращения к
+///   `list.nth()` с индексом. Рекомендуется проверять список
+///   на пустоту в вызывающем коде.
+/// - Функция не проверяет, являются ли все элементы
+///   списка строками. Передача списка с нестроковыми
+///   элементами может привести к непредсказуемому поведению.
+/// ---
+/// @name string-lorips
+/// @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/modules/list См. также: Официальная документация Sass - Модуль List
+/// @link https://sass-lang.com/documentation/values/strings См. также: Официальная документация Sass - Тип данных "Строки"
+/// @link https://en.wikipedia.org/wiki/Lorem_ipsum См. также: Wikipedia - Lorem ipsum
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/content См. также: MDN Web Docs - CSS свойство content
+/// @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/repeat См. также: MDN Web Docs - Метод String.repeat()
+/// @link https://css-tricks.com/snippets/sass/lorem-ipsum-generator/ См. также: CSS-Tricks - Генератор Lorem Ipsum на Sass
+/// @link https://css-tricks.com/design-systems-with-sass-placeholders/ См. также: CSS-Tricks - Дизайн-системы с заполнителями
+/// @link https://sass-guidelin.es/ru/#section-44 См. также: Sass Guidelines - Раздел про функции
+/// @link https://loremipsum.io/ См. также: Lorem Ipsum - Генератор текста-заполнителя
+/// @link https://www.lipsum.com/ См. также: Lipsum.com - Классический генератор Lorem Ipsum
+/// @link https://github.com/sass/sass/issues/2871 См. также: GitHub - Обсуждение текстовых утилит в Sass
+/// @link https://www.30secondsofcode.org/sass/p/1/string-repeat См. также: 30 seconds of code - Функция string-repeat
+/// @example scss - Генерация текста с набором по умолчанию
+/// 	@debug string-lorips(5);        // "Lorem ipsum dolor sit amet."
+/// 	@debug string-lorips(10);       // "Lorem ipsum dolor sit amet consectetur adipiscing elit sed do."
+/// 	@debug string-lorips(3);        // "Lorem ipsum dolor."
+/// 	@debug string-lorips(1);        // "Lorem."
+/// 	@debug string-lorips();         // "Lorem ipsum dolor sit amet consectetur adipiscing elit sed do."
+/// @example scss - Генерация длинного текста (циклическое повторение)
+/// 	@debug string-lorips(15);       // "Lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor incididunt ut labore."
+/// 	@debug string-lorips(20);       // "Lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor incididunt ut labore et dolore magna aliqua ut."
+/// 	@debug string-lorips(40);       // "Lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor incididunt ut labore et dolore magna aliqua ut enim ad minim veniam quis nostrud exercitation ullamco laboris nisi ut."
+/// @example scss - Использование кастомного списка слов
+/// 	$my-words: "hello" "world" "test" "example";
+/// 	@debug string-lorips(5, $my-words);   // "Hello world test example hello."
+/// 	@debug string-lorips(3, $my-words);   // "Hello world test."
+/// 	@debug string-lorips(7, $my-words);   // "Hello world test example hello world test."
+/// @example scss - Граничные случаи
+/// 	@debug string-lorips(0, ());    // Error: $n: calc(NaN) is not an int.
+/// 	@debug string-lorips(5, ("single",));  // "Single single single single single."
+/// @param {Number} $word-count [10] - Количество слов в
+///   генерируемом тексте. Должно быть целым неотрицательным
+///   числом. При значении 0 возвращается только точка.
+///   При значении 1 возвращается одно слово с точкой.
+///   Значение по умолчанию - 10 слов.
+/// @param {List} $words-list [configs.$set-lorem-ipsum-words] -
+///   Список слов для генерации текста. По умолчанию используется
+///   глобальная переменная с классическим набором слов
+///   Lorem Ipsum. Может быть передан любой список строк
+///   (слов), которые будут использоваться циклически.
+///   При пустом списке и ненулевом $word-count будет ошибка
+///   выполнения при обращении к list.nth().
+/// @return {String} - Текст-заполнитель указанной длины,
+///   начинающийся с заглавной буквы и заканчивающийся точкой.
+///   Если запрошено больше слов, чем в списке, набор слов
+///   циклически повторяется с начала списка.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$word-count` → `number`
+/// - `$words-list` → `list`
+@function string-lorips($word-count: 10, $words-list: configs.$set-lorem-ipsum-words) {
+
+	// Проверка типа первого параметра: ожидается числовое значение.
+	// Количество слов должно быть числом для использования в цикле
+	// и математических операциях с модулем.
+	@if not is-number($word-count) {
+
+		// Если $word-count не является числом, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные операции с нечисловыми типами данных.
+		@return log-invalid-type(
+			'string-lorips',
+			$word-count,
+			'$word-count',
+			'number'
+		);
+
+	}
+
+	// Проверка типа второго параметра: ожидается список (list).
+	// Список слов должен быть именно типом list для работы с
+	// функциями list.length() и list.nth().
+	@if not is-list($words-list) {
+
+		// Если $words-list не является списком, возвращаем ошибку.
+		// Проверка выполняется только если $word-count прошел валидацию.
+		@return log-invalid-type(
+			'string-lorips',
+			$words-list,
+			'$words-list',
+			'list'
+		);
+
+	}
+
+	// Все параметры прошли валидацию - генерируем текст-заполнитель.
+	@else {
+
+		// Использование предоставленного списка слов.
+		// Локальная переменная создается для удобства работы
+		// и лучшей читаемости кода.
+		$-words: $words-list;
+
+		// Инициализация переменной результата.
+		// Начальное значение null позволяет начать конкатенацию
+		// с первого слова без специальной обработки первого элемента.
+		$-result: null;
+
+		// Цикл генерации указанного количества слов.
+		// Цикл выполняется от 1 до $word-count включительно.
+		// Каждая итерация добавляет очередное слово из списка.
+		@for $i from 1 through $word-count {
+
+			// Вычисление индекса текущего слова в списке.
+			// Формула ($i - 1) % list.length($-words) + 1 обеспечивает:
+			// 1. Циклический доступ к словам при превышении длины списка
+			// 2. Корректную индексацию (от 1 до длины списка)
+			// 3. Последовательное прохождение по всему списку
+			$-word-index: ($i - 1) % list.length($-words) + 1;
+
+			// Получение слова по вычисленному индексу.
+			// list.nth() возвращает элемент списка по заданной позиции.
+			// Если список пустой и $word-count > 0, здесь будет ошибка.
+			$-word: list.nth($-words, $-word-index);
+
+			// Добавление слова к результату.
+			// Конкатенация накапливает слова в итоговой строке.
+			// При первой итерации $-result равен null, что приводит
+			// к начальному значению, равному $-word.
+			$-result: $-result + $-word;
+
+			// Добавление пробела после слова, если это не последнее слово.
+			// Условие $i != $word-count проверяет, не достигли ли мы
+			// запрошенного количества слов, чтобы не добавлять лишний пробел
+			// в конце строки перед точкой.
+			@if $i != $word-count {
+				$-result: $-result + " ";
+			}
+
+		}
+
+		// Возвращаем отформатированный результат.
+		// string-capitalize() делает первую букву заглавной,
+		// а добавление точки завершает предложение.
+		// Если $word-count = 0, $-result будет null, что после
+		// string-capitalize() станет пустой строкой, и результат
+		// будет просто ".".
+		@return string-capitalize($-result) + ".";
+
+	}
+
+}