@omnisass/library 0.2.0

package/modules/utilities/helpers/misc/_url-encode.scss

@@ -0,0 +1,148 @@
+@forward 'url-encode.configs';
+
+@use 'url-encode.configs' as configs;
+@use '../string/string-replace' as *;
+@use '../../loggers/log-invalid-type' as *;
+@use '../../validators/type-of/is-map' as *;
+@use '../../validators/type-of/is-string' as *;
+
+/// Кодирует строку для безопасного использования в URL.
+///
+/// Функция заменяет зарезервированные и небезопасные символы в
+/// строке на их процентное представление в соответствии с
+/// RFC 3986. Это позволяет безопасно включать пользовательские
+/// данные, параметры и динамические значения в URL-адреса без
+/// риска нарушения структуры URL или возникновения ошибок.
+///
+/// Важные особенности функции:
+/// - Заменяет зарезервированные символы URL на процентное кодирование
+/// - Использует настраиваемую карту замены символов
+/// - Поддерживает кастомные наборы символов для кодирования
+/// - Обрабатывает строки любой длины и сложности
+/// - Сохраняет безопасные символы без изменений
+/// - Полезно для динамической генерации URL с параметрами
+/// - Используется для создания безопасных ссылок и маршрутов
+/// - Обеспечивает корректную работу с международными символами
+/// - Предотвращает инъекции и нарушения структуры URL
+/// - Совместима со стандартами кодирования URL
+/// ---
+/// @name url-encode
+/// @group utilities-helpers
+/// @since 2026.01.13
+/// @access public
+/// @author Sindre Sorhus
+/// @author Murad Rustamov (therteenten) [адаптация]
+/// @link https://github.com/sindresorhus GitHub - Sindre Sorhus
+/// @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/encodeURIComponent См. также: MDN Web Docs - Функция encodeURIComponent()
+/// @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURI См. также: MDN Web Docs - Функция encodeURI()
+/// @link https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding См. также: MDN Web Docs - Глоссарий: Percent-encoding
+/// @link https://developer.mozilla.org/en-US/docs/Web/API/URL_API См. также: MDN Web Docs - URL API
+/// @link https://datatracker.ietf.org/doc/html/rfc3986 См. также: RFC 3986 - Uniform Resource Identifier (URI): Generic Syntax
+/// @link https://en.wikipedia.org/wiki/Percent-encoding См. также: Wikipedia - Percent-encoding
+/// @link https://css-tricks.com/snippets/sass/string-replace-function/ См. также: CSS-Tricks - Функция замены строк в Sass
+/// @link https://css-tricks.com/snippets/jquery/get-query-params-object-from-url/ См. также: CSS-Tricks - Получение параметров запроса из URL
+/// @link https://sass-guidelin.es/ru/#section-42 См. также: Sass Guidelines - Раздел про строки
+/// @link https://www.urlencoder.io/learn/ См. также: URL Encoder - Обучение кодированию URL
+/// @example scss - Базовое кодирование строк
+/// 	@debug url-encode('Hello World!');        // 'Hello%20World%21'
+/// 	@debug url-encode('query=test&sort=asc'); // 'query%3Dtest%26sort%3Dasc'
+/// 	@debug url-encode('price=$100');          // 'price%3D%24100'
+/// 	@debug url-encode('user@example.com');    // 'user%40example.com'
+/// 	@debug url-encode('path/to/file.js');     // 'path%2Fto%2Ffile.js'
+/// 	@debug url-encode('name=John Doe');       // 'name%3DJohn%20Doe'
+/// @param {String} $value - Строка для кодирования в URL.
+/// 	Может содержать любые символы, включая зарезервированные
+/// 	символы URL. Функция заменит все символы из карты замены
+/// 	на их процентное представление.
+/// @param {Map} $chars-map [configs.$set-url-reserved-chars] -
+/// 	Карта замены символов для кодирования. По умолчанию
+/// 	используется глобальная конфигурация из
+/// 	`configs.$set-url-reserved-chars`. Карта должна содержать
+/// 	пары ключ-значение, где ключ - символ для замены,
+/// 	значение - процентное представление символа.
+/// @return {String} - Закодированная строка, где все символы
+/// 	из карты замены преобразованы в их процентное
+/// 	представление. Строка безопасна для использования в
+/// 	любой части URL (path, query, fragment).
+/// @throws {Error} - Может выбросить ошибку при передаче
+/// 	нестрокового значения или если функция `string-replace`
+/// 	не определена. Требуется наличие функции `string-replace`
+/// 	в доступном scope.
+/// @require {function} string-replace - Вспомогательная
+/// 	функция замены подстрок в строке. Должна быть определена
+/// 	и доступна для корректной работы данной функции.
+/// @require {variable} configs.$set-url-reserved-chars -
+/// 	Глобальная переменная с картой зарезервированных символов
+/// 	URL. Содержит маппинг символов на их процентное
+/// 	кодирование по умолчанию.
+@function url-encode(
+	$value,
+	$chars-map: configs.$set-url-reserved-chars) {
+
+	// Проверка типа первого параметра: ожидается строковое значение.
+	// Функция is-string() проверяет, является ли $value строкой
+	// (тип данных string).
+	@if not is-string($value) {
+
+		// Если $value не является строкой, возвращаем ошибку через
+		// стандартную функцию логирования. Это предотвращает
+		// некорректные операции кодирования с нестроковыми данными.
+		@return log-invalid-type(
+			'url-encode',
+			$value,
+			'$value',
+			'string'
+		);
+
+	}
+
+	// Проверка типа второго параметра: ожидается карта (map) символов.
+	// $chars-map содержит сопоставление символов, которые нужно заменить,
+	// с их URL-закодированными представлениями. По умолчанию используется
+	// значение из конфигурации configs.$set-url-reserved-chars.
+	@else if not is-map($chars-map) {
+
+		// Если $chars-map не является картой, возвращаем ошибку.
+		// Проверка выполняется только если $value прошел валидацию.
+		@return log-invalid-type(
+			'url-encode',
+			$chars-map,
+			'$chars-map',
+			'map'
+		);
+
+	}
+
+	// Все параметры прошли валидацию - выполняем кодирование строки.
+	@else {
+
+		// Инициализация переменной для хранения результата.
+		// Начинаем с исходного значения, которое будет постепенно
+		// преобразовываться путем замены символов.
+		$-result: $value;
+
+		// Итерация по всем парам ключ-значение в карте символов.
+		// - $string: символ или последовательность символов для замены.
+		// - $replacement: закодированное представление символа для URL.
+		@each $string, $replacement in $chars-map {
+
+			// Замена каждого вхождения $string на $replacement в строке.
+			// Функция string-replace() выполняет глобальную замену
+			// всех вхождений искомой подстроки.
+			$-result: string-replace($-result, $string, $replacement);
+
+		}
+
+		// Возвращаем закодированную строку, безопасную для использования в URL.
+		// Все символы, указанные в $chars-map, будут заменены на их
+		// URL-закодированные эквиваленты (обычно в формате %XX,
+		// где XX - шестнадцатеричный код символа).
+		@return $-result;
+
+	}
+
+}

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

@@ -0,0 +1,111 @@
+@use 'sass:math';
+
+/// Округляет число вверх до ближайшего кратного значения.
+///
+/// Функция выполняет округление числа вверх (в сторону
+/// положительной бесконечности) до ближайшего значения,
+/// кратного указанному числу.
+///
+/// Используется для выравнивания значений по сетке или
+/// заданному шагу.
+///
+/// Важные особенности функции:
+/// - Всегда округляет вверх (в сторону увеличения)
+/// - Работает с положительными и отрицательными числами
+/// - Сохраняет единицы измерения исходного числа
+/// - Использует `math.ceil()` для округления вверх
+/// - Поддерживает дробные значения для `$nearest`
+/// - Использует математически корректное деление через
+/// 	`math.div()`
+/// ---
+/// @name number-ceil-to
+/// @group utilities-helpers
+/// @since 2025.12.27
+/// @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/math#ceil См. также: Официальная документация Sass - Функция math.ceil()
+/// @link https://sass-lang.com/documentation/modules/math#div См. также: Официальная документация Sass - Функция math.div()
+/// @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/ceil MDN Web Docs - Math.ceil()
+/// @link https://css-tricks.com/snippets/sass/ См. также: CSS-Tricks - Коллекция сниппетов Sass
+/// @link https://sass-guidelin.es/ru/#math-functions См. также: Sass Guidelines - Математические функции
+/// @link https://frontender.info/sass-numbers/ См. также: 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 number-ceil-to(13, 5);        // 15
+/// 	@debug number-ceil-to(17, 10);       // 20
+/// 	@debug number-ceil-to(23, 4);        // 24
+/// 	@debug number-ceil-to(100, 50);      // 100
+/// 	@debug number-ceil-to(101, 50);      // 150
+/// @example scss - Округление дробных чисел
+/// 	@debug number-ceil-to(12.3, 5);      // 15
+/// 	@debug number-ceil-to(3.14, 1);      // 4
+/// 	@debug number-ceil-to(7.89, 2.5);    // 10
+/// 	@debug number-ceil-to(0.333, 0.25);  // 0.5
+/// @example scss - Округление отрицательных чисел
+/// 	@debug number-ceil-to(-13, 5);       // -10
+/// 	@debug number-ceil-to(-17, 10);      // -10
+/// 	@debug number-ceil-to(-23, 4);       // -20
+/// 	@debug number-ceil-to(-3.5, 1);      // -3
+/// @example scss - Округление чисел с единицами измерения
+/// 	@debug number-ceil-to(13px, 5px);    // 15px
+/// 	@debug number-ceil-to(1.7rem, 0.5rem); // 2rem
+/// 	@debug number-ceil-to(45%, 10%);     // 50%
+/// 	@debug number-ceil-to(120deg, 90deg); // 180deg
+/// @example scss - Практическое использование для сетки
+/// 	$item-width: 287px;
+/// 	$grid-step: 12px;
+/// 	$aligned-width: number-ceil-to($item-width, $grid-step);
+///
+/// 	// $aligned-width: 288px
+/// 	.grid-item {
+/// 		width: $aligned-width;
+/// 	}
+/// @example css - Результат
+/// 	.grid-item {
+/// 		width: 288px;
+/// 	}
+/// @example scss - Практическое использование для типографики
+/// 	$font-size: 15.3px;
+/// 	$type-scale: 2px;
+/// 	$aligned-font-size: number-ceil-to($font-size, $type-scale);
+///
+/// 	// $aligned-font-size: 16px
+/// 	.text {
+/// 		font-size: $aligned-font-size;
+/// 	}
+/// @example css - Результат
+/// 	.text {
+/// 		font-size: 16px;
+/// 	}
+/// @example scss - Практическое использование для интервалов
+/// 	$spacing: 23px;
+/// 	$spacing-step: 8px;
+/// 	$consistent-spacing: number-ceil-to($spacing, $spacing-step);
+///
+/// 	// $consistent-spacing: 24px
+/// 	.container {
+/// 		padding: $consistent-spacing;
+/// 	}
+/// @example css - Результат
+/// 	.container {
+/// 		padding: 24px;
+/// 	}
+/// @param {Number} $value - Число для округления. Может быть
+/// 	любым числом: положительным, отрицательным, целым,
+/// 	дробным, с единицами измерения или без них.
+/// @param {Number} $nearest - Кратное значение, до которого
+/// 	нужно округлить. Определяет шаг округления. Может быть
+/// 	дробным числом. Рекомендуется использовать те же единицы
+/// 	измерения, что и у `$value`.
+/// @return {Number} - Число, округленное вверх до ближайшего
+/// 	значения, кратного `$nearest`. Сохраняет единицы
+/// 	измерения исходного числа `$value`.
+/// @throws {Error} - Может выбросить ошибку если `$value` или
+/// 	`$nearest` не являются числами, или если происходит
+/// 	деление на ноль.
+@function number-ceil-to($value, $nearest) {
+	@return math.ceil(math.div($value, $nearest)) * $nearest;
+}

package/modules/utilities/helpers/number/_number-clamp-max.scss

@@ -0,0 +1,92 @@
+@use 'sass:math';
+
+/// Ограничивает число сверху, обеспечивая максимальное
+/// значение.
+///
+/// Функция принимает число и максимальную границу, и
+/// возвращает наименьшее из этих двух значений. Если число
+/// больше максимального значения, возвращается максимальное
+/// значение. В противном случае возвращается исходное число.
+///
+/// Визуализация работы:
+/// - Если `value > max` → возвращает `max`
+/// - Если `value ≤ max` → возвращает `value`
+///
+/// Важные особенности функции:
+/// - Гарантирует, что результат будет не больше `$max`
+/// - Использует встроенную функцию `math.min()`
+/// - Работает с любыми числовыми значениями (целые, дробные,
+/// 	с единицами)
+/// - Сохраняет единицы измерения исходного значения при их
+/// 	наличии
+/// - Не изменяет значения, уже меньшие или равные максимальному
+/// - Обрабатывает отрицательные числа и ноль
+/// - Полезна для установки максимальных границ
+/// - Частный случай функции `number-clamp()` без нижней границы
+/// ---
+/// @name number-clamp-max
+/// @group utilities-helpers
+/// @since 2025.12.27
+/// @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/math См. также: Официальная документация Sass - Модуль math
+/// @link https://sass-lang.com/documentation/modules/math#min См. также: Официальная документация Sass - Функция math.min()
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/min См. также: MDN Web Docs - CSS-функция min()
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/max См. также: MDN Web Docs - CSS-функция max()
+/// @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/min См. также: MDN Web Docs - JavaScript Math.min()
+/// @link https://css-tricks.com/snippets/sass/ См. также: CSS-Tricks - Коллекция сниппетов Sass
+/// @link https://sass-guidelin.es/ru/#section-41 См. также: Sass Guidelines - Раздел про математические операции
+/// @link https://www.w3schools.com/css/css_math_functions.asp См. также: W3Schools - CSS математические функции
+/// @example scss - Ограничение сверху
+/// 	@debug number-clamp-max(5, 10);       // 5
+/// 	@debug number-clamp-max(15, 10);      // 10 (больше максимума)
+/// 	@debug number-clamp-max(0, 10);       // 0
+/// 	@debug number-clamp-max(10, 10);      // 10 (равно максимуму)
+/// 	@debug number-clamp-max(-5, 10);      // -5
+/// @example scss - Ограничение дробных чисел
+/// 	@debug number-clamp-max(3.14, 5);     // 3.14
+/// 	@debug number-clamp-max(6.28, 5);     // 5
+/// 	@debug number-clamp-max(1.0, 5);      // 1
+/// 	@debug number-clamp-max(2.718, 3.5);  // 2.718
+/// 	@debug number-clamp-max(3.501, 3.5);  // 3.5
+/// @example scss - Отрицательные максимальные значения
+/// 	@debug number-clamp-max(5, -10);      // -10
+/// 	@debug number-clamp-max(-5, -10);     // -10
+/// 	@debug number-clamp-max(-15, -10);    // -15
+/// 	@debug number-clamp-max(0, -10);      // -10
+/// 	@debug number-clamp-max(-3.5, -5);    // -5
+/// @example scss - Ограничение с единицами измерения
+/// 	@debug number-clamp-max(25px, 32px);      // 25px
+/// 	@debug number-clamp-max(40px, 32px);      // 32px
+/// 	@debug number-clamp-max(10px, 32px);      // 10px
+/// 	@debug number-clamp-max(1.5rem, 2rem);    // 1.5rem
+/// 	@debug number-clamp-max(2.5rem, 2rem);    // 2rem
+/// 	@debug number-clamp-max(0.5rem, 2rem);    // 0.5rem
+/// 	@debug number-clamp-max(150%, 100%);      // 100%
+/// @example scss - Граничные случаи
+/// 	@debug number-clamp-max(0, 0);        // 0
+/// 	@debug number-clamp-max(100, 0);      // 0
+/// 	@debug number-clamp-max(-0, -10);     // -10
+/// 	@debug number-clamp-max(1e-10, 1);    // 0.0000000001
+/// 	@debug number-clamp-max(1000, 100);   // 100
+/// 	@debug number-clamp-max(-1000, -100); // -1000
+/// 	@debug number-clamp-max(999.999, 1000); // 999.999
+/// @param {Number} $value - Число, которое нужно ограничить
+/// 	сверху. Может быть любым числом: целым, дробным,
+/// 	положительным, отрицательным, с единицами измерения
+/// 	или без.
+/// @param {Number} $max - Максимальное допустимое значение.
+/// 	Если `$value` больше `$max`, возвращается `$max`.
+/// @return {Number} - Наименьшее из двух значений: `$value`
+/// 	или `$max`. Если `$value` меньше или равно `$max`,
+/// 	возвращается `$value`. В противном случае возвращается
+/// 	`$max`.
+/// @throws Не выбрасывает ошибок, безопасно обрабатывает
+/// 	все числовые значения. Оба аргумента должны быть
+/// 	числами для корректной работы.
+@function number-clamp-max($value, $max) {
+	@return math.min($value, $max);
+}

package/modules/utilities/helpers/number/_number-clamp-min.scss

@@ -0,0 +1,100 @@
+@use 'sass:math';
+
+/// Ограничивает число снизу, обеспечивая минимальное значение.
+///
+/// Функция принимает число и минимальную границу, и
+/// возвращает наибольшее из этих двух значений. Если число
+/// меньше минимального значения, возвращается минимальное
+/// значение. В противном случае возвращается исходное число.
+///
+/// Визуализация работы:
+/// - Если `value < min` → возвращает `min`
+/// - Если `value ≥ min` → возвращает `value`
+///
+/// Важные особенности функции:
+/// - Гарантирует, что результат будет не меньше `$min`
+/// - Использует встроенную функцию `math.max()`
+/// - Работает с любыми числовыми значениями (целые, дробные,
+/// 	с единицами)
+/// - Сохраняет единицы измерения исходного значения при их
+/// 	наличии
+/// - Не изменяет значения, уже большие или равные минимальному
+/// - Обрабатывает отрицательные числа и ноль
+/// - Полезна для установки минимальных границ
+/// - Частный случай функции `number-clamp()` без верхней
+/// 	границы
+///
+/// > Функция является оберткой над `math.max()` с семантически
+/// > ясным названием, которое явно указывает на ограничение
+/// > снизу. Является частным случаем функции `number-clamp()`,
+/// > где не указана верхняя граница. Эта функция особенно
+/// > полезна для доступности (accessibility), гарантируя
+/// > минимальные размеры для взаимодействия и минимальные
+/// > временные интервалы для восприятия.
+/// ---
+/// @name number-clamp-min
+/// @group utilities-helpers
+/// @since 2025.12.27
+/// @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/math См. также: Официальная документация Sass - Модуль math
+/// @link https://sass-lang.com/documentation/modules/math#max См. также: Официальная документация Sass - Функция math.max()
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/min См. также: MDN Web Docs - CSS-функция min()
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/max См. также: MDN Web Docs - CSS-функция max()
+/// @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/max См. также: MDN Web Docs - JavaScript Math.max()
+/// @link https://css-tricks.com/snippets/sass/ См. также: CSS-Tricks - Коллекция сниппетов Sass
+/// @link https://sass-guidelin.es/ru/#section-41 См. также: Sass Guidelines - Раздел про математические операции
+/// @link https://www.w3schools.com/css/css_math_functions.asp См. также: W3Schools - CSS математические функции
+/// @example scss - Ограничение снизу
+/// 	@debug number-clamp-min(5, 1);        // 5
+/// 	@debug number-clamp-min(15, 1);       // 15
+/// 	@debug number-clamp-min(0, 1);        // 1 (меньше минимума)
+/// 	@debug number-clamp-min(1, 1);        // 1 (равно минимуму)
+/// 	@debug number-clamp-min(-5, 1);       // 1
+/// @example scss - Ограничение дробных чисел
+/// 	@debug number-clamp-min(3.14, 1);     // 3.14
+/// 	@debug number-clamp-min(0.5, 1);      // 1
+/// 	@debug number-clamp-min(1.0, 1);      // 1
+/// 	@debug number-clamp-min(2.718, 1.5);  // 2.718
+/// 	@debug number-clamp-min(1.499, 1.5);  // 1.5
+/// @example scss - Отрицательные минимальные значения
+/// 	@debug number-clamp-min(5, -10);      // 5
+/// 	@debug number-clamp-min(-5, -10);     // -5
+/// 	@debug number-clamp-min(-15, -10);    // -10
+/// 	@debug number-clamp-min(0, -10);      // 0
+/// 	@debug number-clamp-min(-3.5, -5);    // -3.5
+/// @example scss - Ограничение с единицами измерения
+/// 	@debug number-clamp-min(25px, 16px);      // 25px
+/// 	@debug number-clamp-min(10px, 16px);      // 16px
+/// 	@debug number-clamp-min(40px, 16px);      // 40px
+/// 	@debug number-clamp-min(1.5rem, 1rem);    // 1.5rem
+/// 	@debug number-clamp-min(0.5rem, 1rem);    // 1rem
+/// 	@debug number-clamp-min(2.5rem, 1rem);    // 2.5rem
+/// 	@debug number-clamp-min(100%, 50%);       // 100%
+/// @example scss - Граничные случаи
+/// 	@debug number-clamp-min(0, 0);        // 0
+/// 	@debug number-clamp-min(100, 0);      // 100
+/// 	@debug number-clamp-min(-0, -10);     // 0
+/// 	@debug number-clamp-min(1e-10, 0);    // 0.0000000001
+/// 	@debug number-clamp-min(1000, 0);     // 1000
+/// 	@debug number-clamp-min(-1000, -100); // -100
+/// 	@debug number-clamp-min(0.000001, 0); // 0.000001
+/// @param {Number} $value - Число, которое нужно ограничить
+/// 	снизу. Может быть любым числом: целым, дробным,
+/// 	положительным, отрицательным, с единицами измерения или
+/// 	без.
+/// @param {Number} $min - Минимальное допустимое значение.
+/// 	Если `$value` меньше `$min`, возвращается `$min`.
+/// @return {Number} - Наибольшее из двух значений: `$value`
+/// 	или `$min`. Если `$value` больше или равно `$min`,
+/// 	возвращается `$value`. В противном случае возвращается
+/// 	`$min`.
+/// @throws Не выбрасывает ошибок, безопасно обрабатывает все
+/// 	числовые значения. Оба аргумента должны быть числами
+/// 	для корректной работы.
+@function number-clamp-min($value, $min) {
+	@return math.max($value, $min);
+}

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

@@ -0,0 +1,109 @@
+@use 'sass:math';
+
+/// Ограничивает число заданным диапазоном значений.
+///
+/// Функция принимает число и возвращает его значение,
+/// ограниченное минимальной и максимальной границами. Если
+/// число меньше минимального значения, возвращается
+/// минимальное значение. Если число больше максимального
+/// значения, возвращается максимальное значение.
+///
+/// В противном случае возвращается исходное число.
+///
+/// Визуализация работы:
+/// - Если `value < min` → возвращает `min`
+/// - Если `value > max` → возвращает `max`
+/// - Если `min ≤ value ≤ max` → возвращает `value`
+///
+/// Важные особенности функции:
+/// - Гарантирует, что результат будет в диапазоне `[$min, $max]`
+/// - Использует встроенные функции `math.max()` и `math.min()`
+/// - Работает с любыми числовыми значениями (целые, дробные,
+/// 	с единицами)
+/// - Сохраняет единицы измерения исходного значения при их
+/// 	наличии
+/// - Не изменяет значения, уже находящиеся в диапазоне
+/// - Обрабатывает отрицательные числа и ноль
+/// - Может использоваться для нормализации значений
+///
+/// > Функция является аналогом CSS-функции `clamp()`, но
+/// > работает на этапе компиляции Sass. В отличие от CSS
+/// > `clamp()`, которая динамически вычисляется браузером,
+/// > `number-clamp()` вычисляется один раз при компиляции и
+/// > возвращает фиксированное значение. Для обеспечения
+/// > корректной работы рекомендуется всегда передавать
+/// > `$min ≤ $max`. При `$min > $max` функция все равно
+/// > работает, но результат может отличаться от ожидаемого.
+/// ---
+/// @name number-clamp
+/// @group utilities-helpers
+/// @since 2025.12.27
+/// @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/math См. также: Официальная документация Sass - Модуль math
+/// @link https://sass-lang.com/documentation/modules/math#min См. также: Официальная документация Sass - Функция math.min()
+/// @link https://sass-lang.com/documentation/modules/math#max См. также: Официальная документация Sass - Функция math.max()
+/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/clamp См. также: MDN Web Docs - CSS-функция clamp()
+/// @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/clamp См. также: MDN Web Docs - JavaScript Math.clamp()
+/// @link https://css-tricks.com/snippets/sass/ См. также: CSS-Tricks - Коллекция сниппетов Sass
+/// @link https://sass-guidelin.es/ru/#section-41 См. также: Sass Guidelines - Раздел про математические операции
+/// @link https://www.w3schools.com/css/css_math_functions.asp См. также: W3Schools - CSS математические функции
+/// @example scss - Ограничение в пределах диапазона
+/// 	@debug number-clamp(5, 1, 10);        // 5
+/// 	@debug number-clamp(15, 1, 10);       // 10 (больше максимума)
+/// 	@debug number-clamp(0, 1, 10);        // 1 (меньше минимума)
+/// 	@debug number-clamp(1, 1, 10);        // 1 (равно минимуму)
+/// 	@debug number-clamp(10, 1, 10);       // 10 (равно максимуму)
+/// @example scss - Ограничение дробных чисел
+/// 	@debug number-clamp(3.14, 1, 5);      // 3.14
+/// 	@debug number-clamp(0.5, 1, 5);       // 1
+/// 	@debug number-clamp(6.28, 1, 5);      // 5
+/// 	@debug number-clamp(2.718, 1.5, 3.5); // 2.718
+/// 	@debug number-clamp(1.499, 1.5, 3.5); // 1.5
+/// @example scss - Ограничение отрицательных чисел
+/// 	@debug number-clamp(-5, -10, 10);     // -5
+/// 	@debug number-clamp(-15, -10, 10);    // -10
+/// 	@debug number-clamp(15, -10, 10);     // 10
+/// 	@debug number-clamp(0, -10, 10);      // 0
+/// 	@debug number-clamp(-3.5, -5, 5);     // -3.5
+/// @example scss - Ограничение с единицами измерения
+/// 	@debug number-clamp(25px, 16px, 32px);    // 25px
+/// 	@debug number-clamp(10px, 16px, 32px);    // 16px
+/// 	@debug number-clamp(40px, 16px, 32px);    // 32px
+/// 	@debug number-clamp(1.5rem, 1rem, 2rem);  // 1.5rem
+/// 	@debug number-clamp(0.5rem, 1rem, 2rem);  // 1rem
+/// 	@debug number-clamp(2.5rem, 1rem, 2rem);  // 2rem
+/// @example scss - Граничные случаи
+/// 	@debug number-clamp(0, 0, 100);       // 0
+/// 	@debug number-clamp(100, 0, 100);     // 100
+/// 	@debug number-clamp(-0, -10, 10);     // 0
+/// 	@debug number-clamp(1e-10, 0, 1);     // 0.0000000001
+/// 	@debug number-clamp(1000, 0, 100);    // 100
+/// 	@debug number-clamp(-1000, -100, 0);  // -100
+/// @example scss - Некорректные диапазоны (min > max)
+/// 	@debug number-clamp(5, 10, 1);        // 1 (ведет себя неинтуитивно!)
+/// 	@debug number-clamp(15, 10, 1);       // 1
+/// 	@debug number-clamp(0, 10, 1);        // 1
+/// 	// Внимание: при min > max функция работает, но результат может быть
+/// 	// неожиданным. Рекомендуется всегда передавать min ≤ max.
+/// @param {Number} $value - Число, которое нужно ограничить.
+/// 	Может быть любым числом: целым, дробным, положительным,
+/// 	отрицательным, с единицами измерения или без.
+/// @param {Number} $min - Минимальное допустимое значение.
+/// 	Если `$value` меньше `$min`, возвращается `$min`.
+/// @param {Number} $max - Максимальное допустимое значение.
+/// 	Если `$value` больше `$max`, возвращается `$max`.
+/// @return {Number} - Значение `$value`, ограниченное
+/// 	диапазоном `[$min, $max]`. Если `$value` находится в
+/// 	пределах диапазона, возвращается исходное значение. В
+/// 	противном случае возвращается соответствующая граница
+/// 	диапазона.
+/// @throws {Error} - Не выбрасывает ошибок, даже при
+/// 	некорректных диапазонах (когда `$min > $max`). Однако
+/// 	в таких случаях поведение функции может быть неинтуитивным.
+@function number-clamp($value, $min, $max) {
+	@return math.min(math.max($value, $min), $max);
+}