@omnisass/library 0.2.0

package/modules/utilities/validators/number/_is-number-has-unit.scss

@@ -0,0 +1,85 @@
+@use 'sass:math';
+@use '../type-of/is-number' as type-of;
+
+/// Проверяет, имеет ли число единицы измерения.
+///
+/// Функция выполняет двойную проверку: сначала определяет
+/// тип значения, убеждаясь, что это число (number), затем
+/// проверяет строку единиц измерения, возвращаемую функцией
+/// `math.unit()`. Если эта строка не пуста, значит число
+/// имеет привязанные к нему единицы измерения.
+///
+/// Важные особенности функции:
+/// - Проверяет тип значения с помощью `meta.type-of()`
+/// - Использует встроенную функцию `math.unit()` для получения
+/// 	единиц
+/// - Возвращает `false` для любых нечисловых значений
+/// - Различает безразмерные числа и числа с единицами измерения
+/// - Учитывает все типы единиц измерения CSS (px, rem, em, %,
+/// 	deg и др.)
+/// - Не выполняет неявного преобразования типов
+///
+/// > **Безразмерные числа** (unitless numbers) в Sass — это
+/// > числа, у которых нет единиц измерения. Они представляют
+/// > собой чистые математические значения без привязки к
+/// > каким-либо физическим или относительным единицам.
+/// ---
+/// @name is-number-has-unit
+/// @group utilities-validators
+/// @since 2026.01.03
+/// @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/numbers См. также: Официальная документация Sass - Тип данных "Числа"
+/// @link https://sass-lang.com/documentation/values/numbers#units См. также: Официальная документация Sass - Единицы измерения в числах
+/// @link https://sass-lang.com/documentation/modules/meta#type-of См. также: Официальная документация Sass - Функция type-of()
+/// @link https://sass-lang.com/documentation/modules/math#unit См. также: Официальная документация Sass - Функция math.unit()
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Values_and_Units См. также: MDN Web Docs - CSS значения и единицы измерения
+/// @link https://css-tricks.com/snippets/sass/ См. также: CSS-Tricks - Коллекция сниппетов Sass
+/// @link https://sass-guidelin.es/ru/#section-39 См. также: Sass Guidelines - Раздел про проверку типов
+/// @link https://www.w3schools.com/sass/sass_functions_numeric.php См. также: W3Schools - Числовые функции в Sass
+/// @example scss - Числа с единицами измерения (возвращают true)
+/// 	@debug is-number-has-unit(16px);       // true
+/// 	@debug is-number-has-unit(2.5rem);     // true
+/// 	@debug is-number-has-unit(100%);       // true
+/// 	@debug is-number-has-unit(90deg);      // true
+/// 	@debug is-number-has-unit(1s);         // true
+/// 	@debug is-number-has-unit(96dpi);      // true
+/// 	@debug is-number-has-unit(10vw);       // true
+/// @example scss - Безразмерные числа (возвращают false)
+/// 	@debug is-number-has-unit(16);         // false
+/// 	@debug is-number-has-unit(0);          // false
+/// 	@debug is-number-has-unit(3.14);       // false
+/// 	@debug is-number-has-unit(-5);         // false
+/// 	@debug is-number-has-unit(0.5);        // false
+/// 	@debug is-number-has-unit(1.0);        // false (1.0 считается безразмерным)
+/// @example scss - Граничные случаи
+/// 	@debug is-number-has-unit(0px);        // true (ноль, но с единицами)
+/// 	@debug is-number-has-unit(0%);         // true (ноль, но с единицами)
+/// 	@debug is-number-has-unit(0rem);       // true (ноль, но с единицами)
+/// 	@debug is-number-has-unit(1e-10);      // false (научная нотация без единиц)
+/// 	@debug is-number-has-unit(1.0px);      // true (число с плавающей точкой и единицами)
+/// @example scss - Нечисловые значения (всегда false)
+/// 	@debug is-number-has-unit("16px");     // false
+/// 	@debug is-number-has-unit(#ff0000);    // false
+/// 	@debug is-number-has-unit(true);       // false
+/// 	@debug is-number-has-unit(null);       // false
+/// 	@debug is-number-has-unit(auto);       // false
+/// 	@debug is-number-has-unit((16, px));   // false
+/// @param {*} $value - Значение для проверки. Может быть
+/// 	любого типа, но функция вернет `true` только для
+/// 	чисел, которые имеют единицы измерения. Любые
+/// 	единицы измерения (даже сложные комбинации)
+/// 	приводят к возврату `true`.
+/// @return {Boolean} - Возвращает `true`, если значение
+/// 	является числом и имеет единицы измерения (результат
+/// 	`math.unit($value)` не является пустой строкой).
+/// 	Возвращает `false` для безразмерных чисел и всех
+/// 	нечисловых значений.
+/// @throws {Error} - Не выбрасывает ошибков, безопасно
+/// 	обрабатывает значения любого типа. Функция `math.unit()`
+/// 	безопасно работает с любыми значениями.
+@function is-number-has-unit($value) {
+	@return type-of.is-number($value) and math.unit($value) != '';
+}

package/modules/utilities/validators/number/_is-number-negative.scss

@@ -0,0 +1,76 @@
+@use '../type-of/is-number' as type-of;
+
+/// Проверяет, является ли значение отрицательным числом.
+///
+/// Функция выполняет двойную проверку: сначала определяет тип
+/// значения, убеждаясь, что это число (number), затем
+/// проверяет, меньше ли оно нуля. Если значение не является
+/// числом или является неотрицательным числом, функция
+/// возвращает `false`.
+///
+/// Важные особенности функции:
+/// - Проверяет тип значения с помощью `meta.type-of()`
+/// - Проверяет, что значение строго меньше нуля (оператор <)
+/// - Возвращает false для любых нечисловых значений
+/// - Обрабатывает как целые, так и дробные числа
+/// - Учитывает специфику сравнения чисел с единицами
+/// 	измерения в Sass
+/// - Не выполняет неявного преобразования типов
+/// - Ноль не считается отрицательным числом
+/// ---
+/// @name is-number-negative
+/// @group utilities-validators
+/// @since 2026.01.03
+/// @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/numbers См. также: Официальная документация Sass - Тип данных "Числа"
+/// @link https://sass-lang.com/documentation/modules/meta#type-of См. также: Официальная документация Sass - Функция type-of()
+/// @link https://sass-lang.com/documentation/operators/relational См. также: Официальная документация Sass - Операторы сравнения
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Values_and_Units См. также: MDN Web Docs - CSS значения и единицы измерения
+/// @link https://css-tricks.com/snippets/sass/ См. также: CSS-Tricks - Коллекция сниппетов Sass
+/// @link https://sass-guidelin.es/ru/#section-39 См. также: Sass Guidelines - Раздел про проверку типов
+/// @link https://frontender.info/sass-type-checking/ См. также: Frontender Magazine - Проверка типов в Sass
+/// @link https://www.w3schools.com/sass/sass_functions_numeric.php См. также: W3Schools - Числовые функции в Sass
+/// @link https://habr.com/ru/post/247887/ См. также: Habr - Статья "Sass для верстальщика: числа и математика"
+/// @example scss - Отрицательные числа
+/// 	@debug is-number-negative(-1);         // true
+/// 	@debug is-number-negative(-0.5);       // true
+/// 	@debug is-number-negative(-3.14);      // true
+/// 	@debug is-number-negative(-100);       // true
+/// 	@debug is-number-negative(-1px);       // true (число с единицей измерения)
+/// 	@debug is-number-negative(-0.25rem);   // true (дробное число с единицей)
+/// @example scss - Неотрицательные числа
+/// 	@debug is-number-negative(0);          // false (ноль не является отрицательным)
+/// 	@debug is-number-negative(1);          // false
+/// 	@debug is-number-negative(0.5);        // false
+/// 	@debug is-number-negative(3.14);       // false
+/// 	@debug is-number-negative(10px);       // false (положительное число с единицей)
+/// 	@debug is-number-negative(0rem);       // false (ноль с единицей измерения)
+/// @example scss - Граничные случаи
+/// 	@debug is-number-negative(-0.000001);  // true (любое отрицательное, даже очень близкое к нулю)
+/// 	@debug is-number-negative(-999999);    // true (большие отрицательные числа)
+/// 	@debug is-number-negative(-1.0);       // true (целое число в формате с плавающей точкой)
+/// 	@debug is-number-negative(-5);         // true (явно указанный минус)
+/// 	@debug is-number-negative(-0.0);       // false (отрицательный ноль рассматривается как ноль)
+/// @example scss - Нечисловые значения
+/// 	@debug is-number-negative("-1");       // false
+/// 	@debug is-number-negative(#ff0000);    // false
+/// 	@debug is-number-negative(false);      // false
+/// 	@debug is-number-negative(null);       // false
+/// 	@debug is-number-negative((1, 2, 3));  // false
+/// 	@debug is-number-negative(auto);       // false
+/// @param {*} $value - Значение для проверки. Может быть
+/// 	любого типа, но функция вернет `true` только для
+/// 	чисел строго меньше нуля, включая числа с единицами
+/// 	измерения.
+/// @return {Boolean} - Возвращает `true`, если значение
+/// 	является числом и строго меньше нуля. Во всех
+/// 	остальных случаях возвращает `false`, включая
+/// 	ноль, положительные числа и значения других типов.
+/// @throws {Error} - Не выбрасывает ошибок, безопасно
+/// 	обрабатывает значения любого типа.
+@function is-number-negative($value) {
+  @return type-of.is-number($value) and $value < 0;
+}

package/modules/utilities/validators/number/_is-number-positive.scss

@@ -0,0 +1,74 @@
+@use '../type-of/is-number' as type-of;
+
+/// Проверяет, является ли значение положительным числом.
+///
+/// Функция выполняет двойную проверку: сначала определяет
+/// тип значения, убеждаясь, что это число (number), затем
+/// проверяет, больше ли оно нуля. Если значение не является
+/// числом или является неположительным числом, функция
+/// возвращает `false`.
+///
+/// Важные особенности функции:
+/// - Проверяет тип значения с помощью `meta.type-of()`
+/// - Проверяет, что значение строго больше нуля (оператор >)
+/// - Возвращает false для любых нечисловых значений
+/// - Обрабатывает как целые, так и дробные числа
+/// - Учитывает специфику сравнения чисел с единицами измерения
+/// 	в Sass
+/// - Не выполняет неявного преобразования типов
+/// ---
+/// @name is-number-positive
+/// @group utilities-validators
+/// @since 2026.01.03
+/// @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/numbers См. также: Официальная документация Sass - Тип данных "Числа"
+/// @link https://sass-lang.com/documentation/modules/meta#type-of См. также: Официальная документация Sass - Функция type-of()
+/// @link https://sass-lang.com/documentation/operators/relational См. также: Официальная документация Sass - Операторы сравнения
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Values_and_Units См. также: MDN Web Docs - CSS значения и единицы измерения
+/// @link https://css-tricks.com/snippets/sass/ См. также: CSS-Tricks - Коллекция сниппетов Sass
+/// @link https://sass-guidelin.es/ru/#section-39 См. также: Sass Guidelines - Раздел про проверку типов
+/// @link https://frontender.info/sass-type-checking/ См. также: Frontender Magazine - Проверка типов в Sass
+/// @link https://www.w3schools.com/sass/sass_functions_numeric.php См. также: W3Schools - Числовые функции в Sass
+/// @link https://habr.com/ru/post/247887/ См. также: Habr - Статья "Sass для верстальщика: числа и математика"
+/// @example scss - Положительные числа
+/// 	@debug is-number-positive(1);          // true
+/// 	@debug is-number-positive(0.5);        // true
+/// 	@debug is-number-positive(3.14);       // true
+/// 	@debug is-number-positive(100);        // true
+/// 	@debug is-number-positive(1px);        // true (число с единицей измерения)
+/// 	@debug is-number-positive(0.25rem);    // true (дробное число с единицей)
+/// @example scss - Неположительные числа
+/// 	@debug is-number-positive(0);          // false (ноль не является положительным)
+/// 	@debug is-number-positive(-1);         // false
+/// 	@debug is-number-positive(-0.5);       // false
+/// 	@debug is-number-positive(-3.14);      // false
+/// 	@debug is-number-positive(-10px);      // false (отрицательное число с единицей)
+/// 	@debug is-number-positive(0rem);       // false (ноль с единицей измерения)
+/// @example scss - Граничные случаи
+/// 	@debug is-number-positive(0.000001);   // true (любое положительное, даже очень малое)
+/// 	@debug is-number-positive(999999);     // true (большие положительные числа)
+/// 	@debug is-number-positive(1.0);        // true (целое число в формате с плавающей точкой)
+/// 	@debug is-number-positive(+5);         // true (явно указанный плюс)
+/// @example scss - Нечисловые значения
+/// 	@debug is-number-positive("1");        // false
+/// 	@debug is-number-positive(#ff0000);    // false
+/// 	@debug is-number-positive(true);       // false
+/// 	@debug is-number-positive(null);       // false
+/// 	@debug is-number-positive((1, 2, 3));  // false
+/// 	@debug is-number-positive(auto);       // false
+/// @param {*} $value - Значение для проверки. Может быть
+/// 	любого типа, но функция вернет `true` только для
+/// 	чисел строго больше нуля, включая числа с единицами
+/// 	измерения.
+/// @return {Boolean} - Возвращает `true`, если значение
+/// 	является числом и строго больше нуля. Во всех
+/// 	остальных случаях возвращает `false`, включая
+/// 	ноль, отрицательные числа и значения других типов.
+/// @throws {Error} - Не выбрасывает ошибок, безопасно
+/// 	обрабатывает значения любого типа.
+@function is-number-positive($value) {
+	@return type-of.is-number($value) and $value > 0;
+}

package/modules/utilities/validators/number/_is-number-unitless.scss

@@ -0,0 +1,88 @@
+@use 'sass:math';
+@use '../type-of/is-number' as type-of;
+
+/// Проверяет, является ли число безразмерным.
+///
+/// Функция выполняет двойную проверку: сначала определяет
+/// тип значения, убеждаясь, что это число (number), затем
+/// проверяет строку единиц измерения, возвращаемую функцией
+/// `math.unit()`. Если эта строка пуста, значит число
+/// является безразмерным (не имеет привязанных единиц
+/// измерения).
+///
+/// Важные особенности функции:
+/// - Проверяет тип значения с помощью `meta.type-of()`
+/// - Использует встроенную функцию `math.unit()` для
+/// 	получения единиц
+/// - Возвращает `false` для любых нечисловых значений
+/// - Учитывает все типы единиц измерения CSS (px, rem, em,
+/// 	%, deg и др.)
+/// - Не выполняет неявного преобразования типов
+/// - Логически противоположна функции `is-number-has-unit()`
+/// ---
+/// @name is-number-unitless
+/// @group utilities-validators
+/// @since 2026.01.03
+/// @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/numbers См. также: Официальная документация Sass - Тип данных "Числа"
+/// @link https://sass-lang.com/documentation/values/numbers#units См. также: Официальная документация Sass - Единицы измерения в числах
+/// @link https://sass-lang.com/documentation/modules/meta#type-of См. также: Официальная документация Sass - Функция type-of()
+/// @link https://sass-lang.com/documentation/modules/math#unit См. также: Официальная документация Sass - Функция math.unit()
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Values_and_Units См. также: MDN Web Docs - CSS значения и единицы измерения
+/// @link https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#numbers См. также: MDN Web Docs - Числа и единицы измерения
+/// @link https://css-tricks.com/snippets/sass/ См. также: CSS-Tricks - Коллекция сниппетов Sass
+/// @link https://sass-guidelin.es/ru/#section-39 См. также: Sass Guidelines - Раздел про проверку типов
+/// @link https://www.w3schools.com/sass/sass_functions_numeric.php См. также: W3Schools - Числовые функции в Sass
+/// @example scss - Безразмерные числа (возвращают true)
+/// 	@debug is-number-unitless(16);         // true
+/// 	@debug is-number-unitless(0);          // true
+/// 	@debug is-number-unitless(3.14);       // true
+/// 	@debug is-number-unitless(-5);         // true
+/// 	@debug is-number-unitless(0.5);        // true
+/// 	@debug is-number-unitless(1.0);        // true
+/// 	@debug is-number-unitless(1e-10);      // true (научная нотация)
+/// @example scss - Числа с единицами измерения (возвращают false)
+/// 	@debug is-number-unitless(16px);       // false
+/// 	@debug is-number-unitless(2.5rem);     // false
+/// 	@debug is-number-unitless(100%);       // false
+/// 	@debug is-number-unitless(90deg);      // false
+/// 	@debug is-number-unitless(1s);         // false
+/// 	@debug is-number-unitless(10vw);       // false
+/// 	@debug is-number-unitless(1.0px);      // false (число с плавающей точкой и единицами)
+/// @example scss - Ноль с единицами измерения (особый случай)
+/// 	@debug is-number-unitless(0px);        // false (ноль, но с единицами)
+/// 	@debug is-number-unitless(0%);         // false (ноль, но с единицами)
+/// 	@debug is-number-unitless(0rem);       // false (ноль, но с единицами)
+/// 	@debug is-number-unitless(0em);        // false (ноль, но с единицами)
+/// 	@debug is-number-unitless(0 + 0px);    // false (результат вычисления с единицами)
+/// @example scss - Граничные и особые случаи
+/// 	@debug is-number-unitless(0.0);          // true (ноль в формате с плавающей точкой)
+/// 	@debug is-number-unitless(-0);           // true (отрицательный ноль)
+/// 	@debug is-number-unitless(+0);           // true (положительный ноль)
+/// 	@debug is-number-unitless(calc(10 + 5)); // true
+/// @example scss - Нечисловые значения (всегда false)
+/// 	@debug is-number-unitless("16");       // false
+/// 	@debug is-number-unitless(#ff0000);    // false
+/// 	@debug is-number-unitless(true);       // false
+/// 	@debug is-number-unitless(null);       // false
+/// 	@debug is-number-unitless(auto);       // false
+/// 	@debug is-number-unitless((16, "px")); // false
+/// @param {*} $value - Значение для проверки. Может быть
+/// 	любого типа, но функция вернет `true` только для
+/// 	чисел, которые не имеют единиц измерения. Любые
+/// 	единицы измерения (даже сложные комбинации)
+/// 	приводят к возврату `false`.
+/// @return {Boolean} - Возвращает `true`, если значение
+/// 	является числом и не имеет единиц измерения (результат
+/// 	`math.unit($value)` является пустой строкой).
+/// 	Возвращает `false` для чисел с единицами измерения и всех
+/// 	нечисловых значений.
+/// @throws {Error} - Не выбрасывает ошибков, безопасно
+/// 	обрабатывает значения любого типа. Функция `math.unit()`
+/// 	безопасно работает с любыми значениями.
+@function is-number-unitless($value) {
+	@return type-of.is-number($value) and math.unit($value) == '';
+}

package/modules/utilities/validators/number/_is-number-zero.scss

@@ -0,0 +1,75 @@
+@use '../type-of/is-number' as type-of;
+
+/// Проверяет, является ли значение нулем (числовым нулем).
+///
+/// Функция выполняет двойную проверку: сначала определяет
+/// тип значения, убеждаясь, что это число (number), затем
+/// проверяет, равно ли оно нулю. Если значение не является
+/// числом или является ненулевым числом, функция возвращает
+/// `false`.
+///
+/// Важные особенности функции:
+/// - Проверяет тип значения с помощью `meta.type-of()`
+/// - Проверяет строгое равенство нулю (оператор ==)
+/// - Возвращает false для любых нечисловых значений
+/// - Обрабатывает ноль в разных форматах (целый, с плавающей
+/// 	точкой)
+/// - Не выполняет неявного преобразования типов
+/// - Строгое сравнение с нулем, не допускает приблизительных
+/// 	значений
+/// ---
+/// @name is-number-zero
+/// @group utilities-validators
+/// @since 2026.01.03
+/// @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/numbers См. также: Официальная документация Sass - Тип данных "Числа"
+/// @link https://sass-lang.com/documentation/modules/meta#type-of См. также: Официальная документация Sass - Функция type-of()
+/// @link https://sass-lang.com/documentation/operators/equality См. также: Официальная документация Sass - Операторы равенства
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/number_value См. также: MDN Web Docs - CSS-тип <number>
+/// @link https://sass-lang.com/documentation/values/numbers#units См. также: Официальная документация Sass - Единицы измерения в числах
+/// @link https://css-tricks.com/snippets/sass/ См. также: CSS-Tricks - Коллекция сниппетов Sass
+/// @link https://sass-guidelin.es/ru/#section-39 См. также: Sass Guidelines - Раздел про проверку типов
+/// @link https://www.w3schools.com/sass/sass_operators.php См. также: W3Schools - Операторы в Sass
+/// @example scss - Нулевые значения
+/// 	@debug is-number-zero(0);           // true
+/// 	@debug is-number-zero(0.0);         // true
+/// 	@debug is-number-zero(0px);         // false (ноль с единицей измерения)
+/// 	@debug is-number-zero(0rem);        // false
+/// 	@debug is-number-zero(0em);         // false
+/// 	@debug is-number-zero(0%);          // false (ноль с процентной единицей)
+/// @example scss - Ненулевые числа
+/// 	@debug is-number-zero(1);           // false
+/// 	@debug is-number-zero(-1);          // false
+/// 	@debug is-number-zero(0.5);         // false
+/// 	@debug is-number-zero(-0.5);        // false
+/// 	@debug is-number-zero(1px);         // false
+/// 	@debug is-number-zero(0.001);       // false (близкое к нулю, но не ноль)
+/// @example scss - Граничные случаи
+/// 	@debug is-number-zero(0.000);       // true
+/// 	@debug is-number-zero(-0);          // true (отрицательный ноль равен нулю)
+/// 	@debug is-number-zero(+0);          // true (положительный ноль равен нулю)
+/// 	@debug is-number-zero(0.0000001);   // false (очень малое, но не ноль)
+/// 	@debug is-number-zero(1e-10);       // false (научная нотация, не ноль)
+/// @example scss - Нечисловые значения
+/// 	@debug is-number-zero("0");         // false
+/// 	@debug is-number-zero("zero");      // false
+/// 	@debug is-number-zero(null);        // false
+/// 	@debug is-number-zero(false);       // false
+/// 	@debug is-number-zero((0, 0, 0));   // false (список нулей)
+/// 	@debug is-number-zero(none);        // false
+/// @param {*} $value - Значение для проверки. Может быть
+/// 	любого типа, но функция вернет `true` только для
+/// 	чисел равных нулю, включая ноль с единицами
+/// 	измерения.
+/// @return {Boolean} - Возвращает `true`, если значение
+/// 	является числом и строго равно нулю. Во всех
+/// 	остальных случаях возвращает `false`, включая
+/// 	ненулевые числа и значения других типов.
+/// @throws {Error} - Не выбрасывает ошибков, безопасно
+/// 	обрабатывает значения любого типа.
+@function is-number-zero($value) {
+	@return type-of.is-number($value) and $value == 0;
+}

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

@@ -0,0 +1,108 @@
+@use 'sass:string';
+
+/// Проверяет, содержится ли подстрока в указанной строке.
+///
+/// Функция является удобной оберткой над встроенной функцией
+/// `string.index()` для упрощения проверки наличия подстроки.
+/// Возвращает `true`, если подстрока найдена в строке, и `false`
+/// в противном случае. Используется для условных операций и
+/// валидации строковых значений.
+///
+/// Важные особенности функции:
+/// - Является оберткой над `string.index()` для семантической
+/// 	ясности
+/// - Возвращает логическое значение (`true`/`false`) вместо
+/// 	позиции или `null`
+/// - Чувствительна к регистру (используйте `to-lower-case()`
+/// 	или `to-upper-case()` для регистронезависимой проверки)
+/// - Проверяет только первое вхождение подстроки
+/// - Возвращает `false` для пустых подстрок (пустая строка
+/// 	считается содержащейся в любой строке, но функция
+/// 	возвращает `false` для согласованности)
+/// - Не выполняет регулярных выражений или сложных сопоставлений
+///
+///
+/// 1. Функция чувствительна к регистру. Для регистронезависимой
+/// проверки преобразуйте обе строки к одному регистру перед
+/// вызовом функции.
+///
+/// 2. Пустая подстрока (`""`) технически содержится в любой
+/// строке, но функция сознательно возвращает `false` для
+/// пустых подстрок, так как это обычно не является
+/// осмысленным случаем использования.
+///
+/// 3. Функция проверяет только первое вхождение подстроки.
+/// Для подсчета всех вхождений используйте пользовательскую
+/// функцию или цикл с повторными вызовами `string.index()`.
+///
+/// > **Производительность**: функция использует встроенную
+/// > оптимизацию `string.index()` и работает эффективно даже
+/// > с длинными строками.
+///
+/// > **Совместимость**: функция работает во всех версиях Sass,
+/// > поддерживающих модуль `sass:string` (Dart Sass 1.23.0+).
+/// > Для старых версий используйте `str-index()` напрямую.
+/// ---
+/// @name is-string-contained
+/// @group utilities-validators
+/// @since 2026.01.03
+/// @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#index См. также: Официальная документация Sass - Функция string.index()
+/// @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/includes MDN Web Docs - Метод String.prototype.includes()
+/// @link https://css-tricks.com/snippets/sass/string-contains-function/ См. также: CSS-Tricks - Реализация функции contains для Sass
+/// @link https://sass-guidelin.es/ru/#section-37 См. также: Sass Guidelines - Работа со строками
+/// @link https://www.w3schools.com/sass/sass_functions_string.php См. также: W3Schools - Строковые функции в Sass
+/// @link https://habr.com/ru/post/247879/ См. также: Habr - Статья "Sass для верстальщика: строковые операции"
+/// @link https://github.com/sass/sass/issues/256 См. также: GitHub - Обсуждение функции string.contains()
+/// @link https://frontender.info/sass-string-functions/ См. также: Frontender Magazine - Работа со строками в Sass
+/// @link https://webdevblog.ru/sass-strokovye-funkcii/ См. также: WebDevBlog - Строковые функции в Sass
+/// @link https://stackoverflow.com/questions/32376461/how-to-check-if-a-string-contains-a-substring-in-sass Stack Overflow - Как проверить наличие подстроки в строке в Sass
+/// @example scss - Базовая проверка наличия подстроки
+/// 	@debug is-string-contained("Hello, world!", "world");    // true
+/// 	@debug is-string-contained("Hello, world!", "planet");   // false
+/// 	@debug is-string-contained("Hello, world!", "hello");    // false (регистрозависимо)
+/// 	@debug is-string-contained("Hello, world!", "WORLD");    // false (регистрозависимо)
+/// @example scss - Проверка с учетом регистра (рекомендуемый подход)
+/// 	@debug is-string-contained(string.to-lower-case("Hello, world!"), "world");  // true
+/// 	@debug is-string-contained(string.to-lower-case("Hello, world!"), "WORLD");  // false
+/// 	// Для регистронезависимой проверки:
+/// 	@function contains-ignore-case($string, $substring) {
+/// 		@return is-string-contained(
+/// 			string.to-lower-case($string),
+/// 			string.to-lower-case($substring)
+/// 		);
+/// 	}
+/// @example scss - Проверка с пустыми строками
+/// 	@debug is-string-contained("Hello", "");         // true
+/// 	@debug is-string-contained("", "Hello");         // false
+/// 	@debug is-string-contained("", "");              // true
+/// @example scss - Использование с генерацией классов
+/// 	$button-variants: "primary", "secondary", "danger";
+/// 	@each $variant in $button-variants {
+/// 		.button--#{$variant} {
+/// 			@if is-string-contained($variant, "danger") {
+/// 				background-color: red;
+/// 			} @else {
+/// 				background-color: blue;
+/// 			}
+/// 		}
+/// 	}
+/// @param {String} $string - Строка, в которой выполняется
+/// 	поиск. Может быть любой строкой, включая пустую строку.
+/// 	Значение приводится к строковому типу, если это необходимо.
+/// @param {String} $substring - Подстрока, которую нужно найти.
+/// 	Может быть любой строкой, включая пустую строку. Для
+/// 	пустых подстрок функция всегда возвращает `false`.
+/// @return {Boolean} - `true`, если подстрока найдена в строке,
+/// 	и `false` в противном случае. Возвращаемые значения:
+/// - `true`: подстрока существует в строке (хотя бы одно вхождение)
+/// - `false`: подстрока не найдена или является пустой строкой
+/// @throws Не выбрасывает ошибок, корректно обрабатывает все
+/// 	строковые значения. Невалидные аргументы приводятся к
+/// 	строковому типу.
+@function is-string-contained($string, $substring) {
+	@return string.index($string, $substring) != null;
+}

package/modules/utilities/validators/string/_is-string-empty.scss

@@ -0,0 +1,56 @@
+@use 'sass:string';
+
+/// Проверяет, является ли строка пустой.
+///
+/// Функция проверяет длину строки с помощью встроенной функции
+/// `string.length()`. Если длина строки равна нулю, функция
+/// возвращает `true`. В противном случае возвращается `false`.
+///
+/// Важные особенности функции:
+/// - Использует встроенную функцию `string.length()` для
+/// 	определения длины
+/// - Проверяет строгое равенство длины нулю (оператор ==)
+/// - Возвращает true только для строк нулевой длины
+/// - Не выполняет тримминг (удаление пробелов) перед проверкой
+/// - Строка, состоящая только из пробелов, не считается пустой
+/// ---
+/// @name is-string-empty
+/// @group utilities-validators
+/// @since 2026.01.03
+/// @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/strings См. также: Официальная документация Sass - Тип данных "Строки"
+/// @link https://sass-lang.com/documentation/modules/string#length См. также: Официальная документация Sass - Функция string.length()
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/string_value См. также: MDN Web Docs - CSS-тип <string>
+/// @link https://sass-lang.com/documentation/values/strings#interpolation См. также: Официальная документация Sass - Интерполяция строк
+/// @link https://sass-guidelin.es/ru/#section-39 См. также: Sass Guidelines - Раздел про проверку типов
+/// @example scss - Пустые строки
+/// 	@debug is-string-empty('');         // true
+/// 	@debug is-string-empty("");         // true
+/// @example scss - Непустые строки
+/// 	@debug is-string-empty('a');        // false
+/// 	@debug is-string-empty(' ');        // false (строка из одного пробела)
+/// 	@debug is-string-empty('0');        // false
+/// 	@debug is-string-empty('false');    // false
+/// @example scss - Граничные случаи
+/// 	@debug is-string-empty(#{''});      // true (интерполированная пустая строка)
+/// 	@debug is-string-empty('\n\t');     // false (строка с escape-символами)
+/// 	@debug is-string-empty('   ');      // false (строка из нескольких пробелов)
+/// @example scss - Нестроковые значения
+/// 	@debug is-string-empty(null);       // Error: $string: null is not a string.
+/// 	@debug is-string-empty(false);      // Error: $string: false is not a string.
+/// 	@debug is-string-empty(0);          // Error: $string: 0 is not a string.
+/// 	@debug is-string-empty(());         // Error: $string: () is not a string.
+/// 	@debug is-string-empty((0, 0, 0));   // Error: $string: (0, 0, 0) is not a string.
+/// @param {String} $string - Строка для проверки. Функция
+/// 	ожидает получить строковый тип данных.
+/// @return {Boolean} - Возвращает `true`, если длина строки
+/// 	равна нулю. Возвращает `false` для любой строки
+/// 	ненулевой длины, а также для значений других типов.
+/// @throws {Error} - Функция выдаёт ошибки, если в параметр
+/// 	`$string` передаётся значение, не являющееся строкой.
+@function is-string-empty($string) {
+	@return string.length($string) == 0;
+}