@omnisass/library 0.2.1 → 0.4.0

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) + ".";
+
+	}
+
+}

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

@@ -0,0 +1,147 @@
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-string' as *;
+@use '../../validators/type-of/is-number' as *;
+
+/// Повторяет строку указанное количество раз.
+///
+/// Функция создает новую строку путем конкатенации исходной
+/// строки с собой заданное количество раз. Это полезно для
+/// генерации повторяющихся паттернов, заполнителей, рамок
+/// или любых других конструкций, требующих дублирования
+/// строковых элементов.
+///
+/// Важные особенности функции:
+/// - Выполняет строгую проверку типов обоих параметров
+/// - Возвращает пустую строку при нулевом количестве повторов
+/// - Обрабатывает целые положительные числа повторений
+/// - Использует эффективный цикл для построения результата
+/// - Сохраняет исходную строку без изменений
+/// - Полезна для создания визуальных разделителей
+/// - Может использоваться для генерации тестовых данных
+/// - Подходит для построения ASCII-графики или рамок
+/// - Обеспечивает детерминированный результат
+/// - Совместима с многострочными строками и Unicode
+/// - Функция использует простой цикл `for` для
+///   конкатенации строк. Для большого количества повторов
+///   (>1000) производительность может снижаться.
+/// - Для работы с очень большими строками или
+///   количеством повторов рекомендуется использовать
+///   рекурсивную реализацию или мемоизацию.
+/// ---
+/// @name string-repeat
+/// @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://sass-lang.com/documentation/values/numbers См. также: Официальная документация Sass - Тип данных "Числа"
+/// @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/repeat См. также: MDN Web Docs - Метод String.repeat()
+/// @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/concat См. также: MDN Web Docs - Метод String.concat()
+/// @link https://en.wikipedia.org/wiki/String_(computer_science)#Concatenation См. также: Wikipedia - Конкатенация строк
+/// @link https://en.wikipedia.org/wiki/Iteration См. также: Wikipedia - Итерация (программирование)
+/// @link https://css-tricks.com/snippets/sass/string-repetition-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-repeat См. также: 30 seconds of code - Функция string-repeat
+/// @example scss - Базовое повторение строк
+/// 	@debug string-repeat('a', 5);       // "aaaaa"
+/// 	@debug string-repeat('ab', 3);      // "ababab"
+/// 	@debug string-repeat('test', 2);    // "testtest"
+/// 	@debug string-repeat('', 10);       // ""
+/// @example scss - Создание разделителей и рамок
+/// 	@debug string-repeat('-', 20);      // "--------------------"
+/// 	@debug string-repeat('* ', 10);     // "* * * * * * * * * * "
+/// 	@debug string-repeat('=-', 8);      // "-=-=-=-=-=-=-=-=-=-="
+/// 	@debug string-repeat('▮', 5);       // "▮▮▮▮▮"
+/// @example scss - Граничные случаи
+/// 	@debug string-repeat('abc', 0);     // ""
+/// 	@debug string-repeat('abc', 1);     // "abc"
+/// 	@debug string-repeat(' ', 10);      // "          "
+/// 	@debug string-repeat('\n', 3);      // "nnn"
+/// @param {String} $string - Исходная строка для повторения.
+///   Может быть любой строкой, включая пустую строку,
+///   многострочные строки, строки с пробелами и Unicode-
+///   символами. Каждое повторение будет точной копией
+///   исходной строки.
+/// @param {Number} $repetitions - Количество повторений
+///   строки. Должно быть целым неотрицательным числом.
+///   При значении 0 возвращается пустая строка. При
+///   значении 1 возвращается исходная строка без изменений.
+/// @return {String} - Новая строка, состоящая из исходной
+///   строки, повторенной указанное количество раз. Если
+///   $repetitions равно 0, возвращается пустая строка.
+///   Если $repetitions равно 1, возвращается исходная
+///   строка. Для отрицательных чисел поведение не определено.
+/// @throws {Error} - Выбрасывает ошибку, если в параметр передано
+/// 	значение, не соответствующее необходимому типу:
+///
+/// - `$string` → `string`
+/// - `$repetitions` → `number`
+@function string-repeat($string, $repetitions) {
+
+	// Проверка типа первого параметра: ожидается строковое значение.
+	// Функция предназначена для повторения именно строк, так как
+	// операция конкатенации определена только для строковых значений.
+	@if not is-string($string) {
+
+		// Если $string не является строкой, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// попытки конкатенации нестроковых значений.
+		@return log-invalid-type(
+			'string-repeat',
+			$string,
+			'$string',
+			'string'
+		);
+
+	}
+
+	// Проверка типа второго параметра: ожидается числовое значение.
+	// Количество повторений должно быть числом, чтобы можно было
+	// использовать его в цикле for.
+	@else if not is-number($repetitions) {
+
+		// Если $repetitions не является числом, возвращаем ошибку.
+		// Проверка выполняется только если $string прошел валидацию.
+		@return log-invalid-type(
+			'string-repeat',
+			$repetitions,
+			'$repetitions',
+			'number'
+		);
+
+	}
+
+	// Все параметры прошли валидацию - выполняем повторение строки.
+	@else {
+
+		// Инициализация переменной результата.
+		// Начальное значение null позволяет начать конкатенацию
+		// с первой итерации цикла без специальной обработки.
+		$-result: null;
+
+		// Цикл повторения строки заданное количество раз.
+		// Цикл выполняется от 1 до $repetitions включительно.
+		// Каждая итерация добавляет исходную строку к результату.
+		@for $i from 1 through $repetitions {
+
+			// Конкатенация текущего результата с исходной строкой.
+			// При первой итерации $-result равен null, что приводит
+			// к начальному значению, равному $string.
+			$-result: $-result + $string;
+
+		}
+
+		// Возвращаем итоговую строку после всех повторений.
+		// Если $repetitions было 0, цикл не выполнится ни разу,
+		// и функция вернет null, который в контексте строки
+		// преобразуется в пустую строку.
+		@return $-result;
+
+	}
+
+}

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