@omnisass/library 0.2.0

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

@@ -0,0 +1,160 @@
+@use 'sass:math';
+
+/// Нормализует число к единичному интервалу [0, 1].
+///
+/// Функция выполняет линейное преобразование числа из
+/// исходного диапазона `[$min, $max]` в нормализованный
+/// диапазон `[0, 1]`. Это фундаментальная математическая
+/// операция, используемая в статистике, компьютерной графике,
+/// анимациях и алгоритмах интерполяции.
+///
+/// Математическая формула:
+/// - `normalized = (value - min) / (max - min)`
+///
+/// Свойства результата:
+/// - Если `value = min` → возвращает `0`
+/// - Если `value = max` → возвращает `1`
+/// - Если `value` находится посередине между `min`
+/// 	и `max` → возвращает `0.5`
+/// - Результат всегда находится в диапазоне `[0, 1]`
+/// 	при `min ≤ value ≤ max`
+///
+/// Важные особенности функции:
+/// - Преобразует значение к нормализованному диапазону [0, 1]
+/// - Использует `math.div()` для безопасного деления
+/// - Работает с любыми числовыми значениями
+/// - Возвращает безразмерное дробное число
+/// - Является основой для многих алгоритмов интерполяции
+/// - Полезен для создания прогресс-индикаторов и анимаций
+///
+/// > Нормализация к диапазону [0, 1] является фундаментальной
+/// > операцией в компьютерной графике, статистике и анимациях.
+/// > Полученное значение можно использовать для интерполяции,
+/// > создания прогресс-баров, цветовых градиентов и других
+/// > алгоритмов, требующих значений в единичном интервале.
+/// >
+/// > Для значений вне диапазона `[$min, $max]` результат будет
+/// > выходить за пределы [0, 1], что может быть полезно для
+/// > экстраполяции или обнаружения выбросов.
+/// ---
+/// @name number-normalize
+/// @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#div См. также: Официальная документация Sass - Функция math.div()
+/// @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-41 См. также: Sass Guidelines - Раздел про математические операции
+/// @example scss - Базовая нормализация
+/// 	@debug number-normalize(50, 0, 100);    // 0.5
+/// 	@debug number-normalize(25, 0, 100);    // 0.25
+/// 	@debug number-normalize(75, 0, 100);    // 0.75
+/// 	@debug number-normalize(0, 0, 100);     // 0
+/// 	@debug number-normalize(100, 0, 100);   // 1
+/// @example scss - Граничные значения
+/// 	@debug number-normalize(10, 10, 20);    // 0
+/// 	@debug number-normalize(15, 10, 20);    // 0.5
+/// 	@debug number-normalize(20, 10, 20);    // 1
+/// 	@debug number-normalize(12.5, 10, 20);  // 0.25
+/// 	@debug number-normalize(17.5, 10, 20);  // 0.75
+/// @example scss - Нестандартные диапазоны
+/// 	@debug number-normalize(30, 10, 50);    // 0.5
+/// 	@debug number-normalize(45, 10, 50);    // 0.875
+/// 	@debug number-normalize(10, 10, 50);    // 0
+/// 	@debug number-normalize(50, 10, 50);    // 1
+/// 	@debug number-normalize(25, 10, 50);    // 0.375
+/// @example scss - Отрицательные диапазоны
+/// 	@debug number-normalize(-50, -100, 0);  // 0.5
+/// 	@debug number-normalize(-25, -100, 0);  // 0.75
+/// 	@debug number-normalize(-75, -100, 0);  // 0.25
+/// 	@debug number-normalize(-100, -100, 0); // 0
+/// 	@debug number-normalize(0, -100, 0);    // 1
+/// @example scss - Смешанные положительные/отрицательные
+/// 	@debug number-normalize(0, -50, 50);    // 0.5
+/// 	@debug number-normalize(25, -50, 50);   // 0.75
+/// 	@debug number-normalize(-25, -50, 50);  // 0.25
+/// 	@debug number-normalize(-50, -50, 50);  // 0
+/// 	@debug number-normalize(50, -50, 50);   // 1
+/// @example scss - Дробные числа
+/// 	@debug number-normalize(2.5, 0, 10);    // 0.25
+/// 	@debug number-normalize(7.5, 0, 10);    // 0.75
+/// 	@debug number-normalize(3.14, 0, 10);   // 0.314
+/// 	@debug number-normalize(1.618, 0, 10);  // 0.1618
+/// 	@debug number-normalize(8.675, 0, 10);  // 0.8675
+/// @example scss - Маленькие диапазоны
+/// 	@debug number-normalize(1.5, 1, 2);     // 0.5
+/// 	@debug number-normalize(1.25, 1, 2);    // 0.25
+/// 	@debug number-normalize(1.75, 1, 2);    // 0.75
+/// 	@debug number-normalize(1.1, 1, 2);     // 0.10000000000000009
+/// 	@debug number-normalize(1.9, 1, 2);     // 0.8999999999999999
+/// @example scss - Большие диапазоны
+/// 	@debug number-normalize(5000, 0, 10000); // 0.5
+/// 	@debug number-normalize(2500, 0, 10000); // 0.25
+/// 	@debug number-normalize(7500, 0, 10000); // 0.75
+/// 	@debug number-normalize(100, 0, 10000);  // 0.01
+/// 	@debug number-normalize(9900, 0, 10000); // 0.99
+/// @example scss - Значения за пределами диапазона
+/// 	@debug number-normalize(-10, 0, 100);   // -0.1
+/// 	@debug number-normalize(110, 0, 100);   // 1.1
+/// 	@debug number-normalize(150, 0, 100);   // 1.5
+/// 	@debug number-normalize(-50, 0, 100);   // -0.5
+/// 	@debug number-normalize(200, 0, 100);   // 2
+/// @example scss - С единицами измерения
+/// 	@debug number-normalize(25px, 0px, 100px); // 0.25
+/// 	@debug number-normalize(50px, 0px, 100px); // 0.5
+/// 	@debug number-normalize(75px, 0px, 100px); // 0.75
+/// 	@debug number-normalize(0px, 0px, 100px);  // 0
+/// 	@debug number-normalize(100px, 0px, 100px); // 1
+/// @example scss - Разные единицы измерения (конвертируются)
+/// 	@debug number-normalize(1rem, 0rem, 2rem); // 0.5
+/// 	@debug number-normalize(1.5rem, 0rem, 2rem); // 0.75
+/// 	@debug number-normalize(0.5rem, 0rem, 2rem); // 0.25
+/// 	@debug number-normalize(2rem, 0rem, 2rem);   // 1
+/// 	@debug number-normalize(0rem, 0rem, 2rem);   // 0
+/// @example scss - Процентные значения
+/// 	@debug number-normalize(50%, 0%, 100%);  // 0.5
+/// 	@debug number-normalize(25%, 0%, 100%);  // 0.25
+/// 	@debug number-normalize(75%, 0%, 100%);  // 0.75
+/// 	@debug number-normalize(0%, 0%, 100%);   // 0
+/// 	@debug number-normalize(100%, 0%, 100%); // 1
+/// @example scss - Нецелочисленные границы
+/// 	@debug number-normalize(3.5, 1.5, 5.5);  // 0.5
+/// 	@debug number-normalize(2.5, 1.5, 5.5);  // 0.25
+/// 	@debug number-normalize(4.5, 1.5, 5.5);  // 0.75
+/// 	@debug number-normalize(1.5, 1.5, 5.5);  // 0
+/// 	@debug number-normalize(5.5, 1.5, 5.5);  // 1
+/// @example scss - Очень малые значения
+/// 	@debug number-normalize(0.5, 0, 1);      // 0.5
+/// 	@debug number-normalize(0.25, 0, 1);     // 0.25
+/// 	@debug number-normalize(0.75, 0, 1);     // 0.75
+/// 	@debug number-normalize(0.001, 0, 1);    // 0.001
+/// 	@debug number-normalize(0.999, 0, 1);    // 0.999
+/// @example scss - Симметричные диапазоны
+/// 	@debug number-normalize(0, -1, 1);       // 0.5
+/// 	@debug number-normalize(0.5, -1, 1);     // 0.75
+/// 	@debug number-normalize(-0.5, -1, 1);    // 0.25
+/// 	@debug number-normalize(1, -1, 1);       // 1
+/// 	@debug number-normalize(-1, -1, 1);      // 0
+/// @param {Number} $value - Число для нормализации.
+/// 	Может быть любым числом: целым, дробным, положительным,
+/// 	отрицательным, с единицами измерения или без.
+/// @param {Number} $min - Нижняя граница исходного диапазона.
+/// 	Значение, соответствующее `0` в нормализованном диапазоне.
+/// @param {Number} $max - Верхняя граница исходного диапазона.
+/// 	Значение, соответствующее `1` в нормализованном диапазоне.
+/// @return {Number} - Нормализованное значение в диапазоне [0, 1].
+/// 	Возвращает дробное безразмерное число. Если `$value` находится
+/// 	между `$min` и `$max`, результат будет в диапазоне [0, 1].
+/// 	Если `$value` меньше `$min`, результат будет отрицательным.
+/// 	Если `$value` больше `$max`, результат будет больше 1.
+/// @throws {Error} - Может выбросить ошибку деления на ноль, если
+/// 	`$min == $max`. В этом случае знаменатель формулы становится
+/// 	нулем, что приводит к математической неопределенности.
+@function number-normalize($value, $min, $max) {
+	@return math.div($value - $min, $max - $min);
+}

package/modules/utilities/helpers/number/_number-random-between-int.scss

@@ -0,0 +1,84 @@
+@use 'sass:math';
+
+/// Генерирует случайное целое число в заданном диапазоне.
+///
+/// Функция принимает минимальное и максимальное целые значения
+/// и возвращает случайное целое число, равномерно распределенное
+/// в диапазоне [`$min`, `$max`] включительно.
+///
+/// Формула генерации:
+/// `math.floor($min + math.random() * ($max - $min + 1))`
+///
+/// Визуализация работы:
+/// - Генерирует базовое случайное число от 0 до 1 (исключая 1)
+/// - Масштабирует его на длину диапазона плюс 1
+/// - Сдвигает на минимальное значение (`$min`)
+/// - Округляет вниз до ближайшего целого числа
+///
+/// Важные особенности функции:
+/// - Работает только с целыми числами (без единиц измерения)
+/// - Диапазон включает оба конца: `$min` и `$max`
+/// - Равномерное распределение в заданном диапазоне
+/// - Каждый вызов функции возвращает новое случайное значение
+/// - Результат компилируется в CSS как фиксированное целое число
+/// - Может использоваться для генерации случайных индексов,
+///   количеств, таймингов, целочисленных параметров
+///
+/// > Внимание: функция использует `math.random()` и `math.floor()`,
+/// > которые генерируют псевдослучайные числа. При каждом
+/// > запуске компилятора Sass будет генерироваться новая
+/// > последовательность чисел. В отличие от JavaScript, который
+/// > выполняется в браузере, эта функция вычисляется при
+/// > компиляции Sass.
+/// ---
+/// @name number-random-between-int
+/// @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 См. также: Официальная документация Sass - Модуль math
+/// @link https://sass-lang.com/documentation/modules/math#random См. также: Официальная документация Sass - Функция math.random()
+/// @link https://sass-lang.com/documentation/modules/math#floor См. также: Официальная документация Sass - Функция math.floor()
+/// @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random См. также: MDN Web Docs - JavaScript Math.random()
+/// @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/floor См. также: MDN Web Docs - JavaScript Math.floor()
+/// @link https://en.wikipedia.org/wiki/Uniform_distribution_(discrete) См. также: Wikipedia - Дискретное равномерное распределение
+/// @link https://stackoverflow.com/questions/1527803/generating-random-whole-numbers-in-javascript-in-a-specific-range См. также: Stack Overflow - Генерация случайных целых чисел в диапазоне
+/// @example scss - Базовая генерация случайных целых чисел
+/// 	@debug number-random-between-int(1, 10);     // например: 7
+/// 	@debug number-random-between-int(1, 10);     // например: 3
+/// 	@debug number-random-between-int(1, 10);     // например: 10
+/// @example scss - Диапазоны с включенными границами
+/// 	@debug number-random-between-int(0, 100);    // например: 42
+/// 	@debug number-random-between-int(5, 15);     // например: 12
+/// 	@debug number-random-between-int(-10, 10);   // например: -3
+/// 	@debug number-random-between-int(100, 200);  // например: 150
+/// @example scss - Отрицательные диапазоны
+/// 	@debug number-random-between-int(-20, -10);  // например: -15
+/// 	@debug number-random-between-int(-5, 5);     // например: 2
+/// 	@debug number-random-between-int(-100, 0);   // например: -73
+/// @example scss - Единичные значения и малые диапазоны
+/// 	@debug number-random-between-int(5, 5);      // всегда: 5
+/// 	@debug number-random-between-int(0, 1);      // например: 0 или 1
+/// 	@debug number-random-between-int(1, 2);      // например: 1 или 2
+/// 	@debug number-random-between-int(-1, 1);     // например: -1, 0 или 1
+/// @example scss - Практическое применение (через переменные)
+/// 	$columns: number-random-between-int(2, 6);   // например: 4
+/// 	$repeat-count: number-random-between-int(3, 8); // например: 5
+/// 	$z-index: number-random-between-int(1, 10);  // например: 7
+/// @param {Number} $min - Минимальное целое значение диапазона (включительно).
+///   Должно быть целым числом без единиц измерения.
+///   Определяет нижнюю границу генерации.
+/// @param {Number} $max - Максимальное целое значение диапазона (включительно).
+///   Должно быть целым числом без единиц измерения.
+///   Определяет верхнюю границу генерации.
+///   Должно быть больше или равно `$min` для корректных результатов.
+/// @return {Number} - Случайное целое число в диапазоне [`$min`, `$max`].
+///   Всегда возвращает целое число без единиц измерения.
+/// @throws {Error} - Может выбросить ошибку при передаче
+///   нецелых чисел или чисел с единицами измерения.
+///   При `$max < $min` результат может быть неожиданным.
+@function number-random-between-int($min, $max) {
+  @return math.floor($min + math.random() * ($max - $min + 1));
+}

package/modules/utilities/helpers/number/_number-random-between.scss

@@ -0,0 +1,120 @@
+@use 'sass:math';
+
+/// Генерирует случайное число в заданном диапазоне.
+///
+/// Функция принимает минимальное и максимальное значения
+/// и возвращает случайное число, равномерно распределенное
+/// в диапазоне [`$min`, `$max`] (включительно для `$min`,
+/// исключительно для `$max` для дробных чисел).
+///
+/// Формула генерации:
+/// `$min + math.random() * ($max - $min)`
+///
+/// Визуализация работы:
+/// - Генерирует базовое случайное число от 0 до 1 (исключая 1)
+/// - Масштабирует его на длину диапазона (`$max - $min`)
+/// - Сдвигает на минимальное значение (`$min`)
+///
+/// Важные особенности функции:
+/// - Работает с любыми числовыми значениями (целые, дробные,
+///   положительные, отрицательные, с единицами измерения)
+/// - Возвращает дробное число даже при целых границах
+/// - Для получения целых чисел используйте `math.floor()` или
+///   `math.round()` вместе с функцией
+/// - Равномерное распределение в заданном диапазоне
+/// - Каждый вызов функции возвращает новое случайное значение
+/// - Результат компилируется в CSS как фиксированное значение
+/// - Может использоваться для генерации случайных размеров,
+///   цветов, отступов, анимационных параметров
+///
+/// > Внимание: функция использует `math.random()`, которая
+/// > генерирует псевдослучайные числа.
+/// >
+/// > В отличие от JavaScript `Math.random()`, которая
+/// > выполняется в браузере, `number-random-between()` вычисляется
+/// > при компиляции и возвращает фиксированное значение в CSS.
+/// ---
+/// @name number-random-between
+/// @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 См. также: Официальная документация Sass - Модуль math
+/// @link https://sass-lang.com/documentation/modules/math#random См. также: Официальная документация Sass - Функция math.random()
+/// @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random См. также: MDN Web Docs - JavaScript Math.random()
+/// @link https://en.wikipedia.org/wiki/Uniform_distribution_(continuous) См. также: Wikipedia - Непрерывное равномерное распределение
+/// @link https://www.w3schools.com/js/js_random.asp См. также: W3Schools - JavaScript Random Numbers
+/// @example scss - Базовая генерация случайных чисел
+/// 	// Каждый вызов дает разный результат при компиляции
+/// 	@debug number-random-between(0, 10);       // например: 7.244421653570976
+/// 	@debug number-random-between(0, 10);       // например: 8.669635705053507
+/// 	@debug number-random-between(0, 10);       // например: 4.402152393988244
+/// @example scss - Диапазоны с единицами измерения
+/// 	@debug number-random-between(10px, 50px);     // например: 40.47629084995985px
+/// 	@debug number-random-between(1rem, 3rem);     // например: 2.194695513077836rem
+/// 	@debug number-random-between(0%, 100%);       // например: 50.82019390506141%
+/// @example scss - Дробные диапазоны
+/// 	@debug number-random-between(0.1, 0.9);       // например: 0.8165020190345386
+/// 	@debug number-random-between(1.5, 3.5);       // например: 2.1496319539946427
+/// 	@debug number-random-between(-0.5, 0.5);      // например: 0.41678528339764553
+/// @example scss - Отрицательные диапазоны
+/// 	@debug number-random-between(-10, 10);        // например: -8.712447491197564
+/// 	@debug number-random-between(-100, -50);      // например: -86.74387500886313
+/// 	@debug number-random-between(-5.5, 5.5);      // например: -2.7145449118153575
+/// @example scss - Получение целых чисел (с использованием math.floor)
+/// 	// Целое число от 1 до 10 включительно
+/// 	$int: math.floor(number-random-between(1, 11));
+/// 	@debug $int; // например: 9
+///
+/// 	// Целое число от 0 до 100 включительно
+/// 	$percentage: math.floor(number-random-between(0, 101));
+/// 	@debug $percentage; // например: 50
+/// @example scss - Практическое применение
+/// 	// Случайный отступ
+/// 	.element {
+/// 	  padding: number-random-between(8px, 24px);
+/// 	}
+///
+/// 	// Случайная прозрачность
+/// 	.overlay {
+/// 	  opacity: number-random-between(0.3, 0.8);
+/// 	}
+///
+/// 	// Случайный угол поворота
+/// 	.decorative {
+/// 	  transform: rotate(number-random-between(-5deg, 5deg));
+/// 	}
+/// @example css - Результат
+/// 	.element {
+/// 		padding: 20.9060027047px;
+/// 	}
+///
+/// 	.overlay {
+/// 		opacity: 0.3586561047;
+/// 	}
+///
+/// 	.decorative {
+/// 		transform: rotate(2.1312623254deg);
+/// 	}
+/// @param {Number} $min - Минимальное значение диапазона (включительно).
+///   Может быть любым числом: целым, дробным, положительным,
+///   отрицательным, с единицами измерения или без.
+///   Определяет нижнюю границу генерации.
+/// @param {Number} $max - Максимальное значение диапазона (исключительно
+///   для дробных чисел, но практически достижимо).
+///   Может быть любым числом: целым, дробным, положительным,
+///   отрицательным, с единицами измерения или без.
+///   Определяет верхнюю границу генерации.
+///   Должно быть больше или равно `$min` для корректных результатов.
+/// @return {Number} - Случайное число в диапазоне [`$min`, `$max`).
+///   Если параметры имеют единицы измерения, результат будет
+///   иметь те же единицы. Всегда возвращает дробное число.
+/// @throws {Error} - Не выбрасывает ошибок явно, но при
+///   `$max < $min` результат может быть неожиданным (возможны
+///   отрицательные значения длины диапазона). Рекомендуется
+///   всегда передавать `$min ≤ $max`.
+@function number-random-between($min, $max) {
+	@return $min + math.random() * ($max - $min);
+}

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

@@ -0,0 +1,268 @@
+@use 'sass:list';
+
+/// Генерирует последовательность чисел в заданном диапазоне
+/// с определенным шагом.
+///
+/// Функция `number-range()` создает упорядоченный список чисел,
+/// равномерно распределенных между начальным и конечным значениями
+/// с заданным шагом. Поддерживает как возрастающие, так и убывающие
+/// последовательности, автоматически определяя направление на основе
+/// входных параметров.
+///
+/// Каждое число в последовательности вычисляется с использованием
+/// модульной арифметики, обеспечивая точное соответствие шагу.
+/// Функция гарантирует включение как начального, так и конечного
+/// значений в результат, если они соответствуют заданному шагу.
+/// Полезно для генерации числовых интервалов, систем отступов,
+/// размеров сеток, z-index слоев и других числовых систем.
+///
+/// > Для создания последовательностей с плавающими числами
+/// > убедитесь, что шаг кратен разнице между значениями,
+/// > чтобы избежать ошибок округления.
+/// ---
+/// @name number-range
+/// @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/list См. также: Sass - Модуль list
+/// @link https://sass-lang.com/documentation/at-rules/control/#for См. также: Sass - Циклы @for
+/// @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/from См. также: MDN - Array.from() с диапазоном
+/// @link https://docs.python.org/3/library/functions.html#func-range См. также: Python - Функция range()
+/// @link https://www.w3.org/TR/css-values-4/#numeric-types См. также: W3C - Числовые типы CSS
+/// @example scss - Создание базовой последовательности
+/// 	@use 'sass:list';
+///
+/// 	$sequence: number-range(1, 10);
+/// 	// Возвращает: (1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
+///
+/// 	@each $number in $sequence {
+/// 		.item-#{$number} {
+/// 			order: $number;
+/// 		}
+/// 	}
+/// @example css - Результат
+/// 	.item-1 {
+/// 		order: 1;
+/// 	}
+/// 	.item-2 {
+/// 		order: 2;
+/// 	}
+/// 	.item-3 {
+/// 		order: 3;
+/// 	}
+/// 	.item-4 {
+/// 		order: 4;
+/// 	}
+/// 	.item-5 {
+/// 		order: 5;
+/// 	}
+/// 	.item-6 {
+/// 		order: 6;
+/// 	}
+/// 	.item-7 {
+/// 		order: 7;
+/// 	}
+/// 	.item-8 {
+/// 		order: 8;
+/// 	}
+/// 	.item-9 {
+/// 		order: 9;
+/// 	}
+/// 	.item-10 {
+/// 		order: 10;
+/// 	}
+/// @example scss - Генерация системы отступов с шагом
+/// 	@use 'sass:list';
+///
+/// 	:root {
+/// 		$spacings: number-range(0, 64, 8);
+///
+/// 		@for $i from 1 through list.length($spacings) {
+/// 			$value: list.nth($spacings, $i);
+/// 			--spacing-#{$value}: #{$value}px;
+/// 		}
+/// 	}
+/// @example css - Результат
+/// 	:root {
+/// 		--spacing-0: 0px;
+/// 		--spacing-8: 8px;
+/// 		--spacing-16: 16px;
+/// 		--spacing-24: 24px;
+/// 		--spacing-32: 32px;
+/// 		--spacing-40: 40px;
+/// 		--spacing-48: 48px;
+/// 		--spacing-56: 56px;
+/// 		--spacing-64: 64px;
+/// 	}
+/// @example scss - Создание убывающей последовательности для z-index
+/// 	@use 'sass:list';
+///
+/// 	$layers: number-range(10, 1);
+/// 	// Возвращает: (10, 9, 8, 7, 6, 5, 4, 3, 2, 1)
+///
+/// 	@each $layer in $layers {
+/// 		.layer-#{$layer} {
+/// 			z-index: $layer * 10;
+/// 			opacity: math.div($layer, 10);
+/// 		}
+/// 	}
+/// @example css - Результат
+/// 	.layer-10 {
+/// 		z-index: 100;
+/// 		opacity: 1;
+/// 	}
+/// 	.layer-9 {
+/// 		z-index: 90;
+/// 		opacity: 0.9;
+/// 	}
+/// 	.layer-8 {
+/// 		z-index: 80;
+/// 		opacity: 0.8;
+/// 	}
+/// 	.layer-7 {
+/// 		z-index: 70;
+/// 		opacity: 0.7;
+/// 	}
+/// 	.layer-6 {
+/// 		z-index: 60;
+/// 		opacity: 0.6;
+/// 	}
+/// 	.layer-5 {
+/// 		z-index: 50;
+/// 		opacity: 0.5;
+/// 	}
+/// 	.layer-4 {
+/// 		z-index: 40;
+/// 		opacity: 0.4;
+/// 	}
+/// 	.layer-3 {
+/// 		z-index: 30;
+/// 		opacity: 0.3;
+/// 	}
+/// 	.layer-2 {
+/// 		z-index: 20;
+/// 		opacity: 0.2;
+/// 	}
+/// 	.layer-1 {
+/// 		z-index: 10;
+/// 		opacity: 0.1;
+/// 	}
+/// @example scss - Генерация сетки с динамическими колонками
+/// 	@use 'sass:list';
+/// 	@use 'sass:math';
+///
+/// 	.grid {
+/// 		display: grid;
+/// 		grid-template-columns: repeat(12, 1fr);
+/// 		gap: 1rem;
+/// 	}
+///
+/// 	$columns: number-range(1, 12);
+///
+/// 	@each $col in $columns {
+/// 		.grid__col--#{$col} {
+/// 			grid-column: span $col;
+/// 			width: percentage(math.div($col, 12));
+/// 		}
+/// 	}
+/// @example css - Результат
+/// 	.grid {
+/// 		display: grid;
+/// 		grid-template-columns: repeat(12, 1fr);
+/// 		gap: 1rem;
+/// 	}
+/// 	.grid__col--1 {
+/// 		grid-column: span 1;
+/// 		width: 8.3333333333%;
+/// 	}
+/// 	.grid__col--2 {
+/// 		grid-column: span 2;
+/// 		width: 16.6666666667%;
+/// 	}
+/// 	.grid__col--3 {
+/// 		grid-column: span 3;
+/// 		width: 25%;
+/// 	}
+/// 	.grid__col--4 {
+/// 		grid-column: span 4;
+/// 		width: 33.3333333333%;
+/// 	}
+/// 	.grid__col--5 {
+/// 		grid-column: span 5;
+/// 		width: 41.6666666667%;
+/// 	}
+/// 	.grid__col--6 {
+/// 		grid-column: span 6;
+/// 		width: 50%;
+/// 	}
+/// 	.grid__col--7 {
+/// 		grid-column: span 7;
+/// 		width: 58.3333333333%;
+/// 	}
+/// 	.grid__col--8 {
+/// 		grid-column: span 8;
+/// 		width: 66.6666666667%;
+/// 	}
+/// 	.grid__col--9 {
+/// 		grid-column: span 9;
+/// 		width: 75%;
+/// 	}
+/// 	.grid__col--10 {
+/// 		grid-column: span 10;
+/// 		width: 83.3333333333%;
+/// 	}
+/// 	.grid__col--11 {
+/// 		grid-column: span 11;
+/// 		width: 91.6666666667%;
+/// 	}
+/// 	.grid__col--12 {
+/// 		grid-column: span 12;
+/// 		width: 100%;
+/// 	}
+/// @param {Number} $start - Начальное значение последовательности.
+/// 	Включается в результат как первый элемент, если соответствует шагу.
+/// 	Может быть любым числом (целым или с плавающей точкой).
+/// @param {Number} $end - Конечное значение последовательности.
+/// 	Включается в результат как последний элемент, если соответствует шагу.
+/// 	Определяет направление последовательности:
+///   - Если `$start < $end` → возрастающая последовательность
+///   - Если `$start > $end` → убывающая последовательность
+///   - Если `$start == $end` → последовательность из одного элемента
+/// @param {Number} $step [1] - Шаг между соседними элементами.
+/// 	Определяет расстояние между значениями в последовательности.
+/// 	Должен быть положительным числом больше нуля.
+/// 	Фактический шаг применяется в направлении последовательности:
+///   - Возрастающая: `$current + $step`
+///   - Убывающая: `$current - $step`
+/// @return {List} - Упорядоченный список (list) чисел, где:
+///   - Первый элемент: ближайшее к `$start` значение, кратное шагу
+///   - Последний элемент: ближайшее к `$end` значение, кратное шагу
+///   - Все элементы: равномерно распределены с шагом `$step`
+///   - Направление: соответствует соотношению `$start` и `$end`
+@function number-range($from, $to, $step: 1) {
+	$-result: ();
+
+	@if $from < $to {
+		@for $i from $from through $to {
+			@if ($i - $from) % $step == 0 {
+
+				$-result: list.append($-result, $i);
+
+			}
+		}
+	} @else {
+		@for $i from $from through $to {
+			@if ($from - $i) % $step == 0 {
+
+				$-result: list.append($-result, $i);
+
+			}
+		}
+	}
+
+	@return $-result;
+
+}